Optional
blocks: null | Iterable<[number, Buffer]> | { [key: string]: Buffer }The initial value for the memory blocks inside this S19MemoryMap. All keys must be numeric, and all values must be instances of Buffer. Optionally it can also be a plain Object with only numeric keys.
Returns a String of text representing a .s19 file.
The writer has an opinionated behaviour. Automatically chooses between S1 (16-bit), S2 (24-bit), and S3 (32-bit)
records based on the maximum address. Uses S2 if any address exceeds 0xFFFF, S3 if any address exceeds 0xFFFFFF.
Optional
lineSize: number = 16Maximum number of bytes to be encoded in each data record. Must have a value between 1 and 255, as per the specification.
String of text with the .s19 representation of the input binary data
Performs a deep copy of the current S19MemoryMap
, returning a new one
with exactly the same contents, but allocating new memory for each of its
Buffers.
Checks whether the current memory map contains the one given as a parameter.
The memory map to check
Locates the Buffer which contains the given offset, and returns the four bytes held at that offset, as a 32-bit unsigned integer.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getUint32|DataView.prototype.getUint32
,
except that this operates over a S19MemoryMap
instead of
over an ArrayBuffer, and that this may return undefined if
the address is not entirely contained within one of the Buffers.
The memory offset to read the data
Optional
littleEndian: booleanWhether to fetch the 4 bytes as a little- or big-endian integer
An unsigned 32-bit integer number
Returns a new instance of S19MemoryMap
, containing
the same data, but concatenating together those memory blocks that are adjacent.
The insertion order of keys in the S19MemoryMap
is guaranteed to be strictly
ascending. In other words, when iterating through the S19MemoryMap
, the addresses
will be ordered in ascending order.
If maxBlockSize is given, blocks will be concatenated together only
until the joined block reaches this size in bytes. This means that the output
S19MemoryMap
might have more entries than the input one.
If there is any overlap between blocks, an error will be thrown.
The returned S19MemoryMap
will use newly allocated memory.
Optional
maxBlockSize: number = InfinityMaximum size of the Buffers in the
returned S19MemoryMap
.
Returns a new instance of S19MemoryMap
, where:
S19MemoryMap
is guaranteed
to be strictly ascending. In other words, when iterating through the
S19MemoryMap
, the addresses will be ordered in ascending order.
Optional
pageSize: number = 1024The size of the output pages, in bytes
Optional
pad: number = 0xffThe byte value to use for padding
Returns a new instance of S19MemoryMap
, containing only data between
the addresses address and address + length.
Behaviour is similar to https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/slice|Array.prototype.slice
,
in that the return value is a portion of the current S19MemoryMap
.
S19MemoryMap
might be empty.
The start address of the slice
The length of memory map to slice out
Returns a new instance of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getUint32|Buffer
, containing only data between
the addresses address and address + length. Any byte without a value
in the input S19MemoryMap
will have a value of padByte.
The start address of the slice
The length of memory map to slice out
Optional
padByte: number = 0xffThe value of the byte assumed to be used as padding
Static
flattenGiven the output of the overlapS19MemoryMaps
(a Map of address to an Array of (id, Buffer) tuples),
returns a S19MemoryMap
. This discards the IDs in the process.
The output Map contains as many entries as the input one (using the same addresses
as keys), but the value for each entry will be the Buffer of the last
tuple for each address in the input data.
The scenario is wanting to join together several parsed .s19 files, not worrying about
their overlaps.
The (possibly overlapping) input memory blocks
The flattened memory blocks
Static
fromGiven one Buffer, looks through its contents and returns a new
S19MemoryMap
, stripping away those regions where there are only
padding bytes.
The start of the input Buffer is assumed to be offset zero for the output.
The use case here is dumping memory from a working device and try to see the
"interesting" memory regions it has. This assumes that there is a constant,
predefined padding byte value being used in the "non-interesting" regions.
In other words: this will work as long as the dump comes from a flash memory
which has been previously erased (thus 0xFFs for padding), or from a
previously blanked HDD (thus 0x00s for padding).
This method uses subarray on the input data, and thus does not allocate memory
for the Buffers.
The input data
Optional
padByte: number = 0xffThe value of the byte assumed to be used as padding
Optional
minPadLength: number = 64The minimum number of consecutive pad bytes to be considered actual padding
Static
fromParses a string containing data formatted in "Motorola S-record" format, and
returns an instance of S19MemoryMap
.
Supports S0 (header), S1 (16-bit data), S2 (24-bit data), S3 (32-bit data), S5/S6 (count), S7/S8/S9 (end) records.
The insertion order of keys in the S19MemoryMap
is guaranteed to be strictly
ascending. In other words, when iterating through the S19MemoryMap
, the addresses
will be ordered in ascending order.
The parser has an opinionated behaviour, and will throw a descriptive error if it
encounters some malformed input.
If maxBlockSize is given, any contiguous data block larger than that will
be split in several blocks.
The contents of a .s19 file.
Optional
maxBlockSize: number = InfinityMaximum size of the returned Buffers.
import {S19MemoryMap} from 'ECB';
let srecordString =
"S00F000068656C6C6F202020202000003C\n" +
"S11F00007C0802A6900100049421FFF07C6C1B787C8C23784E800020E8010010C\n" +
"S5030001FB\n" +
"S9030000FC";
let memMap = S19MemoryMap.fromS19(srecordString);
for (let [address, dataBlock] of memMap) {
console.log('Data block at ', address, ', bytes: ', dataBlock);
}
Static
overlapGiven a https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map|Map
of S19MemoryMap
s, indexed by a alphanumeric ID,
returns a Map of address to tuples (Arrayss of length 2) of the form
(id, Buffer)s.
The scenario for using this is having several S19MemoryMap
s, from several calls to
module:ECB~s19ToArrays|s19ToArrays, each having a different identifier.
This function locates where those memory block sets overlap, and returns a Map
containing addresses as keys, and arrays as values. Each array will contain 1 or more
(id, Buffer) tuples: the identifier of the memory block set that has
data in that region, and the data itself. When memory block sets overlap, there will
be more than one tuple.
The Buffers in the output are
https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray|subarrays
of the input data; new memory is not allocated for them.
The insertion order of keys in the output Map is guaranteed to be strictly
ascending. In other words, when iterating through the Map, the addresses
will be ordered in ascending order.
When two blocks overlap, the corresponding array of tuples will have the tuples ordered
in the insertion order of the input Map of block sets.
The input memory block sets
The map of possibly overlapping memory blocks
Example