DOKK / manpages / debian 12 / libocxl-dev / ocxl_afu_open_specific.3.en
ocxl_afu(3) Library Functions Manual ocxl_afu(3)

ocxl_afu - OpenCAPI AFU Management


- These functions provide access to open and close the AFU.


ocxl_err ocxl_afu_open_from_dev (const char *path, ocxl_afu_h *afu)
Open an AFU context at a specified path. ocxl_err ocxl_afu_open_specific (const char *name, const char *physical_function, int16_t afu_index, ocxl_afu_h *afu)
Open an AFU context with a specified name on a specific card/afu index. ocxl_err ocxl_afu_open (const char *name, ocxl_afu_h *afu)
Open an AFU context with a specified name. ocxl_err ocxl_afu_attach (ocxl_afu_h afu, __attribute__((unused)) uint64_t flags)
Attach the calling process's memory to an open AFU context. ocxl_err ocxl_afu_close (ocxl_afu_h afu)
Close an AFU and detach it from the context.

These functions provide access to open and close the AFU.

A typical workflow involves the following:

  • ocxl_afu_open_from_dev(), ocxl_afu_open() - Open the device by device or name
  • ocxl_afu_attach() - Attach the device to the process's address space
  • ocxl_mmio_map() - Map the MMIO space

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)

Finally, to free the AFU handle, you can use ocxl_afu_close().

ocxl_err ocxl_afu_attach (ocxl_afu_h afu, __attribute__((unused)) uint64_t flags)

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.

If specified, also sets the value of the PPC specific PSL AMR.

Precondition

the AFU is opened

Parameters

afu the AFU to attach
flags An ORed bitmask of flags OCXL_ATTACH_FLAGS_NONE accept the default behavior

Return values

OCXL_OK if the AFU was successful attached
OCXL_NO_CONTEXT if the AFU was not opened
OCXL_INTERNAL_ERROR if the AFU was unable to attach (check dmesg)

ocxl_err ocxl_afu_close (ocxl_afu_h afu)

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.

Parameters

afu a pointer to the AFU handle we want to close

Return values

OCXL_OK if the AFU was freed
OCXL_ALREADY_DONE if the AFU was not open

Postcondition

All resources associated with the handle are closed and freed, the handle is no longer usable

ocxl_err ocxl_afu_open (const char * name, ocxl_afu_h * afu)

Open an AFU context with a specified name.

Parameters

name the name of the AFU
afu the AFU handle which we will allocate. This should be freed with ocxl_afu_close

Return values

OCXL_OK if we have successfully fetched the AFU
OCXL_NO_MEM if an out of memory error occurred
OCXL_NO_DEV if no valid device was found
OCXL_NO_MORE_CONTEXTS if maximum number of AFU contexts has been reached on all matching AFUs

ocxl_err ocxl_afu_open_from_dev (const char * path, ocxl_afu_h * afu)

Open an AFU context at a specified path.

Parameters

path the path of the AFU
afu the AFU handle which we will allocate. This should be freed with ocxl_afu_close

Return values

OCXL_OK if we have successfully fetched the AFU
OCXL_NO_MEM if an out of memory error occurred
OCXL_NO_DEV if the device is invalid
OCXL_NO_MORE_CONTEXTS if maximum number of AFU contexts has been reached

ocxl_err ocxl_afu_open_specific (const char * name, const char * physical_function, int16_t afu_index, ocxl_afu_h * afu)

Open an AFU context with a specified name on a specific card/afu index.

Parameters

name the name of the AFU
physical_function the PCI physical function of the card (as a string, or NULL for any)
afu_index the AFU index (or -1 for any)
afu the AFU handle which we will allocate. This should be freed with ocxl_afu_close

Return values

OCXL_OK if we have successfully fetched the AFU
OCXL_NO_MEM if an out of memory error occurred
OCXL_NO_DEV if no valid device was found
OCXL_NO_MORE_CONTEXTS if maximum number of AFU contexts has been reached on all matching AFUs

Generated automatically by Doxygen for libocxl from the source code.

Mon Sep 19 2022 libocxl