📝 Fixup readme for scripts (#93)

Author: kammce

scripts/README.md

@@ -2,38 +2,69 @@
 
 The scripts for testing and playing around with libhal exceptions.
 
-## Near Point Script?
+## `nearpoint.py`
 
 ```plaintext
-usage: nearpoint.py [-h] [-b BLOCK_POWER] [-s SMALL_BLOCK_POWER] [-n] file
+usage: nearpoint.py [-h] [-b BLOCK_POWER] [-s SMALL_BLOCK_POWER] [-e ERROR_THRESHOLD] [--auto-optimize] [--tool-prefix TOOL_PREFIX] -m MAP
+                    [-o ORDER_FILE] [-n NEARPOINT_FILE] [-v]
+                    elf_file
+
+Generate nearpoint exception tables and linker script from a .map and .elf file
 
 positional arguments:
-  file                  text file with a list of function addresses in your code starting from 0 to N where N is the last function
-                        address, or output from the command: nm app.elf --size-sort --radix=d | grep " [Tt] " | awk '{print $1}'
+  elf_file              Path to the ELF binary
 
 options:
   -h, --help            show this help message and exit
-  -b BLOCK_POWER, --block_power BLOCK_POWER
-                        Set the block size based on a power of 2.
-  -s SMALL_BLOCK_POWER, --small_block_power SMALL_BLOCK_POWER
-                        Set the small block size based on a power of 2.
-  -n, --nm              The input file is actually output from an NM command: nm app.elf --size-sort --radix=d | grep " [Tt] " | awk
-                        '{print $1}'
+  -b BLOCK_POWER, --block-power BLOCK_POWER
+                        Normal block size power of 2 (0 = auto-optimize)
+  -s SMALL_BLOCK_POWER, --small-block-power SMALL_BLOCK_POWER
+                        Small block size power of 2 (0 = auto-optimize) (NOT CURRENTLY SUPPORTED!)
+  -e ERROR_THRESHOLD, --error-threshold ERROR_THRESHOLD
+                        Error threshold for small table generation (default: 8, min: 4) (NOT CURRENTLY SUPPORTED!)
+  --auto-optimize       Automatically find optimal block sizes (NOT CURRENTLY SUPPORTED!)
+  --tool-prefix TOOL_PREFIX
+                        Toolchain prefix for objdump/nm (e.g., "arm-none-eabi-" or full path)
+  -m MAP, --map MAP     Path to map file for executable
+  -o ORDER_FILE, --order_file ORDER_FILE
+                        Path to where to store the ordering file.
+  -n NEARPOINT_FILE, --nearpoint_file NEARPOINT_FILE
+                        Path to where to store the nearpoint table.
+  -v, --verbose         Enable verbose logging
 ```
 
-The script works with output from nm following this:
+You will need to pass in the map file generated by your linker as well as the
+final elf file.
 
 ```bash
 python3 nearpoint.py --tool-prefix="/path/to/arm-none-eabi/bin/" --map="app.elf.map" app.elf
 ```
 
-After
+This will generate a `order.ld` file which you can add as an additonal linker
+script with `-Torder.ld`. The `order.ld` file uses the `INSERT BEFORE .text`
+directive which allows it to be added to the set of linkers and does not
+overtake your linker script.
 
-What this will do is create a size sorted list of each function in the program
-and output its starting address. This easy to execute script enable 3rd parties
-to send us this information in a mostly erased fashion to compare against our
-application. Even if the application does not use exceptions.
+This command will also generate a `nearpoint.cpp` which contains the nearpoint
+descriptor and the nearpoint table.
 
-```bash
-python3 scripts/nearpoint.py demos/multi_levels.elf.nm -n -b 10
+## `prel31.py`
+
+Converts a positive relative 31-bit (or `prel31`) number and the location of the number to the absolute address of where the object points to.
+
+```plaintext
+usage: prel31.py [-h] [-a ADDRESS] [-e {big,little}] prel31_offset
+
+Converts a positive relative 31-bit (or `prel31`) number and the location of the number to the absolute address of where the object points to.
+
+positional arguments:
+  prel31_offset         value to convert
+
+options:
+  -h, --help            show this help message and exit
+  -a ADDRESS, --address ADDRESS
+                        Address of the prel31 offset value which is needed to get an absolute value. The default of 0 returns the relative offset
+                        from the value
+  -e {big,little}, --endian {big,little}
+                        Set the endianess of the prel31_offset. The address must be big endian (or the way its spelled)
 ```