Buffers

Base classes

ACCL::BaseBuffer

class BaseBuffer

Abstract base class of device buffer that doesn’t specify datatype of host buffer.

Subclassed by ACCL::Buffer< dtype >, ACCL::DummyBuffer

Public Functions

inline BaseBuffer(void *byte_array, size_t size, dataType type, addr_t address)

Construct a new Base Buffer object.

Parameters:

  • byte_array – Pointer to the host buffer.

  • size – Size of the host and device buffer in bytes.

  • type – Datatype of the device buffer.

  • address – The location of the device buffer.

inline virtual ~BaseBuffer()

Destroy the Base Buffer object.

virtual void sync_from_device() = 0

Sync the host buffer to the device buffer.

virtual void sync_to_device() = 0

Sync the device buffer to the host buffer.

virtual void free_buffer() = 0

Free the device buffer.

virtual bool is_simulated() const = 0

Check if buffer is an actual fpga buffer, or a simulated buffer.

Returns:

true The buffer is simulated.

Returns:

false The buffer is not simulated.

virtual bool is_host_only() const = 0

Check if buffer is host-only.

Returns:

true The buffer is host-only.

Returns:

false The buffer is not host-only.

inline virtual void sync_bo_to_device()

Sync bo to device if necessary for simulated buffers.

inline virtual void sync_bo_from_device()

Sync bo from device if necessary for simulated buffers.

inline size_t size() const

Get the size of the buffer in bytes.

Returns:

size_t The size of the buffer.

inline dataType type() const

Get the datatype of the device buffer.

Returns:

dataType The datatype of the device buffer.

inline void *byte_array() const

Get the host buffer as void pointer.

Returns:

void* The host buffer as void pointer.

inline addr_t address() const

Get the location of the device buffer.

Returns:

addr_t The location of the device buffer.

virtual std::unique_ptr<BaseBuffer> slice(size_t start, size_t end) = 0

Get a slice of the buffer from start to end.

Parameters:

  • start – Start of the slice.

  • end – End of the slice.

Returns:

BaseBuffer Slice of the buffer from start to end.

ACCL::Buffer

template<typename dtype>
class Buffer : public ACCL::BaseBuffer

Abstract buffer class that specifies the datatype of the host buffer.

Template Parameters:

dtype – The datatype of the host buffer.

Subclassed by ACCL::CoyoteBuffer< dtype >, ACCL::SimBuffer< dtype >, ACCL::XRTBuffer< dtype >

Public Functions

inline Buffer(dtype *buffer, size_t length, dataType type, addr_t address)

Construct a new Buffer object.

Parameters:

  • buffer – The host buffer.

  • length – The length of the host buffer.

  • type – The datatype of the device buffer.

  • address – The location of the device buffer.

inline virtual ~Buffer()

Destroy the Buffer object.

inline size_t length() const

Get the length of the host buffer.

Returns:

size_t The length of the host buffer.

inline dtype *buffer() const

Get the host buffer.

Returns:

dtype* The host buffer.

Hardware buffers

ACCL::XRTBuffer

template<typename dtype>
class XRTBuffer : public ACCL::Buffer<dtype>

A buffer that is allocated on the FPGA with an accompanying host pointer.

The host pointer will be aligned to 4096 bytes. If a non-aligned host pointer is provided, ACCL will keep it’s own aligned host buffer, and copy between the unaligned and aligned host buffers when required. It is recommended to provide an aligned host pointer to avoid unnecessary memory copies.

Template Parameters:

dtype – Datatype of the buffer.

Public Functions

inline XRTBuffer(dtype *buffer, addr_t length, dataType type, xrt::device &device, xrt::bo::flags flags, xrt::memory_group mem_grp)

Construct a new XRTBuffer object from an existing host pointer.

If a non-aligned host pointer is provided, ACCL will keep it’s own aligned host buffer, and copy between the unaligned and aligned host buffers when required. It is recommended to provide an aligned host pointer to avoid unnecessary memory copies.

Parameters:

  • buffer – The host pointer containing the data.

  • length – Amount of elements in the host buffer.

  • type – ACCL datatype of buffer.

  • device – Device to allocate the buffer on.

  • flags – BO flags

  • mem_grp – Memory bank on the device to allocate the buffer on.

inline XRTBuffer(dtype *buffer, addr_t length, dataType type, xrt::device &device, xrt::memory_group mem_grp)

Construct a new device-side XRTBuffer object from an existing host pointer.

