PREV NEXT


1. Function Descriptions

abs 



int abs(int x);

Description

Computes the absolute value of an integer argument.

Parameters 


x

Interger argument

Return value

Absolute value of the argument.

Library 


MATH.LIB

See also 


fabs

acos 



float acos(float x);

Description

Computes the arccosine of real float value x.

Parameters 


x

Assumed to be between -1 and 1.

Return value

Arccosine of the argument.
If x is out of bounds, the function returns 0 and signals a domain error.

Library 


MATH.LIB

See also 


cos, cosh, asin, atan

acot 



float acot(float x);

Description

Computes the arcotangent of real float value x.

Parameters 


x

Assumed to be between -INF and +INF.

Return value

Arccotangent of the argument.

Library 


MATH.LIB

See also 


tan, atan

acsc 



float acsc(float x);

Description

Computes the arccosecant of real float value x.

Parameters 


x

Assumed to be between -INF and +INF.

Return value

The arccosecant of the argument.

Library 


MATH.LIB

See also 


sin, asin

AESdecrypt 



void AESdecrypt(char *data, char *expandedkey, int nb, int nk );

Description

Decrypts a block of data using an implementation of the Rijndael AES cipher. The encryped block of data is overwritten by the decrypted block of data.

Parameters 


data

A block of data to be decrypted. 


expandedkey

A set of round keys (generated by AESexpandKey()). 


nb

The block size to use. Block is 4 * nb bytes long. 


nk

The key size to use. Cipher key is 4 * nk bytes long.

Library 


AES_CRYPT.LIB

AESdecryptStream 



 void AESdecryptStream(AESstreamState *state, char *data, int count);

Description

Decrypts an array of bytes using the Rabbit implementation of cipher feedback mode. See Samples\Crypt\AES_STREAMTEST.C for a sample program and a detailed explanation of the encryption/decryption process.

Parameters 


state

The AESstreamState structure. This memory must be allocated in the program code before calling AESdecrptyStream(): 


static AESstreamState decrypt_state;


data

An array of bytes that will be decrypted in place. 


count

Size of data array

Library 


AES_CRYPT.LIB

AESencrypt 



void AESencrypt(char *data, char *expandedkey, int nb, int nk );

Description

Encrypts a block of data using an implementation of the Rijndael AES cipher. The block of data is overwritten by the encrypted block of data.

Parameters 


data

A block of data to be encrypted 


expandedkey

A set of round keys (generated by AESexpandKey()) 


nb

The block size to use. Block is 4 * nb bytes long 


nk

The key size to use. Cipher key is 4 * nk bytes long

Return value

None.

Library 


AES_CRYPT.LIB

AESencryptStream 



void AESencryptStream(AESstreamState *state, char *data, int count);

Description

Encrypts an array of bytes using the Rabbit implementation of cipher feedback mode. See Samples\Crypt\AES_STREAMTEST.C for a sample program and a detailed explanation of the encryption/decryption process.

Parameters 


state

The AESstreamState structure. This memory must be allocated in the program code before calling AESencrptyStream(): 


static AESstreamState encrypt_state;


data

An array of bytes that will be encrypted in place. 


count

Size of data array.

Library 


AES_CRYPT.LIB

AESexpandKey 



void AESexpandKey(char *expanded, char *key, int nb, int nk, int rounds);

Description

Prepares a key for use by expanding it into a set of round keys. A key is a "password" to decipher encoded data.

Parameters 


expanded

A buffer for storing the expanded key. The size of the expanded key is 4 * nb * (rounds + 1). 


key

The cipher key, the size should be 4 * nk 


nb

The block size will be 4 * nb bytes long. 


nk

The key size will be 4 * nk bytes long. 


rounds

The number of cipher rounds to use.

Return value

None.

Library 


AES_CRYPT.LIB

AESinitStream 



void AESinitStream(AESstreamState *state, char *key, char *init_vector);

Description

Sets up AESstreamState to begin encrypting or decrypting a stream. Each AESstreamState structure can only be used for one direction. See Samples\Crypt\AES_STREAMTEST.C for a sample program and a detailed explanation of the encryption/decryption process.

Parameters 


state

An AESstreamState structure to be initialized. This memory must be allocated in the program code before calling AESinitStream(). 


key

The 16-byte cipher key, using a NULL pointer will prevent an existing key from being recalculated. 


init_vector

A 16-byte array representing the initial state of the feedback registers. Both ends of the stream must begin with the same initialization vector.

Return value

None.

Library 


AES_CRYPT.LIB

asec 



float asec(float x);

Description

Computes the arcsecant of real float value x.

Parameters 


x

Assumed to be between -INF and +INF.

Return value

The arcsecant of the argument.

Library 


MATH.LIB

See also 


cos, acos

asin 



float asin(float x);

Description

Computes the arcsine of real float value x.

Parameters 


x

Assumed to be between -1 and +1.

Return value

The arcsine of the argument.

Library 


MATH.LIB

See also 


sin, acsc

atan 



float atan(float x);

Description

Computes the arctangent of real float value x.

Parameters 


x

Assumed to be between -INF and +INF.

Return value

The arctangent of the argument.

Library 


MATH.LIB

See also 


tan, acot

atan2 



float atan2(float y, float x);

Description

Computes the arctangent of real float value y/x to find the angle in radians between the x-axis and the ray through (0,0) and (x,y).

Parameters 


y

The point corresponding to the y-axis 


x

The point corresponding to the x-axis

Return value

If both y and x are zero, the function returns 0 and signals a domain error. Otherwise the arctangent of y/x is returned as follows:

Returned Value
 		Parameter Values

angle

x ≠ 0, y ≠ 0

PI/2

x = 0, y > 0

-PI/2

x = 0, y <

0

x > 0, y = 0

PI

x < 0, y = 0

Library 


MATH.LIB

See also 


acos, asin, atan, cos, sin, tan

atof 



float atof(char *sptr);

Description

ANSI String to Float Conversion (UNIX compatible).

Parameters 


sptr

String to convert.

Return value

The converted floating value.
If the conversion is invalid, _xtoxErr is set to 1. Otherwise _xtoxErr is set to 0.

Library 


STRING.LIB

See also 


atoi, atol, strtod

atoi 



int atoi(char *sptr);

Description

ANSI String to Integer Conversion (UNIX compatible).

Parameters 


sptr

String to convert.

Return value

The converted integer value.

Library 


STRING.LIB

See also 


atol, atof, strtod

atol 



long atol(char *sptr);

Description

ANSI String to Long Conversion (UNIX compatible).

Parameters 


sptr

String to convert.

Return value

The converted long integer value.

Library 


STRING.LIB

See also 


atoi, atof, strtod

bit 



unsigned int bit(void *address, unsigned int bit);

Description

Dynamic C may expand this call inline

Reads specified bit at memory address. bit may be from 0 to 31. This is equivalent to the following expression, but more efficient: (*(long *)address >> bit) & 1

Parameters 


address

Address of byte containing bits 7-0 


bit

Bit location where 0 represents the least significant bit

Return value

1: Specified bit is set.
0: Bit is clear.

Library 


UTIL.LIB

See also 


BIT

BIT 



unsigned int BIT(void *address, unsigned int bit);

Description

Dynamic C may expand this call inline

Reads specified bit at memory address. bit may be from 0 to 31. This is equivalent to the following expression, but more efficient: (*(long *)address>>bit) &1

Parameters 


address

Address of byte containing bits 7-0 


bit

Bit location where 0 represents the least significant bit

Return value

1 if specified bit is set; 0 if bit is clear.

Library 


UTIL.LIB

See also 


bit

BitRdPortE 



root int BitRdPortE(unsigned int port, int bitnumber);

Description

Returns 1 or 0 matching the value of the bit read from the specified external I/O port.

Parameters 


port

Address of external parallel port data register. 


bitnumber

Bit to read (0-7).

Return value

0 or 1: The value of the bit read.

Library 


SYSIO.LIB

See also 


RdPortI, BitRdPortI, WrPortI, BitWrPortI, RdPortE, WrPortE, BitWrPortE

BitRdPortI 



int BitRdPortI(int port, int bitnumber);

Description

Returns 1 or 0 matching the value of the bit read from the specified internal I/O port.

Parameters 


port

Address of internal parallel port data register. 


bitnumber

Bit to read (0-7).

Return value

0 or 1: The value of the bit read.

Library 


SYSIO.LIB

See also 


RdPortI, WrPortI, BitWrPortI, BitRdPortE, RdPortE, WrPortE, BitWrPortE

BitWrPortE 



void BitWrPortE( unsigned int port, char *portshadow, int value, int bitcode);

Description

Updates shadow register at bitcode with value (0 or 1) and copies shadow to register.

WARNING! A shadow register is required for this function.

Parameters 


port

Address of external parallel port data register. 


portshadow

Reference pointer to a variable to shadow the current value of the register. 


value

Value of 0 or 1 to be written to the bit position. 


bitcode

Bit position 0-7.

Library 


SYSIO.LIB

See also 


RdPortI, BitRdPortI, WrPortI, BitWrPortI, BitRdPortE, RdPortE, WrPortE

BitWrPortI 



void BitWrPortI( int port, char *portshadow, int value, int bitcode);

Description

Updates shadow register at position bitcode with value (0 or 1); copies shadow to register.

WARNING! A shadow register is required for this function.

Parameters 


port

Address of internal parallel port data register. 


portshadow

Reference pointer to a variable to shadow the current value of the register. 


value

Value of 0 or 1 to be written to the bit position. 


bitcode

Bit position 0-7.

Library 


SYSIO.LIB

See also 


RdPortI, BitRdPortI, WrPortI, BitRdPortE, RdPortE, WrPortE, BitWrPortE

ceil 



float ceil(float x);

Description

Computes the smallest integer greater than or equal to the given number.

Parameters 


x

Number to round up.

Return value

The rounded up number.

Library 


MATH.LIB

See also 


floor, fmod

chkHardReset 



int chkHardReset( void );

Description

This function determines whether this restart of the board is due to a hardware reset. Asserting the RESET line or recycling power are both considered hardware resets. A watchdog timeout is not a hardware reset.

Return value

1: The processor was restarted due to a hardware reset.
0: If it was not.

Library 


Sys.lib

See Also 


chkSoftReset, chkWDTO, _sysIsSoftReset

chkSoftReset 



int chkSoftReset( void );

Description

This function determines whether this restart of the board is due to a software reset from Dynamic C or a call to forceSoftReset().

Return value

1: The board was restarted due to a soft reset.
0: If it was not.

Library 


Sys.lib

See Also

chkHardReset, chkWDTO, _sysIsSoftReset

chkWDTO 



int chkWDTO( void );

Description

This function determines whether this restart of the board is due to a watchdog timeout.

Return value

1: If the board was restarted due to a watchdog timeout.
0: If it was not.

Library 


Sys.lib

See Also

chkHardReset, chkSoftReset, _sysIsSoftReset

clockDoublerOn 



void clockDoublerOn();

Description

Enables the Rabbit clock doubler. If the doubler is already enabled, there will be no effect. Also attempts to adjust the communication rate between Dynamic C and the board to compensate for the frequency change. User serial port rates need to be adjusted accordingly. Also note that single-stepping through this routine will cause Dynamic C to lose communication with the target.

Library 


SYS.LIB

See also 


clockDoublerOff

clockDoublerOff 



void clockDoublerOff();

Description

Disables the Rabbit clock doubler. If the doubler is already disabled, there will be no effect. Also attempts to adjust the communication rate between Dynamic C and the board to compensate for the frequency change. User serial port rates need to be adjusted accordingly. Also note that single-stepping through this routine will cause Dynamic C to lose communication with the target.

Library 


SYS.LIB

See also 


clockDoublerOn

CoBegin 



void CoBegin(CoData *p);

Description

Initialize a costatement structure so the costatement will be executed next time it is encountered.

Parameters 


p

Address of costatement

Library 


COSTATE.LIB

cof_pktXreceive 



int cof_pktXreceive(void *buffer, int buffer_size); X=A|B|C|D

Description

Receives an incoming packet. This function will return after a complete packet has been read into the buffer.

Starting with Dynamic C version 7.25, the functions cof_pktEreceive() and cof_pktFreceive() are available when using the Rabbit 3000 microprocessor.

Parameters 


buffer

A buffer for the packet to be written into. 


buffer_size

Length of the buffer.

Return value

>0: The number of bytes in the received packet on success.
 0: No new packets have been received.
-1: The packet is too large for the given buffer.
-2: A needed test_packet function is not defined.

Library 


PACKET.LIB

cof_pktXsend 



void cof_pktXsend(void *send_buffer int buffer_length, char delay); X=A|B|C|D

Description

Initiates the sending of a packet of data. The function will exit when the packet is finished transmitting.

Starting with Dynamic C version 7.25, the functions cof_pktEsend() and cof_pktFsend() are available when using the Rabbit 3000 microprocessor.

Parameters 


send_buffer

The data to be sent. 


buffer_length

Length of the data buffer to transmit. 


delay

The number of byte times (0-255) to delay before sending data. This is used to implement protocol-specific delays between packets.

Library 


PACKET.LIB

cof_serXgetc 



int cof_serXgetc(); /* where X = A|B|C|D */

Description

This single-user cofunction yields to other tasks until a character is read from port X. This function only returns when a character is successfully written. It is non-reentrant.

Starting with Dynamic C version 7.25, the functions cof_serEgetc() and cof_serFgetc() may be used with the Rabbit 3000 microprocessor.

Return value

An integer with the character read into the low byte.

Library 


RS232.LIB

Example 

// echoes characters
main() {
   int c;
   serXopen(19200);
   loopinit();
   while (1) {
      loophead();
      wfd c = cof_serAgetc();
      wfd cof_serAputc(c);
   }
   serAclose();
}

cof_serXgets 



int cof_serXgets(char *s, int max, unsigned long tmout);
/* where X = A|B|C|D */

Description

This single-user cofunction reads characters from port X until a NULL terminator, linefeed, or carriage return character is read, max characters are read, or until tmout milliseconds transpires between characters read. A timeout will never occur if no characters have been received. This function is non-reentrant.

It yields to other tasks for as long as the input buffer is locked or whenever the buffer becomes empty as characters are read. s will always be NULL terminated upon return.

Starting with Dynamic C version 7.25, the functions cof_serEgets() and cof_serFgets() may be used with the Rabbit 3000 microprocessor.

Parameters 


s

Character array into which a NULL terminated string is read. 


max

The maximum number of characters to read into s. 


tmout

Millisecond wait period to allow between characters before timing out.

Return value

1 if CR or max bytes read into s.
0 if function times out before reading CR or max bytes.

Library 


RS232.LIB

Example 

// echoes NULL terminated character strings

main() {
   int getOk;
   char s[16];
   serAopen(19200);
   loopinit();
   while (1) {
      loophead();
      costate {
         wfd getOk = cof_serAgets (s, 15, 20);
         if (getOk) {
            wfd cof_serAputs(s);
         }
         else {          // timed out: s null terminated,
         }               // but incomplete
      }
   }
   serAclose();
}

cof_serXputc 



void cof_serXputc(int c); /* where X = A|B|C|D */

Description

This single-user cofunction writes a character to serial port X, yielding to other tasks when the input buffer is locked. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions cof_serEputc() and cof_serFputc() may be used with the Rabbit 3000 microprocessor.

Parameters 


c

Character to write.

Library 


RS232.LIB

Example 

// echoes characters
main() {
   int c;
   serAopen(19200);
   loopinit();
   while (1) {
      loophead();
      wfd c = cof_serAgetc();
      wfd cof_serAputc(c);
   }
   serAclose();
}

cof_serXputs 



void cof_serXputs(char *str); /* where X = A|B|C|D */

Description

This single-user cofunction writes a NULL terminated string to port X. It yields to other tasks for as long as the input buffer may be locked or whenever the buffer may become full as characters are written. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions cof_serEputs() and cof_serFputs() may be used with the Rabbit 3000 microprocessor.

Parameters 


str

NULL-terminated character string to write.

Library 


RS232.LIB

Example 

// writes a NULL-terminated character string, repeatedly
main() {
   const char s[] = "Hello Z-World";
   serAopen(19200);
   loopinit();
   while (1) {
      loophead();
      costate {
         wfd cof_serAputs(s);
      }
   }
   serAclose();
}

cof_serXread 



int cof_serXread(void* data, int length, unsigned long tmout); /* where X = A|B|C|D */

Description

This single-user cofunction reads length characters from port X or until tmout milliseconds transpires between characters read. It yields to other tasks for as long as the input buffer is locked or whenever the buffer becomes empty as characters are read. A timeout will never occur if no characters have been read. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions cof_serEread() and cof_serFread() may be used with the Rabbit 3000 microprocessor.

Parameters 


data

Data structure into which characters are read. 


length

The number of characters to read into data. 


tmout

Millisecond wait period to allow between characters before timing out.

Return value

Number of characters read into data.

Library 


RS232.LIB

Example 

// echoes a block of characters
main() {
   int n;
   char s[16];
   serAopen(19200);
   loopinit();
   while (1) {
      loophead();
      costate {
         wfd n = cof_serAread(s, 15, 20);
         wfd cof_serAwrite(s, n);
      }
   }
   serAclose();
}

cof_serXwrite 



void cof_serXwrite(void *data, int length);
 /* where X = A|B|C|D */

Description

This single-user cofunction writes length bytes to port X. It yields to other tasks for as long as the input buffer is locked or whenever the buffer becomes full as characters are written. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions cof_serEwrite() and cof_serFwrite() may be used with the Rabbit 3000 microprocessor.

Parameters 


data

Data structure to write. 


length

Number of bytes in data to write.

Library 


RS232.LIB

Example 


// writes a block of characters, repeatedly
main() {
   const char s[] = "Hello Z-World";
   serAopen(19200);
   loopinit();
   while (1) {
      loophead();
      costate {
         wfd cof_serAwrite(s, strlen(s));
      }
   }
   serAclose();
}

CoPause 



void CoPause(CoData *p);

Description

Pause execution of a costatement so that it will not run the next time it is encountered unless and until CoResume(p) or CoBegin(p) are called.

Parameters 


p

Address of costatement

Library 


COSTATE.LIB

CoReset 



void CoReset(CoData *p);

Description

Initializes a costatement structure so the costatement will not be executed next time it is encountered (unless the costatement is declared to be always_on).

Parameters 


p

Address of costatement

Library 


COSTATE.LIB

CoResume 



void CoResume(CoData *p);

Description

Resume execution of a costatement that has been paused.

Parameters 


p

Address of costatement

Library 


COSTATE.LIB

cos 



float cos(float x);

Description

Computes the cosine of real float value x (radians).

Parameters 


x

Radian value to compute

Return value

Cosine of the argument.

Library 


MATH.LIB

See also 


acos, cosh, sin, tan

cosh 



float cosh(float x);

Description

Computes the hyperbolic cosine of real FLOAT value x.

Parameters 


x

value to compute

Return value

Hyperbolic cosine
If |x| > 89.8 (approx.), the function returns INF and signals a range error.

Library 


MATH.LIB

See also 


cos, acos, sin, sinh, tan, tanh

defineErrorHandler 



void defineErrorHandler(void *errfcn)

Description

Sets the BIOS function pointer for runtime errors to the function pointed to by errfcn. This user-defined function must be in root memory. Specify root at the start of the function definition to ensure this. When a runtime error occurs, the following information is passed to the error handler on the stack:

Stack Position
Stack Contents
SP+0 Return address for exceptionRet
SP+2 Error code
SP+4 0x0000 (can be used for additional information)
SP+6 XPC when exception() was called (upper byte)
SP+8 Address where exception() was called

Parameters 


errfcn

Pointer to user-defined run-time error handler.

Library 


SYS.LIB

deg 



float deg(float x);

Description

Changes float radians x to degrees

Parameters 


x

Radian value to convert

Return value

Angle in degrees (a float).

Library 


MATH.LIB

See also 


rad

DelayMs 



int DelayMs(long delayms);

Description

Millisecond time mechanism for the costatement "waitfor" constructs. The initial call to this function starts the timing. The function returns zero and continues to return zero until the number of milliseconds specified has passed.

Parameters 


delayms

The number of milliseconds to wait.

Return value

1: The specified number of milliseconds have elapsed
0: The specified number of milliseconds have not elapsed.

Library 


COSTATE.LIB

DelaySec 



int DelaySec(long delaysec);

Description

Second time mechanism for the costatement "waitfor" constructs. The initial call to this function starts the timing. The function returns zero and continues to return zero until the number of seconds specified has passed.

Parameters 


delaysec

The number of seconds to wait.

Return value

1: The specified number of seconds have elapsed.
0: The specified number of seconds have not elapsed.

Library 


COSTATE.LIB

DelayTicks 



int DelayTicks(unsigned ticks);

Description

Tick time mechanism for the costatement "waitfor" constructs. The initial call to this function starts the timing. The function returns zero and continues to return zero until the number of ticks specified has passed.

1 tick = 1/1024 second.

Parameters 


ticks

The number of ticks to wait.

Return value

1: The specified tick delay has elapsed.
0: The specified tick delay has not elapsed.

Library 


COSTATE.LIB

Disable_HW_WDT 



void Disable_HW_WDT();

Description

Disables the hardware watchdog timer on the Rabbit processor. Note that the watchdog will be enabled again just by hitting it. The watchdog is hit by the periodic interrupt, which is on by default. This function is useful for special situations such as low power "sleepy mode."

Library 


SYS.LIB

errlogGetHeaderInfo 



root char* errlogGetHeaderInfo();

Description

Reads the error log header and formats the output.

When running stand alone (not talking to Dynamic C), this function reads the header directly from the log buffer. When in debug mode, this function reads the header from the copy in flash.

When a Dynamic C cold boot takes place, the header in RAM is zeroed out to initialize it, but first its contents are copied to an address in the BIOS code before the BIOS in RAM is copied to flash. This means that on the second cold boot, the data structure in flash will be zeroed out. The configuration of the log buffer may still be read, and the log buffer entries are not affected.

Because the exception mechanism resets the processor by causing a watchdog time-out, the number of watchdog time-outs reported by this functions is the number of actual WDTOs plus the number of exceptions.

Return value

A NULL-terminated string containing the header information: 


Status Byte: 0
#Exceptions: 5
Index last exception: 5
#SW Resets: 2
#HW Resets: 2
#WD Timeouts: 5

