intel-cmt-cat icon indicating copy to clipboard operation
intel-cmt-cat copied to clipboard
verified publisher icon intel

Add go bindings for libpqos

Open rucoder opened this issue 5 months ago • 2 comments

This PR introduces CGO bindings for libpqos library. Almost all functionality is covered except for some specialized features

NOTE This is just a draft PR to start a discussion. It may be updated as I proceed with testing

Description

The Go bindings provide complete coverage of the core PQoS API (initialization, capability detection, cache/memory allocation, monitoring) but are missing some advanced/specialized features from the C library.

Coverage: ~85% of commonly-used APIs, ~65% of total C APIs

Fully Implemented

Core Library (100%)

  • pqos_init() - Initialize library
  • pqos_fini() - Finalize library
  • pqos_cap_get() - Get capabilities
  • pqos_inter_get() - Get interface type

Capability Detection (100%)

  • pqos_cap_get_type() - Get capability by type (via HasL3CA(), HasL2CA(), etc.)
  • All capability structures (L3CA, L2CA, MBA, MON)
  • CPU topology information
  • Cache information (L2/L3)

L3 Cache Allocation (100%)

  • pqos_l3ca_set() - Set L3 CAT configuration
  • pqos_l3ca_get() - Get L3 CAT configuration
  • pqos_l3ca_get_min_cbm_bits() - Get minimum CBM bits
  • CDP support (Code/Data Prioritization)
  • Non-contiguous CBM support

L2 Cache Allocation (100%)

  • pqos_l2ca_set() - Set L2 CAT configuration
  • pqos_l2ca_get() - Get L2 CAT configuration
  • pqos_l2ca_get_min_cbm_bits() - Get minimum CBM bits
  • CDP support

Memory Bandwidth Allocation (100%)

  • pqos_mba_set() - Set MBA configuration
  • pqos_mba_get() - Get MBA configuration
  • Controller mode support
  • SMBA field support

Core/Process Association (100%)

  • pqos_alloc_assoc_set() - Associate core with COS
  • pqos_alloc_assoc_get() - Get core's COS
  • pqos_alloc_assoc_set_pid() - Associate PID with COS
  • pqos_alloc_assoc_get_pid() - Get PID's COS
  • pqos_alloc_assign() - Auto-assign COS to cores
  • pqos_alloc_release() - Release cores to default
  • pqos_alloc_assign_pid() - Auto-assign COS to PIDs
  • pqos_alloc_release_pid() - Release PIDs to default
  • pqos_alloc_reset() - Reset allocation

Resource Monitoring - Cores (100%)

  • pqos_mon_start_cores() - Start core monitoring
  • pqos_mon_stop() - Stop monitoring
  • pqos_mon_poll() - Poll monitoring data
  • pqos_mon_reset() - Reset monitoring
  • pqos_mon_assoc_get() - Get core RMID

Resource Monitoring - Processes (100%)

  • pqos_mon_start_pids2() - Start PID monitoring
  • pqos_mon_add_pids() - Add PIDs to group
  • pqos_mon_remove_pids() - Remove PIDs from group

Event Values (100%)

  • LLC occupancy
  • Local/Total/Remote memory bandwidth
  • Instructions per cycle (IPC)
  • LLC misses/references
  • Helper methods (GetIPC, GetLLCMissRate)

Partially Implemented

Capability Queries (50%)

Implemented:

  • Check if feature supported (HasL3CA, HasMBA, etc.)
  • Get capability details (GetL3CA, GetMBA, etc.)

Missing:

  • pqos_l3ca_get_cos_num() - Get number of COS
  • pqos_l2ca_get_cos_num() - Get number of COS
  • pqos_mba_get_cos_num() - Get number of COS
  • pqos_smba_get_cos_num() - Get number of COS
  • pqos_l3ca_cdp_enabled() - Check CDP status
  • pqos_l2ca_cdp_enabled() - Check CDP status
  • pqos_mba_ctrl_enabled() - Check MBA controller status
  • pqos_l3ca_iordt_enabled() - Check I/O RDT status
  • pqos_cap_get_event() - Get monitoring event details

Workaround: These can be accessed via capability structures, e.g., l3ca.NumClasses, l3ca.CDPOn

Not Implemented

