StarterWare ConsoleUtilities

Background

Previous versions of StarterWare were supporting only UART based console utilities, where the I/O operations were  redirected to the serial console through UART interface. This imposes a limitation where, the I/O operations can not be performed without the UART interface. To overcome this limitation, generic console utilities have been developed. The generic console utilities are wrapper functions which are compliant with the standard I/O utility functions. These utilities will allow user to select either debugger console or UART console. Configuring the console type will redirect all the console input/output to the selected console type.

Console Utils APIs

The below table provides the list of Console Utils APIs present in StarterWare and corresponding functionally equivalent standard I/O APIs.

S.No	Console Utils API	Standard I/O API
1	ConsoleUtilsPrintf	printf
2	ConsoleUtilsScanf	scanf
3	ConsoleUtilsGets	gets - with buffer overrun check
4	ConsoleUtilsPuts	puts
5	ConsoleUtilsGetChar	getchar
6	ConsoleUtilsPutChar	putchar

Note: UARTGetc API functionality is not compliant with Standard I/O functionality of 'getchar'. To read a character, 'getchar' requires an ENTER key press along with the character, where as UARTGetc does not require ENTER key press.

Debug Console Support

In the StarterWare applications the default console is configured as uart. The support for the debugger console is provided through a mechanism called "Semihosting". More information about Semihosting and procedure to enable Semihosting can be at Semihosting.

Code Modifications

Following mandatory steps should be performed before using any of the Console Utils APIs.

1. Initialization of Console. Following API should be called to init the Console.

     ConsoleUtilsInit();

2. Selecting the type of Console. Console selection can be achieved through the following run time macros

   CONSOLE_UART     : For selecting UART console
   CONSOLE_DEBUGGER : For selecting the debug console

Following API should be called to select the console type

  
   ConsoleUtilsSetType(CONSOLE_UART);

            or 

   ConsoleUtilsSetType(CONSOLE_DEBUGGER);

Note:

1. In the StarterWare applications the default console is configured as uart.

2. Semihosting should be enabled first to support redirection of I/O operations to debugger console. Without enabling the semihosting, if the runtime macro is configured as "CONSOLE_DEBUGGER", then an error message will be displayed on the UART console. The procedure to enable semihosting has been given at StarterWare_Semihosting.

Deprecated APIs

The following list of APIs have been deprecated in the current version of StarterWare. All the references to the above APIs have been replaced with "ConsoleUtilsPrintf" and "ConsoleUtilsScanf" instead.

1. UARTPutHexNum 
2. UARTGetHexNum 
3. UARTPutNum 
4. UARTGetNum 
5. UARTPrintf

Note:

1.The deprecated API will give a warning for GCC and CCS when used anywhere in the code.

2. IAR does not give any warning for deprecated API, because Deprecated attribute/pragma is not supported by the compiler

Known issues / Limitations

1. ConsoleUtilsPrintf and ConsoleUtilsScanf do not support I/O operations of float data types (format specifier %f is not supported).
2. Redirection to debugger console is supported with CCS5.4 only because SemiHosting is enabled with CCS 5.4 and the previous versions do not support semihosting.
3. Non-blocking getc is not supported in ConsoleUtils since that does not match with any standard IO functions. If such a functionality is needed with UART, UARTgetc must be directly used.