143 lines
5.8 KiB
Markdown
143 lines
5.8 KiB
Markdown
# 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:
|
|
``` C
|
|
sh_devs_query(char *path,sh_devs_RESULT *result)
|
|
```
|
|
|
|
The result is stored inside `result`, which is a structure like this:
|
|
``` C
|
|
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:
|
|
``` C
|
|
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:
|
|
``` C
|
|
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:
|
|
``` C
|
|
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:
|
|
``` C
|
|
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:
|
|
``` C
|
|
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
|