vystem-b/docs/shelter/devs/devs.md

DevS querying

Introduction

The Device System provides a central way to query various kernel subsystems. It is defined in shelter/lib/include/devs/devs.h and implemented in shelter/lib/src/devs/devs.c.

Entry point

All DevS related API call goes through a standard entry point:

sh_devs_query(char *path,sh_devs_RESULT *result)

The result is stored inside result, which is a structure like this:

typedef struct {
  enum sh_devs_RESULT_TYPE type;
  sh_uint64 value;
} sh_devs_RESULT;

There are severals returned types:

• SH_DEVS_VALUE: a 64 bits value
• SH_DEVS_BOOL: a boolean stored inside value by casting the sh_bool to sh_uint64
• SH_DEVS_LAPIC: value should be casted to sh_lapic_DEVICE*, which points directly to a LAPIC device structure
• SH_DEVS_IOAPIC: value should be casted to sh_ioapic_DEVICE*, which points directly to a IOAPIC device structure

Each endpoint has a specific syntax, but here are the common syntax elements:

• each path starts with the $ sign
• each subsystem has its own prefix

Unless you are querying for a pointer (in this case, you can modify the value inside the pointed structure), you can't write anything in the DevS endpoints.

Endpoint categories

All the kernel subsystems that expose datas through the DevS provide a function to parse the rest of the path without the subsystem prefix once sh_devs_query() dispatched the query.

These functions aren't documented in the documentation of these subsystems and shouldn't be called directly.

LAPIC endpoints

Function:

sh_lapic_devs_query(char *sub_path,sh_devs_RESULT *result)

Prefix: $apic/lapic

Endpoints:

Path with syntax	Returned type	Description
$apic/lapic/by-apic-id/<id>	SH_DEVS_LAPIC	Return the struct of the LAPIC device correspoding to the provided LAPIC id. Can return SH_NULLPTR with a success due to sparses id
$apic/lapic/by-acpi-id/<id>	SH_DEVS_LAPIC	Return the struct of the LAPIC device correspoding to the provided ACPI processor id. Can return SH_NULLPTR with a success due to sparses id
$apic/lapic/count	SH_DEVS_VALUE	Return the number of LAPIC devices registered
$apic/lapic/timer-frequency	SH_DEVS_VALUE	Return the estimated frequency of the LAPIC timer
$apic/lapic/max-apic-id	SH_DEVS_VALUE	Return the biggest LAPIC id among all registered LAPIC devices
$apic/lapic/max-acpi-id	SH_DEVS_VALUE	Return the biggest ACPI processor id among all registered LAPIC devices
$apic/lapic/base-address	SH_DEVS_VALUE	Return the physical address of the memory mapped pages for LAPICs
$apic/lapic/this-cpu-lapic	SH_DEVS_LAPIC	Return the struct of the LAPIC device corresponding to this CPU

IOAPIC endpoints

Function:

sh_ioapic_devs_query(char *sub_path,sh_devs_RESULT *result)

Prefix: $apic/ioapic

Endpoints:

Path with syntax	Returned type	Description
$apic/ioapic/by-ioapic-id/<id>	SH_DEVS_ioAPIC	Return the struct of the IOAPIC device correspoding to the provided IOAPIC id. Can return SH_NULLPTR with a success due to sparses id
$apic/lapic/by-gsi/<gsi>	SH_DEVS_IOAPIC	Return the struct of the IOAPIC device that manages the corresponding GSI. Can return SH_NULLPTR with a success due to sparses GSI
$apic/lapic/count	SH_DEVS_VALUE	Return the number of IOAPIC devices registered
$apic/lapic/max-ioapic-id	SH_DEVS_VALUE	Return the biggest IOAPIC id among all registered IOAPIC devices

TSC endpoints

Function:

sh_tsc_devs_query(char *sub_path,sh_devs_RESULT *result)

Prefix: $tsc

Endpoints:

Path with syntax	Returned type	Description
$tsc/kernel-init-tsc	SH_DEVS_VALUE	Return the TSC value saved at the start of the kernel C entry point, before AP bootstrap
$tsc/cpu-freq	SH_DEVS_VALUE	Return the CPU frequency, either estimated or provided by CPU ID
$tsc/is-cpu-freq-provided	SH_DEVS_BOOL	Return SH_TRUE if CPU frequency is provided by CPU ID, SH_FALSE if CPU frequency is estimated

Kernel config endpoints

Function:

sh_conf_devs_query(char *sub_path,sh_devs_RESULT *result)

Prefix: $kernel/conf

Endpoints:

Path with syntax	Returned type	Description
$kernel/conf/log-level	SH_DEVS_VALUE	Return the log level of the kernel
$kernel/conf/test-benchmark	SH_DEVS_BOOL	Return the test-benchmark state, SH_TRUE if enabled
$kernel/conf/bench-iterations	SH_DEVS_VALUE	Return the amount of iterations used for benchmarking
$kernel/conf/disable-serial-port	SH_DEVS_BOOL	Return SH_TRUE if serial port is disabled, SH_FALSE otherwise
$kernel/conf/kbd-events-queue-capacity	SH_DEVS_VALUE	Return the amount of events a keyboard events queue can store

Memory subsystem endpoints

Function:

sh_memory_devs_query(char *sub_path,sh_devs_RESULT *result)

Prefix: $memory

Endpoints:

Path with syntax	Returned type	Description
$memory/free-pages	SH_DEVS_VALUE	Return the amount of free pages in the Pez physical plane
$memory/used-pages	SH_DEVS_VALUE	Return the amount of allocated pages in the Pez physical plane
$memory/total-pages	SH_DEVS_VALUE	Return the amount of physical pages detected when parsing the memory map
$memory/installed-pages	SH_DEVS_VALUE	Return the amount of pages detected usable when parsing the memory map. Can be slightly smaller than total pages

SMP endpoints

Function: integrated to sh_devs_query()

Prefix: $smp

Path with syntax	Returned type	Description
$smp/cpu-count	SH_DEVS_VALUE	Return the number of processors