sdk/fidl/zbi/cpu.fidl

// Copyright 2023 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 zbi;

// TODO(https://fxbug.dev/42062786): Figure out documentation convention.

const MAX_SMT uint64 = 4;

type TopologyProcessorFlags = bits : uint16 {
    /// The associated processor boots the system and is the last to be shutdown.
    PRIMARY = 0b1;

    /// The associated processor handles all interrupts. Some architectures
    /// will not have such a processor.
    INTERRUPT = 0b10;
};

type TopologyArm64Info = struct {
    /// Cluster ids for each level, one being closest to the cpu.
    /// These map to aff1, aff2, and aff3 values in the ARM registers.
    cluster_1_id uint8;
    cluster_2_id uint8;
    cluster_3_id uint8;

    /// Id of the cpu inside of the bottom-most cluster, aff0 value.
    cpu_id uint8;

    /// The GIC interface number for this processor.
    /// In GIC v3+ this is not necessary as the processors are addressed by their
    /// affinity routing (all cluster ids followed by cpu_id).
    gic_id uint8;
};

type TopologyX64Info = struct {
    apic_ids array<uint32, MAX_SMT>;
    apic_id_count uint32;
};

type TopologyRiscv64Info = struct {
    /// ID that represents this logical CPU (i.e., hart) in SBI.
    hart_id uint64;

    /// Index into the ZBI_TYPE_RISCV64_ISA_STRTAB string table payload giving
    /// the start of the associated ISA string.
    isa_strtab_index uint32;

    reserved uint32;
};

type TopologyArchitectureInfo = strict overlay {
    1: arm64 TopologyArm64Info;
    2: x64 TopologyX64Info;
    3: riscv64 TopologyRiscv64Info;
};

type TopologyProcessor = struct {
    architecture_info TopologyArchitectureInfo;
    flags TopologyProcessorFlags;
    logical_ids array<uint16, MAX_SMT>;
    logical_id_count uint8;
};

type TopologyCluster = struct {
    /// Relative performance level of this processor in the system. The value is
    /// interpreted as the performance of this processor relative to the maximum
    /// performance processor in the system. No specific values are required for
    /// the performance level, only that the following relationship holds:
    ///
    ///   Pmax is the value of performance_class for the maximum performance
    ///   processor in the system, operating at its maximum operating point.
    ///
    ///   P is the value of performance_class for this processor, operating at
    ///   its maximum operating point.
    ///
    ///   R is the performance ratio of this processor to the maximum performance
    ///   processor in the system in the range (0.0, 1.0].
    ///
    ///   R = (P + 1) / (Pmax + 1)
    ///
    /// If accuracy is limited, choose a conservative value that slightly under-
    /// estimates the performance of lower-performance processors.
    performance_class uint8;
};

type TopologyCache = struct {
    /// Unique id of this cache node. No other semantics are assumed.
    cache_id uint32;
};

type TopologyDie = struct {
    reserved uint64;
};

type TopologySocket = struct {
    reserved uint64;
};

type TopologyNumaRegion = struct {
    /// Starting memory addresses of the numa region.
    start uint64;

    /// Size in bytes of the numa region.
    size uint64;
};

type TopologyEntity = strict overlay {
    1: processor TopologyProcessor;
    2: cluster TopologyCluster;
    3: cache TopologyCache;
    4: die TopologyDie;
    5: socket TopologySocket;
    6: numa_region TopologyNumaRegion;
};

const TOPOLOGY_NO_PARENT uint16 = 0xffff;

/// The ZBI_TYPE_CPU_TOPOLOGY payload consists of an array of
/// zbi_topology_node_t, giving a flattened tree-like description of the CPU
/// configuration according to the entity hierarchy.
type TopologyNode = struct {
    entity TopologyEntity;
    parent_index uint16;
};