Merge branch 'main' of github.com:betrusted-io/xous-core into main

This commit is contained in:
bunnie 2023-02-20 17:11:17 +08:00
commit ecf2cf2a7e

View file

@ -1,3 +1,7 @@
This section has been superceded by the [Xous Book chapter on Arguments](https://betrusted.io/xous-book/ch05-01-arguments.html)
The contents here are historical, and not normative.
# 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
@ -35,6 +39,7 @@ The `XArg` block **must** be first.
| 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.
| IniF | Same as IniE, except laid out on disk such that the sub-page address offsets correspond 1:1 with the virtual memory representation, allowing an execute in place (XIP) mapping of code into the virtual memory space.
### XArg
@ -67,10 +72,18 @@ of data.
Extra memory regions. See [memory.md](memory.md) for more information.
### IniE
### IniE & IniF
The `IniE` argument describes how to load initial processes. It has the
following values:
The `IniE` argument describes how to load initial processes. 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. Thus when printed as `u32`, an IniE/F argument has this structure:
```
0xJJJJ_JJJJ 0KK_LLLLLL
```
Where `J` is the offset, `K` is the flag, and `L` is the size. There are about
7 pairs of these, one corresponding to each section of the MiniElf:
* LOAD_OFFSET -- Position in RAM relative to the start of the arguments
block where this program is stored, or an absolute value if `ABSOLUTE`
@ -87,21 +100,18 @@ following values:
* 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
| Bit | Binary | Name | Description
| ------ | ----------- | ---------- | ---------------------------------------------
| 0 | 0b000001 | NOCOPY | No data should be copied -- useful for `.bss`
| 1 | 0b000010 | WRITABLE | Region will be allocated with the "W" bit
| 2 | 0b000100 | READABLE | Region will be allocated with the "R" bit
| 3 | 0b001000 | EXECUTABLE | Region will be allocated with the "X" bit
| 4 | 0b010000 | EH_FLAG | Region is an EH_FLAG region
| 5 | 0b100000 | EH_FLAG_HDR | Region is an EH_FLAG_HEADER region
Programs **cannot** access the final four megabytes, as this memory
is reserved for the kernel.