<< Previous | Next >>

writeUserBlockArray

int writeUserBlockArray( unsigned addr, void * sources[], unsigned numbytes[], int numsources );

Description

Rabbit Semiconductor boards are released with System ID blocks located on the primary flash. Version 2 and later of this ID block has a pointer to a User block that can be used for storing calibration constants, passwords, and other non-volatile data. The User block is protected from normal write to the flash device and can only be accessed through this function or writeUserBlock().

This function writes a set of scattered data from root memory to the User block. If the data to be written are in contiguous bytes, using the function writeUserBlock()is sufficient. Use of writeUserBlockArray() is recommended when the data to be written is in noncontiguous bytes, as may be the case for something like network configuration data.

See the designer's handbook for your Rabbit processor (e.g., the Rabbit 4000 Designer's Handbook) for more information about the System ID and User blocks.

NOTE	Portions of the User block may be used by the BIOS for your board to store values, e.g., calibration constants. See the manual for your particular board for more information before overwriting any part of the User block.

NOTE

When using a board with serial bootflash (e.g., RCM4300, RCM4310), writeUserBlockArray() should be called until it returns zero or a negative error code. A positive return value indicates that the SPI port needed by the serial flash is in use by another device. However, if using µC/OS-II and _SPI_USE_UCOS_MUTEX is #defined, then this function only needs to be called once. If the mutex times out waiting for the SPI port to free up, the run time error ERR_SPI_MUTEX_ERROR will occur. See the description for _rcm43_InitUCOSMutex() for more information on using µC/OS-II and _SPI_USE_UCOS_MUTEX.

Backwards Compatibility:

If the System ID block on the board doesn't support the User block, or no System ID block is present, then the 8K bytes starting 16K bytes from the top of the primary flash are designated User block area. This only works if the flash type is small sector. Rabbit manufactured boards with large sector flash will have valid System ID and User blocks, so is not a problem on Rabbit boards. If users create boards with large sector flash, they must install System ID blocks version 3 or greater to use this function, or modify this function.

Parameters

addr

Address offset in User block to write to.

sources

Array of pointer to sources to copy data from.

numbytes

Array of number of bytes to copy for each source. The sum of the lengths in this array must not exceed 32767 bytes, or an error will be returned.

numsources

Number of data sources.

Return value

 0: Successful.
-1: Invalid address or range.
-2: No valid User block found (block version 3 or later).
-3: Flash writing error.

The return values below are applicable only if _SPI_USE_UCOS_MUTEX is not #defined:
-ETIME: (Serial flash only, time out waiting for SPI)
postive N: (Serial flash only, SPI in use by device N)

Library

IDBLOCK.LIB