worldbuilding/ain48
1
0
Fork 0
Code

docs: fix typos and punctuation errors, run formatter

Browse Source 
Signed-off-by: Annwan <annwan@annwan.me>
This commit is contained in:
cinthyr
2026-06-01 23:48:10 +07:00
committed by Annwan
parent bd58085d9e
commit 6ccbe2fdbf
1 changed files with 76 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
docs/ucsd_abi.typ
View File

@ -1,7 +1,9 @@
#import ".template.typ": *
#show: conf
#show regex("[\u{e3e0}-\u{e3ff}]+(\s+[\u{e3e0-\u{e3ff}]+)*"): text.with(font: "AndikaAmbNaran")
#show regex("[\u{e3e0}-\u{e3ff}]+(\s+[\u{e3e0-\u{e3ff}]+)*"): text.with(
font: "AndikaAmbNaran",
)
#show raw.where(block: true): block.with(breakable: false)
#title[Unichal Software Distribution System ABI\ Version 3.4 for AIN-48]
@ -9,18 +11,19 @@
= The RIM file format
The RIM#footnote[
   --- Rainsihen Iehanac Móscirts --- Computer
Instruction Format
] format is the format used by UCSD to encode machine code object files and executables.. It is defined as follows. where each box represents a byte, in execution order.
All numbers bigger than a byte are represented in little endian.
   --- Rainsihen Iehanac Móscirts --- Computer
