The Debug I/O module

Introduction - - One of the most basic things any HAL or indeed operating system will need to do is output to some form of debug monitor. The debug i/o module in NedHAL is a portable way of interfacing with a UART driver module in a fashion which allows easy changing of debug output. In other words, you can use the debug i/o module to alias access to a UART driver.
Callability
Assembler:  INCLUDE "DebugIOH.s"
C:  #include "DebugIO.h"
HALError
Module name:  "DebugIO", 0    (0x75626544, 0x004f4967)
Codes:
0:  (0x00):  Reserved
Portability API is portable
Code is portable
Constituents Entirely written in ANSI C for portability
Porting notes All non-portable information will be in the common.h file held in the specific port directory
Other Notes None
General use All calls to and from the debug i/o module are prefixed by DbgIO_. As the module is written in C, calls may only be made when the C run-time system is operational (ie; main memory and C library working and initialised).

To initialise and finalise the operation of this module, the usual calls DbgIO_Initialise and DbgIO_Finalise are provided. The API DbgIO_Set sets the UART driver which is to be the medium for debug input and output. If one needs to set up the UART driver prior to use by the debug i/o module, one may initialise the driver and call its <name>_Set to configure the UART before passing the details to DbgIO_Set.

DbgIO_Write0 writes a zero-terminated ASCII string, DbgIO_WriteC writes just one character and DbgIO_ReadC reads just one character. For your convenience, the API DbgIO_WriteF is provided which acts much like the standard C library's printf() - however, it is not a full implementation (only %d, %x & %s implemented) and additionally, if this call is not used then the linker will not link in the code for DbgIO_WriteF.

 

DbgIO_Initialise

Purpose - - Initialises the debug i/o module for subsequent use
Prototype HALError *DbgIO_Initialise(void)
Exit Null if no error occurred, pointer to valid HALError structure otherwise
Staticity Not static
Use None
Notes None

 

DbgIO_Finalise

Purpose     Deinitialises the debug i/o module
Prototype HALError *DbgIO_Finalise(void)
Exit Null if no error occurred, pointer to valid HALError structure otherwise
Staticity Not static
Use None
Notes None

 

DbgIO_Set

Purpose     Sets the debug i/o module to use a particular UART driver
Prototype HALError *DbgIO_Set(DbgIO_UARTDetails *uartdetails, HALUARTBlk *contextblk)
Exit Null if no error occurred, pointer to valid HALError structure otherwise
Staticity Not static
Use This call finalises the currently set UART driver (if there is one) before installing the one whose details have been passed as parameters. Given no error upon return from this call, all i/o done through the debug i/o module will now pass through the specified UART driver. Note that the UART driver you wish to set the debug i/o module to use need not have already been successfully initialised.

The first parameter, uartdetails, points to a DbgIO_UARTDetails structure, which is comprised of as follows:

typedef struct DbgIO_UARTDetails_t
{
	int initialised:1;
	HALError *(*initialise)(HALUARTBlk *, void *);
	HALError *(*finalise)(HALUARTBlk *);
	HALError *(*send)(HALUARTBlk *, const char *, int no);
	HALError *(*get)(HALUARTBlk *, char *, int no);
} DbgIO_UARTDetails;

In other words, you fill in the structure with the addresses of the <name>_Initialise, <name>_Finalise, <name>_WriteN and <name>_ReadN functions of the UART driver. If you have no special configuration wishes for the UART driver, set initialised to 0. You must supply an appropriate context block for the UART driver to use in contextblk.

If you wish to set the UART driver to use a configuration other than its initialisation default, you will need to initialise the UART driver by calling its <name>_Initialise function with an appropriate context block (subsequently passed in contextblk) and then perform a <name>_Set on it with the desired configuration. After setting initialised in uartdetails to 1, you then pass pointers to both items to this function.
Notes None

 

DbgIO_Write0

Purpose     Writes a zero-terminated string to the currently set debug UART driver
Prototype HALError *DbgIO_Write0(const char *string)
Exit Null if no error occurred, pointer to valid HALError structure otherwise
Staticity Not static
Use This call writes the zero terminated string specified by string out to the currently set debug driver. It may or may not do this asynchronously.
Notes None

 

DbgIO_WriteC

Purpose     Writes a single character to the currently set debug UART driver
Prototype HALError *DbgIO_WriteC(const char c)
Exit Null if no error occurred, pointer to valid HALError structure otherwise
Staticity Not static
Use This call writes the single character specified by c out to the currently set debug driver. It may or may not do this asynchronously.
Notes None

 

DbgIO_ReadC

Purpose     Reads a single character from the currently set debug UART driver
Prototype HALError *DbgIO_ReadC(char *c)
Exit Null if no error occurred, pointer to valid HALError structure otherwise
Staticity Not static
Use This call reads a single character into the specified buffer specified by c from the currently set debug driver. It will always wait until the character is read.
Notes None

 

DbgIO_WriteF

Purpose     Writes a formatted zero-terminated string to the currently set debug UART driver
Prototype HALError *DbgIO_WriteF(const char *format, ...)
Exit Null if no error occurred, pointer to valid HALError structure otherwise
Staticity Not static
Use This call acts very similarly to the ANSI standard C library's printf() call. However, it only takes the following inserts within format:
  • %%: inserts a "%"
  • %d: inserts a signed decimal integer
  • %x: inserts a hexadecimal integer
  • %s: inserts a string

No other inserts or modifiers are allowed. Note that if this call is not used anywhere in your code, the expansive amounts of code required to implement this call will not be linked into your executable.
Notes None