Vystem 0.2

docs/shelter/devs/devs.md

@@ -0,0 +1,142 @@
+# 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