Blockmap
This module implements Tizen's block map format, which maps non-empty blocks or block ranges from a raw image file, making it possible to quickly & efficiently flash the image to the target block device by only reading & writing the necessary blocks.
npm
Install via$ npm install --save blockmap
Usage
For detailed API documentation, see /doc
.
const BlockMap =
Parsing a Block Map
const blockMap = BlockMap.parse(xml)
BlockMap version: '2.0' imageSize: 821752 blockSize: 4096 blocksCount: 201 mappedBlocksCount: 117 checksum: '44e9d58de533d5eb94f8232cff22b2e6d71b15d369c2ac2af461c63164cce324' checksumType: 'sha256' ranges: checksum: '9eaf19215d55d23de1be1fe4bed4a95bfe620a404352fd06e782738fff58e500' start: 0 end: 1 checksum: 'e8a26f49a71262870f8294a73f40f122d622fd70fb82bef01c0322785e9fd6b2' start: 3 end: 5 // More ranges omitted for brevity checksum: 'cb732fc3f3a0f81f6a761a534201c05549c8efe4a92630ccd24241f72d7d618c' start: 198 end: 199
Creating a Block Map
Render a .bmap
file from a parsed or otherwise constructed BlockMap
:
const blockMap = BlockMapconst xml = blockMap
Where xml
would look like the following, given the block map from above:
821752 4096 201 117 sha256 44e9d58de533d5eb94f8232cff22b2e6d71b15d369c2ac2af461c63164cce324 0-1 3-5 <!-- More ranges omitted for brevity --> 198-199
NOTE: Regardless of input version, blockMap.toString()
will always
create a .bmap
in the format of the latest version (currently 2.0
).
Block Map Checksum Verification
By default, checksums for mapped ranges and the bmap file itself (only version 1.3+)
will be verified when parsing or streaming. If you need to disable verification,
pass false
as verify
parameter.
// Disable verification of the bmap file checksum:const blockMap = BlockMap
const ReadStream = // Disable range checksum verification:const blockReadStream = fileDescriptor blockMap false
const FilterStream = // Same for filter streams:const filterStream = blockMap false
Reading Mapped Blocks
NOTE: These examples just use fs.writeSync()
in .on('readable')
for brevity;
of course this should be implemented properly in a writable stream, which the readable
side (i.e. the ReadStream
or FilterStream
) is piped to.
Use a parsed block map to read only mapped regions:
const blockMap = BlockMapconst blockReadStream = fileDescriptor blockMap // The chunk emitted will have two properties set;// 1) chunk.buffer – the data buffer// 2) chunk.position – the chunk's offset (or address) in bytes// Which can then be used to write only those blocks to the target:blockReadStream blockReadStream
Filtering Unmapped Blocks
Use a filter transform to filter out unmapped blocks from a stream:
const blockMap = BlockMapconst readStream = fsconst filterStream = blockMap // The chunk emitted will have two properties set;// 1) chunk.buffer – the data buffer// 2) chunk.position – the chunk's offset (or address) in bytes// Which can then be used to write only those blocks to the target:filterStream // Pipe the readable stream into the block filter:readStream
Verifying a Flashed Device
Use a ReadStream
to verify a flashed device image:
const ReadStream = ; { fileDescriptor blockMap } const blockMap = BlockMap
Handling Errors
Parsing
BlockMap.parse()
and blockMap.parse()
will throw when
encountering invalid input, or if the checksum doesn't verify:
try blockMap = BlockMap catcherror // ...
Streams
If the error is due to a checksum mismatch,
the error will have a .checksum
and .range
property,
denoting the calculated checksum, and the range for which it occured:
const blockReadStream = fileDescriptor blockMap blockReadStream