Parameters:

  • buffer – The host pointer containing the data.

  • length – Amount of elements in the host buffer.

  • type – ACCL datatype of buffer.

  • device – Device to allocate the buffer on.

  • mem_grp – Memory bank on the device to allocate the buffer on.

inline XRTBuffer(xrt::bo &bo, addr_t length, dataType type)

Construct a new XRTBuffer object from an existing BO buffer.

No new buffer is allocated when using this constructor, instead ACCL will use the existing BO buffer.

Parameters:

  • bo – Existing BO buffer to use.

  • length – Amount of elements to allocate for.

  • type – ACCL datatype of buffer.

inline XRTBuffer(addr_t length, dataType type, xrt::device &device, xrt::bo::flags flags, xrt::memory_group mem_grp)

Construct a new XRTBuffer object without an existing host pointer.

This constructor will allocate on host and/or FPGA depending on flags.

Parameters:

  • length – Amount of elements to allocate the buffers for.

  • type – ACCL datatype of the buffer.

  • device – Device to allocate the FPGA buffer on.

  • flags – BO flags

  • mem_grp – Memory bank of the device to allocate the FPGA buffer on.

inline XRTBuffer(addr_t length, dataType type, xrt::device &device, xrt::memory_group mem_grp)

Construct a new XRTBuffer object on the FPGA without an existing host pointer.

Parameters:

  • length – Amount of elements to allocate the buffers for.

  • type – ACCL datatype of the buffer.

  • device – Device to allocate the FPGA buffer on.

  • mem_grp – Memory bank of the device to allocate the FPGA buffer on.

inline XRTBuffer(xrt::bo bo_, addr_t length, dataType type, bool is_aligned_, dtype *unaligned_buffer_)

Copy construct of an FPGA buffer for internal use only.

inline virtual ~XRTBuffer()

Destroy the XRTBuffer object.

inline xrt::bo *bo()

Return the underlying BO buffer.

Returns:

xrt::bo* The underlying BO buffer.

inline virtual bool is_simulated() const override

Check if the buffer is simulated, always false.

inline virtual bool is_host_only() const override

Check if the buffer is host-only.

inline virtual void sync_from_device() override

Sync the data from the device back to the host.

Will copy the data from the aligned buffer to the unaligned buffer if an unaligned buffer was used during construction of the XRTBuffer.

inline virtual void sync_to_device() override

Sync the data from the host to the device.

Will copy the data from the unaligned buffer to the aligned buffer first if an unaligned buffer was used during construction of the XRTBuffer.

inline virtual void free_buffer() override

Free the device buffer.

inline virtual std::unique_ptr<BaseBuffer> slice(size_t start, size_t end) override

Get a slice of the buffer from start to end.

Parameters:

  • start – Start of the slice.

  • end – End of the slice.

Returns:

BaseBuffer Slice of the buffer from start to end.

ACCL::XRTBufferP2P

Warning

doxygenclass: Cannot find class “ACCL::XRTBufferP2P” in doxygen xml output for project “ACCL” from directory: ../driver/xrt/docs/xml

Simulated buffers

ACCL::SimBuffer

template<typename dtype>
class SimBuffer : public ACCL::Buffer<dtype>

A buffer that is allocated on a external CCLO emulator or simulator with an accompanying host pointer.

Allocated memory on the external CCLO is currently not reused in simulation mode, so when allocating a lot of buffers on the CCLO the host might run out of memory.

It is possible to pass a simulated BO buffer from the Vitis emulator, in this case a new internal BO buffer will also be allocated for copying data between the simulated BO buffer and the simulated ACCL buffer.

Template Parameters:

dtype – Datatype of the buffer.

Public Functions

inline SimBuffer(dtype *buffer, size_t length, dataType type, zmq_intf_context *const context, bool is_host = false, unsigned int memgrp = ACCL_SIM_DEFAULT_BANK)

Construct a new simulated buffer from an existing host buffer.

Parameters:

  • buffer – Host buffer to use.

  • length – Amount of elements in the existing host buffer.

  • type – ACCL datatype of buffer.

  • context – The zmq server of the CCLO to use.

  • is_host – The type of buffer to create.

  • mmegrp – The bank in which to allocate the buffer.

inline SimBuffer(xrt::bo &bo, xrt::device &device, size_t length, dataType type, zmq_intf_context *const context)

Construct a new simulated buffer from a simulated BO buffer.

