Interface for standardising the API for any Accelerator device: XRTAccelerator. More...

#include <accelerator.hpp>

Inheritance diagram for cynq::IAccelerator:

Public Types
enum	Type { None = 0 , MMIO , XRT }
	Type Type of runtime supported by the IAccelerator. More...

Public Member Functions
virtual	~IAccelerator ()=default
	~IAccelerator destructor method Destroy the IAccelerator object.

virtual Status	Start (const StartMode mode)=0
	Start method This method starts the accelerator in either once or continuous mode (with the autorestart). Under the hood, this writes the control register to turn on the accelerator with/without the autorestart bit. More...

virtual Status	Start (std::shared_ptr< IExecutionGraph > graph, const StartMode mode)
	Start method (asynchronous) Please, refer to IAccelerator::Start for reference. This overload performs an asynchronous execution of the function based on a graph of operations. It returns as soon as the operation is scheduled. More...

virtual Status	Stop ()=0
	Stop method This asynchronously turns off the accelerator by removing the autorestart and start bits from the control registers. Please, note that the accelerator will turn off once it finishes its current task. More...

virtual Status	Stop (std::shared_ptr< IExecutionGraph > graph)
	Stop method (asynchronous) Please, refer to IAccelerator::Stop for reference. This overload performs an asynchronous execution of the function based on a graph of operations. It returns as soon as the operation is scheduled. More...

virtual Status	Sync ()=0
	Sync method This synchronises the execution and wait until the kernel/accelerator finishes its execution. More...

virtual Status	Sync (std::shared_ptr< IExecutionGraph > graph)
	Sync method (asynchronous) Please, refer to IAccelerator::Sync for reference. This overload performs an asynchronous execution of the function based on a graph of operations. It returns as soon as the operation is scheduled. More...

virtual DeviceStatus	GetStatus ()=0
	GetStatus method This returns the accelerator state by using the DeviceStatus. This reads the control register flags. More...

template<typename T >
Status	Write (const uint64_t address, const T *data, const size_t elements=1)
	Write method Performs a write operation to the accelerator through a register. More...

template<typename T >
Status	Write (std::shared_ptr< IExecutionGraph > graph, const uint64_t address, const T *data, const size_t elements=1)
	Write method (asynchronous) Performs a write operation to the accelerator through a register in an execution graph. It returns as soon as the instruction is scheduled. More...

template<typename T >
Status	Read (const uint64_t address, T *data, const size_t elements=1)
	Read method Performs a write operation to the accelerator through a register. More...

template<typename T >
Status	Read (std::shared_ptr< IExecutionGraph > graph, const uint64_t address, T *data, const size_t elements=1)
	Read method (asynchronous) Performs a write operation to the accelerator through a register in an execution graph. It returns as soon as the instruction is scheduled. More...

virtual int	GetMemoryBank (const uint pos)=0
	Get the memory bank ID. More...

template<typename T >
Status	Attach (const uint64_t index, T *data, const RegisterAccess access=RegisterAccess::WO, const size_t elements=1)
	Attach an argument Performs an attachment of the argument and the respective pointer. If the index/address to attach receives a nullptr, it gets detached. More...

template<typename T >
Status	Attach (const uint64_t index, T *data, const size_t elements, const RegisterAccess access=RegisterAccess::WO)
	Overload of the Attach<T>() More...

virtual Status	Attach (const uint64_t addr, std::shared_ptr< IMemory > mem)=0
	Attach a memory argument Performs an attachment of the argument and the respective pointer. The use of this overload for IMemory buffers is highly recommended. More...

Static Public Member Functions
static std::shared_ptr< IAccelerator >	Create (IAccelerator::Type impl, const uint64_t addr)
	Create method Factory method used for creating specific subclasses of IAccelerator. More...

static std::shared_ptr< IAccelerator >	Create (IAccelerator::Type impl, const std::string &kernelname, const std::shared_ptr< HardwareParameters > hwparams)
	Create method (overload) Factory method used for creating specific subclasses of IAccelerator. More...

Protected Member Functions
virtual Status	WriteRegister (const uint64_t address, const uint8_t *data, const size_t size)=0
	Opaque Write Register method Writes to the register of the accelerator. More...

virtual Status	ReadRegister (const uint64_t address, uint8_t *data, const size_t size)=0
	Opaque Read Register method. More...

