From 0ce5b6f66a7fc45c0d20602d643486f2a075a48b Mon Sep 17 00:00:00 2001 From: angie Date: Wed, 1 May 2024 09:59:38 -0400 Subject: [PATCH] vram classes docs progress #53 --- .gitignore | 3 - .vscode/settings.json | 5 + docs/file_format/README.md | 14 ++- docs/file_format/segments.md | 2 +- docs/file_format/settings.md | 10 +- docs/file_format/vram_classes.md | 183 ++++++++++++++++++++++++++++++- 6 files changed, 204 insertions(+), 13 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.gitignore b/.gitignore index f7322bc..7c0fc45 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,4 @@ /target -.vscode/ -!.vscode/extensions.json - perf.data perf.data.old diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..defeea4 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "[markdown]": { + "editor.rulers": [80] + } +} \ No newline at end of file diff --git a/docs/file_format/README.md b/docs/file_format/README.md index 5b83cae..d42718c 100644 --- a/docs/file_format/README.md +++ b/docs/file_format/README.md @@ -1,16 +1,18 @@ # File format -The input file format is composed by two top-level attributes, the +The input file format is composed by two required top-level attributes, the [`settings`](settings.md) attribute and the [`segments`](segments.md) -attribute. Check their specific documents for in-deep explanations. +attribute. Other optional top-level attributes may be specified, like +[vram_classes](vram_classes.md). Check their specific documents for in-deep +explanations. ## Example The following example corresponds to the -[`basic_example.yaml`](../../tests/input_files/basic_example.yaml) from the -test cases, while -[`basic_example.ld`](../../tests/linker_scripts/basic_example.ld) is how the -output linker script looks like. +[`basic_example.yaml`](../../tests_cases/basic_example.yaml) from the test +cases, while +[`basic_example.ld`](../../tests_cases/basic_example.ld) is how the output +linker script looks like. ```yaml settings: diff --git a/docs/file_format/segments.md b/docs/file_format/segments.md index c1b82d5..876488b 100644 --- a/docs/file_format/segments.md +++ b/docs/file_format/segments.md @@ -11,7 +11,7 @@ Every attribute listed is optional unless explicitly stated. ## `name` -This is **required**. +This field is **required**. The name of the corresponding segment. diff --git a/docs/file_format/settings.md b/docs/file_format/settings.md index f6b3bef..4c14640 100644 --- a/docs/file_format/settings.md +++ b/docs/file_format/settings.md @@ -42,6 +42,8 @@ To be precise, symbols are generated for the following: - Segment's allocatable vram start, end and size. - Segment's noload vram start, end and size. - Section's vram start, end and size. +- File's [linker offset](file.md#linker_offset_name). +- [Vram's class](vram_classes.md)'s start, end and size. ### Example @@ -61,7 +63,9 @@ settings: - `.text`: `boot_TEXT_START`, `boot_TEXT_END` and `boot_TEXT_SIZE`. - `.data`: `boot_DATA_START`, `boot_DATA_END` and `boot_DATA_SIZE`. - `.bss`: `boot_BSS_START`, `boot_BSS_END` and `boot_BSS_SIZE`. - - File [`linker_offset_name`](file.md#linker_offset_name): `{name}_OFFSET` + - File [`linker_offset_name`](file.md#linker_offset_name): `{name}_OFFSET`. + - [Vram class](vram_classes.md): `{name}_VRAM_CLASS_START`, + `{name}_VRAM_CLASS_END` and `{name}_VRAM_CLASS_SIZE`. - `makerom`: Produces _camelCase symbols. Given a segment named `boot`: - Segment rom: `_bootSegmentRomStart`, `_bootSegmentRomEnd` and `_bootSegmentRomSize`. @@ -70,7 +74,9 @@ settings: - `.text`: `_bootSegmentTextStart`, `_bootSegmentTextEnd` and `_bootSegmentTextSize`. - `.data`: `_bootSegmentDataStart`, `_bootSegmentDataEnd` and `_bootSegmentDataSize`. - `.bss`: `_bootSegmentBssStart`, `_bootSegmentBssEnd` and `_bootSegmentBssSize`. - - File [`linker_offset_name`](file.md#linker_offset_name): `_{name}Offset` + - File [`linker_offset_name`](file.md#linker_offset_name): `_{name}Offset`. + - [Vram class](vram_classes.md): `_{name}VramClassStart`, `_{name}VramClassEnd` + and `_{name}VramClassSize`. ### Default value diff --git a/docs/file_format/vram_classes.md b/docs/file_format/vram_classes.md index 5db5aab..58668cf 100644 --- a/docs/file_format/vram_classes.md +++ b/docs/file_format/vram_classes.md @@ -1,16 +1,197 @@ # Vram classes Vram classes aim to help reduce duplicated data across the segments and more -clearly organize the memory layout. +clearly organize the memory layout. This is not a common linker script concept. +It was designed for the ease of use with complex memory layouts between multiple +segments. A vram class specifies a place in memory, which may be described in a somewhat complex way, so one or more segments can point to this class instead of try to describe the memory layout on the segment itself. +A vram class may describy a memory location by simply specifying a hardcoded +[`vram` (virtual RAM) location](#fixed_vram), the same address of an +[existing symbol](#fixed_symbol) or something more complex like the address of +a vram class starts where one or more other vram classes ends +([follow_classes](#follow_classes)). + +A vram class is composed by two mandatory fields, the [`name`](#name) field and +exactly one of the fields that describe address memory locations. Specifying +more than one or not specifying any of them is invalid. + +Linker symbols for start, end and size are emitted for vram classes, similarly +to how segments have linker symbols for their start, end and size. See +[`linker_symbols_style`](settings.md#linker_symbols_style). + +- The start symbol is defined depending on the given field that describe a + memory location. +- The end symbol is defined as equal to the end symbol of the largest segment + that uses this vram class. +- The size symbol is defined by the subtraction of the end and the start + symbols. + ## `name` +This field is **required**. + +The name of the corresponding vram class. + +The name of a vram class must be unique between all the vram classes. + +### Example + +```yaml +vram_classes: + - { name: battle_partner, fixed_vram: 0x80238000 } +``` + +### Valid values + +Non empty string. + ## `fixed_vram` +Forces the given vram class to be at a fixed `vram` address. + +The start symbol for this vram classs will be hardcoded to the given value. + +### Example + +```yaml +vram_classes: + - { name: segment_05, fixed_vram: 0x05000000 } + +segments: + - name: assets1 + vram_class: segment_05 + files: + - { path: src/assets/assets1/texture.o } + - { path: src/assets/assets1/dlist.o } + + - name: assets2 + vram_class: segment_05 + files: + - { path: src/assets/assets2/texture.o } + - { path: src/assets/assets2/dlist.o } + + - name: assets3 + vram_class: segment_05 + files: + - { path: src/assets/assets3/texture.o } + - { path: src/assets/assets3/dlist.o } +``` + +### Valid values + +Any unsigned integer. + ## `fixed_symbol` +Forces the given vram class to have the same address as the given symbol. + +The start symbol for this vram classs will be hardcoded to the given symbol. + +### Example + +```yaml +vram_classes: + - { name: battle_area2, fixed_symbol: Vine1Base } + +segments: + - name: omo2_1 + vram_class: battle_area2 + files: + - { path: actor/shy_squad.o } + + - name: omo2_2 + vram_class: battle_area2 + files: + - { path: actor/stilt_guy.o } + + - name: omo2_3 + vram_class: battle_area2 + files: + - { path: actor/shy_stack.o } +``` + +### Valid values + +Non empty string. + ## `follow_classes` + +A list of names of other vram classes. + +Specifies that this vram class must follow the end of the largest vram class of +the given list. + +The start symbol for this vram classs will be equal to the largest end of the +given vram classes. + +### Example + +```yaml +vram_classes: + - { name: battle_partner, fixed_vram: 0x80238000 } + - { name: battle_code, follows_classes: [battle_partner] } + + - { name: heaps2, fixed_vram: 0x80267FF0 } + - { name: world_script_api, follows_classes: [heaps2] } + + - { name: texture_memory, follows_classes: [battle_partner, world_script_api] } + +segments: + - name: battle_partner_goompa + vram_class: battle_partner + files: + - { path: src/battle_partner/goompa.o } + - name: battle_partner_goombario + vram_class: battle_partner + files: + - { path: src/battle_partner/goombario.o } + + - name: battle_code + vram_class: battle_code + files: + - { path: src/battle_code/btl_states_actions.o } + - { path: src/battle_code/camera.o } + + - name: heaps2 + vram_class: heaps2 + files: + - { path: src/heaps2/heaps2.o } + + - name: world_script_api + vram_class: world_script_api + files: + - { path: src/world/script_api/shops.o } + - { path: src/world/script_api/rooms.o } + + - name: texture_memory + vram_class: texture_memory + files: + - { path: src/texture_memory/texture_memory.o } +``` + +This example describes the following interactions between segments and vram +classes: + +- The `battle_partner_goompa` and `battle_partner_goombario` segments will have + the same `vram` address as the `battle_partner` vram class, which has a fixed + `vram` address of `0x80238000`. +- `battle_partner`'s end symbol will be set to the end symbol of either + `battle_partner_goompa` or `battle_partner_goombario`. If the + `battle_partner_goompa` segment is bigger then its end symbol will be used, + otherwise the end symbol of `battle_partner_goombario` will be used. +- The `battle_code` will have the same `vram` address as the `battle_code` vram + class. +- The vram address of the `battle_code` vram class will be the same as the end + address of the `battle_partner` vram class (which is defined depending on the + corresponding segments that use that vram class). +- TODO. + +TODO: Add images to explain this memory layout visually. + +### Valid values + +A list of strings. The strings must be names of existing vram classes.