mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-04 04:27:34 +00:00
2e4fb672ab
The `PNam` tag stores information in the kernel about process names. This can be used at runtime to discover what process maps to what program name. Signed-off-by: Sean Cross <sean@xobs.io>
139 lines
6.3 KiB
Markdown
139 lines
6.3 KiB
Markdown
# Xous Arguments
|
|
|
|
Xous arguments are automatically generated by [tools/src/bin/create-image.rs](https://github.com/betrusted-io/xous-core/blob/master/tools/src/bin/create-image.rs). Most
|
|
parameters are extracted from the soc.svd file provided to the builder script.
|
|
|
|
Xous arguments are passed by giving a page-aligned address pointed to
|
|
by register `$a0`. This uses IFF-style tags with the following format:
|
|
|
|
```rust
|
|
struct Tag {
|
|
/// Ascii-printable name, not null-terminated, in little endian format.
|
|
tag: u32,
|
|
|
|
/// CRC16 of the data section, using CCITT polynomial.
|
|
crc16: u16,
|
|
|
|
/// Size of the data section, in 4-byte words.
|
|
size: u16,
|
|
}
|
|
```
|
|
|
|
The size is in little endian byte order, and does not include the 8
|
|
bytes describing the tag type or the size. The data must be padded to
|
|
4-bytes, so the `size` field is in 4-byte words. That is, a tag with
|
|
four bytes of contents would have a `size` of `1`.
|
|
|
|
The `XArg` block **must** be first.
|
|
|
|
## Tag Types
|
|
|
|
| Tag | Description
|
|
| ---- | ------------
|
|
| XArg | Xous Args. This indicates the size of the entire block (including the XArg tag and size), as well as the user RAM area, and can be used to determine how many pages to save for this block. This must be the first argument.
|
|
| BFlg | Bootloader config flags.
|
|
| MREx | Extra memory ranges. This is a series of offset/size pairs indicating additional memory regions in the system beyond RAM, as well as a code name for the memory page. It does not include system RAM.
|
|
| XKrn | Kernel source specification. Includes the offset of the kernel in RAM as well as its size. Does not need to be page-aligned, unless NO_COPY is 1.
|
|
| IniE | Initial program specification, based on a degenerate ELF header. This includes the load offset of the binary, as well as the size of each section. Does not need to be page-aligned unless NO_COPY is 1. May appear more than once, for each of the initial processes.
|
|
|
|
### XArg
|
|
|
|
The overall size of the argument block. This must come first. This tag
|
|
has four words of contents, which is the number of words of data plus
|
|
the system memory definition. Therefore, a minimum boot tag structure
|
|
would have an `XArg` size of 5: One word for the tag, one for the
|
|
crc+size, and four for the contents of the `XArg` region.
|
|
|
|
| Offset | Size | Name | Description
|
|
| ------- | ---- | --------- | -----------
|
|
| 0 | 4 | Arg Size | The size of the entire args structure, including all headers, but excluding any trailing data (such as executables)
|
|
| 4 | 4 | Version | Version of the XArg structure. Currently `1`.
|
|
| 8 | 4 | RAM Start | The origin of system RAM, in bytes
|
|
| 12 | 4 | RAM Size | The size of system RAM, in bytes
|
|
| 16 | 4 | RAM Name | A printable name for system RAM
|
|
|
|
### Bflg
|
|
|
|
This configures various bootloader flags. It consists of a single word
|
|
of data.
|
|
|
|
* 0x00000001 `NO_COPY` -- Skip copying data to RAM.
|
|
* 0x00000002 `ABSOLUTE` -- All program addresses are absolute.
|
|
Otherwise, they're relative to the start of the config block.
|
|
* 0x00000004 `DEBUG` -- Allow the kernel to access memory inside user
|
|
programs, which allows a debugger to run in the kernel.
|
|
|
|
### MREx
|
|
|
|
Extra memory regions. See [memory.md](memory.md) for more information.
|
|
|
|
### IniE
|
|
|
|
The `IniE` argument describes how to load initial processes. It has the
|
|
following values:
|
|
|
|
* LOAD_OFFSET -- Position in RAM relative to the start of the arguments
|
|
block where this program is stored, or an absolute value if `ABSOLUTE`
|
|
is `1`.
|
|
* ENTRYPOINT - Virtual memory address of the `_start()` function
|
|
* SECTION1_OFFSET -- Virtual memory address of the first memory section
|
|
* SECTION1_SIZE -- Size of the first memory section
|
|
* SECTION1_FLAGS -- Flags describing the first memory section
|
|
* SECTION2_OFFSET -- Virtual memory address of the second memory section
|
|
* SECTION2_SIZE -- Size of the second memory section
|
|
* SECTION2_FLAGS -- Flags describing the second memory section
|
|
* ...
|
|
* SECTIONn_OFFSET -- Virtual memory address of the `nth` memory section
|
|
* SECTIONn_SIZE -- Size of the `nth` memory section
|
|
* SECTIONn_FLAGS -- Flags describing the `nth` memory section
|
|
|
|
The fields `size`, `flags`, and `offset` occupy 64 bits (8 bytes). The
|
|
`OFFSET` is a full 32-bit address. The `SIZE` field is in units of
|
|
bytes, however as it is only 24 bits, meaning the largest section size
|
|
is `2^24` bytes.
|
|
|
|
The `FLAGS` field contains the following four bits. Any region may be
|
|
marked NOCOPY, however RISC-V does not allow regions to be marked
|
|
"Write-only":
|
|
|
|
| Bit | Binary | Name | Description
|
|
| ------ | --------- | ---------- | ---------------------------------------------
|
|
| 0 | 0b0001 | NOCOPY | No data should be copied -- useful for `.bss`
|
|
| 1 | 0b0010 | WRITABLE | Region will be allocated with the "W" bit
|
|
| 2 | 0b0100 | READABLE | Region will be allocated with the "R" bit
|
|
| 3 | 0b1000 | EXECUTABLE | Region will be allocated with the "X" bit
|
|
|
|
Programs **cannot** access the final four megabytes, as this memory
|
|
is reserved for the kernel.
|
|
|
|
### XKrn
|
|
|
|
This describes the kernel image. This image will get mapped into every
|
|
process within the final 4 megabytes, and therefore the text and data
|
|
offsets must be in the range `0xffc0_0000` - `0xfff0_0000`.
|
|
|
|
* LOAD_OFFSET -- Physical address (or offset) where the kernel is stored
|
|
* TEXT_OFFSET -- Virtual memory address where the kernel expects the
|
|
program image to live. This should be `0xffd00000`
|
|
* TEXT_SIZE -- Size of the text section. This indicates how many bytes
|
|
to copy from the boot image.
|
|
* DATA_OFFSET -- Virtual memory address where the kernel expects the
|
|
.data/.bss section to be. This should be above `0xffd00000` and below
|
|
`0xffe00000`
|
|
* DATA_SIZE -- Size of the .data section
|
|
* BSS_SIZE -- The size of the .bss section, which immediately follows .data
|
|
* ENTRYPOINT -- Virtual address of the `_start()` function
|
|
|
|
The kernel will run in Supervisor mode, and have its own private stack.
|
|
|
|
### PNam
|
|
|
|
`PNam` maps process IDs to process names. If multiple `PNam` tags exist
|
|
within a block, the first one that is encountered should take precedence.
|
|
This tag is a series of entries that take the following format:
|
|
|
|
| Size (bytes) | Name | Description
|
|
| --------- | ---- | -----
|
|
| 4 | PID | ID of the process that this name describes
|
|
| 4 | Length | The length of the data that follows
|
|
| varies | Data | The UTF-8 name string
|