OpenCAPI AFU Management

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

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

Detailed Description

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

Function Documentation

ocxl_afu_attach()

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)

Definition at line 654 of file afu.c.

ocxl_afu_close()

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

Definition at line 692 of file afu.c.

ocxl_afu_open()

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
[out]	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

Definition at line 631 of file afu.c.

ocxl_afu_open_from_dev()

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
[out]	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

Definition at line 528 of file afu.c.

ocxl_afu_open_specific()

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)
[out]	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

Definition at line 562 of file afu.c.