Specify more file formats

README.md

@@ -10,7 +10,10 @@ A set of tools and specifications related to the MiMa
   * [Instructions](#instructions)
   * [Registers](#registers)
   * [Opcodes](#opcodes)
+  * [Extension memory flags](#extension-memory-flags)
   * [Memory dump file format: `.mima`](#memory-dump-file-format-mima)
+  * [Memory flag file format: `.mima-flags`](#memory-flag-file-format-mima-flags)
+  * [Symbol table file format: `.mima-symbols`](#symbol-table-file-format-mima-symbols)
 * [Conventions](#conventions)
 
 For example MiMa programs, see the [examples folder](examples/).
@@ -159,12 +162,33 @@ ignored. They don't have to be set to 0.
   signed integer, whose value is then added to the address in the
   respective register.
 
+## Extension memory flags
+
+Memory flags are single characters associated with certain memory
+locations and ranges. They can be used to add supplemental information
+to a `.mima` file.
+
+It is entirely up to a tool which flags it recognizes and implements,
+and what each of those flags do. Unknown flags are not errors. If a
+tool encounteres an unknown flag, it should ignore the flag.
+
+The following table contains suggestions for the meanings of certain
+flags, in the hope that different tool's implementations of these
+flags are compatible.
+
+| Flag | Name       | Description                                                                                                            |
+|------|------------|------------------------------------------------------------------------------------------------------------------------|
+| `b`  | Breakpoint | In an interactive execution environment, pause execution immediately before this instruction would have been executed. |
+| `e`  | Executable | If this flag is present, only instructions at memory locations marked with this flag can be executed.                  |
+| `r`  | Read-only  | Any command that would modify a memory location marked with this flag fails.                                           |
+
 ## Memory dump file format: `.mima`
 
 All tools share a common memory dump file format with extension
 `.mima`. It contains the whole execution state of a MiMa, meaning the
 contents of its memory and all its registers. It also doubles as "MiMa
-excutable" format.
+excutable" format. It is supplemented by the `.mima-flags` and
+`.mima-symbols` file formats.
 
 The file is split up into blocks of 3 bytes, which form MiMa
 words. The bytes within a word are ordered from most to least
@@ -200,6 +224,65 @@ unspecified values are to be intialized as `0x000000`.
 A `.mima` file must always be a multiple of 3 bytes long. It must
 always be at least 15 bytes long (contains all register values).
 
+## Memory flag file format: `.mima-flags`
+
+The memory flag file is a text-based file that assigns [memory
+flags](#extension-memory-flags) to ranges of memory. It has the file
+extension `.mima-flags`.
+
+The format is line-based and uses LF as line endings. Other whitespace
+is ignored. A line can either be empty or have the following format:
+
+`<start address>-<end address>:<flags>`
+
+* `<start address>` and `<end address>` are case-insensitive,
+  hexadecimal, 5 digit numbers. `<end address>` is inclusive.
+* `<flags>` are multiple characters (at least one).
+
+The format `<address>:<flags>` is also allowed and equivalent to
+`<address>-<same address>:<flags>`.
+
+Here are some examples of valid lines:
+
+* `12345-54321: abc`
+* `54d3f:x`
+* `  aa5b2 - aa67c  : x    y z   `
+
+And here are some examples of invalid lines:
+
+* `12g6z: abc`
+* `112-115: e`
+* `34321 - 22345:`
+* `34321 - 22345 abc`
+* `34321 22345: abc`
+
+## Symbol table file format: `.mima-symbols`
+
+The symbol table file contains the addresses of various labels. It can
+be generated by an assembler in addition to the corresponding `.mima`
+file.
+
+The format is line-based and uses LF as line endings. Other whitespace
+is ignored. A line can either be empty or have the following format:
+
+`<address>:<label name>[ <label name>]*`
+
+* `<address>` is a case-insensitive, hexadecimal, 5 digit number.
+* `<label name>` is the name of a label. It conforms to the regex `[a-zA-Z][a-zA-Z0-9_-]*`.
+
+Here are some examples of valid lines:
+
+* `0a68c: some-label`
+* `20980: label other-label third_label label_nr_4`
+* `  0a68c   :   label    other-label    `
+
+And here are some examples of invalid lines:
+
+* `1234: label`
+* `12134:`
+* `0033c label`
+* `002d4: label-1, label-2, label-3`
+
 ## Conventions
 
 In the source code, the name MiMa is spelled `Mima`. When displayed,