.TH "ocxl_mmio" 3 "Tue Sep 11 2018" "libocxl" \" -*- nroff -*-
.ad l
.nh
.SH NAME
ocxl_mmio \- The MMIO functions map the global and per-PASID MMIO spaces of the AFU into the address space of the process, as well as moderating access to them\&.  

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

.in +1c
.ti -1c
.RI "\fBocxl_err\fP \fBglobal_mmio_open\fP (ocxl_afu *afu)"
.br
.RI "Open the global MMIO descriptor on an AFU\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_map_advanced\fP (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type, size_t size, int prot, uint64_t flags, off_t offset, \fBocxl_mmio_h\fP *region)"
.br
.RI "Map an MMIO area of an AFU\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_map\fP (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type, \fBocxl_mmio_h\fP *region)"
.br
.RI "Map an MMIO area of an AFU\&. "
.ti -1c
.RI "void \fBocxl_mmio_unmap\fP (\fBocxl_mmio_h\fP region)"
.br
.RI "Unmap an MMIO region from an AFU\&. "
.ti -1c
.RI "int \fBocxl_mmio_get_fd\fP (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type)"
.br
.RI "Get a file descriptor for an MMIO area of an AFU\&. "
.ti -1c
.RI "size_t \fBocxl_mmio_size\fP (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type)"
.br
.RI "Get the size of an MMIO region for an AFU\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_get_info\fP (\fBocxl_mmio_h\fP region, void **address, size_t *size)"
.br
.RI "Get the address & size of a mapped MMIO region\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_read32\fP (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint32_t *out)"
.br
.RI "Read a 32-bit value from an AFU's MMIO region & convert endianness\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_read64\fP (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint64_t *out)"
.br
.RI "Read a 64-bit value from an AFU's MMIO region & convert endianness\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_write32\fP (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint32_t value)"
.br
.RI "Convert endianness and write a 32-bit value to an AFU's MMIO region\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_write64\fP (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint64_t value)"
.br
.RI "Convert endianness and write a 64-bit value to an AFU's MMIO region\&. "
.in -1c
.SH "Detailed Description"
.PP 
The MMIO functions map the global and per-PASID MMIO spaces of the AFU into the address space of the process, as well as moderating access to them\&. 

Only 32bit & 64bit accesses are supported\&. 
.SH "Function Documentation"
.PP 
.SS "\fBocxl_err\fP global_mmio_open (ocxl_afu * afu)"

.PP
Open the global MMIO descriptor on an AFU\&. 
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_NO_DEV\fP if the MMIO descriptor could not be opened 
.RE
.PP

.SS "int ocxl_mmio_get_fd (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type)"

.PP
Get a file descriptor for an MMIO area of an AFU\&. Once obtained, the descriptor may be used to manually MMAP a section of the MMIO area\&.
.PP
\fBSee also:\fP
.RS 4
\fBocxl_mmio_size()\fP to get the size of the MMIO areas
.RE
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened
.RE
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to operate on 
.br
\fItype\fP the type of MMIO area to map
.RE
.PP
\fBReturns:\fP
.RS 4
the requested descriptor, or -1 if it is not available 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_mmio_get_info (\fBocxl_mmio_h\fP region, void ** address, size_t * size)"

.PP
Get the address & size of a mapped MMIO region\&. 
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened, and the MMIO area mapped
.RE
.PP
\fBParameters:\fP
.RS 4
\fIregion\fP the MMIO region to get the details for 
.br
\fIaddress\fP [out] The address of the MMIO region 
.br
\fIsize\fP [out] the size of the MMIO region in bytes
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the details were retrieved 
.br
\fIOCXL_INVALID_ARGS\fP if the region is invalid 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_mmio_map (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type, \fBocxl_mmio_h\fP * region)"

.PP
Map an MMIO area of an AFU\&. Maps the entire global/per-PASID region of MMIO memory on the AFU with read/write access granted\&.
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened, and if a per-PASID region is to be mapped, the AFU has been attached
.RE
.PP
\fBSee also:\fP
.RS 4
\fBocxl_afu_attach()\fP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to operate on 
.br
\fItype\fP the type of MMIO area to map 
.br
\fIregion\fP [out] the MMIO region handle
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP on success 
.br
\fIOCXL_NO_MEM\fP if the map failed 
.br
\fIOCXL_NO_CONTEXT\fP if the AFU has not been opened 
.br
\fIOCXL_INVALID_ARGS\fP if the flags are not valid 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_mmio_map_advanced (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type, size_t size, int prot, uint64_t flags, off_t offset, \fBocxl_mmio_h\fP * region)"