virtual Status	WriteRegister (std::shared_ptr< IExecutionGraph > graph, const uint64_t address, const uint8_t *data, const size_t size)
	Write Register method (asynchronous) More...

virtual Status	ReadRegister (std::shared_ptr< IExecutionGraph > graph, const uint64_t address, uint8_t *data, const size_t size)
	Read Register method (asynchronous) More...

virtual Status	AttachRegister (const uint64_t index, uint8_t *data, const RegisterAccess access, const size_t size)=0
	Opaque Attach Register method. More...

Detailed Description

Interface for standardising the API for any Accelerator device: XRTAccelerator.

Member Enumeration Documentation

◆ Type

enum cynq::IAccelerator::Type

Type Type of runtime supported by the IAccelerator.

Enumerator
None	No runtime
MMIO	MMIO runtime: compatible with ZYNQ and Vivado workflows
XRT	XRT kernel runtime: compatible with Vitis and Alveo workflows

Member Function Documentation

◆ Attach() [1/3]

virtual Status cynq::IAccelerator::Attach	(	const uint64_t	addr,
		std::shared_ptr< IMemory >	mem
	)

pure virtual

Attach a memory argument Performs an attachment of the argument and the respective pointer. The use of this overload for IMemory buffers is highly recommended.

Parameters

addr	Argument address to set the memory address. In the case of Alveo or Vitis-based workflows, it is the argument index.
mem	Memory buffer to attach to the argument

Returns: Status

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ Attach() [2/3]

template<typename T >

Status cynq::IAccelerator::Attach	(	const uint64_t	index,
		T *	data,
		const RegisterAccess	access = `RegisterAccess::WO`,
		const size_t	elements = `1`
	)

inline

Attach an argument Performs an attachment of the argument and the respective pointer. If the index/address to attach receives a nullptr, it gets detached.

Template Parameters

T	Datatype used as the individual unit of information being written to the device.

Parameters

index	Argument position/address (Ultrascale) of the argument to set
data	Raw pointer of type T used by the register to access the data. The ownership is borrowed and its existence must be guaranteed.
access	Access type of the register (read-only, write-only, read-write). Defaults to Write-Only (autodetected and unused in Alveo or Vitis-based).
elements	Number of elements being written to the device. Defaults to one

Returns: Status

◆ Attach() [3/3]

template<typename T >

Status cynq::IAccelerator::Attach	(	const uint64_t	index,
		T *	data,
		const size_t	elements,
		const RegisterAccess	access = `RegisterAccess::WO`
	)

inline

Overload of the Attach<T>()

See Attach()

◆ AttachRegister()

virtual Status cynq::IAccelerator::AttachRegister	(	const uint64_t	index,
		uint8_t *	data,
		const RegisterAccess	access,
		const size_t	size
	)

protectedpure virtual

Opaque Attach Register method.

Parameters

index	index of the argument to set
data	a pointer to an unsigned 8 bits variable which holds the data to read from the register.
access	Access type of the register (read-only, write-only, read-write).
size	size in bytes of the data to read.

Returns: Status

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ Create() [1/2]

std::shared_ptr< IAccelerator > cynq::IAccelerator::Create	(	IAccelerator::Type	impl,
		const std::string &	kernelname,
		const std::shared_ptr< HardwareParameters >	hwparams
	)

static

Create method (overload) Factory method used for creating specific subclasses of IAccelerator.

Parameters

impl	Used for establishing if the object is dependent on a runtime, use None if this is not the case.
kernelname	Name of the kernel in case of using XRT runtime and the Vitis workflow. Use this factory only in case of being in a ZYNQ with Vitis workflow or in the Alveo.
hwparams	Hardware parameters required for creating the accelerator

Returns: std::shared_ptr<IAccelerator> This is a shared_ptr with reference counting, the type will depend on the value of impl, the options are the following: XRT -> XRTAccelerator None -> nullptr

◆ Create() [2/2]

std::shared_ptr< IAccelerator > cynq::IAccelerator::Create	(	IAccelerator::Type	impl,
		const uint64_t	addr
	)

static

Create method Factory method used for creating specific subclasses of IAccelerator.

Parameters

impl	Used for establishing if the object is dependent on a runtime, use None if this is not the case.
addr	A 64 bit unsigned integer establishing the address from which the address space of the accelerator starts.