The string will contain "Header checksum invalid" if a checksum error occurs. The meaning of the status byte is as follows: 


bit 0   - An error has occurred since deployment
bit 1   - The count of SW resets has rolled over.
bit 2   - The count of HW resets has rolled over.
bit 3   - The count of WDTOs has rolled over.
bit 4   - The count of exceptions has rolled over.
bit 5-7 - Not used

The index of the last exception is the index from the start of the error log entries. If this index does not equal the total exception count minus one, the error log entries have wrapped around the log buffer.

Library 


ERRORS.LIB

errlogGetNthEntry 



root int errlogGetNthEntry(int N);

Description

Loads errLogEntry structure with Nth entry of the error buffer. This must be called before the functions below that format the output.

Parameters 


N

Index of entry to load into errLogEntry

Return value

 0: Success, entry checksum OK.
-1: Failure, entry checksum not OK.

Library 


ERRORS.LIB

errlogFormatEntry 



root char* errlogFormatEntry();

Description

Returns a NULL-terminated string containing the basic information contained in errLogEntry: 


Error type=240
Address = 00:16aa
Time: 06/11/2001 20:49:29

Return value

The NULL-terminated string described above.

Library 


ERRORS.LIB

errlogFormatRegDump 



root char* errlogFormatRegDump();

Description

Returns a NULL-terminated string containing a register dump using the data in errLogEntry: 


AF=0000,AF'=0000
HL=00f0,HL'=15e3
BC=16ce,BC'=1600
DE=0000,DE'=1731
IX=d3f1,IY =0560
SP=d3eb,XPC=0000

Return value

The NULL-terminated string described above.

Library 


ERRORS.LIB

errlogFormatStackDump 



root char* errlogFormatStackDump();

Description

Returns a NULL-terminated string containing a stack dump using the data in errLogEntry. 


Stack Dump:
 0024,04f1,
 d378,c146,
 c400,a108,
 2404,0000,

Return value

The NULL-terminated string describe above.

Library 


ERRORS.LIB

errlogGetMessage 



root char* errlogGetMessage();

Description

Returns a NULL-terminated string containing the 8 byte message in errLogEntry.

Return value

A NULL-terminated string.

Library 


ERRORS.LIB

errlogReadHeader 



root int errlogReadHeader();

Description

Reads error log header into the structure errlogInfo.

Return value

 0: Success, entry checksum OK.
-1: Failure, entry checksum not OK.

Library 


ERRORS.LIB

exception 



int exception(int errCode);

Description

This function is called by Rabbit libraries when a runtime error occurs. It puts information relevant to the runtime error on the stack and calls the default runtime error handler pointed to by the ERROR_EXIT macro. To define your own error handler, see the defineErrorHandler() function.

When the error handler is called, the following information will be on the stack:

Location on Stack
Description
SP+0 Return adress for error handler call
SP+2 Runtime error code
SP+4 (can be used for additional information)
SP+6 XPC when exception() was called (upper byte)
SP+8 Address where exception() was called from

Return value

Runtime error code passed to it.

Library 


ERRORS.LIB

See also

defineErrorHandler

exit 



void exit(int exitcode);

Description

Stops the program and returns exitcode to Dynamic C. Dynamic C uses values above 128 for run-time errors. When not debugging, exit will run an infinite loop, causing a watchdog timeout if the watchdog is enabled.

Parameters 


exitcode

Error code passed by Dynamic C

Library 


SYS.LIB

exp 



float exp(float x);

Description

Computes the exponential of real float value x.

Parameters 


x

Value to compute

Return value

Returns the value of ex.

If x > 89.8 (approx.), the function returns INF and signals a range error. If x < -89.8 (approx.), the function returns 0 and signals a range error.

Library 


MATH.LIB

See also 


log, log10, frexp, ldexp, pow, pow10, sqrt

fabs 



float fabs(float x);

Description

Computes the float absolute value of float x.

Parameters 


x

Value to compute

Return value

x, if x >= 0,
else -x.

Library 


MATH.LIB

See also 


abs

fclose 



void fclose(File* f);

Description

Closes a file.

Parameters 


f

The pointer to the file to close.

Library 


FILESYSTEM.LIB

fcreate (FS1) 



int fcreate(File* f, FileNumber fnum);

Description

Creates a file. Before calling this function, a variable of type File must be defined in the application program.

File file;
fcreate (&file, 1);

Parameters 


f

The pointer to the created file. 


fnum

This is a user-defined number in the range of 1 to127 inclusive. Each file in the flash file system is assigned a unique number in this range.

Return value

0: Success.
1: Failure.

Library 


FILESYSTEM.LIB

fcreate (FS2) 



int fcreate(File* f, FileNumber name);

Description

Create a new file with the given "file name" which is composed of two parts: the low byte is the actual file number (1 to 255 inclusive), and the high byte contains an extent number (1 to _fs.num_lx) on which to place the file metadata. The extent specified by fs_set_lx() is always used to determine the actual data extent. If the high byte contains 0, then the default metadata extent specified by fs_set_lx() is used. The file descriptor is filled in if successful. The file will be opened for writing, so a further call to fopen_wr() is not necessary.

The number of files which may be created is limited by the lower of FS_MAX_FILES and 255. This limit applies to the entire filesystem (all logical extents).

Once a file is created, its data and metadata extent numbers are fixed for the life of the file, i.e. until is is deleted.

When created, no space is allocated in the file system until the first write occurs for the file. Thus, if the system power is cycled after creation but before the first byte is written, the file will be effectively deleted. The first write to a file causes one sector to be allocated for the metadata.

Before calling this function, a variable of type File must be defined in the application program. (The sizeof() function will return the number of bytes used for the File data structure.)

File file;
fcreate (&file, 1);

Parameters 


f

Pointer to the file descriptor to fill in. 


name

File number including optional metadata extent number.

Return value

 0: Success.
!0: Failure.

ERRNO values

EINVAL - Zero file number requested, or invalid extent number.
EEXIST - File with given number already exists.
ENFILE - No space is available in the "existing fileable". If this error occurs, increase the definition of FS_MAX_FILES, which is a #define constant which should be declared before #use "fs2.lib".

Library 


fs2.LIB

See also 


fcreate_unused (FS2), fs_set_lx (FS2), fdelete (FS2)

fcreate_unused (FS1) 



FileNumber fcreate_unused(File* f);

Description

Searches for the first unused file number in the range 1 through 127, and creates a file with that number.

Parameters 


f

The pointer to the created file.

Return value

The FileNumber (1-127) of the new file if success.

Library 


FILESYSTEM.LIB

See also 


fcreate (FS1)

fcreate_unused (FS2) 



FileNumber fcreate_unused(File* f);

Description

Create a new file and return the "file name" which is a number between 1 and 255. The new file will be created on the current default extent(s) as specified by fs_set_lx(). Other behavior is the same as fcreate().

Parameters 


f

Pointer to file descriptor to fill in.

Return value

>0: Success, the FileNumber (1-255) of the new file.
 0: Failure.

ERRNO value

ENFILE - No unused file number available.

Library 


fs2.LIB

See also 


 fcreate (FS2), fs_set_lx (FS2), fdelete (FS2)

fdelete (FS1) 



int fdelete(FileNumber fnum);

Description

Deletes a file.

Parameters 


fnum

A number in the range 1 to 127 inclusive that identifies the file in the flash file system.

Return value

0: Success.
1: Failure.

Library 


FILESYSTEM.LIB

fdelete (FS2) 



int fdelete(FileNumber name);

Description

Delete the file with the given number. The specified file must not be open. The file number (i.e. name) is composed of two parts: the low byte contains the actual file number, and the high byte (if not zero) contains the metadata extent number of the file.

Parameters 


name

File number (1 to 255 inclusive).

Return value

 0: Success.
!0: Failure.

Library 


fs2.LIB

ERRNO values

ENOENT - File does not exist, or metadata extent number does not match an existing file.
EBUSY - File is open.
EIO - I/O error when releasing blocks occupied by this file.

See also 


fcreate (FS2)

fflush (FS2) 



int fflush(File * f);

Description

Flush any buffers, associated with the given file, retained in RAM to the underlying hardware device. This ensures that the file is completely written to the filesystem. The file system does not currently perform any buffering, however future revisions of this library may introduce buffering to improve performance.

Parameters 


f

Pointer to open file descriptor.

Return value

 0: Success.
!0: Failure.

ERRNO values

EBADFD - file invalid or not open.
EIO - I/O error.

Library 


fs2.LIB

See also

fs_sync (FS2)

fftcplx 



void fftcplx(int *x, int N, int *blockexp)

Description

Computes the complex DFT of the N-point complex sequence contained in the array x and returns the complex result in x. N must be a power of 2 and lie between 4 and 1024. An invalid N causes a RANGE exception. The N-point complex sequence in array x is replaced with its N-point complex spectrum. The value of blockexp is increased by 1 each time array x has to be scaled, to avoid arithmetic overflow.

Parameters 


x

Pointer to N-element array of complex fractions. 


N

Number of complex elements in array x. 


blockexp

Pointer to integer block exponent.

Library 


FFT.LIB

See also 


fftcplxinv, fftreal, fftrealinv, hanncplx, hannreal, powerspectrum

fftcplxinv 



 void fftcplxinv(int *x, int N, int *blockexp)

Description

Computes the inverse complex DFT of the N-point complex spectrum contained in the array x and returns the complex result in x. N must be a power of 2 and lie between 4 and 1024. An invalid N causes a RANGE exception. The value of blockexp is increased by 1 each time array x has to be scaled, to avoid arithmetic overflow. The value of blockexp is also decreased by log2N to include the 1/N factor in the definition of the inverse DFT

Parameters 


x

Pointer to N-element array of complex fractions. 


N

Number of complex elements in array x. 


blockexp

Pointer to integer block exponent.

Library 


FFT.LIB

See also 


fftcplx, fftreal, fftrealinv, hanncplx, hannreal, powerspectrum

fftreal 



void fftreal(int *x, int N, int *blockexp)

Description

Computes the N-point, positive-frequency complex spectrum of the 2N-point real sequence in array x. The 2N-point real sequence in array x is replaced with its N-point positive-frequency complex spectrum. The value of blockexp is increased by 1 each time array x has to be scaled, to avoid arithmetic overflow.

The imaginary part of the X[0] term (stored in x[1]) is set to the real part of the fmax term.

The 2N-point real sequence is stored in natural order. The zeroth element of the sequence is stored in x[0], the first element in x[1], and the kth element in x[k].

N must be a power of 2 and lie between 4 and 1024. An invalid N causes a RANGE exception.

Parameters 


x

Pointer to 2N-point sequence of real fractions. 


N

Number of complex elements in output spectrum 


blockexp

Pointer to integer block exponent.

Library 


FFT.LIB

See also 


fftcplx, fftcplxinv, fftrealinv, hanncplx, hannreal, powerspectrum

fftrealinv 



void fftrealinv(int *x, int N, int *blockexp)

Description

Computes the 2N-point real sequence corresponding to the N-point, positive-frequency complex spectrum in array x. The N-point, positive-frequency spectrum contained in array x is replaced with its corresponding 2N-point real sequence. The value of blockexp is increased by 1 each time array x has to be scaled, to avoid arithmetic overflow. The value of blockexp is also decreased by log2N to include the 1/N factor in the definition of the inverse DFT.

The function expects to find the real part of the fmax term in the imaginary part of the zero-frequency X[0] term (stored x[1]).

The 2N-point real sequence is stored in natural order. The zeroth element of the sequence is stored in x[0], the first element in x[1], and the kth element in x[k].

N must be a power of 2 and lie between 4 and 1024. An invalid N causes a RANGE exception.

Parameters 


x

Pointer to N-element array of complex fractions. 


N

Number of complex elements in array x. 


blockexp

Pointer to integer block exponent.

Library 


FFT.LIB

See also 


fftcplx, fftcplxinv, fftreal, hanncplx, hannreal, powerspectrum

flash_erasechip 



void flash_erasechip(FlashDescriptor* fd);

Description

Erases an entire Flash Memory chip.

NOTE: fd must have already been initialized with flash_init before calling this function. See flash_init description for further restrictions.

Parameters 


fd

Pointer to flash descriptor of the chip to erase.

Library 


FLASH.LIB

See also 


flash_erasesector, flash_gettype, flash_init, flash_read, flash_readsector, flash_sector2xwindow, flash_writesector

flash_erasesector 



int flash_erasesector(FlashDescriptor* fd, word which);

Description

Erases a sector of a Flash Memory chip.

NOTE: fd must have already been initialized with flash_init before calling this function. See flash_init description for further restrictions.

Parameters 


fd

Pointer to flash descriptor of the chip to erase a sector of. 


which

The sector to erase.

Return value

0: Success.

Library 


FLASH.LIB

See also 


flash_erasechip, flash_gettype, flash_init, flash_read, flash_readsector, flash_sector2xwindow, flash_writesector

flash_gettype 



int flash_gettype(FlashDescriptor* fd);

Description

Returns the 16-bit Flash Memory type of the Flash Memory.

NOTE: fd must have already been initialized with flash_init before calling this function. See flash_init description for further restrictions.

Parameters 


fd

The FlashDescriptor of the memory to query.

Return value

The integer representing the type of the Flash Memory.

Library 


FLASH.LIB

See also 


flash_erasechip, flash_erasesector, flash_init, flash_read, flash_readsector, flash_sector2xwindow, flash_writesector

flash_init 



int flash_init(FlashDescriptor* fd, int mb3cr);

Description

Initializes an internal data structure of type FlashDescriptor with information about the Flash Memory chip. The Memory Interface Unit bank register (MB3CR) will be assigned the value of mb3cr whenever a function accesses the Flash Memory referenced by fd. See the Rabbit 2000 Users Manual for the correct chip select and wait state settings.

NOTE: Improper use of this function can cause your program to be overwritten or operate incorrectly. This and the other Flash Memory access functions should not be used on the same Flash Memory that your program resides on, nor should they be used on the same region of a second Flash Memory where a file system resides.

Use WriteFlash() to write to the primary Flash Memory.

Parameters 


fd

This is a pointer to an internal data structure that holds information about a Flash Memory chip. 


mb3cr

This is the value to set MB3CR to whenever the Flash Memory is accessed. 0xc2 (i.e., CS2, /OE0, /WE0, 0 WS) is a typical setting for the second Flash Memory on the TCP/IP Dev Kit, the Intellicom, the Advanced Ethernet Core, and the RabbitLink.

Return value

 0: Success.
 1: Invalid Flash Memory type.
-1: Attempt made to initialize primary Flash Memory.

Library 


FLASH.LIB

See also 


flash_erasechip, flash_erasesector, flash_gettype, flash_read, flash_readsector, flash_sector2xwindow, flash_writesector

flash_read 



int flash_read(FlashDescriptor* fd, word sector, word offset, unsigned long buffer, word length);

Description

Reads data from the Flash Memory and stores it in buffer.

NOTE: fd must have already been initialized with flash_init before calling this function. See the flash_init description for further restrictions.

Parameters 


fd

The FlashDescriptor of the Flash Memory to read from. 


sector

The sector of the Flash Memory to read from. 


offset

The displacement, in bytes, from the beginning of the sector to start reading at. 


buffer

The physical address of the destination buffer. TIP: A logical address can be changed to a physical with the function paddr. 


length

The number of bytes to read.

Return value

0: Success.

Library 


FLASH.LIB

See also 


flash_erasechip, flash_erasesector, flash_gettype, flash_init, flash_readsector, flash_sector2xwindow, flash_writesector, paddr

flash_readsector 



int flash_readsector(FlashDescriptor* fd, word sector, unsigned long buffer);

Description

Reads the contents of an entire sector of Flash Memory into a buffer.

NOTE: fd must have already been initialized with flash_init before calling this function. See flash_init description for further restrictions.

Parameters 


fd

The FlashDescriptor of the Flash Memory to read from. 


sector

The source sector to read. 


buffer

The physical address of the destination buffer. TIP: A logical address can be changed to a physical with the function paddr.

Return value

0: Success.

Library 


FLASH.LIB

See also 


flash_erasechip, flash_erasesector, flash_gettype, flash_init, flash_read, flash_sector2xwindow, flash_writesector

flash_sector2xwindow 



void* flash_sector2xwindow(FlashDescriptor* fd, word sector);

Description

This function sets the MB3CR and XPC value so the requested sector falls within the XPC window. The MB3CR is the Memory Interface Unit bank register. XPC is one of four Memory Management Unit registers. See flash_init description for restrictions.

Parameters 


fd

The FlashDescriptor of the Flash Memory. 


sector

The sector to set the XPC window to.

Return value

The logical offset of the sector.

Library 


FLASH.LIB

See also 


flash_erasechip, flash_erasesector, flash_gettype, flash_init, flash_read, flash_readsector, flash_writesector

flash_writesector 



int flash_writesector(FlashDescriptor* fd, word sector, unsigned long buffer);

Description

Writes the contents of buffer to sector on the Flash Memory referenced by fd. NOTE: fd must have already been initialized with flash_init before calling this function. See flash_init description for further restrictions.

Parameters 


fd

The FlashDescriptor of the Flash Memory to write to. 


sector

The destination sector. 


buffer

The physical address of the source. TIP: A logical address can be changed to a physical address with the function paddr

Return value

0: Success.

Library 


FLASH.LIB

See also 


flash_erasechip, flash_erasesector, flash_gettype, flash_init, flash_read, flash_readsector, flash_sector2xwindow

floor 



float floor(float x);

Description

Computes the largest integer less than or equal to the given number.

Parameters 


x

Value to round down

Return value

Rounded down value.

Library 


MATH.LIB

See also 


ceil, fmod

fmod 



float fmod(float x, float y);

Description

Calculates modulo math.

Parameters 


x

Dividend 


y

Divisor

Return value

Returns the remainder of x/y. The remaining part of x after all multiples of y have been removed. For example, if x is 22.7 and y is 10.3, the integral division result is 2. Then the remainder is: 22.7 - 2 × 10.3 = 2.1.

Library 


MATH.LIB

See also 


ceil, floor

fopen_rd (FS1) 



int fopen_rd(File* f, FileNumber fnum);

Description

Opens a file for reading.

Parameters 


f

A pointer to the file to read. 


fnum

A number in the range 1 to 127 inclusive that identifies the file in the flash file system.

Return value

0: Success.
1: Failure.

Library 


FILESYSTEM.LIB

fopen_rd (FS2) 



int fopen_rd(File* f, FileNumber name);

Description

Open file for reading only. See fopen_wr() for a more detailed description.

Parameters 


f

Pointer to file descriptor (uninitialized). 


name

File number (1 to 255 inclusive).

Return value

 0: Success.
!0: Failure.

ERRNO values

ENOENT - File does not exist, or metadata extent number does not match an existing file.

Library 


fs2.lib

See also 


fclose, fopen_wr (FS2)

fopen_wr (FS1) 



int fopen_wr(File* f, FileNumber fnum);

Description

Opens a file for writing.

Parameters 


f

A pointer to the file to write. 


fnum

A number in the range 1 to 127 inclusive that identifies the file in the flash file system.

Return value

0: Success.
1: Failure.

Library 


FILESYSTEM.LIB

fopen_wr (FS2) 



int fopen_wr(File* f, FileNumber name);

Description

Open file for read or write. The given file number is composed of two parts: the low byte contains the file number (1 to 255 inclusive) and the high byte, if not zero, contains the metadata extent number. If the extent number is zero, it defaults to the correct metadata extent - this is for the purpose of validating an expected extent number. Most applications should just pass the file number with zero high byte.

A file may be opened multiple times, with a different file descriptor pointer for each call, which allows the file to be read or written at more than one position at a time. A reference count for the actual file is maintained, so that the file can only be deleted when all file descriptors referring to this file are closed.

fopen_wr() or fopen_rd() must be called before any other function from this library is called that requires a File pointer. The "current position" is set to zero i.e. the start of the file.

When a file is created, it is automatically opened for writing thus a subsequent call to fopen_wr() is redundant.

Parameters 


f

Pointer to file descriptor (uninitialized). 


name

File number (1 to 255 inclusive).

Return value

 0: Success.
!0: Failure.

ERRNO values

ENOENT - File does not exist, or metadata extent number does not match an existing file.

Library 


fs2.lib

See also 


fclose, fopen_rd (FS2)

forceSoftReset 



void forceSoftReset();

Description

Forces the board into a software reset by jumping to the start of the BIOS.

Library 


SYS.LIB

fread (FS1) 



int fread(File* f, char* buf, int len);

Description

Reads len bytes from a file pointed to by f, starting at the current offset into the file, into buffer. Data is read into buffer pointed to by buf.

Parameters 


f

A pointer to the file to read from 


buf

A pointer to the destination buffer. 


len

Number of bytes to copy.

Return value

Number of bytes read.

Library 


FILESYSTEM.LIB

fread (FS2) 



int fread(File* f, void* buf, int len);

Description

Read data from the "current position" of the given file. When the file is opened, the current position is 0, i.e. at the start of file. Subsequent reads or writes advance the position by the number of bytes read/written fseek() can also be used to position the read point.

If the application permits, it is much more efficient to read multiple data bytes rather than reading one-by-one.

Parameters 


f

Pointer to file descriptor (initialized by fopen_rd(), fopen_wr() or fcreate()). 


buf

Data buffer located in root data memory or stack. This must be dimensioned with at least len bytes. 


len

Length of data to read (0 to 32767 inclusive).

Return value

 len: Success.

<len : Partial success. Returns amount successfully read. errno gives further details (probably 0 meaning that end-of-file was encountered).

 0: Failure, or len was zero.

Library 


fs2.LIB

ERRNO values

EBADFD - File descriptor not opened.
EINVAL - len less than zero.
0 - Success, but len was zero or EOF was reached prior to reading len bytes.
EIO - I/O error.

See also 


fseek (FS2), fwrite (FS2)

frexp 



float frexp(float x, int *n);

Description

Splits x into a fraction and exponent, f*(2**n)

Parameters 


x

Number to split 


n

An integer

Return value

The function returns the exponent in the integer *n and the fraction between 0.5, inclusive and 1.0.

Library 


MATH.LIB

See also 


exp, ldexp

fs_format (FS1) 



int fs_format(long reserveblocks, int num_blocks, unsigned long wearlevel);

Description

Initializes the internal data structures and file system. All blocks in the file system are erased.

