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

117
docs/ucsd_abi.typ
View File

@ -1,7 +1,9 @@
#import ".template.typ": * #import ".template.typ": *
#show: conf #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) #show raw.where(block: true): block.with(breakable: false)
#title[Unichal Software Distribution System ABI\ Version 3.4 for AIN-48] #title[Unichal Software Distribution System ABI\ Version 3.4 for AIN-48]
@ -11,16 +13,17 @@
The RIM#footnote[ The RIM#footnote[
   --- Rainsihen Iehanac Móscirts --- Computer    --- Rainsihen Iehanac Móscirts --- Computer
Instruction Format 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. ] format is the format used by UCSD to encode machine code object files and executables.
All numbers bigger than a byte are represented in little endian. It is defined as follows.
All numbers bigger than a byte are represented in little-endian.
The sizes of the types are as follows: The sizes of the types are as follows:
/ ```struct byte```: 12 bit / ```struct byte```: 12 bits
/ ```struct hword```: 24 bit / ```struct hword```: 24 bits, or 2 bytes
/ ```struct word```: 48 bit / ```struct word```: 48 bits, or 4 bytes
All numbers are unsigned All numbers are unsigned.
== RIM Header == 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 ```struct
enum PLATFORM as hword: enum PLATFORM as hword:
@ -52,7 +55,7 @@ Placed at the file offset indicated by `index_address` in the header, the sectio
```struct ```struct
enum SEC_TYPE as byte: enum SEC_TYPE as byte:
RO_DATA = 0 % Data to be copied into non-executable read-only memory 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_DATA = 2 % Data to be copied into non-executable read-write memory
RW_CODE = 3 % Data to be copied into 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 SYMBOLS_INTERNAL = 4 % Table listing all the linkable symbols of
@ -88,7 +91,7 @@ struct DATA_SECTION:
``` ```
== Symbol tables == 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
struct SYMBOL_TABLE: struct SYMBOL_TABLE:
hword count hword count
@ -100,9 +103,9 @@ struct SYMBOL_TABLE_ENTRY:
% referencing the name of the symbol % referencing the name of the symbol
hword string_section hword string_section
hword string_number 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 % 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 % to be linked between two data sections of the object, have it be
% present in both the internal and external tables. % present in both the internal and external tables.
hword data_section hword data_section
@ -123,7 +126,7 @@ The contents of debug tables is platform-specific.
/ TODO: Write the debug info format for UCSD eventually™ / TODO: Write the debug info format for UCSD eventually™
== Meta == Meta
The meta section contains additional metadata about the file The meta section contains additional metadata about the file.
```struct ```struct
struct META_TABLE: struct META_TABLE:
@ -136,7 +139,7 @@ struct META_ENTRY:
union META_VALUE val union META_VALUE val
``` ```
```struct ```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 struct META_VALUE_STRING string_value
word int_value word int_value
``` ```
@ -148,19 +151,19 @@ struct META_VALUE_STRING:
```struct ```struct
enum META_ENTRY_TYPE as hword: enum META_ENTRY_TYPE as hword:
ENTRY_POINT = 0 % Kind: int_value, only useful when the file is said to 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 DYNAMIC_LINKER = 1 % Kind: string_value, the name of the dynamic linker
% in charge of resolving the symbols upon load of % in charge of resolving the symbols upon load of
% theobject, only useful if the SHARED flag is set. % theobject, only useful if the SHARED flag is set.
HASH = 2 % Kind: string_value, a hash against which to verify the HASH = 2 % Kind: string_value, a hash against which to verify the
% integrity of the object file, suported algorithms depend on % integrity of the object file. Supported algorithms depend on
% the linker used. the string is of the format % the linker used. The string is of the format
% `algorithm:octal-dump-of-hash` % `algorithm:octal-dump-of-hash`
% META_ENTRY_TYPEs between 1000 0000 and 3777 7777 (inclusive) are % META_ENTRY_TYPEs between 1000 0000 and 3777 7777 (inclusive) are
% reserved for platform-specific information. Here are the ones for % reserved for platform-specific information. Here are the ones for
% UCSD 3.4 % 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 % of the application
UCSD_ICON_DATA_SYM = 1000 0001 % Kind: string_value, name of a symbol UCSD_ICON_DATA_SYM = 1000 0001 % Kind: string_value, name of a symbol
% referencing bitmap image data for an % referencing bitmap image data for an
@ -180,36 +183,38 @@ enum META_ENTRY_TYPE as hword:
= Representation of types = Representation of types
== Integers == 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)[ #grid(columns: (1fr, 1fr), row-gutter: .65em)[
/ `u12`: Unsigned 12-bit integer / `u12`: Unsigned 12-bit integer
/ Storage size: 1 byte / Storage size: 1 byte
/ Alignment: 1 byte / Alignment: 1 byte
][ ][
/ `i12`: Signed 12-bit integer / `i12`: Signed 12-bit integer
/ Storage size: 1 byte / Storage size: 1 byte
/ Alignment: 1 byte / Alignment: 1 byte
][ ][
/ `u24`: Unsigned 24-bit integer / `u24`: Unsigned 24-bit integer
/ Storage size: 2 bytes / Storage size: 2 bytes
/ Alignment: 2 bytes / Alignment: 2 bytes
][ ][
/ `i24`: Signed 24-bit integer / `i24`: Signed 24-bit integer
/ Storage size: 2 bytes / Storage size: 2 bytes
/ Alignment: 2 bytes / Alignment: 2 bytes
][ ][
/ `u48`: Unsigned 48-bit integer / `u48`: Unsigned 48-bit integer
/ Storage size: 4 bytes / Storage size: 4 bytes
/ Alignment: 4 bytes / Alignment: 4 bytes
][ ][
/ `i48`: Signed 48-bit integer / `i48`: Signed 48-bit integer
/ Storage size: 4 bytes / Storage size: 4 bytes
/ Alignment: 4 bytes / Alignment: 4 bytes
]] ]]
== Booleans == 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
Strings are represented by pointers to a `u12`, followed by that number of bytes of data representing the contents of the string. 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 == Parameter passing
Parameters are expanded to take a full word and are placed in order: Parameters are expanded to take a full word and are placed in order:
#columns(2)[ #columns(2)[
+ in ```ain48 %01``` + in ```ain48 %01```
+ in ```ain48 %02``` + in ```ain48 %02```
+ in ```ain48 %03``` + in ```ain48 %03```
+ in ```ain48 %04``` + in ```ain48 %04```
#colbreak() #colbreak()
5. in ```ain48 %05``` 5. in ```ain48 %05```
+ in ```ain48 %06``` + in ```ain48 %06```
+ in ```ain48 %07``` + 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. + 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 == Return value passing
The return value is to be placed in ```ain48 %01```. The return value is to be placed in ```ain48 %01```.
== Clobbering == Clobbering
Registers ```ain48 %01```, ```ain48 %02```, ```ain48 %03```, ```ain48 %04```, ```ain48 %05```, 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 == Invocation Sequence
+ The invoker pushes all the registers it needs saved to the stack + The invoker pushes all the registers it needs saved to the stack
+ The invoker pushes the stack arguments to the stack + The invoker pushes the stack arguments to the stack
+ The invoker loads the registers with the register arguments + 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 allocates its local variables on top of the stack.
+ The invokee saves any register it needs to prevent the clobering of. + The invokee saves any register it needs to prevent the clobbering of.
+ The invokee run its course + The invokee runs its course
+ The invokee restores the registers + The invokee restores the registers
+ The invokee frees it’s local variables + The invokee frees its local variables
+ The invokee loads it’s return value into ```ain48 %01``` + The invokee loads its 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 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 frees the stack arguments.
+ The invoker restores the registers it pushed + 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 ILG %02, arg8 ; 2. Push 8th argument
LG %02, (%02) LG %02, (%02)
CST %02 CST %02
ILG %01, #o1 ; 3. Load Register arguments ILG %01, #o1 ; 3. Load register arguments
... ...
ILG %07, #o7 ILG %07, #o7
IVC res ; 4. Transfer to the invokee IVC res ; 4. Transfer to the invokee
PADD %it, #o10 ; 12. Free the 2 words of stack arguments 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) res: PSTR %it, #o14 ; 5. Allocate local variables (here 3 words)
CST %10 ; 6. Save invoker-safe registers CST %10 ; 6. Save invoker-safe registers
... ; 7. Foo does whatever it does ... ; 7. Res does whatever it does
DST %10 ; 8. The invokee retores the invoker-safe DST %10 ; 8. Restore the invoker-safe registers
; registers
PADD %it, #o14 ; 9. Free the local variables 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 ; return value in %01
RV ; 11. Transfer back to the invoker RV ; 11. Transfer back to the invoker
``` ```
= Kernel invocation convention = Kernel invocation convention