Returns: std::shared_ptr<IAccelerator> This is a shared_ptr with reference counting, the type will depend on the value of impl, the options are the following: XRT -> XRTAccelerator MMIO -> MMIOAccelerator None -> nullptr

◆ GetMemoryBank()

virtual int cynq::IAccelerator::GetMemoryBank ( const uint pos )

pure virtual

Get the memory bank ID.

It corresponds to the argument memory argument for affinity. It is useful for assigning memory banks to the DataMovers before requesting any memory.

It is only used by Vitis and Alveo workflows

Parameters

pos	memory bank position within the kernel

Returns: the memory bank

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ GetStatus()

virtual DeviceStatus cynq::IAccelerator::GetStatus ( )

pure virtual

GetStatus method This returns the accelerator state by using the DeviceStatus. This reads the control register flags.

Returns: DeviceStatus

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ Read() [1/2]

template<typename T >

Status cynq::IAccelerator::Read	(	const uint64_t	address,
		T *	data,
		const size_t	elements = `1`
	)

inline

Read method Performs a write operation to the accelerator through a register.

Template Parameters

T	Datatype used as the individual unit of information being read from the device.

Parameters

address	Address of the accelerator.
data	Raw pointer of type T used by the register to access the data.
elements	Number of elements being read from the device. Defaults to one

Returns: Status

◆ Read() [2/2]

template<typename T >

Status cynq::IAccelerator::Read	(	std::shared_ptr< IExecutionGraph >	graph,
		const uint64_t	address,
		T *	data,
		const size_t	elements = `1`
	)

inline

Read method (asynchronous) Performs a write operation to the accelerator through a register in an execution graph. It returns as soon as the instruction is scheduled.

Template Parameters

T	Datatype used as the individual unit of information being read from the device.

Parameters

graph	Execution graph to execute on. If nullptr is passed, the execution will be synchronous.
address	Address of the accelerator.
data	Raw pointer of type T used by the register to access the data.
elements	Number of elements being read from the device. Defaults to one

Returns: Status. It fills the retval field with the NodeID within the execution graph

◆ ReadRegister() [1/2]

virtual Status cynq::IAccelerator::ReadRegister	(	const uint64_t	address,
		uint8_t *	data,
		const size_t	size
	)

protectedpure virtual

Opaque Read Register method.

Parameters

address	an unsigned integer of 64 bits representing an address.
data	a pointer to an unsigned 8 bits variable which holds the data to read from the register.
size	size in bytes of the data to read.

Returns: Status

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ ReadRegister() [2/2]

Status cynq::IAccelerator::ReadRegister	(	std::shared_ptr< IExecutionGraph >	graph,
		const uint64_t	address,
		uint8_t *	data,
		const size_t	size
	)

protectedvirtual

Read Register method (asynchronous)

Parameters

graph	Execution graph to execute on. If nullptr is passed, the execution will be synchronous.
address	an unsigned integer of 64 bits representing an address.
data	a pointer to an unsigned 8 bits variable which holds the data to read from the register.
size	size in bytes of the data to read.

Returns: Status

◆ Start() [1/2]

virtual Status cynq::IAccelerator::Start ( const StartMode mode )

pure virtual

Start method This method starts the accelerator in either once or continuous mode (with the autorestart). Under the hood, this writes the control register to turn on the accelerator with/without the autorestart bit.

Parameters

mode	One of the values in the StartMode enum class present in the enums.hpp file.

Returns: Status

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ Start() [2/2]

Status cynq::IAccelerator::Start	(	std::shared_ptr< IExecutionGraph >	graph,
		const StartMode	mode
	)

virtual

Start method (asynchronous) Please, refer to IAccelerator::Start for reference. This overload performs an asynchronous execution of the function based on a graph of operations. It returns as soon as the operation is scheduled.

Parameters

mode	One of the values in the StartMode enum class present in the enums.hpp file.
graph	Execution graph to execute on. If nullptr is passed, the execution will be synchronous.

Returns: Status. It fills the retval field with the NodeID of the execution graph.

◆ Stop() [1/2]

virtual Status cynq::IAccelerator::Stop ( )

pure virtual

Stop method This asynchronously turns off the accelerator by removing the autorestart and start bits from the control registers. Please, note that the accelerator will turn off once it finishes its current task.

Returns: Status

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ Stop() [2/2]

Status cynq::IAccelerator::Stop ( std::shared_ptr< IExecutionGraph > graph )

