sdk/fidl/fuchsia.power.cpu/domain.fidl

// Copyright 2025 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.
@available(added=HEAD)
library fuchsia.power.cpu;

type DomainInfo = table {
    // ID of the domain.
    1: id uint64;
    // The IDs of the CPU cores that are part of this domain.
    2: core_ids vector<uint64>:MAX;
    // The frequencies (in Hz) that the cores in this domain can run at.
    3: available_frequencies_hz vector<uint64>:MAX;
    // The name of the domain/cluster.
    4: name string:MAX;
};

/// Errors returned by [`fuchsia.power.cpu/DomainController.GetMaxFrequency`].
type GetMaxFrequencyError = flexible enum {
    INTERNAL = 1;
    INVALID_ARGUMENTS = 2;
};

/// Errors returned by [`fuchsia.power.cpu/DomainController.SetMaxFrequency`].
type SetMaxFrequencyError = flexible enum {
    INTERNAL = 1;
    INVALID_ARGUMENTS = 2;
};

/// Errors returned by [`fuchsia.power.cpu/DomainController.ClearMaxFrequency`].
type ClearMaxFrequencyError = flexible enum {
    INTERNAL = 1;
    INVALID_ARGUMENTS = 2;
};

@discoverable
open protocol DomainController {
    /// Lists info about each domain managed by the server.
    ///
    /// The server is guaranteed to fill all fields within `DomainInfo` unless
    /// the field is explicitly marked as "Optional".
    flexible ListDomains() -> (struct {
        domains vector<DomainInfo>:MAX;
    });

    /// Gets the index of the max frequency the CPU can run at.
    ///
    /// `max_frequency_index` corresponds to the index of a frequency within
    /// this domain's `available_frequencies_hz` list retrieved via
    /// [`ListDomains`].
    ///
    /// If SetMaxFrequency has never been called, this will return the index
    /// that corresponds to the highest available frequency for this domain.
    ///
    /// If `domain_id` is invalid, INVALID_ARGUMENTS is returned.
    flexible GetMaxFrequency(struct {
        domain_id uint64;
    }) -> (struct {
        max_frequency_index uint64;
    }) error GetMaxFrequencyError;

    /// Sets the max frequency the CPU can run at.
    ///
    /// `frequency_index` must correspond to the index of a frequency within
    /// this domain's `available_frequencies_hz` list retrieved via
    /// [`ListDomains`].
    ///
    /// On products with Runtime Processor Power Management (RPPM), the CPU may
    /// briefly exceed max frequency if power limits allow.
    ///
    /// If `domain_id` is invalid, INVALID_ARGUMENTS is returned.
    /// If `frequency_index` is invalid, INVALID_ARGUMENTS is returned.
    flexible SetMaxFrequency(struct {
        domain_id uint64;
        frequency_index uint64;
    }) -> () error SetMaxFrequencyError;

    /// Clears the max frequency limit the CPU can run at.
    ///
    /// If `domain_id` is invalid, INVALID_ARGUMENTS is returned.
    flexible ClearMaxFrequency(struct {
        domain_id uint64;
    }) -> () error ClearMaxFrequencyError;
};