SDPL – Region Mapping

Contents

Region Mapping

Overview

When constructing procedures for things such as flash programs, it is often important to be able to create a list of regions that will be read in a certain order.

The region mapping commands in SDPL allow access to a simple block mapping algorithm that allows easy mapping of regions of an array, and then retrieve the desired data in ordered segments.  Regions of data can also be ‘skipped’ which causes them to be ignored.

With the mapping algorithm, you can do things such as ‘take these blocks first, skip theses blocks, then map the rest automatically’.

MAP_CREATE

This command creates a new (empty) map of a particular array in memory.  Only one map can exist at a time.

The /MAX_BLOCK_SIZE= parameter takes an integer value that specifies the maximum block size that can be mapped.  Blocks larger than this are split into smaller pieces.

The input variable that is specified is remembered, so subsequent commands do not need to name the array in question.

This creates an empty map of $DATA with a max block size of 32 bytes.

MAP_CREATE /MAX_BLOCK_SIZE=32 $DATA

MAP_ADD

This appends a segment to the end of the region map.

The /SIZE= parameter takes an integer and sets the size of this segment.  If not specified, the maximum block size specified at map creation time is used.

This maps the segment at offset 0A 02 with a block size of 24 bytes.

MAP_ADD /SIZE=24 0A 02

MAP_SKIP

This causes a region of the map to be skipped completely.

The syntax is the same as MAP_ADD.

MAP_SKIP /SIZE=24 0A 02

MAP_REMAINDER

This command takes no parameters.  It maps any unmapped (or un-skipped) segments, completing the map automatically.

MAP_REMAINDER

MAP_TAKE

This is how data is retrieved using a map.  It simply takes a %VARIABLE argument, which is used to store the segment.

When you “Take” a value from the map, you are actually copying the segment in memory – the original data array is not modified.

This function sets/unsets the true/false flag in the status register to indicate when the map is empty.  When the map has been exhausted (all mapped data has been taken) the status is set to FALSE.  Otherwise, it is set to TRUE.

You can leverage this run a conditional loop to parse an entire array in chunks very easily.  This example prints the contents of the mapped data in order, segment by segment, until finished:

*REPEAT
MAP_TAKE %CHUNK
IF FALSE GOTO *FINISHED
PRINT /HEX $CHUNK
GOTO *REPEAT
*FINISHED
IF FALSE PRINT "FINISHED"

When ‘taking’ a segment, its offset within the data is copied to the system return variable $*, in 4 byte size.