diff --git a/README.md b/README.md index 0feec41..996ed05 100644 --- a/README.md +++ b/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: + +`-:` + +* `` and `` are case-insensitive, + hexadecimal, 5 digit numbers. `` is inclusive. +* `` are multiple characters (at least one). + +The format `
:` is also allowed and equivalent to +`
-:`. + +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: + +`
: