Document settings for file format

Issue #8

docs/file_format/README.md

@@ -1,14 +1,15 @@
 # File format
 
 The input file format is composed by two top-level attributes, the
-[`settings`](settings.md) and the [`segments`](segments.md).
+[`settings`](settings.md) attribute and the [`segments`](segments.md)
+attribute. Check their specific documents for in-deep explanations.
 
 ## Example
 
 ```yaml
 settings:
-  paths:
-    base_path: build
+  base_path: build
+  use_subalign: True
   subalign: 32
 
 segments:

docs/file_format/settings.md

@@ -1,3 +1,191 @@
 # Settings
 
-TODO
+The top-level `settings` attribute specifies many options to customize the
+generated linker script. Note that many of these options can be customized per
+segment too.
+
+## `base_path`
+
+All the emitted paths are relative to this path. Useful when all the files are
+relative to the same path, like a `build` folder.
+
+Optional.
+
+### Example
+
+```yaml
+settings:
+  base_path: build/us
+```
+
+### Valid values
+
+Any valid path.
+
+### Default value
+
+Defaults to empty path.
+
+## `linker_symbols_style`
+
+The styling used for the automatically generated linker symbols.
+
+These symbols correspond to the vram and rom address of the segments and the
+vram address of the sections of the corresponding segment.
+
+To be precise, symbols are generated for the following:
+
+- Segment's rom start and end.
+- Segment's vram start and end.
+- Section's vram start, end and size.
+
+### Example
+
+```yaml
+settings:
+  linker_symbols_style: makerom
+```
+
+### Valid values
+
+- `splat`: Produces SCREAMING_CASE symbols. Given a segment named `boot`:
+  - Segment rom: `boot_ROM_START` and `boot_ROM_END`.
+  - Segment vram: `boot_VRAM` and `boot_VRAM_END`.
+  - Section vram (not limited to the foloowing examples):
+    - `.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`.
+
+- `makerom`: Produces _camelCase symbols. Given a segment named `boot`:
+  - Segment rom: `_bootSegmentRomStart` and `_bootSegmentRomEnd`.
+  - Segment vram: `_bootSegmentStart` and `_bootSegmentEnd`.
+  - Section vram (not limited to the foloowing examples):
+    - `.text`: `_bootSegmentTextStart`, `_bootSegmentTextEnd` and `_bootSegmentTextSize`.
+    - `.data`: `_bootSegmentDataStart`, `_bootSegmentDataEnd` and `_bootSegmentDataSize`.
+    - `.bss`: `_bootSegmentBssStart`, `_bootSegmentBssEnd` and `_bootSegmentBssSize`.
+
+### Default value
+
+`splat`
+
+## `alloc_sections`
+
+List of allocatable sections (the ones that take ROM space).
+
+The sections from this list will be emitted for each file in the specified
+order.
+
+This option can be overriden per segment, see
+[segments.md#alloc_sections](segments.md#alloc_sections) for more info.
+
+### Example
+
+```yaml
+settings:
+  alloc_sections: `[.rodata, .text, .data]`
+```
+
+### Valid values
+
+List of strings.
+
+### Default value
+
+`[.text, .data, .rodata, .sdata]`
+
+## `noload_sections`
+
+List of noload sections (the ones that don't take ROM space).
+
+The sections from this list will be emitted for each file in the specified
+order.
+
+This option can be overriden per segment, see
+[segments.md#noload_sections](segments.md#noload_sections) for more info.
+
+### Example
+
+```yaml
+settings:
+  alloc_sections: `[.bss]`
+```
+
+### Valid values
+
+List of strings.
+
+### Default value
+
+`[.sbss, .scommon, .bss, COMMON]`
+
+## `use_subalign`
+
+Toggle using `SUBALIGN` directives on the segments.
+
+This option can be overriden per segment, see
+[segments.md#use_subalign](segments.md#use_subalign) for more info.
+
+### Example
+
+```yaml
+settings:
+  use_subalign: False
+```
+
+### Valid values
+
+Boolean
+
+### Default value
+
+`True`
+
+## `subalign`
+
+The value to use in the `SUBALIGN` directives.
+
+The [`use_subalign`](#use_subalign) option controls if this directive is
+emitted or not.
+
+This option can be overriden per segment, see
+[segments.md#subalign](segments.md#subalign) for more info.
+
+### Example
+
+```yaml
+settings:
+  subalign: 4
+```
+
+### Valid values
+
+Positive integers
+
+### Default value
+
+`16`
+
+## `wildcard_sections`
+
+Toggles using wildcards (`*`) as suffix in the emitted sections.
+
+For example the `.rodata` section would be emitted as `.rodata*` if this option
+is enabled.
+
+This option can be overriden per segment, see
+[segments.md#wildcard_sections](segments.md#wildcard_sections) for more info.
+
+### Example
+
+```yaml
+settings:
+  wildcard_sections: False
+```
+
+### Valid values
+
+Boolean
+
+### Default value
+
+`True`

slinky/src/document.rs

@@ -38,9 +38,7 @@ impl Document {
             segment
                 .use_subalign
                 .get_or_insert(document.settings.use_subalign);
-            segment
-                .subalign
-                .get_or_insert(document.settings.subalign);
+            segment.subalign.get_or_insert(document.settings.subalign);
 
             segment
                 .wildcard_sections

slinky/src/lib.rs

@@ -3,8 +3,7 @@
 
 mod error;
 
-mod paths_configs;
-mod segment_symbols_style;
+mod linker_symbols_style;
 mod settings;
 
 mod file_info;
@@ -17,8 +16,7 @@ mod linker_writer;
 
 pub use error::SlinkyError;
 
-pub use paths_configs::PathsConfigs;
-pub use segment_symbols_style::SegmentSymbolsStyle;
+pub use linker_symbols_style::LinkerSymbolsStyle;
 pub use settings::Settings;
 
 pub use file_info::FileInfo;

slinky/src/segment_symbols_style.rs → slinky/src/linker_symbols_style.rs

@@ -3,46 +3,47 @@
 
 use serde::Deserialize;
 
-// TODO: figure out how to allow lowercase for these values in the yaml
 #[derive(Deserialize, PartialEq, Debug)]
-pub enum SegmentSymbolsStyle {
+#[serde(rename_all = "snake_case")]
+pub enum LinkerSymbolsStyle {
     Splat,
     Makerom,
 }
 
-impl SegmentSymbolsStyle {
+impl LinkerSymbolsStyle {
     pub fn segment_rom_start(&self, seg_name: &str) -> String {
         match self {
-            SegmentSymbolsStyle::Splat => format!("{}_ROM_START", seg_name),
-            SegmentSymbolsStyle::Makerom => format!("_{}SegmentRomStart", seg_name),
+            LinkerSymbolsStyle::Splat => format!("{}_ROM_START", seg_name),
+            LinkerSymbolsStyle::Makerom => format!("_{}SegmentRomStart", seg_name),
         }
     }
 
     pub fn segment_rom_end(&self, seg_name: &str) -> String {
         match self {
-            SegmentSymbolsStyle::Splat => format!("{}_ROM_END", seg_name),
-            SegmentSymbolsStyle::Makerom => format!("_{}SegmentRomEnd", seg_name),
+            LinkerSymbolsStyle::Splat => format!("{}_ROM_END", seg_name),
+            LinkerSymbolsStyle::Makerom => format!("_{}SegmentRomEnd", seg_name),
         }
     }
 
     pub fn segment_vram_start(&self, seg_name: &str) -> String {
         match self {
-            SegmentSymbolsStyle::Splat => format!("{}_VRAM", seg_name),
-            SegmentSymbolsStyle::Makerom => format!("_{}SegmentStart", seg_name),
+            LinkerSymbolsStyle::Splat => format!("{}_VRAM", seg_name),
+            LinkerSymbolsStyle::Makerom => format!("_{}SegmentStart", seg_name),
         }
     }
 
     pub fn segment_vram_end(&self, seg_name: &str) -> String {
         match self {
-            SegmentSymbolsStyle::Splat => format!("{}_VRAM_END", seg_name),
-            SegmentSymbolsStyle::Makerom => format!("_{}SegmentEnd", seg_name),
+            LinkerSymbolsStyle::Splat => format!("{}_VRAM_END", seg_name),
+            LinkerSymbolsStyle::Makerom => format!("_{}SegmentEnd", seg_name),
         }
     }
 
     fn convert_section_name_to_linker_format(&self, section_type: &str) -> String {
         match self {
-            SegmentSymbolsStyle::Splat => section_type.replace('.', "_"),
-            SegmentSymbolsStyle::Makerom => {
+            LinkerSymbolsStyle::Splat => section_type.replace('.', "_"),
+            LinkerSymbolsStyle::Makerom => {
+                // TODO: yeet RoData?
                 if section_type == ".rodata" {
                     "RoData".to_string()
                 } else {
@@ -73,26 +74,26 @@ impl SegmentSymbolsStyle {
         let sec = self.convert_section_name_to_linker_format(section_type);
 
         match self {
-            SegmentSymbolsStyle::Splat => format!("{}{}_START", seg_name, sec),
-            SegmentSymbolsStyle::Makerom => format!("_{}Segment{}Start", seg_name, sec),
+            LinkerSymbolsStyle::Splat => format!("{}{}_START", seg_name, sec),
+            LinkerSymbolsStyle::Makerom => format!("_{}Segment{}Start", seg_name, sec),
         }
     }
 
     pub fn segment_section_end(&self, seg_name: &str, section_type: &str) -> String {
         let sec = self.convert_section_name_to_linker_format(section_type);
 
         match self {
-            SegmentSymbolsStyle::Splat => format!("{}{}_END", seg_name, sec),
-            SegmentSymbolsStyle::Makerom => format!("_{}Segment{}End", seg_name, sec),
+            LinkerSymbolsStyle::Splat => format!("{}{}_END", seg_name, sec),
+            LinkerSymbolsStyle::Makerom => format!("_{}Segment{}End", seg_name, sec),
         }
     }
 
     pub fn segment_section_size(&self, seg_name: &str, section_type: &str) -> String {
         let sec = self.convert_section_name_to_linker_format(section_type);
 
         match self {
-            SegmentSymbolsStyle::Splat => format!("{}{}_SIZE", seg_name, sec),
-            SegmentSymbolsStyle::Makerom => format!("_{}Segment{}Size", seg_name, sec),
+            LinkerSymbolsStyle::Splat => format!("{}{}_SIZE", seg_name, sec),
+            LinkerSymbolsStyle::Makerom => format!("_{}Segment{}Size", seg_name, sec),
         }
     }
 }