I/O RDT - Device/Channel Monitoring (0%)

  • pqos_mon_start_channels() - Monitor I/O channels
  • pqos_mon_start_dev() - Monitor specific device
  • pqos_mon_assoc_get_channel() - Get channel RMID
  • pqos_mon_assoc_get_dev() - Get device RMID
  • Channel and device structures

Impact: Cannot monitor I/O RDT devices (PCIe, etc.)

I/O RDT - Device Allocation (0%)

  • pqos_alloc_assoc_set_channel() - Associate channel with COS
  • pqos_alloc_assoc_get_channel() - Get channel's COS
  • pqos_alloc_assoc_set_dev() - Associate device with COS
  • pqos_alloc_assoc_get_dev() - Get device's COS

Impact: Cannot allocate resources to I/O devices

Uncore Monitoring (0%)

  • pqos_mon_start_uncore() - Monitor uncore/socket level

Impact: Cannot do socket-level monitoring, only core/process

Advanced Configuration (0%)

  • pqos_sysconfig_get() - Get system configuration
  • pqos_mon_reset_config() - Reset with config
  • pqos_alloc_reset_config() - Reset allocation with config
  • Configuration structures (pqos_sysconfig, pqos_mon_config, pqos_alloc_config)

Impact: Cannot use advanced reset/configuration options

CPU Topology Helpers (0%)

  • pqos_cpu_get_one_by_mba_id() - Get core by MBA ID
  • pqos_cpu_get_one_by_smba_id() - Get core by SMBA ID
  • pqos_cpu_get_one_core() - Get one core from socket
  • pqos_cpu_get_one_by_numaid() - Get core by NUMA ID
  • pqos_cpu_get_one_by_l3cat_id() - Get core by L3 CAT ID
  • pqos_cpu_get_one_by_l2id() - Get core by L2 ID
  • pqos_cpu_check_core() - Check if core is valid
  • pqos_cpu_get_socketid() - Get socket ID for core
  • pqos_cpu_get_numaid() - Get NUMA ID for core
  • pqos_cpu_get_clusterid() - Get cluster ID for core

Impact: Need to manually search core arrays Workaround: Use CPUInfo methods like FindCore(), GetCoresBySocket()

Monitoring Value Helpers (0%)

  • pqos_mon_get_value() - Get specific event value
  • pqos_mon_get_ipc() - Get IPC value

Impact: Minor - values accessible via MonData.Values struct Workaround: Use MonData.GetIPC(), MonData.Values.LLC, etc.

Deprecated Functions (Intentionally Skipped)

  • pqos_mon_start() - Deprecated, use pqos_mon_start_cores()
  • pqos_mon_start_pid() - Deprecated, use pqos_mon_start_pids2()
  • pqos_mon_start_pids() - Deprecated, use pqos_mon_start_pids2()

Missing Structs/Types

Not Implemented

  • pqos_sysconfig - System configuration
  • pqos_devinfo - Device information
  • pqos_dev - Device structure
  • pqos_channel - Channel structure
  • pqos_mon_config - Monitoring configuration
  • pqos_alloc_config - Allocation configuration
  • pqos_channel_t - Channel ID type

Affected parts

  • [ ] library
  • [ ] pqos utility
  • [ ] rdtset utility
  • [x] other: introduce Go bindings

Motivation and Context

These bindings are required to add a support for Intel RTD technologies into EVE OS https://github.com/lf-edge/eve

How Has This Been Tested?

The test is ongoing. This is a draft PR to start a discussion

Types of changes

  • [ ] Bug fix (non-breaking change which fixes an issue)
  • [x] New feature (non-breaking change which adds functionality)
  • [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

  • [ ] My code follows the code style of this project.
  • [x] My change requires a change to the documentation. - maybe yes
  • [ ] I have updated the documentation accordingly.

rucoder avatar Nov 14 '25 10:11 rucoder

Hi Michael, Thanks for the contribution! This is quite interesting. We are reviewing and will get back to you soon. Thanks, ~Andrew

ajherdri avatar Nov 21 '25 16:11 ajherdri

Hi Michael, Update -- We are interested in supporting, and we would like to discuss the long-term support model for this code, we will set up a calendar invite to discuss in early December. Thanks! ~Andrew

ajherdri avatar Nov 24 '25 17:11 ajherdri