diff --git a/README.md b/README.md index 811490e..ad90787 100644 --- a/README.md +++ b/README.md @@ -127,10 +127,10 @@ not the contents of the corresponding NVRAM file. The map file contains objects describing sections of the `.nv` file and how to interpret them. They're comprised of the following key/value pairs: -- **label**: A label describing this collection of bytes in the `.nv` file. -- **short_label**: An optional, abbreviated label for use when space is - limited (like in a game launcher on a DMD). -- **encoding** _(required)_: One of the following: +- **_note**: A note for someone maintaining the file; not displayed when + processing an NVRAM file. + +- **encoding** _(required)_ must be one of the following: - `"enum"`: An enumerated type where the byte at `start` is used as an index into a list of strings provided in `values`. - `"int"`: A (possibly) multibyte integer, where each byte is multiplied @@ -152,6 +152,7 @@ how to interpret them. They're comprised of the following key/value pairs: from a WPC game, stored as a sequence of 7 bytes. Starts with a two-byte year (2015 is `0x07 0xDF`), month (1-12), day of month (1-31), day of the week (0-6, 0=Sunday), hour (0-23) and minute (0-59). + - You must specify the location of data in the file using one or more of the following directives: - **start**: Offset into the `.nv` file of the first byte to @@ -163,55 +164,67 @@ how to interpret them. They're comprised of the following key/value pairs: - **offsets**: Alternative to using start/end or start/length when bytes aren't contiguous. List of offsets to use. Either `start` or `offsets` are required. -- **null**: Used for `"ch"` encodings to specify null (0x00) byte handling. - For `truncate` and `terminate`, ignore all bytes after the null. - - `"ignore"`: Ignore (skip over) null bytes. - - `"truncate"`: A null can shorten the string, but won't be present for - strings that fill the allotted space. - - `"terminate"`: Null bytes are always present and terminate the string. -- **min** and **max**: Used for adjustments to specify the valid range of - values. -- **default**: Used for adjustments to specify the factory default value. - Used for the **initials** entry of a high score to indicate the value - for an empty entry (e.g., `" "` on WPC, `"\u0000\u0000\u0000"` on - Gottlieb System 80). Defaults to `0` unless specified. -- **values**: A list of strings used for the `enum` encoding, starting at index 0. - Also used for the `bits` encoding, as values for bit 0, 1, 2, etc. -- **special_values**: A set of key/value pairs for numeric field where some - values have special meaning (for example, `{"0": "OFF"}`). -- **units**: Used to indicate that a field contains a time value as either a - number of `"seconds"` or `"minutes"`, and should be displayed as `HH:MM:SS`. -- **suffix**: A string to append to the value (e.g., `"M"` if the value - represents millions). -- **scale**: A numeric multiplier for a decoded `int`, `bcd`, or `bits`. -- **offset**: A numeric value to add to a decided `int`, `bcd`, or `bits` - value before displaying it. Applied after `scale`. -- **mask**: A mask to apply to each byte before processing. For example, a - mask of `"0x5F"` converts lowercase initials to uppercase and a mask of - `"0x0F"` clears the upper four bits. -- **nibble**: Replacement for `packed` attribute for `ch` and `bcd` types. - Defaults to `both` (previously `packed=true`) indicating use of the full - 8 bits/byte. Set to `low` (previously `packed=false`) to use the lower - 4 bits of the byte or `high` to use the upper 4 bits of the byte. - The `bcd` sequence `0x12 0x34 0x56` translates to `123456` when `nibble` is - `both`, `246` when `nibble` is `low` and `135` when `nibble` is `high`. - Robowars has an example of a `nibble=low` `ch` field, where the sequence - `0x04 0x01 0x04 0x02 0x04 0x03` translates to `0x41 0x42 0x43` which is the - string `"ABC"`. - Stern Dracula and Wild Fyre (identical ROM) have examples of `nibble=high`. -- **packed**: Deprecated in favor of `nibble`. Remove `packed=true` and - replace `packed=false` with `nibble=low`. -- **_note**: A note for someone maintaining the file; not displayed when - processing an NVRAM file. + +- These properties provide additional encoding details. + - **endian**: Set to either `"big"` or `"little"` to indicate the byte + order of multi-byte values. Defaults to the `_endian` setting for the + file (which defaults to `"big"`). + - **nibble**: Replacement for `packed` attribute for `ch` and `bcd` types. + Defaults to `both` (previously `packed=true`) indicating use of the full + 8 bits/byte. Set to `low` (previously `packed=false`) to use the lower + 4 bits of the byte or `high` to use the upper 4 bits of the byte. + The `bcd` sequence `0x12 0x34 0x56` translates to `123456` when `nibble` is + `both`, `246` when `nibble` is `low` and `135` when `nibble` is `high`. + Robowars has an example of a `nibble=low` `ch` field, where the sequence + `0x04 0x01 0x04 0x02 0x04 0x03` translates to `0x41 0x42 0x43` which is the + string `"ABC"`. + Stern Dracula and Wild Fyre (identical ROM) have examples of `nibble=high`. + - **null**: Used for `"ch"` encodings to specify null (0x00) byte handling. + For `truncate` and `terminate`, ignore all bytes after the null. + - `"ignore"`: Ignore (skip over) null bytes. Default setting. + - `"truncate"`: A null can shorten the string, but won't be present for + strings that fill the allotted space. + - `"terminate"`: Null bytes are always present and terminate the string. + - **packed**: Deprecated in favor of `nibble`. Remove `packed=true` and + replace `packed=false` with `nibble=low`. + +- These properties are only related to displaying the value, independently of + how it's actually stored in memory or a `.nv` file. + - **label**: A label describing this collection of bytes in the `.nv` file. + - **short_label**: An optional, abbreviated label for use when space is + limited (like in a game launcher on a DMD). + - **values**: A list of strings used for the `enum` encoding, starting at index 0. + Also used for the `bits` encoding, as values for bit 0, 1, 2, etc. + - **special_values**: A set of key/value pairs for a numeric field where some + values have special meaning (for example, `{"0": "OFF"}`). + - **units**: Used to indicate that a field contains a time value as either a + number of `"seconds"` or `"minutes"`, and should be displayed as `HH:MM:SS`. + - **suffix**: A string to append to the value (e.g., `"M"` if the value + represents millions). + - **scale**: A numeric multiplier for a decoded `int`, `bcd`, or `bits`. + - **offset**: A numeric value to add to a decoded `int`, `bcd`, or `bits` + value before displaying it. Applied after `scale`. + - **mask**: A mask to apply to each byte before processing. For example, a + mask of `"0x5F"` converts lowercase initials to uppercase and a mask of + `"0x0F"` clears the upper four bits. + +- Encodings can include properties that describe limitations imposed on + adjustments in the service menu, or just ranges that the ROM considers + invalid. These all pertain to the stored value, exclusive of any `scale` + or `offset`. + - **default**: The factory default value. + Used for the **initials** entry of a high score to indicate the value + for an unused entry (e.g., `" "` on WPC, `"\u0000\u0000\u0000"` on + Gottlieb System 80). Defaults to `0` unless specified. + - **min** and **max**: The valid range of values. + - **multiple_of**: Enforce a subset of values between `min` and `max`. + Defaults to `1` (all values allowed) unless specified. ### File Map Keys that don't start with an underscore typically have groups of **descriptors** as their values. -- **endian**: Set to either `"big"` or `"little"` to indicate the byte - order of multi-byte values in the ROM file. Defaults to the `_endian` - setting for the file (which defaults to `"big"`). - **last_played**: A descriptor (likely with a `wpc_rtc` encoding) with a date stamp of when PinMAME last saved the file. - **last_game**: An array of up to four descriptors representing scores