Skip to content
Merged
44 changes: 43 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,15 @@ information about the CPUs on the host system.
the host system contains
* `ghw.CPUInfo.Processors` is an array of `ghw.Processor` structs, one for each
physical processor package contained in the host
* `ghw.CPUInfo.LogicalProcessors` (Linux only) is an array of pointers to
`cpu.LogicalProcessor` structs, one for each online logical processor,
ascending by ID
* `ghw.CPUInfo.OfflineLogicalProcessors` (Linux only) is an array of the IDs of
the logical processors that are present but offline (for example with SMT
turned off), ascending
* `ghw.CPUInfo.Caches` (Linux only) is an array of pointers to
`ghw.MemoryCache` structs, one for each cache instance of the online logical
processors, with the logical processors sharing it

Each `ghw.Processor` struct contains a number of fields:

Expand All @@ -101,7 +110,8 @@ A `ghw.ProcessorCore` has the following fields:
* `ghw.ProcessorCore.ID` is the `uint32` identifier that the host gave this
core. Note that this does *not* necessarily equate to a zero-based index of
the core within a physical package. For example, the core IDs for an Intel Core
i7 are 0, 1, 2, 8, 9, and 10
i7 are 0, 1, 2, 8, 9, and 10. On Linux it is -1 where the core cannot be told,
and each such core holds a single logical processor
* `ghw.ProcessorCore.TotalHardwareThreads` is the number of hardware threads
associated with the core
* `ghw.ProcessorCore.LogicalProcessors` is an array of ints representing the
Expand All @@ -110,6 +120,31 @@ A `ghw.ProcessorCore` has the following fields:
*zero-based* index of the processor on the host and are *not* related to the
core ID.

A `cpu.LogicalProcessor` (Linux only) describes one online logical processor
(hardware thread) and where it sits in the host's topology. An ID that could
not be read is -1, and a frequency the kernel does not report is 0:

* `cpu.LogicalProcessor.ID` is the logical processor ID the kernel and CPU
affinities use
* `cpu.LogicalProcessor.ProcessorID` is the physical package (socket) it
belongs to: the ID of its `ghw.Processor`
* `cpu.LogicalProcessor.CoreID` is the physical core it runs on: the ID of its
`ghw.ProcessorCore`, unique within the package. Logical processors with the
same known `ProcessorID` and `CoreID` are SMT siblings
* `cpu.LogicalProcessor.NodeID` is the NUMA node it belongs to; 0 on a kernel
without NUMA
* `cpu.LogicalProcessor.CoreType` is the class of core it runs on, a
`cpu.CoreType`: `cpu.CoreTypePerformance` or `cpu.CoreTypeEfficiency` on a
heterogeneous part (Intel P- and E-cores, ARM big.LITTLE),
`cpu.CoreTypeUniform` on a homogeneous one, or `cpu.CoreTypeUnknown` where the
host does not tell. Intel hybrid parts list their cores under the `cpu_core`,
`cpu_atom` and `cpu_lowpower` PMUs; elsewhere each CPU's `cpu_capacity` ranks
it, the highest capacity being a performance core. The ranking sees only
online CPUs and ranks by capacity alone, so on a part with three classes of
core the middle one reads as efficiency
* `cpu.LogicalProcessor.BaseFrequencyKHz` is its base (non-turbo) frequency
* `cpu.LogicalProcessor.MaxFrequencyKHz` is its maximum (turbo) frequency

```go
package main

Expand Down Expand Up @@ -458,6 +493,9 @@ Each `ghw.MemoryCache` struct contains the following fields:
cache can contain
* `ghw.MemoryCache.LogicalProcessors` is an array of integers representing the
logical processors that use the cache
* `ghw.MemoryCache.ID` (Linux only) is the kernel's identifier of this cache
instance, unique among the caches of the same level and type, or -1 where the
kernel does not number it (older kernels did not number device-tree caches)

```go
package main
Expand Down Expand Up @@ -700,6 +738,10 @@ The `ghw.PCIDevice` struct has the following fields:
information is not available. If the information is not available, this does
not mean the device is not functioning, but rather that `ghw` was not able to
retrieve driver information.
* `ghw.PCIDevice.LocalCPUs` (Linux only) is an array of the logical processors
local to the device: those of the NUMA node its DMA and interrupts are local
to, or every CPU when the platform gives it no NUMA affinity. Nil when the
kernel does not report them.

The `ghw.PCIAddress` (which is an alias for the `ghw.pci.address.Address`
struct) contains the PCI address fields. It has a `ghw.PCIAddress.String()`
Expand Down
156 changes: 156 additions & 0 deletions internal/sysfsfixture/sysfsfixture.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
//
Comment thread
christoph-zededa marked this conversation as resolved.
Resolved
// Use and distribution licensed under the Apache license version 2.
//
// See the COPYING file in the root project directory for full text.
//

