libocxl
Loading...
Searching...
No Matches
Functions
OpenCAPI Messages

These functions control messages from libocxl, such as error messages and tracing. More...

Functions

void ocxl_afu_enable_messages (ocxl_afu_h afu, uint64_t sources)
 Enable messages from an AFU.
 
void ocxl_afu_set_error_message_handler (ocxl_afu_h afu, void(*handler)(ocxl_afu_h afu, ocxl_err error, const char *message))
 Override the default handler for emitting error messages for an AFU.
 
void ocxl_enable_messages (uint64_t sources)
 Enable messages from libocxl open calls.
 
void ocxl_set_error_message_handler (void(*handler)(ocxl_err error, const char *message))
 Override the default handler for emitting error messages from open calls.
 
const char * ocxl_err_to_string (ocxl_err err)
 Convert an error value to a string.
 
const char * ocxl_info ()
 Get version & compilation information about LibOCXL.
 

Detailed Description

These functions control messages from libocxl, such as error messages and tracing.

Function Documentation

◆ ocxl_afu_enable_messages()

void ocxl_afu_enable_messages ( ocxl_afu_h  afu,
uint64_t  sources 
)

Enable messages from an AFU.

Error messages, if enabled, are emitted by default on STDERR. This behavior may be overridden by ocxl_afu_set_error_message_handler().

Tracing, if enabled, is always emitted on STDERR. It assists a developer by showing detailed AFU information, as well as MMIO & IRQ interactions between the application and the AFU. It does not show direct accesses to memory from the AFU.

See also
ocxl_afu_set_error_message_handler()
ocxl_enable_messages()
Parameters
afuthe AFU to enable message on
sourcesa bitwise OR of the message sources to enable (OCXL_ERRORS, OCXL_TRACING)

Definition at line 151 of file afu.c.

◆ ocxl_afu_set_error_message_handler()

void ocxl_afu_set_error_message_handler ( ocxl_afu_h  afu,
void(*)(ocxl_afu_h afu, ocxl_err error, const char *message)  handler 
)

Override the default handler for emitting error messages for an AFU.

The default error handler emits messages on STDERR, to override this behavior, pass a callback to this function.

The callback is responsible for prefixing and line termination.

Typical use cases would be redirecting error messages to the application's own logging/reporting mechanisms, and adding additional application-specific context to the error messages.

See also
ocxl_afu_enable_messages()
ocxl_err_to_string()
Parameters
afuthe AFU to override the error handler for
handlerthe new error message handler

Definition at line 175 of file afu.c.

◆ ocxl_enable_messages()

void ocxl_enable_messages ( uint64_t  sources)

Enable messages from libocxl open calls.

Error messages, if enabled, are emitted by default on STDERR. This behavior may be overridden by ocxl_afu_set_error_message_handler().

Tracing, if enabled, is always emitted on STDERR. It assists a developer by showing detailed AFU information.

See also
ocxl_set_error_message_handler()
ocxl_afu_enable_messages()
Parameters
sourcesa bitwise OR of the message sources to enable (OCXL_ERRORS, OCXL_TRACING)

Definition at line 70 of file setup.c.

◆ ocxl_err_to_string()

const char * ocxl_err_to_string ( ocxl_err  err)

Convert an error value to a string.

When implementing an error message handler, it may be useful to decode the provided ocxl_err to a human readable string, before logging the message.

See also
ocxl_set_error_message_handler()
ocxl_afu_set_error_message_handler()
Parameters
errthe error value
Returns
a string representing a human readable version of the error value

Definition at line 111 of file setup.c.

◆ ocxl_info()

const char * ocxl_info ( )

Get version & compilation information about LibOCXL.

This must be included with any bug report.

The format and ordering of lines in this string may change.

Returns
containing the version information

Definition at line 154 of file setup.c.

◆ ocxl_set_error_message_handler()

void ocxl_set_error_message_handler ( void(*)(ocxl_err error, const char *message)  handler)

Override the default handler for emitting error messages from open calls.

The default error handler emits messages on STDERR, to override this behavior, pass a callback to this function.

The callback is responsible for prefixing and line termination.

Typical use cases would be redirecting error messages to the application's own logging/reporting mechanisms, and adding additional application-specific context to the error messages.

See also
ocxl_enable_messages()
ocxl_err_to_string()
Parameters
handlerthe new error message handler

Definition at line 93 of file setup.c.