File buffer.h¶

FileList > docs > sw > include > opae > buffer.h

Functions for allocating and sharing system memory with an FPGA accelerator. More...

#include <opae/types.h>

Public Functions¶

Type	Name
fpga_result	fpgaGetIOAddress (fpga_handle handle, uint64_t wsid, uint64_t * ioaddr) Retrieve base IO address for buffer.
fpga_result	fpgaPrepareBuffer (fpga_handle handle, uint64_t len, void ** buf_addr, uint64_t * wsid, int flags) Prepare a shared memory buffer.
fpga_result	fpgaReleaseBuffer (fpga_handle handle, uint64_t wsid) Release a shared memory buffer.

Detailed Description¶

To share memory between a software application and an FPGA accelerator, these functions set up system components (e.g. an IOMMU) to allow accelerator access to a provided memory region.

There are a number of restrictions on what memory can be shared, depending on platform capabilities. Usually, FPGA accelerators to not have access to virtual address mappings of the CPU, so they can only access physical addresses. To support this, the OPAE C library on Linux uses hugepages to allocate large, contiguous pages of physical memory that can be shared with an accelerator. It also supports sharing memory that has already been allocated by an application, as long as that memory satisfies the requirements of being physically contigous and page-aligned.

Public Functions Documentation¶

function fpgaGetIOAddress¶

Retrieve base IO address for buffer.

fpga_result fpgaGetIOAddress (
    fpga_handle handle,
    uint64_t wsid,
    uint64_t * ioaddr
)

This function is used to acquire the physical base address (on some platforms called IO Virtual Address or IOVA) for a shared buffer identified by wsid.

Note:

This function will disappear once the APIs for secure sharing of buffer addresses is implemented.

Parameters:

handle Handle to previously opened accelerator resource
wsid Buffer handle / workspace ID referring to the buffer for which the IO address is requested
ioaddr Pointer to memory where the IO address will be returned

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if invalid parameters were provided, or if the parameter combination is not valid. FPGA_EXCEPTION if an internal exception occurred while trying to access the handle. FPGA_NOT_FOUND if wsid does not refer to a previously shared buffer.

function fpgaPrepareBuffer¶

Prepare a shared memory buffer.

fpga_result fpgaPrepareBuffer (
    fpga_handle handle,
    uint64_t len,
    void ** buf_addr,
    uint64_t * wsid,
    int flags
)

Prepares a memory buffer for shared access between an accelerator and the calling process. This may either include allocation of physical memory, or preparation of already allocated memory for sharing. The latter case is indicated by supplying the FPGA_BUF_PREALLOCATED flag.

This function will ask the driver to pin the indicated memory (make it non-swappable), and program the IOMMU to allow access from the accelerator. If the buffer was not pre-allocated (flag FPGA_BUF_PREALLOCATED), the function will also allocate physical memory of the requested size and map the memory into the caller's process' virtual address space. It returns in 'wsid' an fpga_buffer object that can be used to program address registers in the accelerator for shared access to the memory.

When using FPGA_BUF_PREALLOCATED, the input len must be a non-zero multiple of the page size, else the function returns FPGA_INVALID_PARAM. When not using FPGA_BUF_PREALLOCATED, the input len is rounded up to the nearest multiple of page size.

Parameters:

handle Handle to previously opened accelerator resource
len Length of the buffer to allocate/prepare in bytes
buf_addr Virtual address of buffer. Contents may be NULL (OS will choose mapping) or non-NULL (OS will take contents as a hint for the virtual address).
wsid Handle to the allocated/prepared buffer to be used with other functions
flags Flags. FPGA_BUF_PREALLOCATED indicates that memory pointed at in '*buf_addr' is already allocated an mapped into virtual memory. FPGA_BUF_READ_ONLY pins pages with only read access from the FPGA.

Returns:

FPGA_OK on success. FPGA_NO_MEMORY if the requested memory could not be allocated. FPGA_INVALID_PARAM if invalid parameters were provided, or if the parameter combination is not valid. FPGA_EXCEPTION if an internal exception occurred while trying to access the handle.

Note:

As a special case, when FPGA_BUF_PREALLOCATED is present in flags, if len == 0 and buf_addr == NULL, then the function returns FPGA_OK if pre-allocated buffers are supported. In this case, a return value other than FPGA_OK indicates that pre-allocated buffers are not supported.

function fpgaReleaseBuffer¶

Release a shared memory buffer.

fpga_result fpgaReleaseBuffer (
    fpga_handle handle,
    uint64_t wsid
)

Releases a previously prepared shared buffer. If the buffer was allocated using fpgaPrepareBuffer (FPGA_BUF_PREALLOCATED was not specified), this call will deallocate/free that memory. Otherwise, it will only be returned to it's previous state (pinned/unpinned, cached/non-cached).

Parameters:

handle Handle to previously opened accelerator resource
wsid Handle to the allocated/prepared buffer

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if invalid parameters were provided, or if the parameter combination is not valid. FPGA_EXCEPTION if an internal exception occurred while trying to access the handle.

The documentation for this class was generated from the following file docs/sw/include/opae/buffer.h