Parameters 


reserveblocks

Starting address of the flash file system. When FS_FLASH is defined this value should be 0 or a multiple of the block size. When FS_RAM is defined this parameter is ignored. 


num_blocks

The number of blocks to allocate for the file system. With a default block size of 4096 bytes and a 256K Flash Memory, this value might be 64. 


wearlevel

This value should be 1 on a new Flash Memory, and some higher value on an unformatted used Flash Memory. If you are reformatting a Flash Memory you can set wearlevel to 0 to keep the old wear leveling.

Return value

0: Success.
1: Failure.

Library 


FILESYSTEM.LIB

Example

This program can be found in samples/filesystem/format.c. 


#define FS_FLASH
#use "filesystem.lib"
#define RESERVE   0
#define BLOCKS   64
#define WEAR      1


main() {
   if(fs_format(RESERVE,BLOCKS,WEAR)) {
      printf("error formating flash\n");
   } else {
      printf("flash successfully formatted\n");
   }
}

fs_format (FS2) 



int fs_format(long reserveblocks, int num_blocks, unsigned wearlevel)

Description

Format all extents of the file system. This must be called after calling fs_init(). Only extents that are not defined as reserved are formatted. All files are deleted.

Parameters 


reserveblocks

Must be zero. Retained for backward compatibility. 


num_blocks

Ignored (backward compatibility). 


wearlevel

Initial wearlevel value. This should be 1 if you have a new flash, and some larger number if the flash is used. If you are reformatting a flash, you can use 0 to use the old flash wear levels.

Return value

 0: Success.
!0: Failure.

ERRNO values

EINVAL - the reserveblocks parameter was non-zero.
EBUSY - one or more files were open.
EIO - I/O error during format. If this occurs, retry the format operation If it fails again, there is probably a hardware error.

See also 


fs_init (FS2), lx_format

fs_init (FS1) 



int fs_init(long reserveblocks, int num_blocks);

Description

Initialize the internal data structures for an existing file system. Blocks that are used by a file are preserved and checked for data integrity.

Parameters 


reserveblocks

Starting address of the flash file system. When FS_FLASH is defined this value should be 0 or a multiple of the block size. When FS_RAM is defined this parameter is ignored. 


num_blocks

The number of blocks that the file system contains. By default the block size is 4096 bytes.

Return Value

0:Success.
1: Failure.

Library 


FILESYSTEM.LIB

fs_init (FS2) 



int fs_init(long reserveblocks, int num_blocks);

Description

Initialize the filesystem. The static structure _fs contains information that defines the number and parameters associated with each extent or "partition". This function must be called before any of the other functions in this library, except for fs_setup(), fs_get_*_lx() and fs_get_lx_size().

Pre-main initialization will create up to 3 devices:

The LX numbers of the default devices can be obtained using the fs_get_flash_lx(), fs_get_ram_lx() and fs_get_other_lx() calls.

If none of these devices can be set up successfully, fs_init() will return ENOSPC when called.

This function performs complete consistency checks and, if necessary, fixups for each LX. It may take up to several seconds to run. It should only be called once at application initialization time.

Parameters 


reserveblocks

Must be zero. Retained for backward compatibility. 


num_blocks

Ignored (backward compatibility).

Return value

 0: Success.
!0: Failure.

ERRNO values

EINVAL - the reserveblocks parameter was non-zero.
EIO - I/O error. This indicates a hardware problem.
ENOMEM - Insufficient memory for required buffers.
ENOSPC - No valid extents obtained e.g. there is no recognized flash or RAM memory device available.

Library 


fs2.lib

See also 


fs_setup (FS2), fs_get_flash_lx (FS2)

fs_reserve_blocks (FS1) 



int fs_reserve_blocks(int blocks);

Description

Sets up a number of blocks that are guaranteed to be available for privileged files. A privileged file has an identifying number in the range 128 through 143. This function is not needed in most cases. If it is used, it should be called immediately after fs_init or fs_format.

Parameters 


blocks

Number of blocks to reserve.

Return Value

0: Success.
1: Failure.

Library 


FILESYSTEM.LIB

fsck (FS1) 



int fsck(int flash);

Description

Check the filesystem for errors

Parameters 


flash

A bitmask indicating which checks to NOT perform. The following checks are available:

FSCK_HEADERS - Block headers.
FSCK_CHECKSUMS - Data checksums.
FSCK_VERSION - Block versions, from a failed write.

Return Value

 0: Success.
!0: Failure, this is a bitmask indicating which checks failed.

Library 


FILESYSTEM.LIB

fseek (FS1) 



int fseek(File* f, long to, char whence);

Description

Places the read pointer at a desired location in the file.

Parameters 


f

A pointer to the file to seek into. 


to

The number of bytes to move the read pointer. This can be a positive or negative number. 


whence

The location in the file to offset from. This is one of the following constants.

SEEK_SET - Seek from the beginning of the file.
SEEK_CUR - Seek from the current read position in the file.
SEEK_END - Seek from the end of the file.

Example

To seek to 10 bytes from the end of the file f, use fseek(f, -10, SEEK_END);. To rewind the file f by 5 bytes, use fseek(f, -5, SEEK_CUR);.

Return value

0: Success.
1: Failure.

Library 


FILESYSTEM.LIB

fseek (FS2) 



int fseek(File * f, long where, char whence);

Description

Set the current read/write position of the file. Bytes in a file are sequentially numbered starting at zero. If the current position is zero, then the first byte of the file will be read or written. If the position equals the file length, then no data can be read, but any write will append data to the file.

fseek() allows the position to be set relative to the start or end of the file, or relative to its current position.

In the special case of SEEK_RAW, an unspecified number of bytes beyond the "known" end-of-file may be readable. The actual amount depends on the amount of space left in the last internal block of the file. This mode only applies to reading, and is provided for the purpose of data recovery in the case that the application knows more about the file structure than the filesystem.

Parameters 


f

Pointer to file descriptor (initialized by fopen_rd(), fopen_wr() or fcreate()). 


where

New position, or offset. 


whence

One of the following values:

SEEK_SET: 'where' (non-negative only) is relative to start of file.
SEEK_CUR: 'where' (positive or negative) is relative to the current position.
SEEK_END: 'where' (non-positive only) is relative to the end of the file.
SEEK_RAW: Similar to SEEK_END, except the file descriptor is set in a special mode which allows reading beyond the end of the file.

Return value

 0: Success.

!0: The computed position was outside of the current file contents, and has been adjusted to the nearest valid position.

ERRNO values

None.

Library 


fs2.lib

See also 


ftell (FS2), fread (FS2), fwrite (FS2)

fs_get_flash_lx (FS2) 



FSLXnum fs_get_flash_lx(void);

Description

Returns the logical extent number of the preferred flash device. This is the second flash if one is available on your hardware, otherwise it is the reserved area in your program flash. In order for the program flash to be available for use by the file system, you must define two constants: the first constant is XMEM_RESERVE_SIZE near the top of BIOS\RABBITBIOS.C. This value is set to the amount of program flash to reserve (in bytes). This is required by the BIOS. The second constant is set in your code before #use "fs2.lib". FS2_USE_PROGRAM_FLASH must be defined to the number of KB (1024 bytes) that will actually be used by the file system. If this is set to a larger value than the actual amount of reserved space, then only the actual amount will be used.

The sample program SAMPLES\FILESYSTEM\FS2INFO.C demonstrates use of this function.

This function may be called before calling fs_init().

Return value

 0: There is no flash file system available.
!0: Logical extent number of the preferred flash.

Library 


FS2.lib

See also 


fs_get_ram_lx (FS2), fs_get_other_lx (FS2)

fs_get_lx (FS2) 



FSLXnum fs_get_lx(int meta);

Description

Return the current extent (LX) number for file creation. Each file has two parts: the main bulk of data, and the metadata which is a relatively small, fixed, amount of data used to journal changes to the file. Both data and metadata can reside on the same extent, or they may be separated.

Parameters 


meta

1: return logical extent number for metadata.
0: return logical extent number for data.

Return value

Logical extent number.

Library 


FS2.lib

See also

fcreate (FS2), fs_set_lx (FS2)

fs_get_lx_size (FS2) 



long fs_get_lx_size(FSLXnum lxn, int all, word ls_shift);

Description

Returns the size of the specified logical extent, in bytes. This information is useful when initially partitioning an LX, or when estimating the capacity of an LX for user data. all is a flag which indicates whether to return the total data capacity (as if all current files were deleted) or whether to return just the available data capacity. The return value accounts for the packing efficiency which will be less than 100% because of the bookkeeping overhead. It does not account for the free space required when any updates are performed; however this free space may be shared by all files on the LX. It also does not account for the space required for file metadata. You can account for this by adding one logical sector for each file to be created on this LX. You can also specify that the metadata be stored on a different LX by use of fs_set_lx().

This function may be called either before or after fs_init(). If called before, then the ls_shift parameter must be set to the value to be used in fs_setup(), since the LS size is not known at this point. ls_shift can also be passed as zero, in which case the default size will be assumed. all must be non-zero if called before fs_init(), since the number of files in use is not yet known.

Parameters 


lxn

Logical extent number to query. 


all

Boolean: 0 for current free capacity only, 1 for total.
Must use 1 if calling before fs_init(). 


ls_shift

Logical sector shift i.e. log base 2 of LS size (6 to 13); may be zero to use default.

Return value

 0: The specified LX does not exist.
!0: Capacity of the LX in bytes.

Library 


FS2.lib

fs_get_other_lx (FS2) 



FSLXnum fs_get_other_lx(void);

Description

Returns the logical extent number of the non-preferred flash device. If it exists, this is usually the program flash. See the description under fs_get_flash_lx() for details about setting up the program flash for use by the filesystem.

The sample program SAMPLES\FILESYSTEM\FS2INFO.C demonstrates use of this function.

This function may be called before calling fs_init().

Return value

 0: There is no other flash filesystem available.
!0: Logical extent number of the non-preferred flash.

Library 


FS2.LIB

See also

fs_get_ram_lx (FS2), fs_get_flash_lx (FS2)

fs_get_ram_lx (FS2) 



FSLXnum fs_get_ram_lx(void);

Description

Return the logical extent number of the RAM file system device. This is only available if you have defined FS2_RAM_RESERVE to a non-zero number of bytes in the BIOS.

A RAM filesystem is only really useful if you have battery-backed SRAM on the board. You can still use a RAM file system on volatile RAM, but of course files will not persist over power cycles and you should explicitly format the RAM filesystem at power-up.

The sample program SAMPLES\FILESYSTEM\FS2INFO.C demonstrates use of this function.

This function may be called before calling fs_init().

Return value

 0: There is no RAM filesystem available.
!0: Logical extent number of the RAM device.

Library 


FS2.LIB

See also

fs_get_flash_lx (FS2), fs_get_other_lx (FS2)

fs_set_lx (FS2) 



int fs_set_lx(FSLXnum meta, FSLXnum data);

Description

Sets the default logical extent (LX) numbers for file creation. Each file has two parts: the main bulk of data, and the metadata which is a relatively small, fixed amount of data used to journal changes to the file. Both data and metadata can reside on the same extent, or they may be separated. The metadata, no matter where it is located, consumes one sector.

The file creation functions allow the metadata extent to be explicitly specified (in the high byte of the file number), however it is usually easier to call fs_set_lx() to set appropriate defaults. Calling fs_set_lx() is the only way to specify the data extent.

If fs_set_lx() is never called, both data and metadata will default to the first non-reserved extent number.

Parameters 


meta

Extent number for metadata. 


data

Extent number for data.

Return value

 0: Success.
!0: Error, e.g. non-existent LX number.

ERRNO values

ENODEV - no such extent number, or extent is reserved.

Library 


FS2.LIB

See also 


fcreate (FS2)

fs_setup (FS2) 



FSLXnum  fs_setup(FSLXnum lxn, word ls_shift, int reserve_it, void * rfu, int partition_it, word part, word part_ls_shift, int part_reserve, void * part_rfu);

Description

To modify or add to the default extents, this function must be called before calling fs_init(). If called after fs_init(), the filesystem will be corrupted.

fs_setup() runs in one of two basic modes, determined by the partition_it parameter. If partition_it is non-zero, then the specified extent (lxn, which must exist), is split into two extents according to the given proportions. If partition_it is zero, then the specified extent must not exist; it is created. This use is beyond the scope of this note, since it involves filesystem internals. The paritioning usage is described here.

partition_it may be FS_MODIFY_EXTENT in which case the base extent, lxn, is modified to use the specified ls_shift and reserve_it parameters (the other parameters are ignored).

partition_it may be set to FS_PARTITION_FRACTION (other values reserved). This causes extent number lxn to be split. The first half is still referred to as extent lxn, and the other half is assigned a new extent number, which is returned.

The base extent number may itself have been previously partitioned, or it should be 1 for the 2nd flash device, or possibly 2 for the NVRAM device.

Parameters 


lxn

Base extent number to partition or modify. 


ls_shift

New logical sector size to assign to base partition, or zero to not alter it. This is expressed as the log base 2 of the desired size, and must be a number between 6 and 13 inclusive. 


reserve_it

TRUE if base partition is to be marked reserved. 


rfu

A pointer reserved for future use. Pass as NULL. 


partition_it

Must be set to FS_PARTITION_FRACTION or FS_MODIFY_EXTENT. The following parameters are ignored if this parameter is not FS_PARTITION_FRACTION. 


part

The fraction of the existing base extent to assign to the new extent. This number is expressed as a fixed-point binary number with the binary point to the left of the MSB e.g. 0x3000 assigns 3/16 of the base extent to the new partition, updating the base extent to 13/16 of its original size. The nearest whole number of physical sectors is used for each extent. 


part_ls_shift

Logical sector size to assign to the new extent, or zero to use the same LS size as the base extent. Expressed in same units as parameter 2. 


part_reserve

TRUE if the new extent is to be reserved. 


part_rfu

A pointer reserved for future use. Pass as NULL.

Return value

 0: Failure, extent could not be partitioned.
!0: Success, number of the new extent, or same as lxd for existing extent modification.

ERRNO values

ENOSPC - one or other half would contain an unusably small number of logical sectors, or the extent table is full. In the latter case, #define FS_MAX_LX to a larger value.

EINVAL - partition_it set to an invalid value, or other parameter invalid.

ENODEV - specified base extent number not defined.

Library 


FS2.LIB

See also 


fs_init (FS2)

fs_sync (FS2) 



int fs_sync(void);

Description

Flush any buffers retained in RAM to the underlying hardware device. The file system does not currently perform any buffering, however future revisions of this library may introduce buffering to improve performance. This function is similar to fflush(), except that the entire file system is synchronized instead of the data for just one file. Use fs_sync() in preference to fflush() if there is only one extent in the filesystem.

Return value

 0: Success.
!0: Failure.

ERRNO values

EIO - I/O error.

Library 


FS2.LIB

See also 


fflush (FS2)

ftell (FS1) 



long ftell(File* f);

Description

Gets the offset from the beginning of a file that the read pointer is currently at.

TIP: ftell() can be used with fseek() to find the length of a file.

fseek(f, 0, SEEK_END); /* seek to the end of the file */
FileLength = ftell(f); /* find the length of the file */

Parameters 


f

A pointer to the file to query.

Return value

The offset in bytes of the read pointer from the beginning of the file: Success.
-1: Failure.

Library 


FILESYSTEM.LIB

ftell (FS2) 



long ftell(File * f);

Description

Return the current read/write position of the file. Bytes in a file are sequentially numbered starting at zero. If the current position is zero, then the first byte of the file will be read or written. If the position equals the file length, then no data can be read, but any write will append data to the file.

Note that no checking is done to see if the file descriptor s valid. If the File is not actually open, the return value will be random.

Parameters 


f

Pointer to file descriptor (initialized by fopen_rd(), fopen_wr() or fcreate()).

Return value

Current read/write position (0 to length-of-file).

ERRNO values

None.

Library 


fs2.lib

See also 


fseek (FS2)

fshift 



int fshift(File *f, int count, char *buffer);

Description

Removes count number of bytes from the beginning of a file and copies them to memory pointed to by buffer.

Parameters 


f

A pointer to the file. 


count

Number of bytes to shift out. 


*buffer

Location to store shifted bytes. If this is NULL, the bytes will be discarded.

Return value

Number of bytes shifted out: Success.
0: Error.

Library 


FILESYSTEM.LIB

fwrite (FS1) 



int fwrite(File* f, char* buf, int len);

Description

Appends len bytes from the source buffer to the end of the file.

Parameters 


f

A pointer to the file to write to. 


buf

A pointer to the source buffer. 


len

The number of bytes to write.

Return value

The number of bytes written: Success.
0: Failure.

Library 


FILESYSTEM.LIB

fwrite (FS2) 



int fwrite(File* f, void* buf, int len);

Description

Write data to file opened for writing. The data is written starting at the "current position". This is zero (start of file) when it is opened or created, but may be changed by fread, fwrite, fshift or fseek functions. After writing the data, the current position is advanced to the position just after the last byte written. Thus, sequential calls to fwrite() will add or append data contiguously.

Unlike the previous file system (FILESYSTEM.LIB), this library allows files to be overwritten not just appended. Internally, overwrite and append are different operations with differing performance, depending on the underlying hardware. Generally, appending is more efficient especially with byte-writable flash memory. If the application allows, it is preferable to use append/shift rather than overwrite. In order to ensure that data is appended, use fseek(f, 0, SEEK_END) before calling fwrite().

The same "current position" pointer is used for both read and write. If interspersing read and write, then fseek() should be used to ensure the correct position for each operation. Alternatively, the same file can be opened twice, with one descriptor used for read and the other for write. This precludes use of fshift(), since it does not tolerate shared files.

Parameters 


f

Pointer to file descriptor (initialized by fopen_wr() or fcreate()). 


buf

Data buffer located in root data memory or stack. 


len

Length of data (0 to 32767 inclusive).

Return value

 len: Success.
<len: Partial success. Returns amount successfully written. errno gives more details.
 0: Failure, or len was zero.

ERRNO values

EBADFD - File descriptor not opened, or is read-only.
EINVAL - len less than zero.
0 - Success, but len was zero.
EIO - I/O error.
ENOSPC - extent out of space.

Library 


fs2.LIB

See also 


fread (FS2)

ftoa 



int ftoa(float f, char *buf);

Description

Converts a float number to a character string.

The character string only displays the mantissa up to 9 digits, no decimal points, and a minus sign if f is negative. The function returns the exponent (of 10) that should be used to compensate for the string: ftoa(1.0,buf) yields buf="100000000", and returns -8.

Parameters 


f

Float number to convert 


buf

Converted string. The string is no longer than 10 characters long.

Return value

The exponent of the number.

Library 


STDIO.LIB

See also 


utoa, itoa

getchar 



char getchar(void);

Description

Busy waits for a character to be typed from the stdio window in Dynamic C. The user should make sure only one process calls this function at a time.

Return value

A character typed in the Stdio window in Dynamic C.

Library 


STDIO.LIB

See also 


gets, putchar

getcrc 



int getcrc(char *dataarray, char count, int accum);

Description

Computes the Cyclic Redundancy Check (CRC), or check sum, for count bytes (maximum 255) of data in buffer. Calls to getcrc can be "concatenated" using accum to compute the CRC for a large buffer.

Parameters 


dataarray

Data buffer 


count

Number of bytes. Maximum is 255. 


accum

Base CRC for the data array.

Return value

CRC value.

Library 


MATH.LIB

gets 



char *gets(char *s);

Description

Waits for a string terminated by <CR> at the stdio window. The string returned is NULL-terminated without the return. The user should make sure only one process calls this function at a time.

Parameters 


s

The input string is put to the location pointed to by the argument s. The caller is responsible to make sure the location pointed to by s is big enough for the string.

Return value

Same pointer passed in, but string is changed to a NULL-terminated.

Library 


STDIO.LIB

See also 


puts, getchar

GetVectExtern2000 



unsigned GetVectExtern2000();

Description

Reads the address of external interrupt table entry. This function really just returns what is present in the table. The return value is meaningless if the address of the external interrupt has not been written.

Return value

Jump address in vector table.

Library 


SYS.LIB

See also 


GetVectIntern, SetVectExtern2000, SetVectIntern

GetVectExtern3000 



unsigned GetVectExtern3000(int interruptNum);

Description

Function to read the address of an external interrupt table entry for the Rabbit 3000 CPU. This function really just returns whatever value is at the address: 


(internal vector table base) + (vectNum*8) + 1.

Parameter 


interruptNum

Interrupt number. Should be 0 or 1.

Return Value

Jump address in vector table

See Also

SetVectExtern3000, SetVectIntern, GetVectIntern

GetVectIntern 



unsigned GetVectIntern(int vectNum);

Description

Reads the address of the internal interrupt table entry and returns whatever value is at the address (internal vector table base) + (vectNum*16) + 1.

Parameter 


vectNum

Interrupt number; should be 0-15.

Return value

Jump address in vector table.

Library 


SYS.LIB

See also 


GetVectExtern2000, SetVectExtern2000, SetVectIntern

gps_get_position 



int gps_get_position(GPSPositon *newpos, char *sentence);

Description

Parses a sentence to extract position data. This function is able to parse any of the following GPS sentence formats: GGA, GLL or RMC.

Parameters 


newpos

A GPSPosition structure to fill. 


sentence

A string containing a line of GPS data. in NMEA-0183 format.

Return value

 0: Success.
-1: Parsing error.
-2: Sentence marked invalid.

Library 


gps.lib

gps_get_utc 



int gps_get_utc(struct tm *newtime, char *sentence);

Description

Parses an RMC sentence to extract time data.

Parameters 


newtime

tm structure to fill with new UTC time. 


sentence

A string containing a line of GPS data in NMEA-0183 format (RMC sentence).

Return value

 0: Success.
-1: Parsing error.
-2: Sentence marked invalid.

Library 


gps.lib

gps_ground_distance 



 float gps_ground_distance(GPSPosition *a, GPSPosition *b);

Description

Calculates ground distance (in km) between to geographical points. (Uses spherical earth model.)

Parameters 


a

First point. 


b

Second point.

Return value

Distance in kilometers.

Library 


gps.lib

hanncplx 



void hanncplx(int *x, int N, int *blockexp);

Description

Convolves an N-point complex spectrum with the three-point Hann kernel. The filtered spectrum replaces the original spectrum.