.PP
Map an MMIO area of an AFU\&. Provides finer grain control of MMIO region mapping\&. Allows for protection parameters to be specified, as well as allowing partial mappings (with PAGE_SIZE granularity)\&.
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened
.RE
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to operate on 
.br
\fItype\fP the type of MMIO area to map 
.br
\fIsize\fP the size of the MMIO region to map (or 0 to map the full region) 
.br
\fIprot\fP the protection parameters as per mmap/mprotect 
.br
\fIflags\fP Additional flags to modify the map behavior (currently unused, must be 0) 
.br
\fIoffset\fP the offset of the MMIO region to map (or 0 to map the full region), should be a multiple of PAGE_SIZE 
.br
\fIregion\fP the MMIO region handle
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP on success 
.br
\fIOCXL_NO_MEM\fP if the map failed 
.br
\fIOCXL_NO_CONTEXT\fP if the AFU has not been opened 
.br
\fIOCXL_INVALID_ARGS\fP if the flags are not valid 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_mmio_read32 (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint32_t * out)"

.PP
Read a 32-bit value from an AFU's MMIO region & convert endianness\&. Read the 32-bit value at offset from the address of the mapped MMIO space, and convert endianness as specified by the endian parameter\&. Memory barriers are inserted before and after the MMIO operation\&.
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened, and the MMIO area mapped 
.RE
.PP
\fBParameters:\fP
.RS 4
\fImmio\fP the MMIO area to operate on 
.br
\fIoffset\fP A byte address that is aligned on a word (4 byte) boundary\&. It must be lower than the MMIO size (-4 bytes) reported by \fBocxl_mmio_size()\fP 
.br
\fIendian\fP the endianness of the stored data (will be converted to native) 
.br
\fIout\fP the value that was read
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the value was read 
.br
\fIOCXL_NO_CONTEXT\fP if the MMIO area is not mapped 
.br
\fIOCXL_OUT_OF_BOUNDS\fP if the offset exceeds the available area 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_mmio_read64 (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint64_t * out)"

.PP
Read a 64-bit value from an AFU's MMIO region & convert endianness\&. Read the 64-bit value at offset from the address of the mapped MMIO space, and convert endianness as specified by the endian parameter\&. Memory barriers are inserted before and after the MMIO operation\&.
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened, and the MMIO area mapped
.RE
.PP
\fBParameters:\fP
.RS 4
\fImmio\fP the MMIO area to operate on 
.br
\fIoffset\fP A byte address that is aligned on an 8 byte boundary\&. It must be lower than the MMIO size (-8 bytes) reported by ocxl_afu_get_mmio_size() 
.br
\fIendian\fP the endianness of the stored data (will be converted to native) 
.br
\fIout\fP the value that was read
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the value was read 
.br
\fIOCXL_NO_CONTEXT\fP if the MMIO area is not mapped 
.br
\fIOCXL_OUT_OF_BOUNDS\fP if the offset exceeds the available area 
.RE
.PP

.SS "size_t ocxl_mmio_size (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type)"

.PP
Get the size of an MMIO region for an AFU\&. 
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to get the MMIO size of 
.br
\fItype\fP the type of the MMIO region
.RE
.PP
\fBReturns:\fP
.RS 4
the size of the MMIO region in bytes 
.RE
.PP

.SS "void ocxl_mmio_unmap (\fBocxl_mmio_h\fP region)"

.PP
Unmap an MMIO region from an AFU\&. 
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened, and the MMIO area mapped
.RE
.PP
\fBParameters:\fP
.RS 4
\fIregion\fP the MMIO region to unmap 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_mmio_write32 (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint32_t value)"

.PP
Convert endianness and write a 32-bit value to an AFU's MMIO region\&. Convert endianness and write the 32-bit word at offset from the address of the mapped MMIO space\&. Memory barriers are inserted before and after the MMIO operation\&.
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened, and the MMIO area mapped
.RE
.PP
\fBParameters:\fP
.RS 4
\fImmio\fP the MMIO area to operate on 
.br
\fIoffset\fP A byte address that is aligned on a 4 byte boundary\&. It must be lower than the MMIO size (-4 bytes) reported by \fBocxl_mmio_size()\fP
.br
\fIendian\fP the endianness of the stored data (value will be converted to this before storing it) 
.br
\fIvalue\fP the value to write
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the value was written 
.br
\fIOCXL_NO_CONTEXT\fP if the MMIO area is not mapped 
.br
\fIOCXL_OUT_OF_BOUNDS\fP if the offset exceeds the available area 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_mmio_write64 (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint64_t value)"

.PP
Convert endianness and write a 64-bit value to an AFU's MMIO region\&. Convert endianness and write the 32-bit word at offset from the address of the mapped MMIO space\&. Memory barriers are inserted before and after the MMIO operation\&.
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened, and the MMIO area mapped
.RE
.PP
\fBParameters:\fP
.RS 4
\fImmio\fP the MMIO area to operate on 
.br
\fIoffset\fP A byte address that is aligned on an 8 byte boundary\&. It must be lower than the MMIO size (-8 bytes) reported by \fBocxl_mmio_size()\fP 
.br
\fIendian\fP the endianness of the stored data (value will be converted to this before storing it) 
.br
\fIvalue\fP the value to write
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the value was written 
.br
\fIOCXL_NO_CONTEXT\fP if the MMIO area is not mapped 
.br
\fIOCXL_OUT_OF_BOUNDS\fP if the offset exceeds the available area 
.RE
.PP

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