This will create a new internal BO buffer as well to copy data between the simulated BO buffer and the simulated ACCL buffer.

Parameters:

  • bo – Existing BO buffer to use.

  • length – Amount of elements in the existing BO buffer.

  • type – ACCL datatype of buffer.

  • context – The zmq server of the CCLO to use.

inline SimBuffer(size_t length, dataType type, zmq_intf_context *const context, bool is_host = false, unsigned int memgrp = ACCL_SIM_DEFAULT_BANK)

Construct a new simulated buffer without an existing host pointer.

Parameters:

  • length – Amount of elements to allocate for.

  • type – ACCL datatype of buffer.

  • context – The zmq server of the CCLO to use.

  • is_host – The type of buffer to create.

  • mmegrp – The bank in which to allocate the buffer.

inline SimBuffer(dtype *buffer, size_t length, dataType type, zmq_intf_context *const context, const addr_t address, bool is_host = false, unsigned int memgrp = ACCL_SIM_DEFAULT_BANK)

Construct a new simulated buffer from an existing host pointer at a specific physical address.

You should generally let ACCL itself decide which physical address to use.

Parameters:

  • buffer – Host buffer to use.

  • length – Amount of elements in host pointer.

  • type – ACCL datatype of buffer.

  • context – The zmq server of the CCLO to use.

  • address – The physical address of the device buffer.

  • is_host – The type of buffer to create.

  • mmegrp – The bank in which to allocate the buffer.

inline SimBuffer(dtype *buffer, size_t length, dataType type, zmq_intf_context *const context, const addr_t address, xrt::bo &bo, xrt::device &device, bool bo_valid_, bool is_host, unsigned int memgrp, bool is_slice = false)

Copy construct of a simulated buffer for internal use only.

inline virtual ~SimBuffer()

Destroy the simulated buffer.

Will not free anything on the CCLO.

inline xrt::bo *bo()

Return the underlying BO buffer.

Will only return a BO buffer if the simulated buffer was constructed from an existing BO buffer. Otherwise it will return a nullptr.

Returns:

xrt::bo* The underlying BO buffer if it exists, otherwise a nullptr.

inline virtual bool is_simulated() const override

Check if the buffer is simulated, always true.

inline virtual bool is_host_only() const override

Check if the buffer is host-only, always false in sim.

inline virtual void sync_bo_to_device() override

Sync the user BO buffer to the simulated buffer.

inline virtual void sync_bo_from_device() override

Sync the user BO buffer from the simulated buffer.

inline virtual void sync_from_device() override

Sync the data from the device back to the host.

Will copy the data from the BO buffer to the simulated buffer first if a BO buffer was provided during construction of the simulated buffer.

inline virtual void sync_to_device() override

Sync the data from the host to the device.

Will copy the data from the host buffer to the BO buffer as well if a BO buffer was provided during construction of the simulated buffer.

inline virtual void free_buffer() override

Free the device buffer.

inline virtual std::unique_ptr<BaseBuffer> slice(size_t start, size_t end) override

Get a slice of the buffer from start to end.

Parameters:

  • start – Start of the slice.

  • end – End of the slice.

Returns:

BaseBuffer Slice of the buffer from start to end.

ACCL::DummyBuffer

class DummyBuffer : public ACCL::BaseBuffer

The dummy buffer class represents a non existing buffer.

Used in ACCL for unused buffers in calls.

Public Functions

inline DummyBuffer(addr_t physical_address = 0x0)

Construct a new Dummy Buffer object.

Parameters:

physical_address – Fake address of dummy buffer, 0x0 by default.

inline virtual ~DummyBuffer()

Destroy the Dummy Buffer object.

inline virtual bool is_simulated() const override

Check if buffer is an actual fpga buffer, or a simulated buffer.

Returns:

true The buffer is simulated.

Returns:

false The buffer is not simulated.

inline virtual bool is_host_only() const override

Check if buffer is host-only.

Returns:

true The buffer is host-only.

Returns:

false The buffer is not host-only.

inline virtual void sync_from_device() override

Sync the host buffer to the device buffer.

inline virtual void sync_to_device() override

Sync the device buffer to the host buffer.

inline virtual void free_buffer() override

Free the device buffer.

inline virtual std::unique_ptr<BaseBuffer> slice(size_t start, size_t end) override

Get a slice of the buffer from start to end.

Parameters:

  • start – Start of the slice.

  • end – End of the slice.

Returns:

BaseBuffer Slice of the buffer from start to end.