The function produces the same results as would be obtained by multiplying the corresponding time sequence by the Hann raised-cosine window.

The zero-crossing width of the main lobe produced by the Hann window is 4 DFT bins. The adjacent sidelobes are 32 db below the main lobe. Sidelobes decay at an asymptotic rate of 18 db per octave.

N must be a power of 2 and lie between 4 and 1024. An invalid N causes a RANGE exception.

Parameters 


x

Pointer to N-element array of complex fractions. 


N

Number of complex elements in array x. 


blockexp

Pointer to integer block exponent.

Library 


FFT.LIB

See also 


fftcplx, fftcplxinv, fftreal, fftrealinv, hanncplx, powerspectrum

hannreal 



 void hannreal(int *x, int N, int *blockexp);

Description

Convolves an N-point positive-frequency complex spectrum with the three-point Hann kernel. The function produces the same results as would be obtained by multiplying the corresponding time sequence by the Hann raised-cosine window.

The zero-crossing width of the main lobe produced by the Hann window is 4 DFT bins. The adjacent sidelobes are 32 db below the main lobe. Sidelobes decay at an asymptotic rate of 18 db per octave.

The imaginary part of the dc term (stored in x[1]) is considered to be the real part of the fmax term. The dc and fmax spectral components take part in the convolution along with the other spectral components. The real part of fmax component affects the real part of the X[N-1] component (and vice versa), and should not arbitrarily be set to zero unless these components are unimportant.

Parameters 


x

Pointer to N-element array of complex fractions. 


N

Number of complex elements in array x. 


blockexp

Pointer to integer block exponent.

Return value

None. The filtered spectrum replaces the original spectrum.

Library 


FFT.LIB

See also 


fftcplx, fftcplxinv, fftreal, fftrealinv, hanncplx, powerspectrum

HDLCdropX 



int HDLCdropX(); /* Where X is E or F */

Description

Drops the next received packet, freeing up its buffer. This must be used if the packet has been examined with HDLCpeekX() and is no longer needed. A call to HDLCreveiceX() is the only other way to free up the buffer.

This function is intended for use with the Rabbit 3000 microprocessor.

Return Value

1: Packet dropped.
0: No received packets were available.

Library 


HDLC_PACKET.LIB

HDLCerrorX 



int HDLCerrorX(unsigned long *bufptr, int *lenptr); 
/* Where X is E or F */

Description

This function returns a set of possible error flags as an integer. A received packet with errors is automatically dropped.

Masks are used to check which errors have occurred. The masks are:

This function is intended for use with the Rabbit 3000 microprocessor.

Return Value

Error flags (see above)

Library 


HDLC_PACKET.LIB

HDLCopenX 



int HDLCopenX(long baud, char encoding, unsigned long buffers,  int buffer_count, int buffer_size); /* Where X is E or F */

Description

Opens serial port E or F in HDLC mode. Sets up buffers to hold received packets. This function is intended for use with the Rabbit 3000 microprocessor.

Parameters 


baud

The baud rate for the serial port. Due to imitations in the baud generator, non-standard baud rates will be approximated within 5% of the value requested. 


encoding

The bit encoding mode to use. Macro labels for the available options are:

· HDLC_NRZ

· HDLC_NRZI

· HDLC_MANCHESTER

· HDLC_BIPHASE_SPACE

· HDLC_BIPHASE_MARK

See the HDLC documentation for more detail on these modes. 


buffers

A pointer to the start of the extended momory block containing the receive buffers. This block must be allocated beforehand by the user. The size of the block should be: 


(# of buffers) * ((size of buffer) + 4)


buffer_count

The number of buffers in the block pointed to by buffer. 


buffer_size

The capacity of each buffer in the block pointed to by buffer.

Return Value

1 if the actual baud rate is within 5% of the requested baud rate,
0 otherwise.

Library 


HDLC_PACKET.LIB

HDLCpeekX 



int HDLCpeekX(unsigned long *bufptr, int *lenptr);
/* Where X is E or F */

Description

Reports the location and size of the next available received packet if one is available. This function can be used to effeciently inspect a received packet without actually copying it into a root memory buffer. Once inspected, the buffer can be received normally (see HDLCreceiveX()), or dropped (see HDLCdropX()).

This function is intended for use with the Rabbit 3000 microprocessor.

Parameters 


bufptr

Pointer to location in xmem of the received packet. 


lenptr

Pointer to the size of the received packet.

Return Value

1: The pointers bufptr and lenptr have been set for the received packet.
0: No received packets available.

Library 


HDLC_PACKET.LIB

HDLCreceiveX 



int HDLCreceiveX (char *rx_buffer, int length);
/* Where X is E or F */

Description

Copies a received packet into rx_buffer if there is one. Packets are received in the order they arrive, even if multiple packets are currently stored in buffers.

This function is intended for use with the Rabbit 3000 microprocessor.

Parameters 


rx_buffer

Pointer to the buffer to copy a received packet into. 


length

Size of the buffer pointed to by rx_buffer.

Return Value

≥0: Size of received packet.
-1: No packets are available to receive.

-2: The buffer is not large enough for the received packet. In this case, the packet remains in the receive buffer)

Library 


HDLC_PACKET.LIB

HDLCsendX 



int HDLCsendX(char *tx_buffer, int length); /* Where X is E or F */

Description

Transmits a packet out serial port E or F in HDLC mode. The tx_buffer is read directly while transmitting, therefore it cannot be altered until a subsequent call to HDLCsendingX() returns false, indicating that the driver is done with it.

This function is intended for use with the Rabbit 3000 microprocessor.

Parameters 


tx_buffer

A pointer to the packet to be sent. This buffer must not change while tranmitting (see above.) 


length

The size of the buffer (in bytes).

Return Value

1: Sending packet
0: Cannot send, another packet is currently being transmitted.

Library 


HDLC_PACKET.LIB

HDLCsendingX 



int HDLCsendingX(); /* Where X is E or F */

Description

Returns true if a packet is currently being transmitted. This function is intended for use with the Rabbit 3000 microprocessor.

Return Value

1: Currently sending a packet.
0: Transmitter is idle.

Library 


HDLC_PACKET.LIB

hitwd 



void hitwd();

Description

Hits the watchdog timer, postponing a hardware reset for 2 seconds. Unless the watchdog timer is disabled, a program must call this function periodically, or the controller will automatically reset itself. If the virtual driver is enabled (which it is by default), it will call hitwd in the background. The virtual driver also makes additional "virtual" watchdog timers available.

Library 


VDRIVER.LIB

htoa 



char *htoa(int value, char *buf);

Description

Converts integer value to hexadecimal number and puts result into buf.

Parameters 


value

16-bit number to convert 


buf

Character string of converted number

Return value

Pointer to end (NULL terminator) of string in buf.

Library 


STDIO.LIB

See also 


itoa, utoa, ltoa

IntervalMs 



int IntervalMs( long ms );

Description

Similar to DelayMs but provides a periodic delay based on the time from the previous call. Intended for use with waitfor.

Parameters 


ms

The number of milliseconds to wait.

Return value

0: Not finished.
1: Delay has expired.

Library 


COSTATE.LIB

IntervalSec 



int IntervalSec( long sec );

Description

Similar to DelayMs but provides a periodic delay based on the time from the previous call. Intended for use with waitfor.

Parameters 


sec

The number of seconds to delay.

Return value

0: Not finished.
1: Delay has expired.

Library 


COSTATE.LIB

IntervalTick 



int IntervalTick( long tick );

Description

Provides a periodic delay based on the time from the previous call. Intended for use with waitfor. A tick is 1/1024 seconds.

Parameters 


tick

The number of ticks to delay

Return value

0: Not finished.
1: Delay has expired.

Library 


COSTATE.LIB

ipres 



void ipres(void);

Description

Dynamic C expands this call inline. Restore previous interrupt priority by rotating the IP register.

Library 


UTIL.LIB

See also 


ipset

ipset 



void ipset(int priority);

Description

Dynamic C expands this call inline. Replaces current interrupt priority with another by rotating the new priority into the IP register.

Parameters 


priority

Interrupt priority range 0-3, lowest to highest priority.

Library 


UTIL.LIB

See also 


ipres

isalnum 



int isalnum(int c);

Description

Tests for an alphabetic or numeric character, (A to Z, a to z and 0 to 9).

Parameters 


c

Character to test.

Return value

 0 if not an alphabetic or numeric character.
!0 otherwise.

Library 


STRING.LIB

See also 


isalpha, isdigit, ispunct

isalpha 



int isalpha(int c);

Description

Tests for an alphabetic character, (A to Z, or a to z).

Parameters 


c

Character to test.

Return value

 0 if not a alphabetic character.
!0 otherwise.

Library 


STRING.LIB

See also 


isalnum, isdigit, ispunct

iscntrl 



int iscntrl(int c);

Description

Tests for a control character: 0 <= c <= 31 or c == 127.

Parameters 


c

Character to test.

Return value

 0 if not a control character.
!0 otherwise.

Library 


STRING.LIB

See also 


isalpha, isalnum, isdigit, ispunct

isCoDone 



int isCoDone(CoData *p);

Description

Determine if costatement is initialized and not running.

Parameters 


p

Address of costatement

Return value

1 if costatement is initialized and not running.
0 otherwise.

Library 


COSTATE.LIB

isCoRunning 



int isCoRunning(CoData *p);

Description

Determine if costatement is stopped or running.

Parameters 


p

Address of costatement

Return value

1 if costatement is running.
0 otherwise.

Library 


COSTATE.LIB

isdigit 



int isdigit(int c);

Description

Tests for a decimal digit: 0 - 9

Parameters 


c

Character to test.

Return value

 0 if not a decimal digit.
!0 otherwise.

Library 


STRING.LIB

See also 


isxdigit, isalpha, isalpha

isgraph 



int isgraph(int c);

Description

Tests for a printing character other than a space: 33 <= c <= 126

Parameters 


c

Character to test.

Return value

 0: c is not a printing character.
!0: c is a printing character.

Library 


STRING.LIB

See also 


isprint, isalpha, isalnum, isdigit, ispunct

islower 



int islower(int c);

Description

Tests for lower case character.

Parameters 


c

Character to test.

Return value

 0 if not a lower case character.
!0 otherwise.

Library 


STRING.LIB

See also 


tolower, toupper, isupper

isspace 



int isspace(int c);

Description

Tests for a white space, character, tab, return, newline, vertical tab, form feed, and space: 9 <= c <= 13 and c == 32 .

Parameters 


c

Character to test.

Return value

0 if not, !0 otherwise.

Library 


STRING.LIB

See also 


ispunct

isprint 



int isprint(int c);

Description

Tests for printing character, including space: 32 <= c <= 126

Parameters 


c

Character to test.

Return value

0 if not a printing character, !0 otherwise.

Library 


STRING.LIB

See also 


isdigit, isxdigit, isalpha, ispunct, isspace, isalnum, isgraph

ispunct 



int ispunct(int c);

Description

Tests for a punctuation character.

Character
 		Decimal Code
