Scroll to navigation

ocxl_mmio(3) Library Functions Manual ocxl_mmio(3)

NAME

ocxl_mmio - OpenCAPI MMIO Functions


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

SYNOPSIS

Functions


ocxl_err global_mmio_open (ocxl_afu *afu)
Open the global MMIO descriptor on an AFU. ocxl_err ocxl_mmio_map_advanced (ocxl_afu_h afu, ocxl_mmio_type type, size_t size, int prot, uint64_t flags, off_t offset, ocxl_mmio_h *region)
Map an MMIO area of an AFU. ocxl_err ocxl_mmio_map (ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h *region)
Map an MMIO area of an AFU. void ocxl_mmio_unmap (ocxl_mmio_h region)
Unmap an MMIO region from an AFU. int ocxl_mmio_get_fd (ocxl_afu_h afu, ocxl_mmio_type type)
Get a file descriptor for an MMIO area of an AFU. size_t ocxl_mmio_size (ocxl_afu_h afu, ocxl_mmio_type type)
Get the size of an MMIO region for an AFU. ocxl_err ocxl_mmio_get_info (ocxl_mmio_h region, void **address, size_t *size)
Get the address & size of a mapped MMIO region. ocxl_err ocxl_mmio_read32 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t *out)
Read a 32-bit value from an AFU's MMIO region & convert endianness. ocxl_err ocxl_mmio_read64 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t *out)
Read a 64-bit value from an AFU's MMIO region & convert endianness. ocxl_err ocxl_mmio_write32 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value)
Convert endianness and write a 32-bit value to an AFU's MMIO region. ocxl_err ocxl_mmio_write64 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t value)
Convert endianness and write a 64-bit value to an AFU's MMIO region.

Detailed Description

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.

Function Documentation

ocxl_err global_mmio_open (ocxl_afu * afu)

Open the global MMIO descriptor on an AFU.

Parameters

afu the AFU

Return values

OCXL_NO_DEV if the MMIO descriptor could not be opened

int ocxl_mmio_get_fd (ocxl_afu_h afu, ocxl_mmio_type type)

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.

See also

ocxl_mmio_size() to get the size of the MMIO areas

Precondition

the AFU has been opened

Parameters

afu the AFU to operate on
type the type of MMIO area to map

Returns

the requested descriptor, or -1 if it is not available

ocxl_err ocxl_mmio_get_info (ocxl_mmio_h region, void ** address, size_t * size)

Get the address & size of a mapped MMIO region.

Precondition

the AFU has been opened, and the MMIO area mapped

Parameters

region the MMIO region to get the details for
address [out] The address of the MMIO region
size [out] the size of the MMIO region in bytes

Return values

OCXL_OK if the details were retrieved
OCXL_INVALID_ARGS if the region is invalid

ocxl_err ocxl_mmio_map (ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h * region)

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.

Precondition

the AFU has been opened, and if a per-PASID region is to be mapped, the AFU has been attached

See also

ocxl_afu_attach()

Parameters

afu the AFU to operate on
type the type of MMIO area to map
region [out] the MMIO region handle

Return values

OCXL_OK on success
OCXL_NO_MEM if the map failed
OCXL_NO_CONTEXT if the AFU has not been opened
OCXL_INVALID_ARGS if the flags are not valid

ocxl_err ocxl_mmio_map_advanced (ocxl_afu_h afu, ocxl_mmio_type type, size_t size, int prot, uint64_t flags, off_t offset, ocxl_mmio_h * region)

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

Precondition

the AFU has been opened

Parameters

afu the AFU to operate on
type the type of MMIO area to map
size the size of the MMIO region to map (or 0 to map the full region)
prot the protection parameters as per mmap/mprotect
flags Additional flags to modify the map behavior (currently unused, must be 0)
offset the offset of the MMIO region to map (or 0 to map the full region), should be a multiple of PAGE_SIZE
region the MMIO region handle

Return values

OCXL_OK on success
OCXL_NO_MEM if the map failed
OCXL_NO_CONTEXT if the AFU has not been opened
OCXL_INVALID_ARGS if the flags are not valid

ocxl_err ocxl_mmio_read32 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t * out)

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.

Precondition

the AFU has been opened, and the MMIO area mapped

Parameters

mmio the MMIO area to operate on
offset A byte address that is aligned on a word (4 byte) boundary. It must be lower than the MMIO size (-4 bytes) reported by ocxl_mmio_size()
endian the endianness of the stored data (will be converted to native)
out the value that was read

Return values

OCXL_OK if the value was read
OCXL_NO_CONTEXT if the MMIO area is not mapped
OCXL_OUT_OF_BOUNDS if the offset exceeds the available area

ocxl_err ocxl_mmio_read64 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t * out)

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.

Precondition

the AFU has been opened, and the MMIO area mapped

Parameters

mmio the MMIO area to operate on
offset 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()
endian the endianness of the stored data (will be converted to native)
out the value that was read

Return values

OCXL_OK if the value was read
OCXL_NO_CONTEXT if the MMIO area is not mapped
OCXL_OUT_OF_BOUNDS if the offset exceeds the available area

size_t ocxl_mmio_size (ocxl_afu_h afu, ocxl_mmio_type type)

Get the size of an MMIO region for an AFU.

Parameters

afu the AFU to get the MMIO size of
type the type of the MMIO region

Returns

the size of the MMIO region in bytes

void ocxl_mmio_unmap (ocxl_mmio_h region)

Unmap an MMIO region from an AFU.

Precondition

the AFU has been opened, and the MMIO area mapped

Parameters

region the MMIO region to unmap

ocxl_err ocxl_mmio_write32 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value)

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.

Precondition

the AFU has been opened, and the MMIO area mapped

Parameters

mmio the MMIO area to operate on
offset A byte address that is aligned on a 4 byte boundary. It must be lower than the MMIO size (-4 bytes) reported by ocxl_mmio_size()
endian the endianness of the stored data (value will be converted to this before storing it)
value the value to write

Return values

OCXL_OK if the value was written
OCXL_NO_CONTEXT if the MMIO area is not mapped
OCXL_OUT_OF_BOUNDS if the offset exceeds the available area

ocxl_err ocxl_mmio_write64 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t value)

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.

Precondition

the AFU has been opened, and the MMIO area mapped

Parameters

mmio the MMIO area to operate on
offset A byte address that is aligned on an 8 byte boundary. It must be lower than the MMIO size (-8 bytes) reported by ocxl_mmio_size()
endian the endianness of the stored data (value will be converted to this before storing it)
value the value to write

Return values

OCXL_OK if the value was written
OCXL_NO_CONTEXT if the MMIO area is not mapped
OCXL_OUT_OF_BOUNDS if the offset exceeds the available area

Author

Generated automatically by Doxygen for libocxl from the source code.

Mon Sep 19 2022 libocxl