// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.virtualization;

using zx;

/// Contains a memory statistic for the balloon device.
type MemStat = struct {
    tag uint16;
    val uint64;
};

/// A `BalloonController` controls a guest instance's memory balloon.
@discoverable
closed protocol BalloonController {
    /// Get the current and requested number of pages in the memory balloon.
    ///
    /// current_num_pages is the number of pages balloon has right now.
    /// requested_num_pages is the desired number of pages in the balloon.
    ///
    /// 'current_num_pages' corresponds to the 'actual' virtio-balloon config field
    /// 'requested_num_pages' corresponds to the 'num_pages' virtio-balloon config field.
    strict GetBalloonSize() -> (struct {
        current_num_pages uint32;
        requested_num_pages uint32;
    });

    /// Request a number of pages to be supplied to the memory balloon.
    ///
    /// If `requested_num_pages` is greater than the `current_num_pages` config
    /// value, the guest driver SHOULD provide additional pages to the memory balloon.
    /// If `requested_num_pages` is less than the 'current_num_pages' config value,
    /// the guest driver MAY reclaim pages from the memory balloon.
    strict RequestNumPages(struct {
        requested_num_pages uint32;
    });

    /// Get memory statistics of the guest instance.
    strict GetMemStats() -> (struct {
        status zx.Status;
        mem_stats vector<MemStat>:<MAX, optional>;
    });
};