UART_stdio.h File Reference

Introduction

This header file contains function prototypes which interface interactively with the user through the serial console to perform some utility operations.

Go to the source code of this file.

Macros
#define	E_PASS   ((int32_t)(0))
#define	E_FAIL   (-((int32_t)1))
#define	S_PASS   (0)

Functions
uint32_t	UART_puts (const char *pTxBuffer, int32_t numBytesToWrite)
	This function writes data from a specified buffer onto the transmitter FIFO of UART. More...
uint32_t	UART_gets (char *pRxBuffer, int32_t numBytesToRead)
	This function reads data from the receiver FIFO to a buffer in the receiver. More...
int32_t	UART_dataWrite (const char *pcBuf, uint32_t ulLen)
void	UART_printf (const char *pcString,...)
void	UART_putc (uint8_t byteTx)
uint8_t	UART_getc (void)
void	UART_stdioInit2 (uint32_t instance, UART_Params *uartParams)
	This function initializes the specified UART instance for use for console operations , with a configuration specified by 'uartParams'. More...
void	UART_stdioInit (uint32_t value)
	This function initializes the specified UART instance for use for console operations. More...
int32_t	UART_scanFmt (const char *pString,...)
	This function shall read the formatted input from UART console. Format specifier follows %[fill][width]specifier Following formatting specifier are supported. More...
void	UART_stdioDeInit (void)
	This function de-initializes the UART instance that is opened for console operations. More...
void	UART_printStatus (const char *statusString)
	This function prints the status on the UART instance that is opened for console operations. More...

Macro Definition Documentation

E_PASS

#define E_PASS   ((int32_t)(0))

E_FAIL

#define E_FAIL   (-((int32_t)1))

S_PASS

#define S_PASS   (0)

Function Documentation

UART_puts()

uint32_t UART_puts	(	const char *	pTxBuffer,
		int32_t	numBytesToWrite
	)

This function writes data from a specified buffer onto the transmitter FIFO of UART.

Parameters

pTxBuffer	Pointer to a buffer in the transmitter.
numBytesToWrite	Number of bytes to be transmitted to the transmitter FIFO. The user has the freedom to not specify any valid value for this if he wants to print until the occurence of a NULL character. In this case, he has to pass a negative value as this parameter.

Returns

Number of bytes written to the transmitter FIFO.

Note

1> Whenever a null character(\0) is encountered in the data to be transmitted, the transmission is stopped.
2> - Whenever the transmitter data has a new line character(\n), it is interpreted as a new line(\n) + carraige return(\r) characters. This is because the serial console interprets a new line character as it is and does not introduce a carraige return.
Some example function calls of this function are:
UARTPuts(txArray, -2): This shall print the contents of txArray[] until the occurence of a NULL character.
UARTPuts("Hello World", 8): This shall print the first 8 characters of the string shown.
UARTPuts("Hello World", 20): This shall print the string shown until the occurence of the NULL character. Here, the NULL character is encountered earlier than the length of 20 bytes.

UART_gets()

uint32_t UART_gets	(	char *	pRxBuffer,
		int32_t	numBytesToRead
	)

This function reads data from the receiver FIFO to a buffer in the receiver.

Parameters

pRxBuffer	Pointer to a buffer in the receiver.
numBytesToRead	The number of bytes the receiver buffer can hold. However, if the user wishes not to specify this parameter, he has freedom to do so. In that case, the user has to pass a negative value for this parameter.

Returns

Number of bytes read from the receiver FIFO.

Note

The two exit points for this function are: 1> To enter an ESC character or a carraige return character('Enter' key on the Keyboard).
2> Specify a limit to the number of bytes to be read.
Some example function calls of this function are:

UARTGets(rxBuffer, -2): This reads characters from the receiver FIFO of UART until the occurence of a carriage return ('Enter' key on the keyboard pressed) or an ESC character.

UARTGets(rxBuffer, 12): This reads characters until 12 characters have been read or until an occurence of a carriage return or an ESC character, whichever occurs first.

UART_dataWrite()

int32_t UART_dataWrite	(	const char *	pcBuf,
		uint32_t	ulLen
	)

Writes a string of characters to the UART output.

Parameters

pcBuf	points to a buffer containing the string to transmit.
ulLen	is the length of the string to transmit.

This function will transmit the string to the UART output. The number of characters transmitted is determined by the ulLen parameter. This function does no interpretation or translation of any characters. Since the output is sent to a UART, any LF (/n) characters encountered will be replaced with a CRLF pair.

Besides using the ulLen parameter to stop transmitting the string, if a null character (0) is encountered, then no more characters will be transmitted and the function will return.

In non-buffered mode, this function is blocking and will not return until all the characters have been written to the output FIFO. In buffered mode, the characters are written to the UART transmit buffer and the call returns immediately. If insufficient space remains in the transmit buffer, additional characters are discarded.

Returns

Returns the count of characters written.

UART_printf()

void UART_printf	(	const char *	pcString,
			...
	)

A simple UART based printf function supporting %c, %d, %p, %s, %u, %x, and %X.

Parameters

pcString	is the format string.
...	are the optional arguments, which depend on the contents of the format string.

This function is very similar to the C library fprintf() function. All of its output will be sent to the UART. Only the following formatting characters are supported:

• %c to print a character
• %d to print a decimal value
• %s to print a string
• %u to print an unsigned decimal value
• %x to print a hexadecimal value using lower case letters
• %X to print a hexadecimal value using lower case letters (not upper case letters as would typically be used)
• %p to print a pointer as a hexadecimal value
• %% to print out a % character

For %s, %d, %u, %p, %x, and %X, an optional number may reside between the % and the format character, which specifies the minimum number of characters to use for that value; if preceded by a 0 then the extra characters will be filled with zeros instead of spaces. For example, \%8d'' will use eight characters to print the decimal value with spaces added to reach eight;%08d'' will use eight characters as well but will add zeroes instead of spaces.

The type of the arguments after pcString must match the requirements of the format string. For example, if an integer was passed where a string was expected, an error of some kind will most likely occur.

Returns

None.

UART_putc()

void UART_putc

(

uint8_t

byteTx

)

UART_getc()

uint8_t UART_getc

(

void

)

UART_stdioInit2()

void UART_stdioInit2	(	uint32_t	instance,
		UART_Params *	uartParams
	)

This function initializes the specified UART instance for use for console operations , with a configuration specified by 'uartParams'.

Parameters

instance	- uart instance ID.
uartParams	- Configuration parameters.

Returns

None.

UART_stdioInit()

void UART_stdioInit

(

uint32_t

value

)

This function initializes the specified UART instance for use for console operations.

Parameters

value

- the UART instance number

Returns

None.

UART_scanFmt()

int32_t UART_scanFmt	(	const char *	pString,
			...
	)

This function shall read the formatted input from UART console. Format specifier follows %[fill][width]specifier Following formatting specifier are supported.

• c to input a character.
• d to input a decimal value.
• s to input a string.
• u to input an unsigned decimal value.
• x, %X to input a hexadecimal value using lower case letters.
• p to input a pointer as a hexadecimal value.

Parameters

pString

Pointer to the format string.

Return values

S_PASS	Sucessfully executed.
E_FAIL	If an error occurred.

UART_stdioDeInit()

void UART_stdioDeInit

(

void

)

This function de-initializes the UART instance that is opened for console operations.

Returns

None.

UART_printStatus()

void UART_printStatus

(

const char *

statusString

)

This function prints the status on the UART instance that is opened for console operations.

Parameters

statusString

- string pointer.

Returns

None.