Skip to content

Commit 6f0e19e

Browse files
authored
Document missing settings on Configuration.md (#449)
1 parent 5405ed2 commit 6f0e19e

File tree

1 file changed

+68
-4
lines changed

1 file changed

+68
-4
lines changed

docs/Configuration.md

Lines changed: 68 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -403,20 +403,84 @@ ld_symbol_header_path: path/to/linker_symbol_header
403403

404404
### ld_discard_section
405405

406-
Determines whether to add a discard section to the linker script
406+
Determines whether to add a wildcard discard section to the linker script.
407+
408+
This tells the linker that every section not explicitly listed on the linker script will be discarded.
409+
410+
### ld_sections_allowlist
411+
412+
A list of sections to preserve during link time. It can be useful to preserve debugging sections.
413+
414+
#### Usage
415+
416+
```yaml
417+
ld_sections_allowlist:
418+
- .shstrtab
419+
- .mdebug
420+
- .mdebug.abi32
421+
```
422+
423+
Generates entries at the bottom of the linker script like:
424+
425+
```text
426+
.shstrtab 0 :
427+
{
428+
*(.shstrtab);
429+
}
430+
.mdebug 0 :
431+
{
432+
*(.mdebug);
433+
}
434+
.mdebug.abi32 0 :
435+
{
436+
*(.mdebug.abi32);
437+
}
438+
```
439+
440+
### ld_sections_denylist
441+
442+
A list of sections to discard during link time. It can be useful to avoid using the [wildcard discard](#ld_discard_section).
443+
444+
Note this option does not turn off [`ld_discard_section`](#ld_discard_section), neither checks if the listed sections overlap with it.
445+
446+
#### Usage
447+
448+
```yaml
449+
ld_sections_denylist:
450+
- .reginfo
451+
- .MIPS.abiflags
452+
- .MIPS.options
453+
- .note.gnu.build-id
454+
- .interp
455+
- .eh_frame
456+
```
457+
458+
Generates a discard section like this:
459+
460+
```text
461+
/DISCARD/ :
462+
{
463+
*(.reginfo);
464+
*(.MIPS.abiflags);
465+
*(.MIPS.options);
466+
*(.note.gnu.build-id);
467+
*(.interp);
468+
*(.eh_frame);
469+
}
470+
```
407471

408472
### ld_wildcard_sections
409473

410474
Determines whether to add wildcards for section linking in the linker script (.rodata* for example)
411475

412-
### ld_use_symbolic_vram_addreses
476+
### ld_use_symbolic_vram_addresses
413477

414478
Determines whether to use `follows_vram` (segment option) and `vram_symbol` / `follows_classes` (vram_class options) to calculate vram addresses in the linker script.
415479
Enabled by default. If disabled, this uses the plain integer values for vram addresses defined in the yaml.
416480

417481
### ld_partial_linking
418482

419-
Change linker script generation to allow partially linking segments. Requires both `ld_partial_scripts_path` and `ld_partial_build_segments_path` to be set.
483+
Change linker script generation to allow partially linking segments. Requires both [`ld_partial_scripts_path`](#ld_partial_scripts_path) and [`ld_partial_build_segments_path`](#ld_partial_build_segments_path) to be set.
420484

421485
### ld_partial_scripts_path
422486

@@ -542,7 +606,7 @@ Determine the format that symbols should be named by default
542606

543607
### symbol_name_format_no_rom
544608

545-
Same as `symbol_name_format` but for symbols with no rom address
609+
Same as [`symbol_name_format`](#symbol_name_format) but for symbols with no rom address
546610

547611
### find_file_boundaries
548612

0 commit comments

Comments
 (0)