system/serenity
system/serenity
1
0
Fork 0
mirror of https://github.com/SerenityOS/serenity synced 2024-09-06 17:06:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Base: Add 2 manual pages to describe the ProcFS and SysFS

Browse source
This commit is contained in:
Liav A 2021-09-24 06:21:03 +03:00 committed by Andreas Kling
parent 5098cd22a4
commit e84c03ad61
2 changed files with 125 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

73
Base/usr/share/man/man7/proc.md Normal file
View file

@ -0,0 +1,73 @@
## Name
proc - SerenityOS ProcFS
## Description
The kernel can expose process related information in /proc.
This functionality is used by various userland programs.
Most of the output layout in the ProcFS nodes is JSON.
### Global entries
* **`all`** - this node exports a list of all processes that currently exist.
* **`cmdline`** - this node exports the kernel boot commandline that was passed to
from the bootloader.
* **`cpuinfo`** - this node exports information on the CPU.
* **`devices`** - this node exports information on all devices that might be represented
by a device file.
* **`df`** - this node exports information on mounted filesystems and basic statistics on
them.
* **`dmesg`** - this node exports information from the kernel log.
* **`interrupts`** - this node exports information on all IRQ handlers and basic statistics on
them.
* **`kernel_base`** - this node reveals the loading address of the kernel.
* **`keymap`** - this node exports information on current used keymap.
* **`memstat`** - this node exports statistics on memory allocation in the kernel.
* **`pci`** - this node exports information on all currently-discovered PCI devices in the system.
### `net` directory
* **`adapters`** - this node exports information on all currently-discovered network adapters.
* **`arp`** - this node exports information on the kernel ARP table.
* **`local`** - this node exports information on local (unix) sockets.
* **`tcp`** - this node exports information on tcp sockets.
* **`udp`** - this node exports information on udp sockets.
### `sys` directory
This subdirectoy includes global settings of the kernel.
* **`caps_lock_to_ctrl`** - this node controls remapping of of caps lock to the Ctrl key.
* **`kmalloc_stacks`** - this node controls whether to send information about kmalloc to debug log.
* **`ubsan_is_deadly`** - this node controls the deadliness of the kernel undefinied behavior
sanitizer errors.
### Per process entries
* **`cwd`** - a symbolic link to current work directory of a process.
* **`exe`** - a symbolic link to the executable binary of the process.
* **`fds`** - this node exports information on all currently open file descriptors.
* **`fd`** - this directory lists all currently open file descriptors.
* **`perf_events`** - this node exports information being gathered during a profile on a process.
* **`pledge`** - this node exports information on all the pledge requests and promises of a process.
* **`stacks`** - this directory lists all stack traces of process threads.
* **`pledge`** - this node exports information on all the unveil requests of a process.
* **`vm`** - this node exports information on virtual memory mappings of a process.
### Consistency and stability of data across multiple read operations
When opening a data node, the kernel generates the required data so it's prepared
for read operation when requested to. However, in order to ensure that multiple reads
will not create a corrupted data from that data node, a read operation alone will
not inquire the kernel to refresh the data.
To keep data output being refreshed, the userland has to re-open the data node with a
new file descriptor, or to perform the `lseek` syscall on the open file descriptor to
reset the the offset to 0.
## See also
* [`mount`(2))](../man2/mount.md).
* [`boot_parameters`(7))](boot_parameters.md).
* [`pledge`(2))](../man2/pledge.md).
* [`unveil`(2))](../man2/unveil.md).

52
Base/usr/share/man/man7/sys.md Normal file
View file

@ -0,0 +1,52 @@
## Name
sys - SerenityOS SysFS
## Description
The kernel can expose system (kernel, firmware and hardware) related information in /sys.
### `bus` directory
This directory include a subdirectory for each discovered and registered bus in the system.
Possible busses to be exposed in this directory are:
1. The `pci` subdirectory that includes all discovered PCI devices as subdirectories.
The subdirectories of the PCI devices include files with basic information on the devices.
2. The `usb` subdirectory that includes all discovered USB devices as files.
The files of the USB devices export basic information on the devices.
### `dev` directory
This directory include two subdirectories - `block` and `char`, each for block
and character devices respectively. The files in these subdirectories are not
device files, but merely a file with filename layout of "major:minor", to aid
userspace in generating the appropriate device files.
### `firmware` directory
This directory include two subdirectories - `acpi` and `bios`.
The `bios` subdirectory maintains files of the exposed SMBIOS blobs, if present
by the firmware.
The `acpi` subdirectory maintains files of the exposed ACPI tables, if present
by the firmware.
A file called `power_state` is responsible for power state switching.
#### `power_state`
This file only responds to write requests on it. A written value of `1` results
in system reboot. A written value of `2` results in system shutdown.
### Consistency and stability of data across multiple read operations
When opening a data node, the kernel generates the required data so it's prepared
for read operation when requested to. However, in order to ensure that multiple reads
will not create a corrupted data from that data node, a read operation alone will
not inquire the kernel to refresh the data.
To keep data output being refreshed, the userland has to re-open the data node with a
new file descriptor, or to perform the `lseek` syscall on the open file descriptor to
reset the the offset to 0.
## See also
* [`mount`(2))](../man2/mount.md).