// Copyright 2019 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.kernel;

using zx;

// The zx library does not include zx_info_kmem_stats_t, so this table is mirroring it.
// See zircon/system/public/zircon/syscalls/object.h for more details.
type MemoryStats = table {
    1: total_bytes uint64;
    2: free_bytes uint64;
    3: wired_bytes uint64;
    4: total_heap_bytes uint64;
    5: free_heap_bytes uint64;
    6: vmo_bytes uint64;
    7: mmu_overhead_bytes uint64;
    8: ipc_bytes uint64;
    9: other_bytes uint64;
};

// Similarly, this table mirrors zx_info_kmem_stats_extended_t.
// See zircon/system/public/zircon/syscalls/object.h for more details.
type MemoryStatsExtended = table {
    1: total_bytes uint64;
    2: free_bytes uint64;
    3: wired_bytes uint64;
    4: total_heap_bytes uint64;
    5: free_heap_bytes uint64;
    6: vmo_bytes uint64;
    7: vmo_pager_total_bytes uint64;
    8: vmo_pager_newest_bytes uint64;
    9: vmo_pager_oldest_bytes uint64;
   10: vmo_discardable_locked_bytes uint64;
   11: vmo_discardable_unlocked_bytes uint64;
   12: mmu_overhead_bytes uint64;
   13: ipc_bytes uint64;
   14: other_bytes uint64;
};

// Similarly, this table mirrors zx_info_cpu_stats_t.
// See zircon/system/public/zircon/syscalls/object.h for more details.
type PerCpuStats = table {
    1: cpu_number uint32;
    2: flags uint32;
    3: idle_time zx.duration;
    4: reschedules uint64;
    5: context_switches uint64;
    6: irq_preempts uint64;
    7: yields uint64;
    8: ints uint64;
    9: timer_ints uint64;
   10: timers uint64;
   11: page_faults uint64;
   12: exceptions uint64;
   13: syscalls uint64;
   14: reschedule_ipis uint64;
   15: generic_ipis uint64;
};

type CpuStats = struct {
    /// This is the total number of CPUs on the actual device. This may not be the same as the length
    /// of the vector `per_cpu_stats` as it is possible the underlying syscall will not return stats
    /// for all CPUs.
    actual_num_cpus uint64;
    per_cpu_stats vector<PerCpuStats>:<zx.MAX_CPUS, optional>;
};

/// Protocol for providing kernel stats. This is roughly a wrapper around zx_object_get_info for
/// the ZX_INFO_KMEM_STATS, ZX_INFO_KMEM_STATS_EXTENDED and ZX_INFO_CPU_STATS topics, which today
/// require the very powerful 'Root Resource' capability to obtain. Instead of vending out that
/// capability, programs that just want stats should use this service instead. If for some reason
/// the protocol fails to retrieve stats, which will be an un-recoverable error, it will close the
/// channel.
@discoverable
protocol Stats {
    GetMemoryStats() -> (struct {
        stats MemoryStats;
    });

    GetMemoryStatsExtended() -> (struct {
        stats MemoryStatsExtended;
    });

    GetCpuStats() -> (struct {
        stats CpuStats;
    });

    /// Gets the average load as a percentage (0.0 - 100.0) from each CPU over the specified
    /// duration.
    ///
    /// Load is calculated as (100 - %idle), where %idle is the percentage value of idle_time (from
    /// PerCpuStats) over a time duration.
    GetCpuLoad(struct {
        duration zx.duration;
    }) -> (struct {
        per_cpu_load vector<float32>:zx.MAX_CPUS;
    });
};