FMDEBUG Reference

FMDEBUG provides debug functions to FM writers. Debug information is available via the hsmtrace utility on the host.

On Linux, these debug messages are also written to /var/log/messages

Historically, debug logging has been via a simulated serial port 0. This is maintained for backwards compatibility. In ProtectToolkit 5 support was added for standard C printf to write to the hsmtrace log. This is the recommended method.

NOTE 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.

Function Descriptions

This section contains the following function descriptions:

>DBG

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

In addition to FMDEBUG logging, FM SDK 5.0 introduces support for the C standard printf() and vprintf() functions. These functions can be called at any time, with or without the debug library, and accept all standard C99 formating specifiers.

In FMs, these functions do not print to stdout, but instead send log messages to the hsmtrace log. Since these are formatting messages for a log rather than stdout, there are two differences from the standard C implementations.

1.Each printf()/vprintf() call prefaces its output with a log header that includes the FM’s ID.

2.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 may 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 PSG. 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 PSG.

On PSI-E and newer, this API writes to the HSM trace log.

On the ProtectServer 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 PSG.

Its use mirrors that of the C function printf.

On PSI-E and newer, this API writes to the HSM trace log.

On ProtectServer 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 PSG.

On PSI-E and newer, this API writes to the HSM trace log.

On ProtectServer 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 PSG.

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 PSG.

Synopsis

include <fmdebug.h>
int dbg_final()