// Package sysfsfixture writes small fake sysfs and procfs trees describing a
// CPU topology, for tests that point ghw at them with a chroot.
package sysfsfixture

import (
"fmt"
"os"
"path/filepath"
"sort"
"strconv"
"strings"
"testing"

"github.com/zededa/ghw/pkg/util"
)

// CPU describes one logical processor. An empty string field means the
// corresponding file does not exist.
type CPU struct {
ID int
Package string // topology/physical_package_id
Core string // topology/core_id
Siblings string // topology/thread_siblings_list
// Offline CPUs are present but not online: cpuN/online is 0 and they have
// no topology, caches or frequencies, as on a real kernel.
Offline bool
Caches []Cache
BaseKHz string // cpufreq/base_frequency
MaxKHz string // cpufreq/cpuinfo_max_freq
Capacity string // cpu_capacity
}

// Cache describes one cache/indexN directory of a CPU.
type Cache struct {
Index int
Level string
Type string
ID string
Size string
Shared string // shared_cpu_list
}

// Tree describes the whole fixture.
type Tree struct {
CPUs []CPU
// Nodes maps a NUMA node to its cpulist. Nil means no node directory at
// all, as on a kernel without NUMA.
Nodes map[int]string
// PMUCore, PMUAtom and PMULowPower are the cpus files of the Intel hybrid
// core PMUs; empty means the PMU is absent.
PMUCore string
PMUAtom string
PMULowPower string
// CorePMU creates /sys/devices/cpu, the core PMU of a homogeneous part.
CorePMU bool
}

// Write writes the tree under a new temporary directory and returns it, to be
// used as the chroot.
func Write(t testing.TB, tree Tree) string {
t.Helper()
root := t.TempDir()
write := func(path, content string) {
t.Helper()
full := filepath.Join(root, path)
if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(full, []byte(content+"\n"), 0o644); err != nil {
t.Fatal(err)
}
}
optional := func(path, content string) {
if content != "" {
write(path, content)
}
}

cpuDir := "sys/devices/system/cpu"
var online, present []int
var cpuinfo strings.Builder
for _, c := range tree.CPUs {
dir := fmt.Sprintf("%s/cpu%d", cpuDir, c.ID)
present = append(present, c.ID)
if c.Offline {
write(dir+"/online", "0")
continue
}
online = append(online, c.ID)
write(dir+"/online", "1")
optional(dir+"/topology/physical_package_id", c.Package)
optional(dir+"/topology/core_id", c.Core)
optional(dir+"/topology/thread_siblings_list", c.Siblings)
optional(dir+"/cpufreq/base_frequency", c.BaseKHz)
optional(dir+"/cpufreq/cpuinfo_max_freq", c.MaxKHz)
optional(dir+"/cpu_capacity", c.Capacity)
for _, cache := range c.Caches {
idx := fmt.Sprintf("%s/cache/index%d", dir, cache.Index)
optional(idx+"/level", cache.Level)
optional(idx+"/type", cache.Type)
optional(idx+"/id", cache.ID)
optional(idx+"/size", cache.Size)
optional(idx+"/shared_cpu_list", cache.Shared)
}
fmt.Fprintf(&cpuinfo, "processor\t: %d\nvendor_id\t: GenuineTest\nmodel name\t: Test CPU\nflags\t\t: fpu\n\n", c.ID)
}
write(cpuDir+"/online", List(online))
write(cpuDir+"/present", List(present))
write(cpuDir+"/possible", List(present))
write("proc/cpuinfo", cpuinfo.String())

if tree.Nodes != nil {
nodes := make([]int, 0, len(tree.Nodes))
for n := range tree.Nodes {
nodes = append(nodes, n)
}
sort.Ints(nodes)
for _, n := range nodes {
nodeDir := fmt.Sprintf("sys/devices/system/node/node%d", n)
write(nodeDir+"/cpulist", tree.Nodes[n])
// Like the kernel, link each of the node's CPUs into its directory.
cpus, err := util.ParseCPUList(tree.Nodes[n])
if err != nil {
t.Fatal(err)
}
for _, c := range cpus {
link := filepath.Join(root, nodeDir, fmt.Sprintf("cpu%d", c))
if err := os.Symlink(fmt.Sprintf("../../cpu/cpu%d", c), link); err != nil {
t.Fatal(err)
}
}
}
}
optional("sys/devices/cpu_core/cpus", tree.PMUCore)
optional("sys/devices/cpu_atom/cpus", tree.PMUAtom)
optional("sys/devices/cpu_lowpower/cpus", tree.PMULowPower)
if tree.CorePMU {
write("sys/devices/cpu/type", "4")
}
return root
}

// List formats logical processor IDs as a comma-separated CPU list.
func List(ids []int) string {
s := make([]string, len(ids))
for i, id := range ids {
s[i] = strconv.Itoa(id)
}
return strings.Join(s, ",")
}
97 changes: 96 additions & 1 deletion pkg/cpu/cpu.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,14 @@
package cpu

