<< Previous | Next >>

writeUserBlock

int writeUserBlock( unsigned addr, void *source, unsigned numbytes );

Description

Rabbit-based boards have a System ID block located on the primary flash. (See the Rabbit Microprocessor Designer's Handbook for more information on the System ID block.) Version 2 and later of this ID block has a pointer to a User ID block: a place intended for storing calibration constants, passwords, and other non-volatile data.

The User block is recommended for storing all non-file data. The User block is where calibration constants are stored for boards with analog I/O. Space in the User block is limited to as small as (8K - sizeof(SysIDBlock)) bytes, or less, if there are calibration constants.

writeUserBlock() writes a number of bytes from root memory to the User block. This block is protected from normal writes to the flash device and can only be accessed through this function or the function writeUserBlockArray().

Using this function can cause all interrupts to be disabled for as long as 20 ms while a flash sector erases, depending on the flash type. A single call can produce as many as four of these erase delays. This will cause periodic interrupts to be missed, and can cause other interrupts to be missed as well. Therefore, it is best to buffer up data to be written rather than to do many writes.

While debugging, several consecutive calls to this function can cause a loss of target serial communications. This effect can be reduced by introducing delays between the calls, lowering the baud rate, or increasing the serial time-out value in the project file.

NOTE	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), writeUserBlock() 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 version of the System ID block doesn't support the User ID block, or no System ID block is present, then 8K bytes starting 16K bytes from the top of the primary flash are designated the User ID block area. However, to prevent errors arising from incompatible large sector configurations, this will only work if the flash type is small sector. Rabbit Semiconductor manufactured boards with large sector flash will have valid System and User ID blocks, so this should not be problem on Rabbit boards.

If users create boards with large sector flash, they must install System ID blocks version 2 or greater to use or modify this function.

Parameters

addr

Address offset in User block to write to.

source

Pointer to source to copy data from.

numbytes

Number of bytes to copy.

Return value

 0: Successful
-1: Invalid address or range

The return values below are new with Dynamic C 10.21:
-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

See also

readUserBlock, writeUserBlockArray