next up previous
Next: Host (PC) RTDX API Up: RTDX API Previous: Client (DSK) RTDX Overview

Client (DSK-board) RTDX API

In this section the Clien RTDX API is listed in detail, such as it is available on the Code Composer Studio RTDX help file.

RTDX_CreateInputChannel


RTDX_CreateInputChannel(name)

This macro declares and initializes RTDX data channels for input. Data channels must be declared as global objects. A data channel may be used either for input or output, but not both. The contents of an input data channel is unknown to the user. The channel can be in one of two states: enabled or disabled. Channels are initialized as disabled. Channels can be enabled or disabled via a User Interface function. They also can be enabled or disabled remotely from CodeComposer or its COM interface.

Parameters:

name Label of the channel.


RTDX_CreateOutputChannel


RTDX_CreateOutputChannel(name)

This macro declares and initializes RTDX data channels for output. Data channels must be declared as global objects. A data channel may be used either for input or output, but not both. The contents of an output data channel is unknown to the user. The channel can be in one of two states: enabled or disabled. Channels are initialized as disabled. Channels can be enabled or disabled via a User Interface function. They also can be enabled or disabled remotely from CodeComposer or its COM interface.

Parameters:

name Label of the channel.


RTDX_enableInput


void RTDX_enableInput(RTDX_inputChannel *ichan)

A call to this function causes the specified data channel to be enabled. Data channels are initialized as disabled. They also can be enabled or disabled remotely from CodeComposer or its COM interface.

Parameters:

ichan identifier for an input data channel.
   
Returns:

nothing


RTDX_disableInput


void RTDX_disableInput(RTDX_inputChannel *ichan)

A call to this function causes the specified data channel to be disabled. Data channels are initialized as disabled. They also can be enabled or disabled remotely from CodeComposer or its COM interface.

Parameters:

ichan identifier for an input data channel.
   
Returns:

nothing


RTDX_isInputEnabled


void RTDX_isInputEnabled(name)

The RTDX_isInputEnabled macro returns the enabled status of a data channel.

Parameters:

name identifier for an input data channel.
   
Returns:

0 Not enabled.
non-zero Enabled.


RTDX_enableOutput


void RTDX_enableOutput(RTDX_outputChannel *ochan)

A call to this function causes the specified data channel to be enabled. Data channels are initialized as disabled. They also can be enabled or disabled remotely from CodeComposer or its COM interface.

Parameters:

ochan identifier for an output data channel.
   
Returns:

nothing


RTDX_disableOutput


void RTDX_disableOutput(RTDX_outputChannel *ochan)

A call to this function causes the specified data channel to be disabled. Data channels are initialized as disabled. They also can be enabled or disabled remotely from CodeComposer or its COM interface.

Parameters:

ochan identifier for an output data channel.
   
Returns:

nothing


RTDX_isOutputEnabled


void RTDX_isOutputEnabled(name)

The RTDX_isOutputEnabled macro returns the enabled status of a data channel.

Parameters:

name identifier for an output data channel.
   
Returns:

0 Not enabled.
non-zero Enabled.


RTDX_read


int RTDX_read(RTDX_InputChannel *ichan, void *buffer, int bsize)

RTDX_read causes a read request to be posted to the specified input data channel. If the channel is enabled, RTDX_read busy waits until the data has arrived. On return from the function, the data has been copied into the specified buffer and the number of address units of data actually supplied is returned. The function returns RTDX_READ_ERROR immediately if the channel is currently busy reading or is not enabled.
When RTDX_read is used, the target application notifies the RTDX Host Library that it is ready to receive data and then waits for the RTDX Host Library to write data into the target buffer. When the data is received, the target application continues execution.

Parameters:

ichan Identifier for an input data channel.
buffer A pointer to the buffer that will receive the data.
bsize The size of the buffer in address units.
   
Returns:

> 0 The number of address units of data actually supplied in buffer.
0 Failure. Cannot post read request because the target buffer is full.
RTDX_READ_ERROR Failure. Channel currently busy or not enabled.


RTDX_readNB


int RTDX_readNB(RTDX_InputChannel *ichan, void *buffer, int bsize)

RTDX_readNB triggers a read request of bufSize bytes to the host. RTDX hardware will take care of transferring the requested data from the host into the memory specified by the buffer pointer. Because the RTDX_readNB function immediately returns after the call to RTDX_readNB, the data transfer continues in the background and the CPU can perform other tasks in the interim. RTDX_channelBusy can be used to later check if the RTDX transfer has completed.

RTDX_readNB is a non-blocking form of the function RTDX_read. RTDX_readNB issues a read request to be posted to the specified input data channel and immediately returns. If the channel is not enabled or the channel is currently busy reading, the function returns RTDX_READ_ERROR. Thefunction returns 0 if it cannot post the read request due to a lack of space in the RTDX target buffer.

When the function RTDX_readNB is used, the target application notifies the RTDX Host Library that it is ready to receive data but the target application does not wait. Execution of the target application continues immediately. Use the RTDX_channelBusy and RTDX_sizeofInput functions to determine when the RTDX Host Library has written data into the target buffer.

Parameters:

ichan Identifier for an input data channel.
buffer A pointer to the buffer that will receive the data.
bsize The size of the buffer in address units.
   
Returns:

RTDX_OK Success.
0 Failure. Cannot post read request because the target buffer is full.
RTDX_READ_ERROR Failure. Channel currently busy or not enabled.


RTDX_sizeofInput


int RTDX_sizeofInput(RTDX_InputChannel *ichan)

RTDX_sizeofInput is designed to be used in conjunction with RTDX_readNB after a read operation has completed. The function returns the number of sizeof() units actually read from the specified data channel. The result of RTDX_sizeofInput is not valid if the channel is busy.

Parameters:

ichan Identifier for an input data channel.
   
Returns:

The number of sizeof() units of data actually supplied in buffer.


RTDX_write


int RTDX_write(RTDX_outputChannel *ochan, void *buffer, int bsize)

RTDX_write causes the specified data to be written to the specified output data channel, provided that channel is enabled. On return from the function, the data has been copied out of the specified buffer and into the RTDX target buffer. If the channel is not enabled, the write operation is suppressed. If the RTDX target buffer is full, 'Failure' is returned.

Parameters:

ochan Identifier for the output data channel.
buffer A pointer to the buffer containing the data.
bsize The size of the buffer in address units.
   
Returns:

non-zero Success
0 Failure


RTDX_channelBusy


int RTDX_channelBusy(RTDX_inputChannel *ichan)

RTDX_channelBusy is designed to be used in conjunction with RTDX_readNB. An RTDX input channel is busy when it is currently waiting for input. It is not busy when any previous request has completed. When RTDX_readNB is completed, the channel is no longer busy. RTDX_channelBusy returns RTDX_READ_ERROR if the channel is not enabled or busy. It returns 0 if the read request cannot be posted due to the buffer being full. It returns RTDX_OK for success, meaning that the channel is currently busy awaiting input.

Parameters:

ichan Identifier for the input data channel.
   
Returns:

RTDX_OK if the channel is currently busy awaiting input.
0 A read request cannot be posted due to the buffer being full.
RTDX_READ_ERROR The channel is not enabled or not busy.
In short:  
True if the channel is currently busy awaiting input.
False if the channel is not busy, meaning that a previous request has completed.



next up previous
Next: Host (PC) RTDX API Up: RTDX API Previous: Client (DSK) RTDX Overview
H. Rogalla 2005-12-07