PSoC1 UART confusion between high and low level API

This forum is for the reporting and discussion of the PSoC documentation from Cypress (data sheet, TRM, user guide, etc).

Moderator: fsu

PSoC1 UART confusion between high and low level API

Postby slandrum » Thu Nov 19, 2009 3:05 pm

In the data sheet for the UART (and RX8 and TX8 modules), the API calls are segregated into low level and high level API calls.

There are a number of functions that are listed as high level API calls, but really aren't. From description near the top of the data sheet:

High Level API

The high level API adds additional firmware on top of the basic functions, to provide command and string level functions instead of character level. The Device Editor allows the user to set the size of the receiver command buffer, command terminator, parameter delimiter, and below what value the receiver should ignore characters. Transmit functions accept pointers to strings, so that an entire string may be printed with a single function call instead of additional lines of C or ASM code. The transmit functions do not require the UART transmit interrupt to be enabled.

To make use of the high-level receiver functions, go to the Device Editor window, select the UART and select the "Enable" option for the "RxCmdBuffer" parameter. Next, select a "RxBufferSize" that is large enough to hold your largest command plus one. [...]


Among the "high level" functions are
void UART_IntCntl(BYTE bMask) Selectively enable/disable RX and TX interrupts.
void UART_PutChar(char bData) Send character to TX port when TX register is empty. Function will not return until TX Data register can be written to without a data overrun error.
char UART_cGetChar(void) Return character from RX Data register when valid data is available. Function will not return until character is received.
char UART_cReadChar(void) Read RX Data register immediately. If valid data not available, return 0, otherwise ASCII char between 1 and 255 is returned.
int UART_ iReadChar(void) Read Rx Data register immediately. If data is not available or an error condition exists, return an error status in the MSB. The received char is returned in the LSB.
void UART_PutSHexByte(BYTE bValue) Send a two character hex representation of bValue to the TX port.
void UART_PutSHexInt(int iValue) Send a four character hex representation of iValue to the TX port.
void UART_PutCRLF(void) Send a carraige return (0x0D) and a line feed (0x0A) to the TX port.


This is about half of the so-called "high level" API functions, but in fact all of the ones I listed are more properly considered low level API calls.

The GetChar and ReadChar functions do not make use of the RX interrupt and buffer, and in fact interact badly with code that attempts to make use of the calls that do use the RX interrupt and buffer.

The Put functions listed above do not take pointers to strings as is suggested by the earlier description of the high level API, but at least the Put functions don't interact badly with the string transmit functions.

At least one person has been incorrectly dissuaded from using exactly the functions that they should have been using because they thought that they would need buffers and interrupts and would need to specify delimiters when in fact they don't.
slandrum
The Big Cheese
The Big Cheese
 
Posts: 453
Joined: Fri Feb 29, 2008 11:38 am
Location: California

Return to “%s” PSoC Documentation Feedback

Who is online

Users browsing this forum: No registered users and 1 guest