import (
"encoding/json"
"fmt"
"strconv"
"strings"

"github.com/zededa/ghw/internal/config"
"github.com/zededa/ghw/pkg/marshal"
"github.com/zededa/ghw/pkg/memory"
)

// ProcessorCore describes a physical host processor core. A processor core is
Expand All @@ -20,7 +24,8 @@ type ProcessorCore struct {
// ID is the `uint32` identifier that the host gave this core. Note that
// this does *not* necessarily equate to a zero-based index of the core
// within a physical package. For example, the core IDs for an Intel Core
// i7 are 0, 1, 2, 8, 9, and 10
// i7 are 0, 1, 2, 8, 9, and 10. It is -1 where the core cannot be told;
// each such core holds a single logical processor.
ID int `json:"id"`
// TotalHardwareThreads is the number of hardware threads associated with
// the core
Expand Down Expand Up @@ -134,6 +139,40 @@ type Info struct {
// Processors is a slice of Processor struct pointers, one for each
// physical processor package contained in the host
Processors []*Processor `json:"processors"`
// LogicalProcessors describes each online logical processor, ascending by
// ID.
LogicalProcessors []*LogicalProcessor `json:"logical_processors,omitempty"`
// OfflineLogicalProcessors are the IDs of the logical processors that are
// present but offline (for example SMT turned off), ascending.
OfflineLogicalProcessors []int `json:"offline_logical_processors,omitempty"`
// Caches lists every cache instance of the online logical processors,
// with the logical processors sharing it.
Caches []*memory.Cache `json:"caches,omitempty"`
}

// LogicalProcessor describes one online logical processor (hardware thread)
// and where it sits in the host's topology. An ID that could not be read is -1,
// and a frequency the kernel does not report is 0.
type LogicalProcessor struct {
Comment thread
europaul marked this conversation as resolved.
Resolved
// ID is the logical processor ID the kernel and CPU affinities use.
ID int `json:"id"`
// ProcessorID is the physical package (socket) it belongs to, the ID of
// its Processor in Processors (unless /proc/cpuinfo does not describe the
// logical processor, which leaves it out of Processors).
ProcessorID int `json:"processor_id"`
// CoreID is the physical core it runs on, the ID of its ProcessorCore,
// unique within the package. Logical processors with the same known
// ProcessorID and CoreID are SMT siblings; two with an ID of -1 are not
// known to be.
CoreID int `json:"core_id"`
// NodeID is the NUMA node it belongs to; 0 on a kernel without NUMA.
NodeID int `json:"node_id"`
// CoreType is the class of core it runs on.
CoreType CoreType `json:"core_type"`
// BaseFrequencyKHz is its base (non-turbo) frequency.
BaseFrequencyKHz uint64 `json:"base_frequency_khz,omitempty"`
// MaxFrequencyKHz is its maximum (turbo) frequency.
MaxFrequencyKHz uint64 `json:"max_frequency_khz,omitempty"`
}

// New returns a pointer to an Info struct that contains information about the
Expand Down Expand Up @@ -189,3 +228,59 @@ func (i *Info) YAMLString() string {
func (i *Info) JSONString(indent bool) string {
return marshal.SafeJSON(cpuPrinter{i}, indent)
}

// CoreType is the class of core a logical processor runs on.
type CoreType int

const (
// CoreTypeUnknown means the host does not tell the class of the core.
CoreTypeUnknown CoreType = iota
// CoreTypePerformance is a performance core of a heterogeneous part, such
// as an Intel P-core or an ARM "big" core.
CoreTypePerformance
// CoreTypeEfficiency is an efficiency core of a heterogeneous part, such
// as an Intel E-core or an ARM "LITTLE" core.
CoreTypeEfficiency
// CoreTypeUniform is a core of a homogeneous part, where every core is of
// the same class.
CoreTypeUniform
)

var (
coreTypeString = map[CoreType]string{
CoreTypeUnknown: "unknown",
CoreTypePerformance: "performance",
CoreTypeEfficiency: "efficiency",
CoreTypeUniform: "uniform",
}
stringCoreType = map[string]CoreType{
"unknown": CoreTypeUnknown,
"performance": CoreTypePerformance,
"efficiency": CoreTypeEfficiency,
"uniform": CoreTypeUniform,
}
)

// String returns the core type's name, as it appears in JSON and YAML.
func (t CoreType) String() string {
return coreTypeString[t]
}

// MarshalJSON writes the core type as its name.
func (t CoreType) MarshalJSON() ([]byte, error) {
return []byte(strconv.Quote(t.String())), nil
}

// UnmarshalJSON reads a core type from its name.
func (t *CoreType) UnmarshalJSON(b []byte) error {
var s string
if err := json.Unmarshal(b, &s); err != nil {
return err
}
val, ok := stringCoreType[strings.ToLower(s)]
if !ok {
return fmt.Errorf("unknown core type: %q", s)
}
*t = val
return nil
}
Loading
Loading