.TH "ocxl_afu" 3 "Tue Sep 11 2018" "libocxl" \" -*- nroff -*-
.ad l
.nh
.SH NAME
ocxl_afu \- These functions provide access to open and close the AFU\&.  

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

.in +1c
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_open_from_dev\fP (const char *path, \fBocxl_afu_h\fP *afu)"
.br
.RI "Open an AFU context at a specified path\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_open_specific\fP (const char *name, const char *physical_function, int16_t afu_index, \fBocxl_afu_h\fP *afu)"
.br
.RI "Open an AFU context with a specified name on a specific card/afu index\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_open\fP (const char *name, \fBocxl_afu_h\fP *afu)"
.br
.RI "Open an AFU context with a specified name\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_attach\fP (\fBocxl_afu_h\fP afu, __attribute__((unused)) uint64_t flags)"
.br
.RI "Attach the calling process's memory to an open AFU context\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_close\fP (\fBocxl_afu_h\fP afu)"
.br
.RI "Close an AFU and detach it from the context\&. "
.in -1c
.SH "Detailed Description"
.PP 
These functions provide access to open and close the AFU\&. 

A typical workflow involves the following:
.IP "\(bu" 2
\fBocxl_afu_open_from_dev()\fP, \fBocxl_afu_open()\fP - Open the device by device or name
.IP "\(bu" 2
\fBocxl_afu_attach()\fP - Attach the device to the process's address space
.IP "\(bu" 2
\fBocxl_mmio_map()\fP - Map the MMIO space
.PP
.PP
Subsequently, you will need to write information to the AFU's MMIO space (see ocxl_mmio) and also configure and handle interrupts (see ocxl_irq)
.PP
Finally, to free the AFU handle, you can use \fBocxl_afu_close()\fP\&. 
.SH "Function Documentation"
.PP 
.SS "\fBocxl_err\fP ocxl_afu_attach (\fBocxl_afu_h\fP afu, __attribute__((unused)) uint64_t flags)"

.PP
Attach the calling process's memory to an open AFU context\&. An open AFU context is sufficient to configure the AFU, but in order for it to access application memory, the context must be attached to the current process\&.
.PP
If specified, also sets the value of the PPC specific PSL AMR\&.
.PP
\fBPrecondition:\fP
.RS 4
the AFU is opened
.RE
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to attach 
.br
\fIflags\fP An ORed bitmask of flags OCXL_ATTACH_FLAGS_NONE accept the default behavior
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the AFU was successful attached 
.br
\fIOCXL_NO_CONTEXT\fP if the AFU was not opened 
.br
\fIOCXL_INTERNAL_ERROR\fP if the AFU was unable to attach (check dmesg) 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_afu_close (\fBocxl_afu_h\fP afu)"

.PP
Close an AFU and detach it from the context\&. This will free all resources allocated to the AFU, including MMIO areas and IRQs\&. The AFU handle may not be used after it is closed\&.
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP a pointer to the AFU handle we want to close
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the AFU was freed 
.br
\fIOCXL_ALREADY_DONE\fP if the AFU was not open
.RE
.PP
\fBPostcondition:\fP
.RS 4
All resources associated with the handle are closed and freed, the handle is no longer usable 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_afu_open (const char * name, \fBocxl_afu_h\fP * afu)"

.PP
Open an AFU context with a specified name\&. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the AFU 
.br
\fIafu\fP the AFU handle which we will allocate\&. This should be freed with ocxl_afu_close
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if we have successfully fetched the AFU 
.br
\fIOCXL_NO_MEM\fP if an out of memory error occurred 
.br
\fIOCXL_NO_DEV\fP if no valid device was found 
.br
\fIOCXL_NO_MORE_CONTEXTS\fP if maximum number of AFU contexts has been reached on all matching AFUs 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_afu_open_from_dev (const char * path, \fBocxl_afu_h\fP * afu)"

.PP
Open an AFU context at a specified path\&. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the AFU 
.br
\fIafu\fP the AFU handle which we will allocate\&. This should be freed with ocxl_afu_close
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if we have successfully fetched the AFU 
.br
\fIOCXL_NO_MEM\fP if an out of memory error occurred 
.br
\fIOCXL_NO_DEV\fP if the device is invalid 
.br
\fIOCXL_NO_MORE_CONTEXTS\fP if maximum number of AFU contexts has been reached 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_afu_open_specific (const char * name, const char * physical_function, int16_t afu_index, \fBocxl_afu_h\fP * afu)"

.PP
Open an AFU context with a specified name on a specific card/afu index\&. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the AFU 
.br
\fIphysical_function\fP the PCI physical function of the card (as a string, or NULL for any) 
.br
\fIafu_index\fP the AFU index (or -1 for any) 
.br
\fIafu\fP the AFU handle which we will allocate\&. This should be freed with ocxl_afu_close
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if we have successfully fetched the AFU 
.br
\fIOCXL_NO_MEM\fP if an out of memory error occurred 
.br
\fIOCXL_NO_DEV\fP if no valid device was found 
.br
\fIOCXL_NO_MORE_CONTEXTS\fP if maximum number of AFU contexts has been reached on all matching AFUs 
.RE
.PP

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