.TH "ocxl_messages" 3 "Tue Sep 11 2018" "libocxl" \" -*- nroff -*-
.ad l
.nh
.SH NAME
ocxl_messages \- These functions control messages from libocxl, such as error messages and tracing\&.  

.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "void \fBocxl_afu_enable_messages\fP (\fBocxl_afu_h\fP afu, uint64_t sources)"
.br
.RI "Enable messages from an AFU\&. "
.ti -1c
.RI "void \fBocxl_afu_set_error_message_handler\fP (\fBocxl_afu_h\fP afu, void(*handler)(\fBocxl_afu_h\fP afu, \fBocxl_err\fP error, const char *message))"
.br
.RI "Override the default handler for emitting error messages for an AFU\&. "
.ti -1c
.RI "void \fBocxl_enable_messages\fP (uint64_t sources)"
.br
.RI "Enable messages from libocxl open calls\&. "
.ti -1c
.RI "void \fBocxl_set_error_message_handler\fP (void(*handler)(\fBocxl_err\fP error, const char *message))"
.br
.RI "Override the default handler for emitting error messages from open calls\&. "
.ti -1c
.RI "const char * \fBocxl_err_to_string\fP (\fBocxl_err\fP err)"
.br
.RI "Convert an error value to a string\&. "
.ti -1c
.RI "const char * \fBocxl_info\fP ()"
.br
.RI "Get version & compilation information about LibOCXL\&. "
.in -1c
.SH "Detailed Description"
.PP 
These functions control messages from libocxl, such as error messages and tracing\&. 


.SH "Function Documentation"
.PP 
.SS "void ocxl_afu_enable_messages (\fBocxl_afu_h\fP afu, uint64_t sources)"

.PP
Enable messages from an AFU\&. Error messages, if enabled, are emitted by default on STDERR\&. This behavior may be overridden by \fBocxl_afu_set_error_message_handler()\fP\&.
.PP
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\&.
.PP
\fBSee also:\fP
.RS 4
\fBocxl_afu_set_error_message_handler()\fP 
.PP
\fBocxl_enable_messages()\fP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to enable message on 
.br
\fIsources\fP a bitwise OR of the message sources to enable (OCXL_ERRORS, OCXL_TRACING) 
.RE
.PP

.SS "void ocxl_afu_set_error_message_handler (\fBocxl_afu_h\fP afu, void(*)(\fBocxl_afu_h\fP afu, \fBocxl_err\fP error, const char *message) handler)"

.PP
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\&.
.PP
The callback is responsible for prefixing and line termination\&.
.PP
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\&.
.PP
\fBSee also:\fP
.RS 4
\fBocxl_afu_enable_messages()\fP 
.PP
\fBocxl_err_to_string()\fP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to override the error handler for 
.br
\fIhandler\fP the new error message handler 
.RE
.PP

.SS "void ocxl_enable_messages (uint64_t sources)"

.PP
Enable messages from libocxl open calls\&. Error messages, if enabled, are emitted by default on STDERR\&. This behavior may be overridden by \fBocxl_afu_set_error_message_handler()\fP\&.
.PP
Tracing, if enabled, is always emitted on STDERR\&. It assists a developer by showing detailed AFU information\&.
.PP
\fBSee also:\fP
.RS 4
\fBocxl_set_error_message_handler()\fP 
.PP
\fBocxl_afu_enable_messages()\fP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIsources\fP a bitwise OR of the message sources to enable (OCXL_ERRORS, OCXL_TRACING) 
.RE
.PP

.SS "const char* ocxl_err_to_string (\fBocxl_err\fP err)"

.PP
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\&.
.PP
\fBSee also:\fP
.RS 4
\fBocxl_set_error_message_handler()\fP 
.PP
\fBocxl_afu_set_error_message_handler()\fP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIerr\fP the error value
.RE
.PP
\fBReturns:\fP
.RS 4
a string representing a human readable version of the error value 
.RE
.PP

.SS "const char* ocxl_info ()"

.PP
Get version & compilation information about LibOCXL\&. This must be included with any bug report\&.
.PP
The format and ordering of lines in this string may change\&.
.PP
\fBReturns:\fP
.RS 4
containing the version information 
.RE
.PP

.SS "void ocxl_set_error_message_handler (void(*)(\fBocxl_err\fP error, const char *message) handler)"

.PP
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\&.
.PP
The callback is responsible for prefixing and line termination\&.
.PP
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\&.
.PP
\fBSee also:\fP
.RS 4
\fBocxl_enable_messages()\fP 
.PP
\fBocxl_err_to_string()\fP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIhandler\fP the new error message handler 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libocxl from the source code\&.