FMDEBUG reference
FMDEBUG provides debug functions to FM writers. Debug information is available via the hsmtrace utility on the host (for more information about this utility, refer to hsmtrace). On Linux, these debug messages are also written to /var/log/messages
Note
Thales recommends that you use the standard C printf function to write debug messages to the hsmtrace log. For backwards compatibility, debug messages can be logged by using the simulated serial port 0.
These functions and macros are supported under the FM emulation build as well. In this case the printing is done to stdout instead of the serial port.
The debug functions are described below.
debug (macro)
This macro is used to conditionally include code in the DEBUG build of the FM or FM emulation.
By placing the statements inside the debug macro, the statements will appear only in the DEBUG build and will not be present in the Release build.
Synopsis
debug( statements )
Example
rv = funct();
debug( if ( rv ) dbg_print(“Error %x from func\r\n”, rv); )
if ( rv ) return rv;
In this example, the error message will only be displayed if the code is compiled for DEBUG and funct() returns an error code.
printf/vprintf
printf() and vprintf() can be called at any time, with or without the debug library, and accept all standard C99 formatting specifiers.
In FMs, these functions do not print to stdout, but instead send log messages to the hsmtrace log (for more information about this utility, refer to hsmtrace). Since these are formatting messages for a log rather than stdout, there are two differences from the standard C implementations.
-
Each printf()/vprintf() call prefaces its output with a log header that includes the FM’s ID.
-
Each call to printf()/vprintf() has a new line appended to its output.
Should an FM developer require raw character logging as existed in PPO toolkits, the FMDEBUG and Serial Port 0 logging APIs can be used.
DBG_INIT
Not required. Retained for backwards compatibility with PSG.
This macro is used to initialize the debug library and claim serial port 1 of the HSM. The port is also moded up for (115200, 8, none, 1) serial mode operations.
Synopsis
int dbg_init()
DBG
This macro is used to send a non-terminated string to serial port 1 of the HSM.
On PSI-E and newer, this API writes to the HSM trace log.
On the ProtectServer 3 PCIe HSMs, printf is preferred over use of this API.
Synopsis
int dbg(buf, len)
| Parameter | Description |
|---|---|
buf |
Array of printable characters to output to the serial port |
len |
Length of buffer to output |
DBG_PRINT
This function formats and dumps the given string to serial port 1 of the HSM.
Its use mirrors that of the C function printf.
On PSI-E and newer, this API writes to the HSM trace log.
OnProtectServer 3 PCIe HSMs, printf is preferred over use of this API.
Synopsis
include <fmdebug.h>
int dbg_print(char *format, ...);
| Parameter | Description |
|---|---|
format |
Format of the string to print. This argument is followed by the values to place inside the format string. |
Return Value
Returns 0 or -1 for failure.
DBG_STR
This macro is used to output a null terminated string to serial port 1 of the HSM.
On PSI-E and newer, this API writes to the HSM trace log.
On ProtectServer 3 PCIe HSMs, printf is preferred over use of this API.
Synopsis
include <fmdebug.h>
int dbg_str()
| Parameter | Description |
|---|---|
str |
String to output to serial port |
DUMP
This function converts unprintable character values into hex values and sends them to serial port 1 of the HSM.
On PSI-E and newer, this API writes to the HSM trace log.
Synopsis
include <fmdebug.h>
void dump(char *desc, unsigned char *data, short len);
| Parameter | Description |
|---|---|
desc |
Pointer to string that holds the description of the dumped buffer. This string is dumped immediately before the dumped buffer. |
data |
Pointer to buffer to be dumped |
len |
The length of the buffer to be dumped (in bytes) |
DBG_FINAL
Not required. Retained for backwards compatibility with PSG.
This macro is used to finalize the debug library and release serial port 1 of the HSM.
Synopsis
include <fmdebug.h>
int dbg_final()