space 32
! " # $ % & ' ( ) * + , - . / 33 <= c <= 47
: ; < = > ? @ 58 <= c <= 64
[\] ^ _ ` 91 <= c <= 96
{|} ~ 123 <= c <= 126

Parameters 


c

Character to test.

Return value

 0 if not a character.
!0 otherwise.

Library 


STRING.LIB

See also 


isspace

isupper 



int isupper(int c);

Description

Tests for upper case character.

Parameters 


c

Character to test.

Return value

0 if not, !0 otherwise.

Library 


STRING.LIB

See also 


tolower, toupper, islower

isxdigit 



int isxdigit(int c);

Description

Tests for a hexadecimal digit: 0 - 9, A - F, a - f

Parameters 


c

Character to test.

Return value

0 if not a hexadecimal digit, !0 otherwise.

Library 


STRING.LIB

See also 


isdigit, isalpha, isalpha

itoa 



char *itoa(int value, char *buf);

Description

Places up to a 5-digit character string, with a minus sign in the leftmost digit when appropriate, at *buf. The string represents value, a signed number.

Leading zeros are suppressed in the character string, except for one zero digit when value = 0. The longest possible string is "-32768."

Parameters 


value

16-bit signed number to convert 


buf

Character string of converted number in base 10

Return value

Pointer to the end (NULL terminator) of the string in buf.

Library 


STDIO.LIB

See also 


atoi, utoa, ltoa

i2c_check_ack 



int i2c_check_ack();

Description

Checks if slave pulls data low for ACK on clock pulse. Allows for clocks stretching on SCL going high.

Return value

 0: ACK sent from slave.
 1: NAK sent from slave.
-1: Timeout occurred.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

i2c_init 



void i2c_init();

Description

Sets up the SCL and SDA port pins for open-drain output.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

i2c_read_char 



int i2c_read_char(char *ch);

Description

Reads 8 bits from the slave. Allows for clocks stretching on all SCL going high. This is not in the protocol for I2C, but allows I2C slaves to be implemented on slower devices.

Parameters 


ch

A one character return buffer.

Return value

 0: Success.
-1: Clock stretching timeout.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

i2c_send_ack 



int i2c_send_ack();

Description

Sends ACK sequence to slave. ACK is usually sent after a successful transfer, where more bytes are going to be read.

Return value

 0: Success.
-1: Clock stretching timeout.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

i2c_send_nak 



int i2c_send_nak();

Description

Sends NAK sequence to slave. NAK is often sent when the transfer is finished.

Return value

 0: Success.
-1: Clock stretching timeout.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

i2c_start_tx 



 int i2c_start_tx();

Description

Initiates I2C transmission by sending the start sequence, which is defined as a high to low transition on SDA while SCL is high. The point being that SDA is supposed to remain stable while SCL is high. If it does not, then that indicates a start (S) or stop (P) condition. This function first waits for possible clock stretching, which is when a bus peripheral holds SCK low.

Return value

 0: Success.
-1: Clock stretching timeout.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

i2c_startw_tx 



 int i2c_startw_tx();

Description

Initiates I2C transmission by sending the start sequence, which is defined as a high to low transition on SDA while SCL is high. The point being that SDA is supposed to remain stable while SCL is high. If it does not, then that indicates a start (S) or stop (P) condition. This function first waits for possible clock stretching, which is when a bus peripheral holds SCK low.

This function is essentially the same as i2c_start_tx() with the addition of a clock stretch delay, which is 2000 "counts," inserted after the start sequence. (A count is an iteration through a loop.)

Return value

 0: Success.
-1: Clock stretching timeout.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

i2c_stop_tx 



 void i2c_stop_tx();

Description

Sends the stop sequence to the slave, which is defined as bringing SDA high while SCL is high, i.e., the clock goes high, then data goes high.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

i2c_write_char 



int i2c_write_char(char d);

Description

Sends 8 bits to slave. Checks if slave pulls data low for ACK on clock pulse. Allows for clocks stretching on SCL going high.

Parameters 


d

Character to send

Return value

 0: Success.
-1: Clock stretching timeout.
 1: NAK sent from slave.

Library 


I2C.LIB

See also

Technical Note 215, Using the I2C Bus with a Rabbit Microprocessor.

kbhit 



int kbhit();

Description

Detects keystrokes in the Dynamic C Stdio window.

Return value

!0 if a key has been pressed, 0 otherwise.

Library 


UTIL.LIB

labs 



long labs(long x);

Description

Computes the long integer absolute value of long integer x.

Parameters 


x

Number to compute.

Return value

x, if x ≥ 0, else -x.

Library 


MATH.LIB

See also 


abs, fabs

ldexp 



float ldexp(float x, int n);

Description

Computes x*(2**n)

Parameters 


x

The value between 0.5 inclusive, and 1.0 


n

An integer

Return value

The result of x*(2^n).

Library 


MATH.LIB

See also 


frexp, exp

log 



float log(float x);

Description

Computes the logarithm, base e, of real float value x.

Parameters 


x

Float value

Return value

The function returns -INF and signals a domain error when x 0.

Library 


MATH.LIB

See also 


exp, log10

log10 



float log10(float x);

Description

Computes the base 10 logarithm of real float value x.

Parameters 


x

Value to compute

Return value

The log base 10 of x.

The function returns -INF and signals a domain error when x 0.

Library 


MATH.LIB

See also 


log, exp

longjmp 



void longjmp(jmp_buf env, int val);

Description

Restores the stack environment saved in array env[ ]. See the description of setjmp for details of use.

Parameters 


env

Environment previously saved with setjmp. 


val

Integer result of setjmp.

Library 


SYS.LIB

See also 


setjmp

loophead 



void loophead();

Description

This function should be called within the main loop in a program. It is necessary for proper single-user cofunction abandonment handling.

When two costatements are requesting access to a single-user cofunction, the first request is honored and the second request is held. When loophead() notices that the first caller is not being called each time around the loop, it cancels the request, calls the abandonment code and allows the second caller in.

See Samples\Cofunc\Cofaband.c for sample code showing abandonment handling.

Parameters

None

Library 


COFUNC.LIB

loopinit 



void loopinit();

Description

This function should be called in the beginning of a program that uses single-user cofunctions. It initializes internal data structures that are used by loophead().

Parameters

None

Library 


COFUNC.LIB

ltoa 



char *ltoa(long num, char *ibuf)

Description

This function outputs a signed long number to the character array.

Parameters 


num

Signed long number 


ibuf

Pointer to character array

Return value

Pointer to the same array passed in to hold the result.

Library 


STDIO.LIB

See also 


ltoa

ltoan 



int ltoan(long num);

Description

This function returns the number of characters required to display a signed long number.

Parameters 


num

32-bit signed number

Return value

The number of characters to display signed long number.

Library 


STDIO.LIB

See also 


ltoa

lx_format 



int lx_format(FSLXnum lxn, long wearlevel);

Description

Format a specified file system extent. This must not be called before calling fs_init(). All files which have either or both metadata and data on this extent are deleted. Formatting can be quite slow (depending on hardware) so it is best performed after power-up, if at all.

Parameters 


lxn

Logical extent number (1.._fs.num_lx inclusive). 


wearlevel

Initial wearlevel value. This should be 1 if you have a new flash, and some larger number if the flash is used. If you are reformatting a flash, you can use 0 to use the old flash wear levels.

Return value

 0: Success.
!0: Failure.

ERRNO values

ENODEV - no such extent number, or extent is reserved.
EBUSY - one or more files were open on this extent.
EIO - I/O error during format. If this occurs, retry the format operation. If it fails again, there is probably a hardware error.

Library 


fs2.LIB

See also 


fs_init, fs_format

md5_append 



void md5_append(md5_state_t *pms, char *data, int nbytes);

Description

This function will take a buffer and compute the MD5 hash of its contents, combined with all previous data passed to it. This function can be called several times to generate the hash of a large amount of data

Parameters 


md5_append

Pointer to the md5_state_t structure that was initialized by md5_init. 


data

Pointer to the data to be hashed. 


nbytes

Length of the data to be hashed.

Library 


MD5.LIB

md5_init 



void md5_init(md5_state_t *pms);

Description

Initialize the MD5 hash process. Initial values are generated for the structure, and this structure will identify a particular transaction in all subsequent calls to the md5 library.

Parameter 


pms

Pointer to the md5_state_t structure.

Library 


MD5.LIB

md5_finish 



void md5_finish(md5_state_t *pms, char digest[16]);

Description

Completes the hash of all the received data and generates the final hash value.

Parameters 


pms

Pointer to the md5_state_t structure that was initialized by md5_init. 


digest

The 16-byte array that the hash value will be written into.

Library 


MD5.LIB

memchr 



void *memchr(void *src, int ch, unsigned int n);

Description

Searches up to n characters at memory pointed to by src for character ch.

Parameters 


src

Pointer to memory source. 


ch

Character to search for. 


n

Number of bytes to search.

Return value

Pointer to first occurrence of ch if found within n characters. Otherwise returns NULL.

Library 


STRING.LIB

See also 


strrchr, strstr

memcmp 



int memcmp(void *s1, void *s2, size_t n);

Description

Performs unsigned character by character comparison of two memory blocks of length n.

Parameters 


s1

Pointer to block 1. 


s2

Pointer to block 2. 


n

Maximum number of bytes to compare.

Return value

<0: A character in str1 is less than the corresponding character in str2.
 0: str1 is identical to str2.
>0: A character in str1 is greater than the corresponding character in str2.

Library 


STRING.LIB

See also 


strncmp

memcpy 



void *memcpy(void *dst, void *src, unsigned int n);

Description

Copies a block of bytes from one destination to another. Overlap is handled correctly.

Parameters 


dst

Pointer to memory destination 


src

Pointer to memory source 


n

Number of characters to copy

Return value

Pointer to destination.

Library 


STRING.LIB

See also 


memmove, memset

memmove 



void *memmove(void *dst, void *src, unsigned int n);

Description

Copies a block of bytes from one destination to another. Overlap is handled correctly.

Parameters 


dst

Pointer to memory destination 


src

Pointer to memory source 


n

Number of characters to copy

Return value

Pointer to destination.

Library 


STRING.LIB

See also 


memcpy, memset

memset 



void *memset(void *dst, int chr, unsigned int n);

Description

Sets the first n bytes of a block of memory to byte destination.

Parameters 


dst

Block of memory to set 


chr

Byte destination 


n

Amount of bytes to set

Library 


STRING.LIB

mktime 



unsigned long mktime(struct tm *timeptr);

Description

Converts the contents of structure pointed to by timeptr into seconds. 


struct tm {
   char tm_sec;       // seconds 0-59
   char tm_min;       // 0-59
   char tm_hour;      // 0-23
   char tm_mday;      // 1-31
   char tm_mon;       // 1-12
   char tm_year;      // 80-147 (1980-2047)
   char tm_wday;      // 0-6 0==sunday
};

Parameters 


timeptr

Pointer to tm structure

Return value

Time in seconds since January 1, 1980.

Library 


RTCLOCK.LIB

See also 


mktm, tm_rd, tm_wr

mktm 



unsigned int mktm(struct tm *timeptr, unsigned long time);

Description

Converts the seconds (time) to date and time and fills in the fields of the tm structure with the result. 


struct tm {
   char tm_sec;       // seconds 0-59
   char tm_min;       // 0-59
   char tm_hour;      // 0-23
   char tm_mday;      // 1-31
   char tm_mon;       // 1-12
   char tm_year;      // 80-147 (1980-2047)
   char tm_wday;      // 0-6 0==sunday
};

Parameters 


timeptr

Address to store date and time into structure: 


time

Seconds since January 1, 1980.

Return value

0

Library 


RTCLOCK.LIB

See also 


mktime, tm_rd, tm_wr

modf 



float modf(float x, int *n);

Description

Splits x into a fraction and integer, f + n.

Parameters 


x

Floating-point integer 


n

An integer

Return value

The integer part in *n and the fractional part satisfies |f| < 1.0

Library 


MATH.LIB

See also 


fmod, ldexp

OS_ENTER_CRITICAL 



void OS_ENTER_CRITICAL();

Description

Enter a critical section. Interrupts will be disabled until OS_EXIT_CRITICAL() is called. Task switching is disabled. This function must be used with great care, since misuse can greatly increase the latency of your application. Note that nesting OS_ENTER_CRITICAL() calls will work correctly.

Library 


UCOS2.LIB

OS_EXIT_CRITICAL 



void OS_EXIT_CRITICAL();

Description

Exit a critical section. If the corresponding previous OS_ENTER_CRITICAL() call disabled interrupts (that is, interrupts were not already disabled), then interrupts will be enabled. Otherwise, interrupts will remain disabled. Hence, nesting calls to OS_ENTER_CRITICAL() will work correctly.

Library 


UCOS2.LIB

OSInit 



void OSInit(void);

Description

Initializes µC/OS-II data; must be called before any other µC/OS-II functions are called.

Library 


UCOS2.LIB

See also 


OSTaskCreate, OSTaskCreateExt, OSStart

OSMboxAccept 



void *OSMboxAccept (OS_EVENT *OSMboxAccept);

Description

Checks the mailbox to see if a message is available. Unlike OSMboxPend(), OSMboxAccept() does not suspend the calling task if a message is not available.

Parameters 


OSMboxAccept

Pointer to the mailbox's event control block.

Return value

Pointer to available message, or a NULL pointer if there is no available message or an error condition exists.

Library 


UCOS2.LIB

See also 


OSMboxCreate, OSMboxPend, OSMboxPost, OSMboxQuery

OSMboxCreate 



OS_EVENT *OSMboxCreate (void *msg);

Description

Creates a message mailbox if event control blocks are available.

Parameters 


msg

Pointer to a message to put in the mailbox.

Return value

Pointer to mailbox's event control block, or NULL pointer if no event control block was available.

Library 


UCOS2.LIB

See also 


OSMboxAccept, OSMboxPend, OSMboxPost, OSMboxQuery

OSMboxPend 



void *OSMboxPend(OS_EVENT *pevent, INT16U timeout, INT8U *err);

Description

Waits for a message to be sent to a mailbox.

Parameters 


pevent

Pointer to mailbox's event control block. 


timeout

Allows task to resume execution if a message was not received by the number of clock ticks specified. Specifying 0 means the task is willing to wait forever. 


err

Pointer to a variable for holding an error code.

Return value

Pointer to a message or, if a timeout or error condition occurs, a NULL pointer.

Library 


UCOS2.LIB

See also 


OSMboxAccept, OSMboxCreate, OSMboxPost, OSMboxQuery

OSMboxPost 



INT8U OSMboxPost (OS_EVENT *pevent, void *msg);

Description

Sends a message to the specified mailbox

Parameters 


pevent

Pointer to mailbox's event control block. 


msg

Pointer to message to be posted. A NULL pointer must not be sent.

Return value 


OS_NO_ERR

The call was successful and the message was sent. 


OS_MBOX_FULL

The mailbox already contains a message. Only one message at a time can be sent and thus, the message MUST be consumed before another can be sent. 


OS_ERR_EVENT_TYPE

Attempting to post to a non-mailbox.

Library 


UCOS2.LIB

See also 


OSMboxAccept, OSMboxCreate, OSMboxPend, OSMboxQuery

OSMboxQuery 



INT8U OSMboxQuery (OS_EVENT *pevent, OS_MBOX_DATA *pdata);

Description

Obtains information about a message mailbox.

Parameters 


pevent

Pointer to message mailbox's event control block. 


pdata

Pointer to a data structure for information about the message mailbox

Return value 


OS_NO_ERR

The call was successful and the message was sent. 


OS_ERR_EVENT_TYPE

Attempting to obtain data from a non mailbox.

Library 


UCOS2.LIB

See also 


OSMboxAccept, OSMboxCreate, OSMboxPend, OSMboxPost

OSMemCreate 



OS_MEM *OSMemCreate (void *addr, INT32U nblks, INT32U blksize, INT8U *err);

Description

Creates a fixed-sized memory partition that will be managed by µC/OS-II.

Parameters 


addr

Pointer to starting address of the partition. 


nblks

Number of memory blocks to create in the partition. 


blksize

The size (in bytes) of the memory blocks. 


err

Pointer to variable containing an error message.

Return value

Pointer to the created memory partition control block if one is available, NULL pointer otherwise.

Library 


UCOS2.LIB

See also 


OSMemGet, OSMemPut, OSMemQuery

OSMemGet 



void *OSMemGet (OS_MEM *pmem, INT8U *err);

Description

Gets a memory block from the specified partition.

Parameters 


pmem

Pointer to partition's memory control block 


err

Pointer to variable containing an error message

Return value

Pointer to a memory block or a NULL pointer if an error condition is detected.

Library 


UCOS2.LIB

See also 


OSMemCreate, OSMemPut, OSMemQuery

OSMemPut 



INT8U OSMemPut(OS_MEM *pmem, void *pblk);

Description

Returns a memory block to a partition.

Parameters 


pmem

Pointer to the partition's memory control block. 


pblk

Pointer to the memory block being released.

Return value 


OS_NO_ERR

The memory block was inserted into the partition. 


OS_MEM_FULL

If returning a memory block to an already FULL memory partition. (More blocks were freed than allocated!)

Library 


UCOS2.LIB

See also 


OSMemCreate, OSMemGet, OSMemQuery

OSMemQuery 



INT8U OSMemQuery (OS_MEM *pmem, OS_MEM_DATA *pdata);

Description

Determines the number of both free and used memory blocks in a memory partition.

Parameters 


pmem

Pointer to partition's memory control block. 


pdata

Pointer to structure for holding information about the partition.

Return value 


OS_NO_ERR

This function always returns no error.

Library 


UCOS2.LIB

See also 


OSMemCreate, OSMemGet, OSMemPut

OSQAccept 



void *OSQAccept (OS_EVENT *pevent);

Description

Checks the queue to see if a message is available. Unlike OSQPend(), with OSQAccept() the calling task is not suspended if a message is unavailable.

Parameters 


pevent

Pointer to the message queue's event control block.

Return value

Pointer to message in the queue if one is available, NULL pointer otherwise.

Library 


UCOS2.LIB

See also 


OSQCreate, OSQFlush, OSQPend, OSQPost, OSQPostFront, OSQQuery

OSQCreate 



OS_EVENT *OSQCreate (void **start, INT16U qsize);

Description

Creates a message queue if event control blocks are available.

Parameters 


start

Pointer to the base address of the message queue storage area. The storage area MUST be declared an array of pointers to void: void *MessageStorage[qsize]. 


qsize

Number of elements in the storage area.

Return value

Pointer to message queue's event control block or NULL pointer if no event control blocks were available.

Library 


UCOS2.LIB

See also 


OSQAccept, OSQFlush, OSQPend, OSQPost, OSQPostFront, OSQQuery

OSQFlush 



INT8U OSQFlush (OS_EVENT *pevent);

Description

Flushes the contents of the message queue.

Parameters 


pevent

Pointer to message queue's event control block.

Return value

OS_NO_ERR: Success.
OS_ERR_EVENT_TYPE: A pointer to a queue was not passed.
OS_ERR_PEVENT_NULL: If pevent is a NULL pointer.

Library 


UCOS2.LIB

See also 


OSQAccept, OSQCreate, OSQPend, OSQPost, OSQPostFront, OSQQuery

OSQPend 



void *OSQPend (OS_EVENT *pevent, INT16U timeout, INT8U *err);

Description

Waits for a message to be sent to a queue.

Parameters 


pevent

Pointer to message queue's event control block. 


timeout

Allow task to resume execution if a message was not received by the number of clock ticks specified. Specifying 0 means the task is willing to wait forever. 


err

Pointer to a variable for holding an error code.

Return value

Pointer to a message or, if a timeout occurs, a NULL pointer.

Library 


UCOS2.LIB

See also 


OSQAccept, OSQCreate, OSQFlush, OSQPost, OSQPostFront, OSQQuery

OSQPost 



INT8U OSQPost (OS_EVENT *pevent, void *msg);

Description

Sends a message to the specified queue.

Parameters 


pevent

Pointer to message queue's event control block. 


msg

Pointer to the message to send. NULL pointer must not be sent.

Return value

OS_NO_ERR: The call was successful and the message was sent.
OS_Q_FULL: The queue cannot accept any more messages because it is full.
OS_ERR_EVENT_TYPE: If a pointer to a queue not passed.
OS_ERR_PEVENT_NULL: If pevent is a NULL pointer.
OS_ERR_POST_NULL_PTR: If attempting to post to a NULL pointer.

Library 


UCOS2.LIB

See also 


OSQAccept, OSQCreate, OSQFlush, OSQPend, OSQPostFront, OSQQuery

OSQPostFront 



INT8U OSQPostFront (OS_EVENT *pevent, void *msg);

Description

Sends a message to the specified queue, but unlike OSQPost(), the message is posted at the front instead of the end of the queue. Using OSQPostFront() allows 'priority' messages to be sent.

Parameters 


pevent

Pointer to message queue's event control block. 


msg

Pointer to the message to send. NULL pointer must not be sent.

Return value

OS_NO_ERR - The call was successful and the message was sent.
OS_Q_FULL - The queue cannot accept any more messages because it is full.
OS_ERR_EVENT_TYPE - A pointer to a queue was not passed.
OS_ERR_PEVENT_NULL - If pevent is a NULL pointer.
OS_ERR_POST_NULL_PTR - Attempting to post to a non mailbox.

Library 


UCOS2.LIB

See also 


OSQAccept, OSQCreate, OSQFlush, OSQPend, OSQPost, OSQQuery

OSQQuery 



INT8U OSQQuery (OS_EVENT *pevent, OS_Q_DATA *pdata);

Description

Obtains information about a message queue.

Parameters 


pevent

Pointer to message queue's event control block. 


pdata

Pointer to a data structure for message queue information.

Return value

OS_NO_ERR - The call was successful and the message was sent.
OS_ERR_EVENT_TYPE - Attempting to obtain data from a non queue.
OS_ERR_PEVENT_NULL - If pevent is a NULL pointer.

Library 


UCOS2.LIB

See also 


OSQAccept, OSQCreate, OSQFlush, OSQPend, OSQPost, OSQPostFront

OSSchedLock 



void OSSchedLock(void);

Description

Prevents task rescheduling. This allows an application to prevent context switches until it is ready for them. There must be a matched call to OSSchedUnlock() for every call to OSSchedLock().

Library 


UCOS2.LIB

See also 


OSSchedUnlock

OSSchedUnlock 



void OSSchedUnlock(void);

Description

Allow task rescheduling. There must be a matched call to OSSchedUnlock() for every call to OSSchedLock().

Library 


UCOS2.LIB

See also 


OSSchedLock

OSSemAccept 



INT16U OSSemAccept (OS_EVENT *pevent);

Description

This function checks the semaphore to see if a resource is available or if an event occurred. Unlike OSSemPend(), OSSemAccept() does not suspend the calling task if the resource is not available or the event did not occur.

Parameters 


pevent

Pointer to the desired semaphore's event control block

Return value

Semaphore value:
If >0, semaphore value is decremented; value is returned before the decrement.
If 0, then either resource is unavailable, event did not occur, or NULL or invalid pointer was passed to the function.

Library 


UCOS2.LIB

See also 


OSSemCreate, OSSemPend, OSSemPost, OSSemQuery

OSSemCreate 



OS_EVENT *OSSemCreate (INT16U cnt);

Description

Creates a semaphore.

Parameters 


 cnt

The initial value of the semaphore.

Return value

Pointer to the event control block (OS_EVENT) associated with the created semaphore, or NULL if no event control block is available.

Library 


UCOS2.LIB

See also 


OSSemAccept, OSSemPend, OSSemPost, OSSemQuery

OSSemPend 



void OSSemPend (OS_EVENT *pevent, INT16U timeout, INT8U *err);

Description

Waits on a semaphore.

Parameters 


pevent

Pointer to the desired semaphore's event control block 


timeout

Time in clock ticks to wait for the resource. If 0, the task will wait until the resource becomes available or the event occurs. 


err

Pointer to error message.

Library 


UCOS2.LIB

See also 


OSSemAccept, OSSemCreate, OSSemPost, OSSemQuery

OSSemPost 



INT8U OSSemPost (OS_EVENT *pevent);

Description

This function signals a semaphore.

Parameters 


pevent

Pointer to the desired semaphore's event control block

Return value

OS_NO_ERR - The call was successful and the semaphore was signaled.
OS_SEM_OVF - If the semaphore count exceeded its limit. In other words, you have signalled the semaphore more often than you waited on it with either OSSemAccept() or OSSemPend().
OS_ERR_EVENT_TYPE - If a pointer to a semaphore not passed.
OS_ERR_PEVENT_NULL - If pevent is a NULL pointer.

Library 


UCOS2.LIB

See also 


OSSemAccept, OSSemCreate, OSSemPend, OSSemQuery

OSSemQuery 



INT8U OSSemQuery (OS_EVENT *pevent, OS_SEM_DATA *pdata);

Description

Obtains information about a semaphore.

Parameters 


pevent

Pointer to the desired semaphore's event control block 


pdata

Pointer to a data structure that will hold information about the semaphore.

Return value

OS_NO_ERR - The call was successful and the message was sent.
OS_ERR_EVENT_TYPE - Attempting to obtain data from a non semaphore.
OS_ERR_PEVENT_NULL - If pevent is a NULL pointer.

Library 


UCOS2.LIB

See also 


OSSemAccept, OSSemCreate, OSSemPend, OSSemPost

OSSetTickPerSec 



INT16U OSSetTickPerSec(INT16U TicksPerSec);

Description

Sets the amount of ticks per second (from 1 - 2048). Ticks per second defaults to 64. If this function is used, the #define OS_TICKS_PER_SEC needs to be changed so that the time delay functions work correctly. Since this function uses integer division, the actual ticks per second may be slightly different that the desired ticks per second.

Parameters 


TicksPerSec

Unsigned 16-bit integer.

Return value

The actual ticks per second set, as an unsigned 16-bit integer.

Library 


UCOS2.LIB

See also 


OSStart

OSStart 



void OSStart(void);

Description

Starts the multitasking process, allowing µC/OS-II to manage the tasks that have been created. Before OSStart() is called, OSInit() MUST have been called and at least one task MUST have been created. This function calls OSStartHighRdy which calls OSTaskSwHook and sets OSRunning to TRUE.

Library 


UCOS2.LIB

See also 


OSTaskCreate, OSTaskCreateExt

OSStatInit 



void OSStatInit(void);

Description

Determines CPU usage.

Library 


UCOS2.LIB

OSTaskChangePrio 



INT8U OSTaskChangePrio (INT8U oldprio, INT8U newprio);

Description

Allows a task's priority to be changed dynamically. Note that the new priority MUST be available.

Parameters 


oldprio

The priority level to change from. 


newprio

The priority level to change to.

Return value

OS_NO_ERR - The call was successful.
OS_PRIO_INVALID - The priority specified is higher that the maximum allowed (i.e. ≥ OS_LOWEST_PRIO).
OS_PRIO_EXIST - The new priority already exist.
OS_PRIO_ERR - There is no task with the specified OLD priority (i.e. the OLD task does not exist).

Library 


UCOS2.LIB

OSTaskCreate 



INT8U OSTaskCreate(void (*task)(), void *pdata, INT16U stk_size, INT8U prio);

Description

Creates a task to be managed by µC/OS-II. Tasks can either be created prior to the start of multitasking or by a running task. A task cannot be created by an ISR.

Parameters 


task

Pointer to the task's starting address. 


pdata

Pointer to a task's initial parameters. 


stk_size

Number of bytes of the stack. 


prior

The task's unique priority number.

Return value

OS_NO_ERR - The call was successful.
OS_PRIO_EXIT - Task priority already exists (each task MUST have a unique priority).
OS_PRIO_INVALID - The priority specified is higher than the maximum allowed (i.e.  ≥ OS_LOWEST_PRIO).

Library 


UCOS2.LIB

See also 


OSTaskCreateExt

OSTaskCreateExt 



INT8U OSTaskCreateExt (void   (*task)(), void *pdata, INT8U prio, INT16U id, INT16U stk_size, void *pext, INT16U opt);

Description

Creates a task to be managed by µC/OS-II. Tasks can either be created prior to the start of multitasking or by a running task. A task cannot be created by an ISR. This function is similar to OSTaskCreate() except that it allows additional information about a task to be specified.

Parameters 


task

Pointer to task's code. 


pdata

Pointer to optional data area; used to pass parameters to the task at start of execution. 


prio

The task's unique priority number; the lower the number the higher the priority. 


id

The task's identification number (0...65535). 


stk_size

Size of the stack in number of elements. If OS_STK is set to INT8U, stk_size corresponds to the number of bytes available. If OS_STK is set to INT16U, stk_size contains the number of 16-bit entries available. Finally, if OS_STK is set to INT32U, stk_size contains the number of 32-bit entries available on the stack. 


pext

Pointer to a user-supplied Task Control Block (TCB) extension. 


opt

The lower 8 bits are reserved by µC/OS-II. The upper 8 bits control application-specific options. Select an option by setting the corresponding bit(s).

Return value

OS_NO_ERR - The call was successful.
OS_PRIO_EXIT - Task priority already exists (each task MUST have a unique priority).
OS_PRIO_INVALID - The priority specified is higher than the maximum allowed (i.e. ≥OS_LOWEST_PRIO).

Library 


UCOS2.LIB

See also 


OSTaskCreate

OSTaskCreateHook 



void OSTaskCreateHook(OS_TCB *ptcb);

Description

Called by µC/OS-II whenever a task is created. This call-back function resides in UCOS2.LIB and extends functionality during task creation by allowing additional information to be passed to the kernel, anything associated with a task. This function can also be used to trigger other hardware, such as an oscilloscope. Interrupts are disabled during this call, therefore, it is recommended that code be kept to a minimum.

Parameters 


ptcb

Pointer to the TCB of the task being created.

Library 


UCOS2.LIB

See also 


OSTaskDelHook

OSTaskDel 



INT8U OSTaskDel (INT8U prio);

Description

Deletes a task. The calling task can delete itself by passing either its own priority number or OS_PRIO_SELF if it doesn't know its priority number. The deleted task is returned to the dormant state and can be re-activated by creating the deleted task again.

Parameters 


prio

Task's priority number.

Return value

OS_NO_ERR - The call was successful.
OS_TASK_DEL_IDLE - Attempting to delete uC/OS-II's idle task.
OS_PRIO_INVALID - The priority specified is higher than the maximum allowed (i.e. ≥ OS_LOWEST_PRIO) or, OS_PRIO_SELF not specified.
OS_TASK_DEL_ERR - The task to delete does not exist.
OS_TASK_DEL_ISR - Attempting to delete a task from an ISR.

Library 


UCOS2.LIB

See also 


OSTaskDelReq

OSTaskDelHook 



void OSTaskDelHook(OS_TCB *ptcb);

Description

Called by µC/OS-II whenever a task is deleted. This call-back function resides in UCOS2.LIB. Interrupts are disabled during this call, therefore, it is recommended that code be kept to a minimum.

Parameters 


ptcb

Pointer to TCB of task being deleted.

Library 


UCOS2.LIB

See also 


OSTaskCreateHook

OSTaskDelReq 



INT8U OSTaskDelReq (INT8U prio);

Description

Notifies a task to delete itself. A well-behaved task is deleted when it regains control of the CPU by calling OSTaskDelReq (OSTaskDelReq) and monitoring the return value.

Parameters 


prio

The priority of the task that is being asked to delete itself. OS_PRIO_SELF is used when asking whether another task wants the current task to be deleted.

Return value

OS_NO_ERR - The task exists and the request has been registered.
OS_TASK_NOT_EXIST - The task has been deleted. This allows the caller to know whether the request has been executed.
OS_TASK_DEL_IDLE - If requesting to delete uC/OS-II's idletask.
OS_PRIO_INVALID - The priority specified is higher than the maximum allowed (i.e. ≥ OS_LOWEST_PRIO) or, OS_PRIO_SELF is not specified.
OS_TASK_DEL_REQ - A task (possibly another task) requested that the running task be deleted.

Library 


UCOS2.LIB

See also 


OSTaskDel

OSTaskQuery 



INT8U OSTaskQuery (INT8U prio, OS_TCB *pdata);

Description

Obtains a copy of the requested task's TCB.

Parameters 


 prio

Priority number of the task. 


 pdata

Pointer to task's TCB.

Return value

OS_NO_ERR - The requested task is suspended.
OS_PRIO_INVALID - The priority you specify is higher than the maximum allowed (i.e. ≥ OS_LOWEST_PRIO) or, OS_PRIO_SELF is not specified.
OS_PRIO_ERR - The desired task has not been created.

Library 


UCOS2.LIB

OSTaskResume 



INT8U OSTaskResume (INT8U prio);

Description

Resumes a suspended task. This is the only call that will remove an explicit task suspension.

Parameters 


prio

The priority of the task to resume.

Return value

OS_NO_ERR - The requested task is resumed.
OS_PRIO_INVALID - The priority specified is higher than the maximum allowed (i.e. ≥ OS_LOWEST_PRIO).
OS_TASK_NOT_SUSPENDED - The task to resume has not been suspended.

Library 


UCOS2.LIB

See also 


OSTaskSuspend

OSTaskStatHook 



void OSTaskStatHook();

Description

Called every second by µC/OS-II's statistics task. This function resides in UCOS2.LIB and allows an application to add functionality to the statistics task.

Library 


UCOS2.LIB

OSTaskStkChk 



INT8U OSTaskStkChk (INT8U prio, OS_STK_DATA *pdata);

Description

Check the amount of free memory on the stack of the specified task.

Parameters 


prio

The task's priority. 


pdata

Pointer to a data structure of type OS_STK_DATA.

Return value

OS_NO_ERR - The call was successful.
OS_PRIO_INVALID - The priority you specify is higher than the maximum allowed (i.e. > OS_LOWEST_PRIO) or, OS_PRIO_SELF not specified.
OS_TASK_NOT_EXIST - The desired task has not been created.
OS_TASK_OPT_ERR - If OS_TASK_OPT_STK_CHK was NOT specified when the task was created.

Library 


UCOS2.LIB

See also 


OSTaskCreateExt

OSTaskSuspend 



INT8U OSTaskSuspend (INT8U prio);

Description

Suspends a task. The task can be the calling task if the priority passed to OSTaskSuspend() is the priority of the calling task or OS_PRIO_SELF. This function should be used with great care. If a task is suspended that is waiting for an event (i.e. a message, a semaphore, a queue ...) the task will be prevented from running when the event arrives.

Parameters 


prio

The priority of the task to suspend.

Return value

OS_NO_ERR - The requested task is suspended.
OS_TASK_SUS_IDLE - Attempting to suspend the idle task (not allowed).
OS_PRIO_INVALID - The priority specified is higher than the maximum allowed (i.e. ≥ OS_LOWEST_PRIO) or, OS_PRIO_SELF is not specified .
OS_TASK_SUS_PRIO - The task to suspend does not exist.

Library 


UCOS2.LIB

See also 


OSTaskResume

OSTaskSwHook 



void OSTaskSwHook();

Description

Called whenever a context switch happens. The TCB for the task that is ready to run is accessed via the global variable OSTCBHighRdy, and the TCB for the task that is being switched out is accessed via the global variable OSTCBCur.

Library 


UCOS2.LIB

OSTimeDly 



void OSTimeDly (INT16U ticks);

Description

Delays execution of the task for the specified number of clock ticks. No delay will result if ticks is 0. If ticks is >0, then a context switch will result.

Parameters 


ticks

Number of clock ticks to delay the task.

Library 


UCOS2.LIB

See also 


OSTimeDlyHMSM, OSTimeDlyResume, OSTimeDlySec

OSTimeDlyHMSM 



INT8U OSTimeDlyHMSM (INT8U hours, INT8U minutes, INT8U seconds, INT16U milli);

Description

Delays execution of the task until specified amount of time expires. This call allows the delay to be specified in hours, minutes, seconds and milliseconds instead of ticks. The resolution on the milliseconds depends on the tick rate. For example, a 10 ms delay is not possible if the ticker interrupts every 100 ms. In this case, the delay would be set to 0. The actual delay is rounded to the nearest tick.

Parameters 


hours

Number of hours that the task will be delayed (max. is 255) 


minutes

Number of minutes (max. 59) 


seconds

Number of seconds (max. 59) 


milli

Number of milliseconds (max. 999)

Return value

OS_NO_ERR
OS_TIME_INVALID_MINUTES
OS_TIME_INVALID_SECONDS
OS_TIME_INVALID_MS
OS_TIME_ZERO_DLY

Library 


UCOS2.LIB

See also 


OSTimeDly, OSTimeDlyResume, OSTimeDlySec

OSTimeDlyResume 



INT8U OSTimeDlyResume (INT8U prio);

Description

Resumes a task that has been delayed through a call to either OSTimeDly() or OSTimeDlyHMSM(). Note that this function MUST NOT be called to resume a task that is waiting for an event with timeout. This situation would make the task look like a timeout occurred (unless this is the desired effect). Also, a task cannot be resumed that has called OSTimeDlyHMSM() with a combined time that exceeds 65535 clock ticks. In other words, if the clock tick runs at 100 Hz then, a delayed task will not be able to be resumed that called OSTimeDlyHMSM(0, 10, 55, 350) or higher.

Parameters 


prio

Priority of the task to resume.

Return value

OS_NO_ERR - Task has been resumed.
OS_PRIO_INVALID - The priority you specify is higher than the maximum allowed (i.e. ≥ OS_LOWEST_PRIO).
OS_TIME_NOT_DLY - Task is not waiting for time to expire.
OS_TASK_NOT_EXIST - The desired task has not been created.

Library 


UCOS2.LIB

See also 


OSTimeDly, OSTimeDlyHMSM, OSTimeDlySec

OSTimeDlySec 



INT8U OSTimeDlySec (INT16U seconds);

Description

Delays execution of the task until seconds expires. This is a low-overhead version of OSTimeDlyHMSM for seconds only.

Parameters 


  seconds

The number of seconds to delay.

Return value

OS_NO_ERR - The call was successful.
OS_TIME_ZERO_DLY - A delay of zero seconds was requested.

Library 


UCOS2.LIB

See also 


OSTimeDly, OSTimeDlyHMSM, OSTimeDlyResume

OSTimeGet 



INT32U OSTimeGet (void);

Description

Obtain the current value of the 32-bit counter that keeps track of the number of clock ticks.

Return value

The current value of OSTime.

Library 


UCOS2.LIB

See also 


OSTimeSet

OSTimeSet 



void OSTimeSet (INT32U ticks);

Description

Sets the 32-bit counter that keeps track of the number of clock ticks.

Parameters 


ticks

The value to set OSTime to.

Library 


UCOS2.LIB

See also 


OSTimeGet

OSTimeTickHook 



void OSTimeTickHook();

Description

This function, as included with Dynamic C, is a stub that does nothing except return. It is called every clock tick. If the user chooses to rewrite this function, code should be kept to a minimum as it will directly affect interrupt latency. This function must preserve any registers it uses, other than the ones that are preserved prior to the call to OSTimeTickHook at the beginning of the periodic interrupt (periodic_isr in VDRIVER.LIB). Therefore, OSTimeTickHook should be written in assembly. The registers saved by periodic_isr are: AF,IP, HL,DE and IX.

Library 


UCOS2.LIB

OSVersion 



INT16U OSVersion (void);

Description

Returns the version number of µC/OS-II. The returned value corresponds to µC/OS-II's version number multiplied by 100; i.e., version 2.00 would be returned as 200.

Return value

Version number multiplied by 100.

Library 


UCOS2.LIB

outchrs 



char outchrs(char c, int n, int (*putc) () );

Description

Use putc to output n times the character c.

Parameters 


c

Character to output 


n

Number of times to output 


putc

Routine to output one character. The function pointed to by putc should take a character argument.

Return value

The character in parameter c.

Library 


STDIO.LIB

See also 


outstr

outstr 



char *outstr(char *string, int (*putc)() );

Description

Output the string pointed to by string via calls to putc. putc should take a one-character parameter.

Parameters 


string

String to output 


putc

Routine to output one character. The function pointed to by putc should take a character argument.

Return value

Pointer to NULL at end of string.

Library 


STDIO.LIB

See also 


outchrs

paddr 



unsigned long paddr(void* pointer);

Description

Converts a logical pointer into its physical address. Use caution when converting address in the E000-FFFF range. Returns the address based on the XPC on entry.

Parameters 


pointer

The pointer to convert.

Return value

The physical address of the pointer.

Library 


XMEM.LIB

pktXclose 



void pktXclose();

Description

Disables serial port X, where X is A|B|C|D. Starting with Dynamic C version 7.25, the functions pktEclose() and pktFclose() may be used with the Rabbit 3000 microprocessor.

Library 


PACKET.LIB

pktXgetErrors 



char pktXgetErrors();

Description

Gets a bit field with flags set for any errors that occured on port X, where X is A|B|C|D. These flags are then cleared, so that a particular error will only cause the flag to be set once.

Starting with Dynamic C version 7.25, the functions pktEgetErrors() and pktFgetErrors() may be used with the Rabbit 3000 microprocessor.

Return value

A bit field with flags for various errors. The errors along with their bit masks are as follows:

PKT_BUFFEROVERFLOW  0x01
PKT_RXOVERRUN       0x02
PKT_PARITYERROR     0x04
PKT_NOBUFFER        0x08

Library 


PACKET.LIB

pktXinitBuffers 



int pktXinitBuffers(int buf_count, int buf_size); X = A|B|C|D

Description

Allocates extended memory for channel X receive buffers. This function should not be called more than once in a program. The total memory allocated is buf_count*(buf_size + 2) bytes.

Starting with Dynamic C version 7.25, the functions pktEinitBuffers() and pktFinitBuffers() may be used with the Rabbit 3000 microprocessor.

Parameters 


buf_count

The number of buffers to allocate. Each buffer can store one received packet. Increasing this number allows for more pending packets and a larger latency time before packets must be processed by the user's program. 


buf_size

The number of bytes each buffer can accomodate. This should be set to the size of the largest possible packet that can be expected.

Return value

1: Success, extended memory was allocated.
0: Failure, no memory allocated, the packet channel cannot be used.

Library 


PACKET.LIB

pktXopen 



int pktXopen(long baud, int mode, char options, int (*test_packet)());

Description

Opens serial port X, where X is A|B|C|D. Starting with Dynamic C version 7.25, the functions pktEopen() and pktFopen() may be used with the Rabbit 3000 microprocessor.

Parameters 


baud

Bits per second of data transfer: minimum is 2400. 


mode

Type of packet scheme used, the options are:

· PKT_GAPMODE

· PKT_9BITMODE

· PKT_CHARMODE


options

Further specification for the packet scheme. The value of this depends on the mode used:

· gap mode - minimum gap size(in byte times)

· 9-bit mode - type of 9-bit protocol

· PKT_RABBITSTARTBYTE
 · PKT_LOWSTARTBYTE
 · PKT_HIGHSTARTBYTE

· char mode - character marking start of packet


test_packet

Pointer to a function that tests for completeness of a packet. The function should return 1 if the packet is complete, or 0 if more data should be read in. For gap mode the test function is not used and should be set to NULL.

Return value

1: The baud set on the rabbit is the same as the input baud.
0: The baud set on the rabbit does not match the input baud.

Library 


PACKET.LIB

pktXreceive 



int pktXreceive(void *buffer, int buffer_size);

Description

Gets a received packet, if there is one, from serial port X, where X is A|B|C|D. Starting with Dynamic C version 7.25, the functions pktEreceive() and pktFreceive() may be used with the Rabbit 3000 microprocessor.

Parameters 


buffer

A buffer for the packet to be written into. 


buffer_size

Length of the data buffer.

Return value

>0: Number of bytes in the successfully received packet.
 0: No new packet has been received.
-1: The packet is too large for the given buffer
-2: A needed test_packet function is not defined

Library 


PACKET.LIB

pktXsend 



int pktXsend(void *send_buffer, int buffer_length, char delay);

Description

Initiates the sending of a packet of data using serial port X, where X is A|B|C|D. This function will always return immediately. If there is already a packet being transmitted, this call will return 0 and the packet will not be transmitted, otherwise it will return 1.

pktXsending() checks if the packet is done transmitting. The system will be using the buffer until then.

Starting with Dynamic C version 7.25, the functions pktEsend() and pktFsend() may be used with the Rabbit 3000 microprocessor.

Parameters 


send_buffer

The data to be sent 


buffer_length

Length of the data buffer to transmit 


delay

The number of byte times to delay before sending the data (0-255) This is used to implement protocol-specific delays between packets

Return value

1: The packet is going to be transmitted.
0: There is already a packet transmitting, and the new packet was refused.

Library 


PACKET.LIB

pktXsending 



int pktXsending();

Description

Tests if a packet is currently being sent on serial port X, where X=A|B|C|D. If pktXsending() returns true, the transmitter is busy and cannot accept another packet.

Starting with Dynamic C version 7.25, the functions pktEsending() and pktFsending() may be used with the Rabbit 3000 microprocessor.

Return value

1: A packet is being transmitted.
0: Port X is idle, ready for a new packet.

Library 


PACKET.LIB

pktXsetParity 



void pktXsetParity(char mode);

Description

Configures parity generation and checking. Can also configure for 2 stop bits.

Starting with Dynamic C version 7.25, the functions pktEsetParity() and pktFsetParity() may be used with the Rabbit 3000 microprocessor.

Parameters 


mode

Code for mode of parity bit:

· PKT_NOPARITY - no parity bit (8N1 format, default)

· PKT_OPARITY - odd parity (8O1 format)

· PKT_EPARITY - even parity (8E1 format)

· PKT_TWOSTOP - an extra stop bit (8N2 format)

Library 


PACKET.LIB

poly 



float poly(float x, int n, float c[]);

Description

Computes polynomial value by Horner's method. For example, for the fourth-order polynomial 10x4 - 3x2 + 4x + 6, n would be 4 and the coefficients would be 


c[4] = 10.0
c[3] =  0.0
c[2] = -3.0
c[1] =  4.0
c[0] =  6.0

Parameters 


x

Variable of the polynomial. 


n

The order of the polynomial 


c

Array containing the coefficients of each power of x.

Return value

The polynomial value.

Library 


MATH.LIB

pow 



float pow(float x, float y);

Description

Raises x to the yth power.

Parameters 


x

Value to be raised 


y

Exponent

Return value

x to the yth power

Library 


MATH.LIB

See also 


exp, pow10, sqrt

pow10 



float pow10(float x);

Description

10 to the power of x.

Parameters 


x

Exponent

Return value

10 raised to power x

Library 


MATH.LIB

See also 


pow, exp, sqrt

powerspectrum 



void powerspectrum(int *x, int N, *int blockexp);

Description

Computes the power spectrum from a complex spectrum according to

Power[k] = (Re X[k])2 + (Im X[k])2

The N-point power spectrum replaces the N-point complex spectrum. The power of each complex spectral component is computed as a 32-bit fraction. Its more significant 16-bits replace the imaginary part of the component; its less significant 16-bits replace the real part.

If the complex input spectrum is a positive-frequency spectrum computed by fftreal(), the imaginary part of the X[0] term (stored x[1]) will contain the real part of the fmax term and will affect the calculation of the dc power. If the dc power or the fmax power is important, the fmax term should be retrieved from x[1] and x[1] set to zero before calling powerspectrum().

The power of the kth term can be retrieved via P[k]=*(long*)&x[2k]*2^blockexp.

The value of blockexp is first doubled to reflect the squaring operation applied to all elements in array x. Then it is further increased by 1 to reflect an inherent division-by-two that occurs during the squaring operation.

Parameters 


x

pointer to N-element array of complex fractions. 


N

number of complex elements in array x. 


blockexp

pointer to integer block exponent.

Library 


FFT.LIB

See also 


fftcplx, fftcplxinv, fftreal, fftrealinv, hanncplx, hannreal

premain 



void premain();

Description

Dynamic C calls premain to start initialization functions such as VdInit. The final thing premain does is call main. This function should never be called by an application program. It is included here for informational purposes only.

Library 


PROGRAM.LIB

printf 



int printf(char *fmt, ...);

Description

This function is similar to sprintf(), but outputs the formatted string to the Stdio window in Dynamic C. Please refer to the description of sprintf() for more details.

This function is task reentrant.

Prior to Dynamic C 7.25, it would work only with the controller in program mode connected to the PC running Dynamic C. As of Dynamic C 7.25, it is possible to redirect printf output to a serial port during run mode by defining a macro to specify the serial port. See the sample program /SAMPLES/STDIO_SERIAL.C for more information.

Parameters 


format

String to be formatted. 


...

Format arguments.

Return Value

Number of characters written

Library 


STDIO.LIB

See also 


sprintf

putchar 



void putchar(int ch);

Description

Puts a single character to Stdout. The user should make sure only one process calls this function at a time.

Parameters 


ch

Character to be displayed.

Library 


STDIO.LIB

See also 


puts, getchar

puts 



int puts(char *s);

Description

This function displays the string on the stdio window in Dynamic C. The Stdio window is responsible for interpreting any escape code sequences contained in the string. Only one process at a time should call this function.

Parameters 


s

Pointer to string argument to be displayed.

Return value

1: Success.

Library 


STDIO.LIB

See also 


putchar, gets

pwm_init 



unsigned long pwm_init(unsigned long frequency);

Description

Sets the base frequency for the pulse width modulation (PWM) and enables the PWM driver on all four channels. The base frequency is the frequency without pulse spreading. Pulse spreading (see pwm_set()) will increase the frequency by a factor of 4.

This function is intended for use with the Rabbit 3000 microprocessor.

Parameter 


frequency

Requested frequency (in Hz)

Return Value

The actual frequency that was set. This will be the closest possible match to the requested frequency.

Library 


R3000.LIB

pwm_set 



int pwm_set(int channel, int duty_cycle, int options);

Description

Sets a duty cycle for one of the pulse width modulation (PWM) channels. The duty cycle can be a value from 0 to 1024, where 0 is logic low the whole time, and 1024 is logic high the whole time. Option flags are used to enable features on an individual PWM channel. Bit masks for these are:

This function is intended for use with the Rabbit 3000 microprocessor.

Parameters 


channel

PWM channel(0 to 3) 


duty_cycle

value from 0 to 1024 


options

combination of optional flags(see above)

Return Value

 0: Success.
-1: Error, an invalid channel number is used.
-2: Error, requested duty_cycle is invalid.

Library 


R3000.LIB

qd_error 



char qd_error(int channel);

Description

Gets the current error bits for that qd channel. This function is intended to be used with the Rabbit 3000 microprocessor.

Parameters 


channel

The channel to read errors from (currently 1 or 2).

Return Value

Set of error flags, that can be decoded with the following masks:

Library 


R3000.LIB

qd_init 



void qd_init(int iplevel);

Description

Initializes the quadrature decoders and sets up the ISR. This must be called before any other QD functions are used. Sets up the lower nibble of port F to be the QD input pins.

This function is intended for use with the Rabbit 3000 microprocessor.

Parameters 


iplevel

The interrupt priority for the ISR that handles the count overflow. This should usually be 1.

Library 


R3000.LIB

qd_read 



long qd_read(int channel);

Description

Reads the current quadrature decoder count. Since this function waits for a clear reading, it can potentially block if there is enough flutter in the decoder count.

This function is intended to be used with the Rabbit 3000 microprocessor.

Parameters 


channel

The channel to read (currently 1 or 2).

Return Value

Returns a signed long for the current count.

Library 


R3000.LIB

qd_zero 



void qd_zero(int channel);

Description

Sets the count for a channel to 0. This function is intended to be used with the Rabbit 3000 microprocessor.

Parameters 


channel

The channel to reset (currently 1 or 2)

Library 


R3000.LIB

qsort 



int qsort(char *base, unsigned n, unsigned s, int (*cmp) ());

Description

Quick sort with center pivot, stack control, and easy-to-change comparison method. This version sorts fixed-length data items. It is ideal for integers, longs, floats and packed string data without delimiters.

Can sort raw integers, longs, floats or strings. However, the string sort is not efficient.

Parameters 


base

Base address of the raw string data 


n

Number of blocks to sort 


s

Number of bytes in each block 


cmp

User-supplied compare routine for two block pointers, p and q, that returns an int with the same rules used by Unix strcmp(p,q):

= 0: Blocks p and q are equal
< 0: p is less than q
> 0: p is greater than q

Beware of using ordinary strcmp()--it requires a NULL at the end of each string.

Return value

0 if the operation is successful.

Library 


SYS.LIB

Example 

// Sort an array of integers.
int mycmp(p,q) int *p,*q; { return (*p - *q);}
const int q[10] = {12,1,3,-2,16,7,9,34,-90,10};
const int p[10] = {12,1,3,-2,16,7,9,34,-90,10};
main() {
    int i;
    qsort(p,10,2,mycmp);
    for(i=0;i<10;++i) printf("%d. %d, %d\n",i,p[i],q[i]);
}



Output from the above sample program:

0. -90,  12
1.  -2,   1
2.   1,   3
3.   3,  -2
4.   7,  16
5.   9,   7
6.  10,   9
7.  12,  34
8.  16, -90
9.  34,  10

rad 



float rad(float x);

Description

Convert degrees (360 for one rotation) to radians (2 for a rotation).

Parameters 


x

Degree value to convert

Return value

The radians equivalent of degree.

Library 


SYS.LIB

See also 


deg

rand 



float rand(void);

Description

Returns a uniformly distributed random number in the range 0.0 v < 1.0. Uses algorithm: 


rand = (5*rand)modulo 232

A default seed value is set on startup, but can be changed with the srand() function. rand() is not reentrant.

Return value

A uniformly distributed random number: 0.0 v < 1.0.

Library 


MATH.LIB

See also 


randb, randg, srand

randb 



float randb(void);

Description

Uses algorithm: 


rand = (5*rand)modulo 232

A default seed value is set on startup, but can be changed with the srand() function. randb() is not reentrant.

Return value

Returns a uniformly distributed random number: -1.0 v < 1.0.

Library 


MATH.LIB

See also 


rand, randg, srand

randg 



float randg(void);

Description

Returns a gaussian-distributed random number in the range -16.0 v < 16.0 with a standard deviation of approximately 2.6. The distribution is made by adding 16 random numbers (see rand()). This function is not task reentrant.

Return value

A gaussian distributed random number: -16.0 v <16.0.

Library 


MATH.LIB

See also 


rand, randb, srand

RdPortE 



int RdPortE(unsigned int port);

Description

Reads an external I/O register specified by the argument.

Parameters 


port

Address of external parallel port data register.

Return value

Returns an integer, the lower 8 bits of which contain the result of reading the port specified by the argument. Upper byte contains zero.

Library 


SYSIO.LIB

See also 


RdPortI, BitRdPortI, WrPortI, BitWrPortI, BitRdPortE, WrPortE, BitWrPortE

RdPortI 



int RdPortI(int port);

Description

Reads an internal I/O port specified by the argument.

Parameters 


port

Address of internal parallel port data register.

Return value

Returns an integer, the lower 8 bits of which contain the result of reading the port specified by the argument. Upper byte contains zero.

Library 


SYSIO.LIB

See also 


RdPortE, BitRdPortI, WrPortI, BitWrPortI, BitRdPortE, WrPortE, BitWrPortE

read_rtc 



unsigned long read_rtc(void);

Description

Reads the Real-time Clock (RTC) directly. Use with caution! In most cases use long variable SEC_TIMER, which contains the same result, unless the RTC has been changed since the start of the program. If you are running the processor off the 32 kHz crystal, use read_rtc_32kHz() instead.

Return value

Time in seconds since January 1, 1980 (if RTC set correctly).

Library 


RTCLOCK.LIB

See also 


write_rtc

read_rtc_32kHz 



unsigned long read_rtc_32kHz(void);

Description

Reads the real-time clock directly when the Rabbit processor is running off the 32 kHz oscillator. See read_rtc for more details.

Return value

Time in seconds since January 1, 1980 (if RTC set correctly).

Library 


RTCLOCK.LIB

readUserBlock 



int readUserBlock(void *dest, int addr, int numbytes);

Description

Reads a number of bytes from the user block on the primary flash to a buffer in root memory. NOTE: Portions of the user block may be used by the BIOS for your board to store values. For example, any board with an A to D converter will require the BIOS to write calibration constants to the user block. For some versions of the BL2000 and the BL2100 this memory area is 0x1C00 to 0x1FFF. See the user's manual for your particular board for more information before overwriting any part of the user block. Also, see the Rabbit 2000 Microprocessor Designer's Handbook for more information on the user block.

Parameters 


dest

Pointer to destination to copy data to. 


addr

Address offset in user block to read from. 


numbytes

Number of bytes to copy.

Return value

 0: Success
-1: Invalid address or range

Library 


IDBLOCK.LIB

See also 


writeUserBlock

res 



void res(void *address, unsigned int bit);

Description

Dynamic C may expand this call inline

Clears specified bit at memory address to 0. bit may be from 0 to 31. This is equivalent to the following expression, but more efficient:
*(long *)address &= ~(1L << bit)

Parameters 


address

Address of byte containing bits 7-0 


bit

Bit location where 0 represents the least significant bit

Library 


UTIL.LIB

See also 


RES

RES 



void RES(void *address, unsigned int bit);

Description

Dynamic C may expand this call inline.

Clears specified bit at memory address to 0. bit may be from 0 to 31. This is equivalent to the following expression, but more efficient:
*(long *)address &= ~(1L << bit)

Parameters 


address

Address of byte containing bits 7-0 


bit

Bit location where 0 represents the least significant bit

Library 


UTIL.LIB

See also 


res

ResetErrorLog 



void ResetErrorLog();

Description

This function resets the exception and restart type counts in the error log buffer header. This function is not called by default from anywhere. It should be used to initialized the error log when a board is programmed by means other than Dynamic C, cloning, the Rabbit Field Utility (RFU), or a service processor. For example, if boards are mass produced with pre-programmed flash chips, then the test program that runs on the boards should call this function.

Library 


ERRORS.LIB

root2xmem 



int root2xmem(unsigned long dest, void *src, unsigned len);

Description

Stores len characters from logical address src to physical address dest.

Parameters 


dest

Physical address 


src

Logical address 


len

Numbers of bytes

Return value

 0: Success
-1: Attempt to write flash memory area, nothing written
-2: Source not all in root

Library 


XMEM.LIB

See also 


xalloc, xmem2root

runwatch 



void runwatch();

Description

Runs and updates watch expressions if Dynamic C has requested it with a Ctrl-U. Should be called periodically in user program.

Library 


SYS.LIB

serCheckParity 



int serCheckParity(char rx_byte, char parity);

Description

This function is different from the other serial routines in that it does not specify a particular serial port. This function takes any 8-bit character and tests it for correct parity. It will return true if the parity of rx_byte matches the parity specified. This function is useful for checking individual characters when using a 7-bit data protocol.

Parameters 


rx_byte

The 8 bit character being tested for parity. 


parity

The character `O' for odd parity, or the character `E' for even parity.

