Add notes about coolwatcher and lod

1 files changed, 71 insertions, 8 deletions

diff --git a/doc/notes.txt b/doc/notes.txt
index 4f40877..478c3bb 100644
--- a/doc/notes.txt
+++ b/doc/notes.txt
@@ -89,11 +89,13 @@ Any other configuration simply fails, despite the A9 AT firmware being known for
 baud rate auto detection.
 
 Unusual compilation flags
-=======================
+=========================
 By inspecting the steps performed by gprs_c_sdk's Makefiles (remember to remove
 the -s from them), it definitely uses some peculiar compilation settings:
 
 - First, mips-rda-elf-gcc is not used, but mips-elf-gcc.
+    - mips-rda-elf-gcc is based on gcc 7.1.0, whereas mips-elf-gcc is based on
+    gcc 4.4.2.
 - -ffixed-t4 -ffixed-t5 -ffixed-t6 -ffixed-t7 -ffixed-s2 -ffixed-s3 -ffixed-s4
   -ffixed-s5 -ffixed-s6 -ffixed-s7 -ffixed-fp. According to
   https://stackoverflow.com/questions/35809832/is-the-flag-ffixed-reg-always-bugged-in-gcc ,
@@ -103,10 +105,7 @@ the -s from them), it definitely uses some peculiar compilation settings:
   reason.
   According to https://cgi.cse.unsw.edu.au/~cs3231/doc/mips.php , registers t0-t7
   are used as general-purpose temporary registers, s0-s7 as general-purpose
-  saved registers and fp is used for floating-point arithmetic (the latter being
-  mentioned on https://vhouten.home.xs4all.nl/mipsel/r3000-isa.html).
-  I guess 'fp' is omitted as the A9 might lack an FPU (like the PSX), but I can't
-  tell why the other registers must not be used by the compiler.
+  saved registers and fp is the frame pointer.
 - Other funky compilation flags are:
     -minterlink-mips16
     -march=xcpu -mtune=xcpu <- Not so rare tbh, even x86 uses them
@@ -165,6 +164,70 @@ formats and communication protocols.
     - coolwatcher and coolhost would be roughly equivalent to OpenOCD or
     avrdude.
     - .lod files are very similar to .hex files, although poorly designed.
-    - HST (a plain old UART despite its fancy name) is used instead of JTAG/SWD.
-    I am unsure of how source-level debugging is accomplished, despite coolwatcher
-    having an interface to mips-elf-insight.
+    More on this later.
+    - HST (a seemingly plain old UART despite its fancy name) is used instead
+    of JTAG/SWD.  I am unsure of how source-level debugging is accomplished,
+    despite coolwatcher having an interface to mips-elf-insight.
+
+The .lod file format includes the following information:
+    - Optional fields prefixed by '#' (maybe comments?). This is an example of
+    the output generated by the gpio demo:
+        #$mode=flsh_spi32m
+        #$sectormap=(16 x 4k, 57 x 64k, 96 x 4k)
+        #$base=0x08000000
+        #$spacesize=0x08000000
+        #$FLSH_MODEL=flsh_spi32m
+        #$FLASH_SIZE=0x400000
+        #$RAM_SIZE=0x00265000
+        #$RAM_PHY_SIZE=0x00400000
+        #$CALIB_BASE=0x3FA000
+        #$FACT_SETTINGS_BASE=0x3FE000
+        #$CODE_BASE=0x00000000
+        #$USER_DATA_BASE=0x00361000
+        #$USER_DATA_SIZE=0x00099000
+        #$USER_BASE=0x00240000
+        #$USER_SIZE=0x00100000
+    - Starting address, prefixed by '@' e.g.: @01c000a0. Must be indicated
+    before program information, although several starting addresses can be
+    indicated throughout the file. See 'host_8955_flsh_spi32m_ramrun.lod'
+    as an example.
+    - Program data, with one 32-bit hex per line e.g.: '3c04d9ef'. This is
+    the main reason why I disliked this file format, as it tends towards
+    *very* long files that are difficult to open with some text editors,
+    as opposed to .hex or .mot, where multiple words are packed into one line.
+
+Frame structure
+===============
+CID 27 readi8 at 0x00000003
+Write host: AD 00 07 FF 04 03 00 00 00 8A 72
+            ^  [   ] ^  ^  [         ]  ^  ^
+            |  [   ] |  |  [         ]  |  unknown
+            |  [   ] |  |  [         ]  unknown
+            |  [   ] |  |  memory address? little-endian
+            |  [   ] |  unknown
+            |  [   ] unknown (frame type?)
+            |  frame size without header or next byte (little-endian)
+            header (always 0xAD)
+
+Another example:
+                Offset
+     00|01|02|03|04|05|06|07|08|09|0a|0b|0c|0d|0e|0f
+    |
+00  |ad 00 35 80 14 80 3c 2d 2d 20 3c 25 73 3e 20 6f ..5...<-- <%s> o
+10  |6e 20 41 72 66 63 6e 20 30 78 25 78 0a 00 4c 31 n Arfcn 0x%x..L1
+20  |5f 53 59 4e 43 48 5f 4e 4f 54 5f 46 4f 55 4e 44 _SYNCH_NOT_FOUND
+30  |00 6a 00 00 00 00 0a 80 00
+
+Coolwatcher reads the following decodified syntax:
+"<-- <L1_SYNCH_NOT_FOUND> on Arcfn 0x6a"
+
+Header: 0xAD
+Size: 0x0035
+Frame type?: 0x80
+Timestamp?: 0x8014
+Plain ASCII data from offset 0x06 to 0x1d
+So it means parameters are specified in a printf-like syntax. In this case,
+two parameters are specified:
+    - Null-terminated string "L1_SYNCH_NOT_FOUND"
+    - 32-bit integer (0x%x) with value 0x0000006a
+    - Unknown 32-bit integer with value 00 0a 80 00