vram classes docs progress

#53

.gitignore

@@ -1,7 +1,4 @@
 /target
 
-.vscode/
-!.vscode/extensions.json
-
 perf.data
 perf.data.old

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "[markdown]": {
+        "editor.rulers": [80]
+    }
+}

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:

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.
 

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
 

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.