virtual

Stop method (asynchronous) Please, refer to IAccelerator::Stop for reference. This overload performs an asynchronous execution of the function based on a graph of operations. It returns as soon as the operation is scheduled.

Parameters

graph Execution graph to execute on. If nullptr is passed, the execution will be synchronous.

Returns: Status. It fills the retval field with the NodeID of the execution graph.

◆ Sync() [1/2]

virtual Status cynq::IAccelerator::Sync ( )

pure virtual

Sync method This synchronises the execution and wait until the kernel/accelerator finishes its execution.

Returns: Status

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ Sync() [2/2]

Status cynq::IAccelerator::Sync ( std::shared_ptr< IExecutionGraph > graph )

virtual

Sync method (asynchronous) Please, refer to IAccelerator::Sync for reference. This overload performs an asynchronous execution of the function based on a graph of operations. It returns as soon as the operation is scheduled.

Parameters

graph Execution graph to execute on. If nullptr is passed, the execution will be synchronous.

Returns: Status. It fills the retval field with the NodeID of the execution graph.

◆ Write() [1/2]

template<typename T >

Status cynq::IAccelerator::Write	(	const uint64_t	address,
		const T *	data,
		const size_t	elements = `1`
	)

inline

Write method Performs a write operation to the accelerator through a register.

Template Parameters

T	Datatype used as the individual unit of information being written to the device.

Parameters

address	Address of the accelerator.
data	Raw pointer of type T used by the register to access the data.
elements	Number of elements being written to the device. Defaults to one

Returns: Status

◆ Write() [2/2]

template<typename T >

Status cynq::IAccelerator::Write	(	std::shared_ptr< IExecutionGraph >	graph,
		const uint64_t	address,
		const T *	data,
		const size_t	elements = `1`
	)

inline

Write method (asynchronous) Performs a write operation to the accelerator through a register in an execution graph. It returns as soon as the instruction is scheduled.

Template Parameters

T	Datatype used as the individual unit of information being written to the device.

Parameters

graph	Execution graph to execute on. If nullptr is passed, the execution will be synchronous.
address	Address of the accelerator.
data	Raw pointer of type T used by the register to access the data.
elements	Number of elements being written to the device. Defaults to one

Returns: Status. It fills the retval field with the NodeID within the execution graph

◆ WriteRegister() [1/2]

virtual Status cynq::IAccelerator::WriteRegister	(	const uint64_t	address,
		const uint8_t *	data,
		const size_t	size
	)

protectedpure virtual

Opaque Write Register method Writes to the register of the accelerator.

Parameters

address	an unsigned integer of 64 bits representing an address.
data	a pointer to an unsigned 8 bits variable which holds the data to write to the register.
size	size in bytes of the data to write.

Returns: Status

Implemented in cynq::XRTAccelerator, and cynq::MMIOAccelerator.

◆ WriteRegister() [2/2]

Status cynq::IAccelerator::WriteRegister	(	std::shared_ptr< IExecutionGraph >	graph,
		const uint64_t	address,
		const uint8_t *	data,
		const size_t	size
	)

protectedvirtual

Write Register method (asynchronous)

Parameters

graph	Execution graph to execute on. If nullptr is passed, the execution will be synchronous.
address	an unsigned integer of 64 bits representing an address.
data	a pointer to an unsigned 8 bits variable which holds the data to write to the register.
size	size in bytes of the data to write.

Returns: Status

The documentation for this class was generated from the following files:

/mnt/usbkey/lleon/cynq/include/cynq/accelerator.hpp
/mnt/usbkey/lleon/cynq/src/cynq/accelerator.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ Type

Member Function Documentation

◆ Attach() [1/3]

◆ Attach() [2/3]

◆ Attach() [3/3]

◆ AttachRegister()

◆ Create() [1/2]

◆ Create() [2/2]

◆ GetMemoryBank()

◆ GetStatus()

◆ Read() [1/2]

◆ Read() [2/2]

◆ ReadRegister() [1/2]

◆ ReadRegister() [2/2]

◆ Start() [1/2]

◆ Start() [2/2]

◆ Stop() [1/2]

◆ Stop() [2/2]

◆ Sync() [1/2]

◆ Sync() [2/2]

◆ Write() [1/2]

◆ Write() [2/2]

◆ WriteRegister() [1/2]

◆ WriteRegister() [2/2]