Return value

1: Parity of the byte being tested matches the parity supplied as an argument.
0: Parity of the byte does not match.

Library 


RS232.LIB

serXclose 



void serXclose(); /* where X = A|B|C|D */

Description

Disables serial port X. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEclose() and serFclose() may be used with the Rabbit 3000 microprocessor.

Library 


RS232.LIB

serXdatabits 



void serXdatabits(state); /* where X = A|B|C|D */

Description

Sets the number of data bits in the serial format for this channel. Currently seven or eight bit modes are supported. A call to serXopen() must be made before calling this function. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEdatabits() and serFdatabits() may be used with the Rabbit 3000 microprocessor.

Parameters 


state

An integer indicating what bit mode to use. It is best to use one of the macros provided for this: 


PARAM_7BIT

Configures serial port to use seven bit data. 


PARAM_8BIT

Configures serial port to use eight bit data (default).

Library 


RS232.LIB

serXflowcontrolOff 



void serXflowcontrolOff(); /* where X = A|B|C|D */

Description

Turns off hardware flow control for serial port X. A call to serXopen() must be made before calling this function. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEflowcontrolOff() and serFflowcontrolOff() may be used with the Rabbit 3000 microprocessor.

Library 


RS232.LIB

serXflowcontrolOn 



void serXflowcontrolOn(); /* where X = A|B|C|D */

