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, ACCL::Buffer< int8_t >

Public Functions

inline BaseBuffer(void *byte_array, size_t size, dataType type, addr_t physical_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.

  • physical_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 xrt::bo *bo() = 0

Get internal bo buffer, or nullptr if it does not exists.

Returns

xrt::bo* The internal bo buffer, or nullptr if it does not exists.

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.

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 physical_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::FPGABuffer< dtype >, ACCL::FPGABufferP2P< dtype >, ACCL::SimBuffer< dtype >

Public Functions

inline Buffer(dtype *buffer, size_t length, dataType type, addr_t physical_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.

  • physical_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::FPGABuffer

template<typename dtype>
class FPGABuffer : 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 FPGABuffer(dtype *buffer, addr_t length, dataType type, xrt::device &device, xrt::memory_group mem_grp)

Construct a new FPGABuffer 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.

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

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

Construct a new FPGABuffer 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 FPGABuffer(addr_t length, dataType type, xrt::device &device, xrt::memory_group mem_grp)

Construct a new FPGABuffer object without an existing host pointer.

This constructor will allocate a buffer on both the host and the FPGA.

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 FPGABuffer(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 ~FPGABuffer()

Destroy the FPGABuffer object.

inline virtual xrt::bo *bo() override

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

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

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::FPGABufferP2P

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

A P2P buffer that is allocated on the FPGA and can be accessed from the host without explicit copying.

Template Parameters

dtype – Datatype of the buffer.

Public Functions

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

Construct a new FPGABufferP2P object from an existing P2P BO buffer.

Parameters

  • bo – An existing P2P BO buffer.

  • length – Amount of elements in the P2P buffer.

  • type – ACCL datatype of the P2P buffer.

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

Construct a new FPGABufferP2P object without any existing buffer.

Parameters

  • length – Amount of elements to allocate for.

  • type – ACCL datatype of the P2P buffer.

  • device – Device to allocate the P2P buffer on.

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

inline FPGABufferP2P(xrt::bo bo_, addr_t length, dataType type)

Copy construct of a P2P buffer for internal use only.

inline virtual ~FPGABufferP2P()

Destroy the FPGABufferP2P object.

inline virtual xrt::bo *bo() override

Return the underlying P2P BO buffer.

Returns

xrt::bo* The underlying P2P BO buffer.

inline virtual bool is_simulated() const override

Check if the buffer is simulated, always false.

inline virtual void sync_from_device() override

Sync the data from the device back to the host, which is not required with a P2P buffer, so this function does nothing.

inline virtual void sync_to_device() override

Sync the data from the host to the device, which is not required with a P2P buffer, so this function does nothing.

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.

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)

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.

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)

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.

inline SimBuffer(dtype *buffer, size_t length, dataType type, zmq_intf_context *const context, const addr_t physical_address)

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.

  • physical_address – The physical address of the device buffer.

inline SimBuffer(dtype *buffer, size_t length, dataType type, zmq_intf_context *const context, const addr_t physical_address, xrt::bo &bo, xrt::device &device, bool bo_valid_, 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 virtual xrt::bo *bo() override

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 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 xrt::bo *bo() override

Get internal bo buffer, or nullptr if it does not exists.

Returns

xrt::bo* The internal bo buffer, or nullptr if it does not exists.

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