My attempt at improving documentation (#288)

* Tried to improve General Workflow with a bit more context and bigger examples Added a link to General Workflow from Quickstart to improve the reading experience Added data and rodata plus their dot-variants to Segments, to have some info to read back on * Add clarification to .data and .rodata segments * Added suggestion by @AngheloAlf to clarify `multiple rodata` messages Co-authored-by: Anghelo Carvajal <[email protected]> * Added clarification to `multiple rodata` that it can be a false positive * Removed text about `splat` generating a C file, instead clarifying that `splat` expects the file to be there * Added `etheck`s suggestion for rewording the "Initially" paragraph Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion for introducing the `splat` output Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion for removing bad text Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion for rewording where I ran out of words Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion... and more to come! Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion for including the actual path the `energy_orb_wave` will end up ("nonmatchings") Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion for expanding the text which explains GLOBAL_ASM() macro Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion for expanding the 'Next steps' paragraph Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion for expanding how `.rodata` affects linking Co-authored-by: Ethan Roseman <[email protected]> * Added `etheck`s suggestion for rewording how to migrate data Co-authored-by: Ethan Roseman <[email protected]> --------- Co-authored-by: berendbutje <[email protected]> Co-authored-by: Anghelo Carvajal <[email protected]> Co-authored-by: Ethan Roseman <[email protected]>
ethteck · Sep 22, 2023 · 7ab3550 · 7ab3550
1 parent def8fdb
commit 7ab3550
Show file tree

Hide file tree

Showing 4 changed files with 173 additions and 10 deletions.
diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -14,7 +14,7 @@ base_path: path/to/base/folder
 
 #### Default
 
-`.`
+`.` *(Current directory)*
 
 
 ### target_path

diff --git a/docs/General-Workflow.md b/docs/General-Workflow.md
@@ -1,26 +1,101 @@
 This describes an example of how to iteratively edit the splat segments config, when decompiling
 
+(If you have no idea what this is about, please head over to the [Quickstart](https://github.com/ethteck/splat/wiki/Quickstart) to get an initial configuration for your ROM.)
+
 # 1 Initially
 
-Assuming that after you split segments you start from a code segment which subsegments include
+After succesfully following the [Quickstart](https://github.com/ethteck/splat/wiki/Quickstart), you should get an initial configuration like the one below:
+```yaml
+- name: main
+  type: code
+  start: 0x1060
+  vram: 0x80070C60
+  follows_vram: entry
+  bss_size: 0x3AE70
+  subsegments:
+      - [0x1060, asm]
+      # ... a lot of additional `asm` sections
+      # This section is found out to contain __osViSwapContext
+      - [0x25C20, asm, "energy_orb_wave"]
+      # ... a lot of addtiional `asm` sections
+      - [0x2E450, data]
+
+      - [0x3E330, rodata]
+      # ... a lot of addtional `rodata` sections
+      - { start: 0x3F1B0, type: bss, vram: 0x800E9C20 }
+
+- [0x3F1B0, bin]
+```
+
+## 1.1 Match rodata to asm sections
+
+In order to simplify decompilation, it's good practice to start pairing `rodata` sections with `asm` sections.
+
+`splat` gives hints about what `rodata` is used in which `asm` segment. These look like:
+
+```
+Rodata segment '3EE10' may belong to the text segment 'energy_orb_wave'
+    Based on the usage from the function func_0xXXXXXXXX to the symbol D_800AEA10
+```
+
+To pair these two sections, simply add the name of the suggested text (`asm`) segment to the `rodata` segment:
+
+```yaml
+- [0x3EE10, rodata, "energy_orb_wave"]
+```
+
+### Useful knowledge about splitting
+
+#### Multiple `rodata`
+Using the following configuration:
+```yaml
+# ...
+- [0x3E900, rodata]
+- [0x3E930, rodata]
+# ...
+```
+
+`splat` outputs a hint that doesn't immediately seem to make sense:
+
+```
+Rodata segment '3E900' may belong to the text segment '16100'
+    Based on the usage from the function func_80085DA0 to the symbol jtbl_800AE500
+
+Rodata segment '3E930' may belong to the text segment '16100'
+    Based on the usage from the function func_800862C0 to the symbol jtbl_800AE530
+```
+
+This hint tells you that `splat` thinks one text (`asm`) segment seems to have two `rodata` sections. This usually means that either there should not be a split at `0x3E930` or `0x16100` is missing a file split, since one text segment should only have one `rodata` segment. 
+
+Please note that this could be a false positive, and you should do your own investigation to figure out the truth. If you, however, feel confident that the `rodata` should not be split, simply remove the second split from the configuration:
+
 ```yaml
-- [0x42100, bin]
+# ...
+- [0x3E900, rodata, "16100"]
+# begone!
+# ...
+
 ```
 
+### **TODO** Multiple `asm` referring to the same `rodata`
+
+Sometimes the opposite from above is true, and `splat` shows you two `asm` segments belonging to one `rodata` segment. In this case, try to split the `asm` segment to make sure two files are not paired with the same `rodata`. Note this too can be a false positive.
+
 # 2 Disassemble text, data, rodata
 
-To start decompiling this subsegment, replace it with
+Let's say you want to start decompiling the subsegment at `0x25C20` (`energy_orb_wave`). Start by replacing the `asm` type with `c`.
+
 ```yaml
-- [0x42100, c, energy_orb_wave]
-- [0x42200, data, energy_orb_wave]
-- [0x42300, rodata, energy_orb_wave]
+- [0x25C20, c, energy_orb_wave]
+# ... 
+- [0x3EE10, rodata, energy_orb_wave]
 ```
 
-This will disassemble `0x42100-0x42200` to individual `.s` files for each function found
+This will disassemble `0x25C20` to individual `.s` files for each function found. The output will be located in `asm/nonmatchings/energy_orb_wave` (depending on the `asm_path` setting, found in the configuration).
 
-It will also write `energy_orb_wave.data.s` and `energy_orb_wave.rodata.s` (using information gained during the disassembly of the functions)
+It will also generate `asm/energy_orb_wave.data.s` (if it is paired with a `data` segment), and `energy_orb_wave.rodata.s` (using information gained during the disassembly of the functions).
 
-And if the project uses asm-processor, write a .c with `GLOBAL_ASM()` to include all disassembled functions.
+Finally, it will generate a C file at `src/energy_orb_wave.c` (depending on the `src_path` setting, found in the configuration) containing `GLOBAL_ASM()` and `GLOBAL_RODATA()` macros to include all disassembled functions. (This macro is to be defined in an included header, which splat currently does not produce. For an example, see [the include.h for Dr. Mario](https://github.com/AngheloAlf/drmario64/blob/master/include/include_asm.h),)
 
 Figuring out the data and rodata addresses is to be done manually. Just disassembling the whole segment may help:
 ```yaml

diff --git a/docs/Quickstart.md b/docs/Quickstart.md
@@ -143,8 +143,11 @@ Notice that **splat** has found some potential file splits (function start/end w
 
 It's up to you to figure out the layout of the ROM.
 
+
 ## Next Steps
 
 The reassembly of the ROM is currently out of scope of this quickstart, as is switching out the `asm` segments for `c`.
 
+You can find a general workflow for using `splat` at [General Workflow](https://github.com/ethteck/splat/wiki/General-Workflow)
+
 Please feel free to improve this guide!
diff --git a/docs/Segments.md b/docs/Segments.md
@@ -118,6 +118,91 @@ This is platform specific; parses the data and interprets as a header for e.g. N
   start: 0xABC
 ```
 
+## `data`
+
+**Description:**
+
+Data located in the ROM.
+
+**Example:**
+
+```yaml
+# as list
+- [0xABC, data, filepath]
+
+# as dictionary
+- name: filepath
+  type: data
+  start: 0xABC
+```
+
+This will created `filepath.asm` in your `asm` folder.
+
+## `.data`
+
+**Description:**
+
+Data located in the ROM, linked from a C file.
+
+Once you have figured out the types of symbols in the data section and you are confident about its file split, you will want probably to migrate symbols from assembly to C. To do this, you will want to first define all of the symbols in the c file. Then, change the `data` segment to `.data`. This instructs the linker to, in the build stage, link to the symbols in the C file specified at `filepath`.
+
+**Example:**
+
+```yaml
+# as list
+- [0xABC, .data, filepath]
+
+# as dictionary
+- name: filepath
+  type: .data
+  start: 0xABC
+```
+
+`splat` will not generate `.data.s` files for these sections, as the symbols should be declared in the C file specified by `filepath`.
+
+## `rodata`
+
+**Description:**
+
+Read-only data located in the ROM.
+
+**Example:**
+
+```yaml
+# as list
+- [0xABC, rodata, filepath]
+
+# as dictionary
+- name: filepath
+  type: rodata
+  start: 0xABC
+```
+
+This will created `filepath.s` in your `asm` folder.
+
+## `.rodata`
+
+**Description:**
+
+Read-only data located in the ROM, linked to a C file.
+
+If you migrate symbols from assembly to C, please prefix the `rodata` with a `.`, like `.rodata` so the linker script chooses to link against that C file's `.rodata` section.
+
+**Example:**
+
+```yaml
+# as list
+- [0xABC, .rodata, filepath]
+
+# as dictionary
+- name: filepath
+  type: .rodata
+  start: 0xABC
+```
+
+`splat` will not generate `.rodata.s` files for these sections, as the symbols should be declared in the C file specified by `filepath`.
+
+
 ## Images
 
 **Description:**