Description

Turns on hardware flow control for channel X. This enables two digital lines that handle flow control, CTS (clear to send) and RTS (ready to send). CTS is an input that will be pulled active low by the other system when it is ready to receive data. The RTS signal is an output that the system uses to indicate that it is ready to receive data; it is driven low when data can be received. A call to serXopen() must be made before calling this function.

This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEflowcontrolOn() and serFflowcontrolOn() may be used with the Rabbit 3000 microprocessor.

If pins for the flow control lines are not explicitly defined, defaults will be used and compiler warnings will be issued. The locations of the flow control lines are specified using a set of 5 macros. 


SERX_RTS_PORT

Data register for the parallel port that the RTS line is on. e.g. PCDR 


SERA_RTS_SHADOW

Shadow register for the RTS line's parallel port. e.g. PCDRShadow 


SERA_RTS_BIT

The bit number for the RTS line 


SERA_CTS_PORT

Data register for the parallel port that the CTS line is on 


SERA_CTS_BIT

The bit number for the CTS line

Library 


RS232.LIB

serXgetc 



int serXgetc(); /* where X = A|B|C|D */

Description

Get next available character from serial port X read buffer. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEgetc() and serFgetc() may be used with the Rabbit 3000 microprocessor.

Return value

Success: the next character in the low byte, 0 in the high byte
Failure: -1

Library 


RS232.LIB

Example 

// echoes characters
main() {
    int c;
    serAopen(19200);
    while (1) {
        if ((c = serAgetc()) != -1) {
            serAputc(c);
        }
    }
    serAclose()
}

serXgetError 



int serXgetError(); /* where X = A|B|C|D */

Description

Returns a byte of error flags, with bits set for any errors that occurred since the last time this function was called. Any bits set will be automatically cleared when this function is called, so a particular error will only be reported once. This function is non-reentrant.

The flags are checked with bitmasks to determine which errors occurred. Error bitmasks:

Starting with Dynamic C version 7.25, the functions serEgetError() and serFgetError() may be used with the Rabbit 3000 microprocessor.

Return value

The error flags byte.

Library 


RS232.LIB

serXopen 



int serXopen(long baud); /* where X = A|B|C|D */

Description

Opens serial port X. This function is non-reentrant.

The user must define the buffer sizes for each port being used with the buffer size macros XINBUFSIZE and XOUTBUFSIZE. The values must be a power of 2 minus 1, e.g.

#define XINBUFSIZE 63
#define XOUTBUFSIZE 127

Defining the buffer sizes to 2n - 1 makes the circular buffer operations very efficient. If a value not equal to 2n- 1 is defined, a default of 31 is used and a compiler warning is given.

Starting with Dynamic C version 7.25, the functions serEopen() and serFopen() may be used with the Rabbit 3000 microprocessor.

Note: The alternate pins on parallel port D can be used for serial port B by defining SERB_USEPORTD at the beginning of a program. See the section on parallel port D in the Rabbit documentation for more detail on the alternate serial port pins.

Parameters 


baud

Bits per second of data transfer. Note that the baud rate must be greater than or equal to the peripheral clock frequency ÷ 8192.

Return value

1: The baud rate achieved on the Rabbit is the same as the input baud rate. The software was able to calculate a valid divisor for the requested baud rate within 5%.

0: The baud rate achieved on the Rabbit does not match the input baud rate.

Library 


RS232.LIB

See also 


serXgetc, serXpeek, serXputs, serXwrite, cof_serXgetc,
cof_serXgets, cof_serXread, cof_serXputc, cof_serXputs,
cof_serXwrite, serXclose

serXparity 



void serXparity(int parity_mode); /* where X = A|B|C|D */

Description

Sets parity mode for channel X. A call to serXopen() must be made before calling this function.

Parity generation for 8 bit data can be unusually slow due to the current method for generating high 9th bits. Whenever, a 9th high bit is needed, the UART is disabled for approximately 10 baud times to create a long stop bit that should be recognized by the receiver as a high 9th bit.

The long delay is imposed because we are using the serial port itself to handle timing for the delay. Creating a shorter delay would the require use of some other timer resource.

This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEparity() and serFparity() may be used with the Rabbit 3000 microprocessor.

Parameters 


parity_mode

An integer indicating what parity mode to use. It is best to use one of the macros provided:

· PARAM_NOPARITY - Disables parity handling (default).

· PARAM_OPARITY - Configures serial port to check/generate for odd parity.

· PARAM_EPARITY - Configures serial port to check/generate for even parity.

· PARAM_2STOP - Configures serial port to generate 2 stop bits.

Library 


RS232.LIB

serXpeek 



int serXpeek(); /* where X = [A|B|C|D] */

Description

Returns 1st character in input buffer X, without removing it from the buffer. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEpeek() and serFpeek() may be used with the Rabbit 3000 microprocessor.

Return value

An integer with 1st character in buffer in the low byte
-1 if the buffer is empty

Library 


RS232.LIB

serXputc 



int serXputc(char c); /* where X = A|B|C|D */

Description

Writes a character to serial port X write buffer. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEputc() and serFputc() may be used with the Rabbit 3000 microprocessor.

Parameters 


c

Character to write to serial port X write buffer.

Return value

0 if buffer locked or full, 1 if character sent.

Library 


RS232.LIB

Example 

main() {    // echoes characters
    int c;
    serAopen(19200);
    while (1) {
        if ((c = serAgetc()) != -1) {
            serAputc(c);
        }
    }
    serAclose();
}

serXputs 



int serXputs(char* s); /* where X = A|B|C|D */

Description

Calls serXwrite(s, strlen(s)). This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEputs() and serFputs() may be used with the Rabbit 3000 microprocessor.

Parameters 


s

NULL-terminated character string to write

Return value

The number of characters actually sent from serial port X.

Library 


RS232.LIB

Example 

// writes a null-terminated string of characters, repeatedly
main() {
    const char s[] = "Hello Z-World";
    serAopen(19200);
    while (1) {
        serAputs(s);
    }
    serAclose();
}

serXrdFlush 



void serXrdFlush(); /* where X = A|B|C|D */

Description

Flushes serial port X input buffer. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serErdFlush() and serFrdFlush() may be used with the Rabbit 3000 microprocessor.

Library 


RS232.LIB

serXrdFree 



int serXrdFree(); /* where X = A|B|C|D */

Description

Calculates the number of characters of unused data space. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serErdFree() and serFrdFree() may be used with the Rabbit 3000 microprocessor.

Return value

The number of chars it would take to fill input buffer X.

Library 


RS232.LIB

serXrdUsed 



int serXrdUsed(); /* where X = A|B|C|D */

Description

Calculates the number of characters ready to read from the serial port receive buffer. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serErdUsed() and serFrdUsed() may be used with the Rabbit 3000 microprocessor.

Return value

The number of characters currently in serial port X receive buffer.

Library 


RS232.LIB

serXread 



int serXread(void *data, int length, unsigned long tmout); 
/* where X = A|B|C|D */

Description

Reads length bytes from serial port X or until tmout milliseconds transpires between bytes. The countdown of tmout does not begin until a byte has been received. A timeout occurs immediately if there are no characters to read. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEread() and serFread() may be used with the Rabbit 3000 microprocessor.

Parameters 


data

Data structure to read from serial port X 


length

Number of bytes to read 


tmout

Maximum wait in milliseconds for any byte from previous one

Return value

The number of bytes read from serial port X.

Library 


RS232.LIB

Example 

// echoes a blocks of characters
main() {
    int n;
    char s[16];
    serAopen(19200);
    while (1) {
        if ((n = serAread(s, 15, 20)) > 0) {
            serAwrite(s, n);
        }
    }
    serAclose();
}

serXwrFlush 



void serXwrFlush(); /* where X = A|B|C|D */

Description

Flushes serial port X transmit buffer. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEwrFlush() and serFwrFlush() may be used with the Rabbit 3000 microprocessor.

Library 


RS232.LIB

serXwrFree 



int serXwrfree(); /* where X = A|B|C|D */

Description

Calculates the free space in the serial port transmit buffer. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEwrFree() and serFwrFree() may be used with the Rabbit 3000 microprocessor.

Return value

The number of characters the serial port transmit buffer can accept before becoming full.

Library 


RS232.LIB

serXwrite 



int serXwrite(void *data, int length); /* where X = A|B|C|D */

Description

Transmits length bytes to serial port X. This function is non-reentrant.

Starting with Dynamic C version 7.25, the functions serEwrite() and serFwrite() may be used with the Rabbit 3000 microprocessor.

Parameters 


data

Data structure to write to serial port X. 


length

Number of bytes to write

Return value

The number of bytes successfully written to the serial port.

Library 


RS232.LIB

Example 

// writes a block of characters, repeatedly
main() {
    const char s[] = "Hello Z-World";
    serAopen(19200);
    while (1) {
        serAwrite(s, strlen(s));
    }
serAclose();
}

set 



void set(void *address, unsigned int bit);

Description

Dynamic C may expand this call inline

Sets specified bit at memory address to 1. bit may be from 0 to 31. This is equivalent to the following expression, but more efficient:
*(long *)address |= 1L << bit

Parameters 


address

Address of byte containing bits 7-0 


bit

Bit location where 0 represents the least significant bit

Library 


UTIL.LIB

See also 


SET

SET 



void SET(void *address, unsigned int bit);

Description

Dynamic C may expand this call inline

Sets specified bit at memory address to 1. bit may be from 0 to 31. This is equivalent to the following expression, but more efficient:
*(long *)address |= 1L << bit

Parameters 


address

Address of byte containing bits 7-0 


bit

Bit location where 0 represents the least significant bit

Library 


UTIL.LIB

See also 


set

set32kHzDivider 



void set32kHzDivider(int setting);

Description

Sets the expanded 32kHz oscillator divider for the Rabbit 3000 processor. This function does not enable running the 32kHz oscillator instead of the main clock. This function will affect the actual rate used by the processor when the 32kHz oscillator has been enabled to run by a call to use32kHzOsc().

This function is not task reentrant.

Parameter 


setting

32kHz divider setting. The following are valid:

· OSC32DIV_1 - don't divide 32kHz oscillator

· OSC32DIV_2 - divide 32kHz oscillator by two

· OSC32DIV_4 - divide 32kHz oscillator by four

· OSC32DIV_8 - divide 32kHz oscillator by eight

· OSC32DIV_16 - divide 32kHz oscillator by sixteen

Library 


SYS.LIB

See Also 


useClockDivider, useClockDivider3000, useMainOsc, use32kHzOsc

setClockModulation 



void setClockModulation(int setting);

Description

Changes the setting of the Rabbit 3000 CPU clock moduation. Calling this function will force a 500 clock delay before the setting is changed to ensure that the previous moduation setting has cleared before the next one is set. See the Rabbit 3000 Microprocessor User's Manual for more details about clock modulation for EMI reduction.

Parameter 


setting

Clock modulation setting. Allowed values are:

· 0 = no modulation

· 1 = weak modulation

· 2 = strong modulation

Library 


SYS.LIB

setjmp 



int setjmp(jmp_buf env);

Description

Store the PC (program counter), SP (stack pointer) and other information about the current state into env. The saved information can be restored by executing longjmp().

Typical usage: 


switch (setjmp(e)) {
   case 0:          // first time
      f();          // try to execute f(), may call longjmp()
      break;              // if we get here, f() was successful
   case 1:          // to get here, f() called longjmp()

      /* do exception handling */

      break;
   case 2:          // like above, but different exception code
     ...
}
f() {
   g()
   ...
}
g() {
   ...
   longjmp(e,2);    // exception code 2, jump to setjmp()statement,
                    // setjmp() returns 2, so execute
                    // case 2 in the switch statement
}

Parameters 


env

Information about the current state

Return value

Returns zero if it is executed. After longjmp() is executed, the program counter, stack pointer and etc. are restored to the state when setjmp() was executed the first time. However, this time setjmp() returns whatever value is specified by the longjmp() statement.

Library 


SYS.LIB

See also 


longjmp

SetVectExtern2000 



unsigned SetVectExtern2000(int priority, void *isr);

Description

Sets up the external interrupt table vectors for external interrupts 0 and 1. This function is presently used for Rabbit 2000 microprocessors because of the way they handle interrupts. Once this function is called, both external interrupts 0 and 1 must be enabled with the same priority level. The priority level should be set higher than all other interrupts currently running. (All system interrupts in the BIOS run at interrupt priority 1.) The interrupt priority is set via the control register I0CR for external interrupt 0 and I1CR for external interrupt 1.

The actual priority used by the interrupt service routine (ISR) is passed to this function.

Parameters 


priority

Priority the ISR should run at. Valid values are 1, 2 or 3. 


isr

ISR handler address. Must be a root address.

Return value

Address of vector table entry, or zero if priority is not valid.

Library 


SYS.LIB

See also 


GetVectExtern2000, SetVectIntern, GetVectIntern

SetVectExtern3000 



unsigned SetVectExtern3000(int interruptNum, void *isr);

DESCRIPTION

Function to set one of the external interrupt jump table entries for the Rabbit 3000 CPU. All Rabbit interrupts use jump vectors. See SetVectIntern() for more information.

Parameters 


interruptNum

External interrupt number. 0 and 1 are the only valid values. 


isr

ISR handler address. Must be a root address.

Return Value

Jump address in vector table

Library 


SYS.LIB

See Also 


GetVectExtern3000, SetVectIntern, GetVectIntern

SetVectIntern 



unsigned SetVectIntern(int vectNum, void *isr);

Description

Sets an internal interrupt table entry. All Rabbit interrupts use jump vectors. This function writes a jp instruction (0xC3) followed by the 16 bit ISR address to the appropriate location in the vector table. The location in RAM of the vector table is determined and set by the BIOS automatically at startup. The start of the table is always on a 0x100 boundary.

It is perfectly permissible to have ISRs in xmem and do long jumps to them from the vector table. It is even possible to place the entire body of the ISR in the vector table if it is 16 bytes long or less, but this function only sets up jumps to 16 bit addresses.

The following table shows the vectNum argument that should be used for each peripheral or RST. The offset into the vector table is also shown. The following vectors are for the Rabbit 2000 and 3000.

Peripheral or RST
vectNum
Vector Table Offset
System Management
(periodic interrupt)
0x00
0x00
RST 10 instruction
0x02
0x20
RST 38 instruction
0x07
0x70
Slave Port
0x08
0x80
Timer A
0x0A
0xA0
Timer B
0x0B
0xB0
Serial Port A
0x0C
0xC0
Serial Port B
0x0D
0xD0
Serial Port C
0x0E
0xE0
Serial Port D
0x0F
0xF0

The following vectors are for the Rabbit 3000 processor only:

Peripheral or RST
vectNum
Vector Table Offset
Input Capture
0x15
0x0150
Quadrature Encoder
0x19
0x0190
Serial port E
0x1C
0x01C0
Serial port F
0x1D
0x01D0

SetVectIntern (continued)

The following three RSTs are included for completeness, but should not be set by the user normally as they are used by Dynamic C

Peripheral or RST
vectNum
Vector Table Offset
RST 18 instruction
0x03
0x30
RST 20 instruction
0x04
0x40
RST 28 instruction
0x05
0x50

Parameters 


vectNum

Interrupt number. See the above table for valid values. 


isr

ISR handler address. Must be a root address.

Return value

Address of vector table entry, or zero if vectNum is not valid.

Library 


SYS.LIB

See also 


GetVectExtern2000, SetVectExtern2000, GetVectIntern

sin 



float sin(float x);

Description

Computes the sine of x.

Parameters 


x

Value to compute

Return value

Sine of x.

Library 


MATH.LIB

See also 


sinh, asin, cos, tan

sinh 



float sinh(float x);

Description

Computes the hyperbolic sine of x.

Parameters 


x

Value to compute

Return value

The hyperbolic sine of x.

If x > 89.8 (approx.), the function returns INF and signals a range error. If x < -89.8 (approx.), the function returns -INF and signals a range error.

Library 


MATH.LIB

See also 


sin, asin, cosh, tanh

SPIinit 



void SPIinit ();

Description

Initialize the SPI port parameters for a serial interface only. This function does nothing for a parallel interface. A description of the values that the user may define before the #use SPI.LIB statement is found at the top of the library Lib\Spi\Spi.lib.

Library 


SPI.LIB

See also 


SPIRead, SPIWrite, SPIWrRd

SPIRead 



void SPIRead ( void *DestAddr, int ByteCount );

Description

Reads a block of bytes from the SPI port. Note: the device Chip Select must already be active. The variable SPIxor needs to be set to either 0x00 or 0xFF depending on whether or not the received signal needs to be inverted. Most applications will not need inversion. SPIinit() sets the value of SPIxor to 0x00.

Parameters 


DestAddr

Address to store the data 


ByteCount

Number of bytes to read

Return value

None.

Library 


SPI.LIB

See also 


SPIinit, SPIWrite, SPIWrRd

SPIWrite 



int SPIWrite ( void *SrcAddr, int ByteCount );

Description

Write a block of bytes to the SPI port. Note: the device Chip Select must already be active.

Parameters 


SrcAddr

Address of data to write 


ByteCount

Number of bytes to write

Return value

None.

Library 


SPI.LIB

See also 


SPIinit, SPIRead, SPIWrRd

SPIWrRd 



void SPIWrRd ( void *SrcAddr, void *DstAddr, int ByteCount );

Description

Read and Write a block of bytes from/to the SPI port. The device Chip Select must already be active

Parameters 


SrcAddr

Address of data to write. 


DstAddr

Address to put received data. 


ByteCount

Number of bytes to read/write. The maximum value is 255 bytes. This limit is not checked! The receive buffer MUST be at least as large as the number of bytes!

Return value

None.

Library 


SPI.LIB

See Also 


SPIinit, SPIRead, SPIWrite

sprintf 



int sprintf(char *buffer, char *format, ...);