Instruction Format
] format is the format used by UCSD to encode machine code object files and executables.
It is defined as follows.
All numbers bigger than a byte are represented in little-endian.
The sizes of the types are as follows:
/ ```struct byte```: 12 bit
/ ```struct hword```: 24 bit
/ ```struct word```: 48 bit
All numbers are unsigned
/ ```struct byte```: 12 bits
/ ```struct hword```: 24 bits, or 2 bytes
/ ```struct word```: 48 bits, or 4 bytes
All numbers are unsigned.
== RIM Header
Placed at the start of the file, it identifies the file as a RIM object and contains some additional flags
Placed at the start of the file, it identifies the file as a RIM object and contains some additional flags.
```struct
enum PLATFORM as hword:
@ -52,7 +55,7 @@ Placed at the file offset indicated by `index_address` in the header, the sectio
```struct
enum SEC_TYPE as byte:
RO_DATA = 0 % Data to be copied into non-executable read-only memory
CODE = 1 % Data to be copied into executable read-only of memory
CODE = 1 % Data to be copied into executable read-only memory
RW_DATA = 2 % Data to be copied into non-executable read-write memory
RW_CODE = 3 % Data to be copied into executable read-write memory
SYMBOLS_INTERNAL = 4 % Table listing all the linkable symbols of
@ -88,7 +91,7 @@ struct DATA_SECTION:
```
== Symbol tables
The symbol tables contains data about the linkable symbols of the object
The symbol tables contain data about the linkable symbols of the object.
```struct
struct SYMBOL_TABLE:
hword count
@ -100,9 +103,9 @@ struct SYMBOL_TABLE_ENTRY:
% referencing the name of the symbol
hword string_section
hword string_number
% For internal symbol tables: the section and offset refering to the
% For internal symbol tables: the section and offset referring to the
% symbol. For external symbol tables: the section and offset where
% the adress for that symbol needs to be replaced. If a symbol needs
% the address for that symbol needs to be replaced. If a symbol needs
% to be linked between two data sections of the object, have it be
% present in both the internal and external tables.
hword data_section
@ -123,7 +126,7 @@ The contents of debug tables is platform-specific.
/ TODO: Write the debug info format for UCSD eventually™
== Meta
The meta section contains additional metadata about the file
The meta section contains additional metadata about the file.
```struct
struct META_TABLE:
@ -136,7 +139,7 @@ struct META_ENTRY:
union META_VALUE val
```
```struct
union META_VALUE: % varient depends on meta entry type
union META_VALUE: % variant depends on meta entry type
struct META_VALUE_STRING string_value
word int_value
```
@ -148,19 +151,19 @@ struct META_VALUE_STRING:
```struct
enum META_ENTRY_TYPE as hword:
ENTRY_POINT = 0 % Kind: int_value, only useful when the file is said to
% be executable, gives the entry point for the program
% be executable, gives the entry point for the program.
DYNAMIC_LINKER = 1 % Kind: string_value, the name of the dynamic linker
% in charge of resolving the symbols upon load of
% theobject, only useful if the SHARED flag is set.
HASH = 2 % Kind: string_value, a hash against which to verify the
% integrity of the object file, suported algorithms depend on
% the linker used. the string is of the format
% integrity of the object file. Supported algorithms depend on
% the linker used. The string is of the format
% `algorithm:octal-dump-of-hash`
% META_ENTRY_TYPEs between 1000 0000 and 3777 7777 (inclusive) are
% reserved for platform-specific information. Here are the ones for
% UCSD 3.4
UCSD_APPLICATION_NAME = 1000 0000 % Kind: string_value user facing name
UCSD_APPLICATION_NAME = 1000 0000 % Kind: string_value, user-facing name
% of the application
UCSD_ICON_DATA_SYM = 1000 0001 % Kind: string_value, name of a symbol
% referencing bitmap image data for an
@ -172,7 +175,7 @@ enum META_ENTRY_TYPE as hword:
% be specified, the system will make use of the first one that resolves
% to a usable image.
% META_ENTRY_TYPEs greater or equal to 4000 0000 are reserved for
% META_ENTRY_TYPEs greater or equal to 4000 0000 are reserved for
% private use by external tooling and are not specified in this
% document
```
@ -180,36 +183,38 @@ enum META_ENTRY_TYPE as hword:
= Representation of types
== Integers
#block(breakable: false)[This ABI defines 6 integer types: `u12`, `u24` and `u48` which are unsigned 12, 24 and 48 bit integers, as well as `i12`, `i24` and `i48` which are signed (by the two's complement method) 12, 24 and 48 bit integers.
#block(
breakable: false,
)[This ABI defines 6 integer types: `u12`, `u24` and `u48` which are unsigned 12, 24 and 48 bit integers, as well as `i12`, `i24` and `i48` which are signed (by the two's complement method) 12, 24 and 48 bit integers.
#grid(columns: (1fr, 1fr), row-gutter: .65em)[
/ `u12`: Unsigned 12-bit integer
/ Storage size: 1 byte
/ Alignment: 1 byte
][
/ `i12`: Signed 12-bit integer
/ Storage size: 1 byte
/ Alignment: 1 byte
][
/ `u24`: Unsigned 24-bit integer
/ Storage size: 2 bytes
/ Alignment: 2 bytes
][
/ `i24`: Signed 24-bit integer
/ Storage size: 2 bytes
/ Alignment: 2 bytes
][
/ `u48`: Unsigned 48-bit integer
/ Storage size: 4 bytes
/ Alignment: 4 bytes
][
/ `i48`: Signed 48-bit integer
/ Storage size: 4 bytes
/ Alignment: 4 bytes
]]
#grid(columns: (1fr, 1fr), row-gutter: .65em)[
/ `u12`: Unsigned 12-bit integer
/ Storage size: 1 byte
/ Alignment: 1 byte
][
/ `i12`: Signed 12-bit integer
/ Storage size: 1 byte
/ Alignment: 1 byte
][
/ `u24`: Unsigned 24-bit integer
/ Storage size: 2 bytes
/ Alignment: 2 bytes
][
/ `i24`: Signed 24-bit integer
/ Storage size: 2 bytes
/ Alignment: 2 bytes
][
/ `u48`: Unsigned 48-bit integer
/ Storage size: 4 bytes
/ Alignment: 4 bytes
][
/ `i48`: Signed 48-bit integer
/ Storage size: 4 bytes
/ Alignment: 4 bytes
]]
== Booleans
Booleans are represented as `u12`s where 0 is false and any non-zero value (but canonically 7777) is true.
Booleans are represented as `u12`s, where 0 is false and any non-zero value (but canonically 7777) is true.
== Strings
Strings are represented by pointers to a `u12`, followed by that number of bytes of data representing the contents of the string.
@ -219,37 +224,37 @@ Strings are represented by pointers to a `u12`, followed by that number of bytes
== Parameter passing
Parameters are expanded to take a full word and are placed in order:
#columns(2)[
+ in ```ain48 %01```
+ in ```ain48 %02```
+ in ```ain48 %03```
+ in ```ain48 %04```
#colbreak()
5. in ```ain48 %05```
+ in ```ain48 %06```
+ in ```ain48 %07```
+ pushed on the stack, with the 8#super[th] argument at the lowest adress and the last argument at the highest address.
+ in ```ain48 %01```
+ in ```ain48 %02```
+ in ```ain48 %03```
+ in ```ain48 %04```
#colbreak()
5. in ```ain48 %05```
+ in ```ain48 %06```
+ in ```ain48 %07```
+ pushed on the stack, with the 8#super[th] argument at the lowest address and the last argument at the highest address.
]
Arguments placed on the stack are placed starting at the word with the adress immediately higher to that of the return adress.
Arguments placed on the stack are placed starting at the word with the address immediately higher to that of the return adress.
== Return value passing
The return value is to be placed in ```ain48 %01```.
== Clobbering
Registers ```ain48 %01```, ```ain48 %02```, ```ain48 %03```, ```ain48 %04```, ```ain48 %05```,
```ain48 %06``` and ```ain48 %07``` may freely be clobbered by the invokee. It is the responsability of the invoker to save them if it is desired to keep their value. Registers ```ain48 %10```, ```ain48 %11```, ```ain48 %12```, ```ain48 %13```, ```ain48 %14```, ```ain48 %15```, ```ain48 %16``` and ```ain48 %it``` must be returned to the invoker in the same state they were upon call. It is the responsability of the invokee to save them if they are needed for other uses.
```ain48 %06``` and ```ain48 %07``` may freely be clobbered by the invokee. It is the responsability of the invoker to save them if it is desired to keep their value. Registers ```ain48 %10```, ```ain48 %11```, ```ain48 %12```, ```ain48 %13```, ```ain48 %14```, ```ain48 %15```, ```ain48 %16``` and ```ain48 %it``` must be returned to the invoker in the same state they were upon call. It is the responsibility of the invokee to save them if they are needed for other uses.
== Invocation Sequence
+ The invoker pushes all the registers it needs saved to the stack
+ The invoker pushes the stack arguments to the stack
+ The invoker loads the registers with the register arguments
+ The register executes the ```ain48 IVC``` instruction. This pushes the return adress to the stack and transfers control flow to the invokee
+ The register executes the ```ain48 IVC``` instruction. This pushes the return address to the stack and transfers control flow to the invokee.
+ The invokee allocates its local variables on top of the stack.
+ The invokee saves any register it needs to prevent the clobering of.
+ The invokee run its course
+ The invokee saves any register it needs to prevent the clobbering of.
+ The invokee runs its course
+ The invokee restores the registers
+ The invokee frees it’s local variables
+ The invokee loads it’s return value into ```ain48 %01```
+ The invokee runs the ```ain48 RV``` instruction. This pops the return adress off the stack and transfers control flow back to the invoker
+ The invokee frees its local variables
+ The invokee loads its return value into ```ain48 %01```
+ The invokee runs the ```ain48 RV``` instruction. This pops the return address off the stack and transfers control flow back to the invoker.
+ The invoker frees the stack arguments.
+ The invoker restores the registers it pushed
@ -269,23 +274,21 @@ _init: CST %02 ; 1. Push registers to be saved
ILG %02, arg8 ; 2. Push 8th argument
LG %02, (%02)
CST %02
ILG %01, #o1 ; 3. Load Register arguments
ILG %01, #o1 ; 3. Load register arguments
...
ILG %07, #o7
IVC res ; 4. Transfer to the invokee
PADD %it, #o10 ; 12. Free the 2 words of stack arguments
DST %02 ; 13. Restor the saved register
DST %02 ; 13. Restore the saved register
res: PSTR %it, #o14 ; 5. Allocate local variables (here 3 words)
CST %10 ; 6. Save invoker-safe registers
... ; 7. Foo does whatever it does
DST %10 ; 8. The invokee retores the invoker-safe
; registers
... ; 7. Res does whatever it does
DST %10 ; 8. Restore the invoker-safe registers
PADD %it, #o14 ; 9. Free the local variables
; 10. Assuming that foo has already put it’s
; 10. Assuming that res has already put its
; return value in %01
RV ; 11. Transfer back to the invoker
```
= Kernel invocation convention