Description

This function takes a string (pointed to by format), arguments of the format, and outputs the formatted string to buffer (pointed to by buffer). The user should make sure that:

The following is a short list of possible format parameters in the format string. For more details, refer to any C language book.

%d decimal integer (expects type int)
%u decimal unsigned integer (expects type unsigned int)
%x hexadecimal integer (expects type signed int or unsigned int)
%s a string (not interpreted, expects type (char *))
%f a float (expects type float)

For example, sprintf(buffer,"%s=%x","variable x",256); should put the string variable x=100 into buffer.

This function can be called by processes of different priorities.

Parameters 


buffer

Result string of the formatted string. 


format

String to be formatted. 


...

Format arguments.

Return Value

Number of characters written.

Library 


STDIO.LIB

See also 


printf

sqrt 



float sqrt(float x);

Description

Calculate the square root of x.

Parameters 


x

Value to compute

Return value

The square root of x.

Library 


MATH.LIB

See also 


exp, pow, pow10

srand 



void srand(unsigned long seed)

Description

Sets the seed value for the rand() function.

Parameter 


seed

This must be an odd number.

Library 


MATH.LIB

See also 


rand, randb, randg

strcat 



char *strcat(char *dst, char *src);

Description

Appends one string to another.

Parameters 


dst

Pointer to location to destination string. 


src

Pointer to location to source string.

Return value

Pointer to destination string.

Library 


STRING.LIB

See also 


strncat

strchr 



char *strchr(char *src, char ch);

Description

Scans a string for the first occurrence of a given character.

Parameters 


src

String to be scanned. 


ch

Character to search

Return value

Pointer to the first occurrence of ch in src.
NULL if ch is not found.

Library 


STRING.LIB

See also 


strrchr, strtok

strcmp 



int strcmp(char *str1, char *str2)

Description

Performs unsigned character by character comparison of two NULL-terminated strings.

Parameters 


str1

Pointer to string 1. 


str2

Pointer to string 2.

Return value

<0: str1 is less than str2 because
character in str1 is less than corresponding character in str2, or
str1 is shorter than but otherwise identical to str2.

=0: str1 is identical to str2

>0: str1 is greater than str2 because
character in str1 is greater than corresponding character in str2, or
str2 is shorter than but otherwise identical to str1.

Library 


STRING.LIB

See also 


strncmp, strcmpi, strncmpi

strcmpi 



int *strcmpi(char *str1, char *str2);

Description

Performs case-insensitive unsigned character by character comparison of two NULL-terminated strings.

Parameters 


str1

Pointer to string 1. 


str2

Pointer to string 2.

Return value

<0: str1 is less than str2 because
character in str1 is less than corresponding character in str2, or
str1 is shorter than but otherwise identical to str2.

=0: str1 is identical to str2

>0: str1 is greater than str2 because
character in str1 is greater than corresponding character in str2, or
str2 is shorter than but otherwise identical to str1.

Library 


STRING.LIB

See also 


strncmpi, strncmp, strcmp

strcpy 



char *strcpy(char *dst, char *src);

Description

Copies one string into another string including the NULL terminator.

Parameters 


dst

Pointer to location to receive string. 


src

Pointer to location to supply string.

Return value

Pointer to destination string.

Library 


STRING.LIB

See also 


strncpy

strcspn 



unsigned int strcspn(char *s1, char *s2);

Description

Scans a string for the occurrence of any of the characters in another string.

Parameters 


s1

String to be scanned. 


s2

Character occurrence string.

Return value

Returns the position (less one) of the first occurrence of a character in s1 that matches any character in s2.

Library 


STRING.LIB

See also 


strchr, strrchr, strtok

strlen 



int strlen(char *s);

Description

Calculate the length of a string.

Parameters 


s

Character string

Return value

Number of bytes in a string.

Library 


STRING.LIB

strncat 



char *strncat(char *dst, char *src, unsigned int n);

Description

Appends one string to another up to and including the NULL terminator or until n characters are transferred, followed by a NULL terminator.

Parameters 


dst

Pointer to location to receive string. 


src

Pointer to location to supply string. 


n

Maximum number of bytes to copy. If equal to zero, this function has no effect.

Return value

Pointer to destination string.

Library 


STRING.LIB

See also 


strcat

strncmp 



int strncmp(char *str1, char *str2, n)

Description

Performs unsigned character by character comparison of two strings of length n.

Parameters 


str1

Pointer to string 1. 


str2

Pointer to string 2. 


n

Maximum number of bytes to compare. If zero, both strings are considered equal.

Return value

<0: str1 is less than str2 because
char in str1 is less than corresponding char in str2.

=0: str1 is identical to str2

>0: str1 is greater than str2 because
char in str1 is greater than corresponding char in str2.

Library 


STRING.LIB

See also 


strcmp, strcmpi, strncmpi

strncmpi 



int strncmpi(char *str1, char *str2, unsigned n)

Description

Performs case-insensitive unsigned character by character comparison of two strings of length n.

Parameters 


str1

Pointer to string 1. 


str2

Pointer to string 2. 


n

Maximum number of bytes to compare, if zero then strings are considered equal

Return value

<0: str1 is less than str2 because
char in str1 is less than corresponding char in str2.

=0: str1 is identical to str2

>0: str1 is greater than str2 because
char in str1 is greater than corresponding char in str2.

Library 


STRING.LIB

See also 


strcmpi, strcmp, strncmp

strncpy 



char *strncpy(char *dst, char *src, unsigned int n);

Description

Copies a given number of characters from one string to another and padding with NULL characters or truncating as necessary.

Parameters 


dst

Pointer to location to receive string. 


src

Pointer to location to supply string. 


n

Maximum number of bytes to copy. If equal to zero, this function has no effect.

Return value

Pointer to destination string.

Library 


STRING.LIB

See also 


strcpy

strpbrk 



char *strpbrk(char *s1, char *s2);

Description

Scans a string for the first occurrence of any character from another string.

Parameters 


s1

String to be scanned. 


s2

Character occurrence string.

Return value

Pointer pointing to the first occurrence of a character contained in s2 in s1. Returns NULL if not found.

Library 


STRING.LIB

See also 


strchr, strrchr, strtok

strrchr 



char *strrchr(char *s, int c);

Description

Similar to strchr, except this function searches backward from the end of s to the beginning.

Parameters 


s

String to be searched 


c

Search character

Return value

Pointer to last occurrence of c in s. If c is not found in s, return NULL.

Library 


STRING.LIB

See also 


strchr, strcspn, strtok

strspn 



size_t strspn(char *src, char *brk);

Description

Scans a string for the first segment in src containing only characters specified in brk.

Parameters 


src

String to be scanned 


brk

Set of characters

Return value

Returns the length of the segment.

Library 


STRING.LIB

strstr 



char *strstr(char *s1, char *s2);

Description

Finds a substring specified by s2 in string s1.

Parameters 


s1

String to be scanned 


s2

Substring

Return value

Pointer pointing to the first occurrence of substring s2 in s1. Returns NULL if s2 is not found in s1.

Library 


STRING.LIB

See also 


strcspn, strrchr, strtok

strtod 



float strtod(char *s, char **tailptr);

Description

ANSI string to float conversion.

Parameters 


s

String to convert 


tailptr

Pointer to a pointer of character. The next conversion may resume at the location specified by *tailptr.

Return value

The float number.

Library 


STRING.LIB

See also 


atof

strtok 



char *strtok(char *src, char *brk);

Description

Scans src for tokens separated by delimiter characters specified in brk.

First call with non-NULL for src. Subsequent calls with NULL for src continue to search tokens in the string. If a token is found (i.e., delineators found), replace the first delimiter in src with a NULL terminator so that src points to a proper NULL-terminated token.

Parameters 


src

String to be scanned, must be in SRAM, cannot be a constant. In contrast, strings initialized when they are declared are stored in Flash Memory, and are treated as constants. 


brk

Character delimiter

Return value

Pointer to a token. If no delimiter (therefore no token) is found, returns NULL.

Library 


STRING.LIB

See also 


strchr, strrchr, strstr, strcspn

strtol 



long strtol(char *sptr, char **tailptr, int base);

Description

ANSI string to long conversion.

Parameters 


sptr

String to convert 


tailptr

Assigned the last position of the conversion. The next conversion may resume at the location specified by *tailptr. 


base

Indicates the radix of conversion.

Return value

The long integer.

Library 


STRING.LIB

See also 


atoi, atol

_sysIsSoftReset 



void _sysIsSoftReset();

Description

This function determines whether this restart of the board is due to a software reset from Dynamic C or a call to forceReset(). If it was a soft reset, this function then does the following:

Calls _prot_init() to initialize the protected variable mechanisms. It is up to the user to initialize protected variables.

Calls sysResetChain(). The user my attach functions to this chain to perform additional startup actions (for example, initializing protected variables). If a soft reset did not take place, this function calls _prot_recover() to recover any protected variables.

Library 


SYS.LIB

See Also 


chkHardReset, chkSoftReset, chkWDTO

sysResetChain 



void sysResetChain ( void );

Description

This is a function chain that should be used to initialize protected variables. By default, it's empty.

Library 


SYS.LIB

tan 



float tan(float x);

Description

Compute the tangent of the argument.

Parameters 


x

Value to compute

Return value

Returns the tangent of x, where -8 ×  PI x +8 ×  PI. If x is out of bounds, the function returns 0 and signals a domain error. If the value of x is too close to a multiple of 90° (PI/2) the function returns INF and signals a range error.

Library 


MATH.LIB

See also 


atan, cos, sin, tanh

tanh 



float tanh(float x);

Description

Computes the hyperbolic tangent of argument.

Parameters 


x

Value to compute

Return value

Returns the hyperbolic tangent of x. If x > 49.9 (approx.), the function returns INF and signals a range error. If x < -49.9 (approx.), the function returns -INF and signals a range error.

Library 


MATH.LIB

See also 


atan, cosh, sinh, tan

tm_rd 



int tm_rd(struct tm *t);

Description

Reads the current system time from SEC_TIMER into the structure t. WARNING: The variable SEC_TIMER is initialized when a program is started. If you change the Real Time Clock (RTC), this variable will not be updated until you restart a program, and the tm_rd function will not return the time that the RTC has been reset to. The read_rtc function will read the actual RTC and can be used if necessary.

Parameters 


t

Address of structure to store time data 


struct tm {
   char tm_sec;     // seconds 0-59
   char tm_min;     // 0-59
   char tm_hour;    // 0-23
   char tm_mday;    // 1-31
   char tm_mon;     // 1-12
   char tm_year;    // 80-147 (1980-2047)
   char tm_wday;    // 0-6 0==Sunday
};

Return value

 0: Successful.
-1: Clock read failed.

Library 


RTCLOCK.LIB

See also 


mktm, mktime, tm_wr

tm_wr 



int tm_wr(struct tm *t);

Description

Sets the system time from a tm struct. It is important to note that although tm_rd() reads the SEC_TIMER variable, not the RTC, tm_wr() writes to the RTC directly, and SEC_TIMER is not changed until the program is restarted. The reason for this is so that the DelaySec() function continues to work correctly after setting the system time. To make tm_rd() match the new time written to the RTC without restarting the program, the following should be done:

tm_wr(tm);
SEC_TIMER = mktime(tm);

But this could cause problems if a waitfor(DelaySec(n)) is pending completion in a cooperative multitasking program or if the SEC_TIMER variable is being used in another way the user, so user beware.

Parameters 


t

Pointer to structure to read date and time from. 


struct tm {
   char tm_sec;     // seconds 0-59
   char tm_min;     // 0-59
   char tm_hour;    // 0-23
   char tm_mday;    // 1-31
   char tm_mon;     // 1-12
   char tm_year;    // 80-147 (1980-2047)
   char tm_wday;    // 0-6 0==Sunday
};

Return value

 0: Success .
-1: Failure.

Library 


RTCLOCK.LIB

See also 


mktm, mktime, tm_rd

tolower 



int tolower(int c);

Description

Convert alphabetic character to lower case.

Parameters 


c

Character to convert

Return value

Lower case alphabetic character.

Library 


STRING.LIB

See also 


toupper, isupper, islower

toupper 



int toupper(int c);

Description

Convert alphabetic character to uppercase.

Parameters 


c

Character to convert

Return value

Upper case alphabetic character.

Library 


STRING.LIB

See also 


tolower, isupper, islower

updateTimers 



void updateTimers();

Description

Updates the values of TICK_TIMER, MS_TIMER, and SEC_TIMER while running off the 32 kHz oscillator. Since the periodic interrupt is disabled when running at 32 kHz, these values will not updated unless this function is called.

Library 


SYS.LIB

See also 


useMainOsc, use32kHzOsc

use32kHzOsc 



void use32kHzOsc();

Description

Sets the Rabbit processor to use the 32kHz real-time clock oscillator for both the CPU and peripheral clock, and shuts off the main oscillator. If this is already set, there is no effect. This mode should provide greatly reduced power consumption. Serial communications will be lost since typical baud rates cannot be made from a 32kHz clock. Also note that this function disables the periodic interrupt, so waitfor and related statements will not work properly (although costatements in general will still work). In addition, the values in TICK_TIMER, MS_TIMER, and SEC_TIMER will not be updated unless you call the function updateTimers() frequently in your code. In addition, you will need to call hitwd() periodically to hit the hardware watchdog timer since the periodic interrupt normally handles that, or disable the watchdog timer before calling this function. The watchdog can be disabled with Disable_HW_WDT().

use32kHzOsc() is not task reentrant.

Library 


SYS.LIB

See also 


useMainOsc, useClockDivider, updateTimers

useClockDivider 



void useClockDivider();

Description

Sets the Rabbit processor to use the main oscillator divided by 8 for the CPU (but not the peripheral clock). If this is already set, there is no effect. Because the peripheral clock is not affected, serial communications should still work. This function also enables the periodic interrupt in case it was disabled by a call to use32kHzOsc(). This function is not task reentrant.

Library 


SYS.LIB

See also 


useMainOsc, use32kHzOsc

useClockDivider3000 



void useClockDivider3000(int setting);

Description

Sets the expanded clock divider options for the Rabbit 3000 processor. This function will also affect the peripheral clock--use useClockDivider() to divide the processor clock by eight but not affect the peripheral clock. Target communications will be lost after changing this setting because of the baud rate change. This function also enables the periodic interrupt in case it was disabled by a call to user32kHzOsc().

This function is not task reentrant.

Parameter 


setting

Divider setting. The following are valid:

· CLKDIV_2 - divide main processor clock by two

· CLKDIV_4 - divide main processor clock by four

· CLKDIV_6 - divide main processor clock by six

· CLKDIV_8 - divide main processor clock by eight

Return Value

None.

Library 


SYS.LIB

See Also 


useClockDivider, useMainOsc, use32kHzOsc, set32kHzDivider

useMainOsc 



void useMainOsc();

Description

Sets the Rabbit processor to use the main oscillator for both the CPU and peripheral clock. If this is already set, there is no effect. This function also enables the periodic interrupt in case it was disabled by a call to use32kHzOsc(), and updates the TICK_TIMER, MS_TIMER, and SEC_TIMER variables from the real-time clock. This function is not task reentrant.

Library 


sys.lib

See also 


use32kHzOsc, useClockDivider

utoa 



char *utoa(unsigned value, char *buf);

Description

Places up to 5 digit character string at *buf representing value of unsigned number. Suppresses leading zeros, but leaves one zero digit for value = 0. Max = 65535. 73 program bytes.

Parameters 


value

16-bit number to convert 


buf

Character string of converted number

Return value

Pointer to NULL at end of string.

Library 


STDIO.LIB

See also 


itoa, htoa, ltoa

VdGetFreeWd 



int VdGetFreeWd(char count);

Description

Returns a free virtual watchdog and initializes that watchdog so that the virtual driver begins counting it down from count. The number of virtual watchdogs available is determined by N_WATCHDOG, which is 5 by default, but can be defined by the user: #define N_WATCHDOG 10. The virtual driver is called every 0.00048828125 sec. On every 128th call to it (62.5 ms), the virtual watchdogs are counted down. If any virtual watchdog reaches 0, this is a fatal error. Once a virtual watchdog is active, it should reset periodically with a call to VdHitWd to prevent this. The count is decremented, tested and, if 0, a fatal error occurs.

Parameters 


count

1 < count <= 255

Return value

Integer id number of an unused virtual watchdog timer.

Library 


VDRIVER.LIB

VdHitWd 



int VdHitWd(int ndog);

Description

Resets virtual watchdog counter to N counts where N is the argument to the call to VdGetFreeWd() that obtained the virtual watchdog ndog. The virtual driver counts down watchdogs every 62.5 ms. If a virtual watchdog reaches 0, this is a fatal error. Once a virtual watchdog is active it should reset periodically with a call to VdHitWd() to prevent this. If count = 2 the VdHitWd() will need to be called again for virtual watchdog ndog within 62.5 ms. If count = 255, VdHitWd() will need to be called again for virtual watchdog ndog within 15.9375 seconds.

Parameters 


ndog

Id of virtual watchdog returned by VdGetFreeWd()

Library 


VDRIVER.LIB

VdInit 



void VdInit(void);

Description

Initializes the Virtual Driver for all Rabbit boards. Supports DelayMs(), DelaySec(), DelayTick(). VdInit() is called by the BIOS unless it has been disabled.

Library 


VDRIVER.LIB

VdReleaseWd 



int VdReleaseWd(int ndog);

Description

Deactivates a virtual watchdog and makes it available for VdGetFreeWd().

Parameters 


ndog

Handle returned by VdGetFreeWd()

Return value

0: ndog out of range.
1: Success.

Library 


VDRIVER.LIB

Example 

// VdReleaseWd virtual watchdog example
main() {
   int wd;                 // handle for a virtual watchdog
   unsigned long tm;
   tm = SEC_TIMER;
   wd = VdGetFreeWd(255);   // wd activated, 9 virtual watchdogs
                            // now available. wd must be hit 
                            // at least every 15.875 seconds
   while(SEC_TIMER - tm < 60) {    // let it run for a minute
      VdHitWd(wd);          // decrements counter corresponding to
                            // wd reset to 12
   }

   VdReleaseWd(wd)          // now there are 10 virtual
                            // watchdogs available
}

WriteFlash2 



int WriteFlash2(unsigned long flashDst, void* rootSrc, int len);

Description

Write len bytes from rootSrc to physical address flashDst on the 2nd flash device. The source must be in root. The flashDst address must be in the range 0x00040000-0x0007FFFF. (256kb is the maximum size visible on the second flash by this function).

This function is not reentrant.

NOTE This function should NOT be used if you are using the second flash device for a flash file system. This function is extremely dangerous when used with large-sector flash. Don't do it.

Parameters 


flashDst

Physical address of the flash destination 


rootSrc

Pointer to the root source 


len

Number of bytes to write

Return value

 0: Success.
-1: Attempt to write non-2nd flash area, nothing written.
-2: rootsrc not in root.
-3: Time out while writing flash.
-4: Attempt to write to ID block
-5: Sector erase needed; write aborted

Library 


XMEM.LIB

write_rtc 



void write_rtc(unsigned long int time);

Description

Writes a 32 bit seconds value to the RTC, zeros other bits. This function does not stop or delay periodic interrupt. It does not affect the SEC_TIMER or MS_TIMER variables.

Parameters 


time

32-bit value representing the number of seconds since January 1, 1980.

Library 


RTCLOCK.C

See also 


read_rtc

writeUserBlock 



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

Description

Z-World boards have a System ID Block located on the primary flash. (See the Rabbit 2000 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 ID Block is recommended for storing all non-file data. This is where calibration constants are stored for boards with analog I/O. Space here 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.

NOTE See the manual for your particular board for more information before overwriting any part of the user block.

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 arisng from incompatible large sector configuartions, this will only work if the flash type is small sector. Z-World manufactured boards with large sector flash will have valid System and User ID blocks, so this should not be problem on Z-World 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.

Library 


IDBLOCK.LIB

See also 


readUserBlock

WrPortE 



void WrPortE(unsigned int port, char *portshadow, int data_value);

Description

Writes an external I/O register with 8 bits and updates shadow for that register. The variable names must be of the form port and portshadow for the most efficient operation. A NULL pointer may be substituted if shadow support is not desired or needed.

Parameters 


port

Address of external data register. 


portshadow

Reference pointer to a variable shadowing the register data. Substitute with NULL pointer (or 0) if shadowing is not required. 


data_value

Value to be written to the data register

Library 


SYSIO.LIB

See also 


RdPortI, BitRdPortI, WrPortI, BitWrPortI, RdPortE, BitRdPortE, BitWrPortE

WrPortI 



void WrPortI(int port, char *portshadow, int data_value);

Description

Writes an internal I/O register with 8 bits and updates shadow for that register.

Parameters 


port

Address of data register. 


portshadow

Reference pointer to a variable shadowing the register data. Substitute with NULL pointer (or 0) if shadowing is not required. 


data_value

Value to be written to the data register

Library 


SYSIO.LIB

See also 


RdPortI, BitRdPortI, BitRdPortE, BitWrPortI, RdPortE, WrPortE, BitWrPortE

xalloc 



long xalloc(long sz)

Description

Allocates the specified number of bytes in extended memory.

Parameters 


sz

Number of bytes to allocate.

Return value

The 20-bit physical address of the allocated data: Success.
0: Failure.

Note: This return value cannot be used with pointer arithmetic.

Library 


STACK.LIB

See also 


root2xmem, xmem2root

xmem2root 



int xmem2root(void *dest, unsigned long int src, unsigned int len);

Description

Stores len characters from physical address src to logical address dest.

Parameters 


dest

Logical address 


src

Physical address 


len

Numbers of bytes

Return value

 0: Success.
-1: Attempt to write flash memory area, nothing written.
-2: Destination not all in root.

Library 


XMEM.LIB

See also 


root2xmem, xalloc

xmem2xmem 



int xmem2xmem(unsigned long dest, unsigned long src, unsigned len);

Description

Stores len characters from physical address src to physical address dest.

Parameters 


dest

Physical address of destination 


src

Physical address of source data 


len

Length of source data in bytes

Return value

 0: Success.
-1: Attempt to write Flash Memory area, nothing written.

Library 


XMEM.LIB
Z-World
http://www.zworld.com
Voice: (530) 757-3737
FAX: (530) 757-3792
sales@zworld.com
PREV NEXT