class ara::shwa::Buffer

The class template serves to manage multidimensional memory buffers for Safe Hardware Acceleration in the Adaptive Platform SWS_SafeHardwareAcceleration §7.1 “High Level Design of Safe Hardware Acceleration in an Adaptive Platform”. Because all default, copy, and move operations are deleted, creation takes place exclusively via static factory methods such as [AP_SWS_SHWA_00209] as an exclusively held pointer. Memory can be customized via configurable properties and allocators, while read accesses to properties are not designed to be thread-safe. Failed memory allocations are reported back to the caller via defined error codes.

more ›

Context

In the Adaptive Platform's Safe Hardware Acceleration (SHWA) module, the template class ara::shwa::Buffer forms a central abstraction for encapsulating and managing multidimensional memory regions. As outlined in the system architecture, Adaptive Applications and functional clusters typically interact with a combination of multiple queues (Queues), accelerator devices (Devices), and buffers (SWS_SafeHardwareAcceleration §7.1 “High Level Design of Safe Hardware Acceleration in an Adaptive Platform”). Buffers provide the memory required for acceleration operations at the host or device level, and can optionally be configured using application-specific allocators ([AP_SWS_SHWA_00210]) or host data pointers.

Context diagram: Embedding of the buffer into the functional interaction of applications, devices, queues, and allocators. Sources: SWS_SafeHardwareAcceleration §7.1 “High Level Design of Safe Hardware Acceleration in an Adaptive Platform”, [AP_SWS_SHWA_00210].

Lifecycle

The lifecycle of a buffer instance is subject to strict semantic restrictions. To ensure unambiguous ownership, both the default constructor ([AP_SWS_SHWA_00202]) as well as the copy constructor ([AP_SWS_SHWA_00203]) and copy assignment operator ([AP_SWS_SHWA_00204]) are deleted. Likewise, the move constructor ([AP_SWS_SHWA_00205]) and the move assignment operator ([AP_SWS_SHWA_00206]) are explicitly deleted. Interpretation: This is likely to prevent buffer resources or hardware relationships from being duplicated or moved uncontrollably in memory. Question Q-dcabd66fa9f3ec2a (open)

Creation therefore occurs exclusively via static factory methods of the overload family Create, which return a std::unique_ptr<Buffer> encapsulated in a ara::core::Result on success. Various construction paths are available:

• Creation with buffer region and optional property list: thread-safe ([AP_SWS_SHWA_00209]).
• Creation with buffer region, dedicated allocator, and property list: thread-safe ([AP_SWS_SHWA_00210]).
• Creation based on existing host data pointers with buffer region: thread-safe both for modifiable pointers ([AP_SWS_SHWA_00211]) and for const data pointers ([AP_SWS_SHWA_00213]).
• Creation with const host data pointer, buffer region, and allocator: thread-safe ([AP_SWS_SHWA_00214]).
• Direct creation solely via an allocator: non_threadsafe ([AP_SWS_SHWA_00212]).

Following successful creation, ownership remains with the calling context via std::unique_ptr. Destruction of the object upon expiration of the smart pointer is likely to automatically release the underlying memory region via the respective allocator. Question Q-aa2b5642b8527803 (open)

Usage Path

A typical usage path begins with allocation and initialization of the buffer via one of the thread-safe factory methods such as [AP_SWS_SHWA_00209]. After successful instantiation, the application can verify whether specific properties are set for this buffer by calling HasProperty<PropertyT>() ([AP_SWS_SHWA_00215]). If the desired property is present, its concrete value can be read synchronously via GetProperty<PropertyT>() ([AP_SWS_SHWA_00216]). Note that both HasProperty and GetProperty are declared as non_threadsafe; concurrent queries on the same buffer object must therefore be synchronized on the application side.

Sequence diagram: Typical sequence for instantiation via the factory and subsequent property query. Sources: [AP_SWS_SHWA_00209], [AP_SWS_SHWA_00215], [AP_SWS_SHWA_00216].

Error Scenarios

All factory and inspection methods are declared with noexcept and offer full exception safety (exception safe). Errors are signaled via the ara::core::Result:

• If memory allocation fails on the host or accelerator side during a call to Create, the error ShwaErrorCode::kMemoryNotAllocated is returned ([AP_SWS_SHWA_00209], [AP_SWS_SHWA_00210], [AP_SWS_SHWA_00211], [AP_SWS_SHWA_00212], [AP_SWS_SHWA_00213], [AP_SWS_SHWA_00214]). Here, ShwaErrorCode::kRuntime is defined as the rollback semantics.
• If a property that is not supported by the buffer or the platform is queried via GetProperty<PropertyT>(), the result yields the error code ShwaErrorCode::kFeatureNotSupported ([AP_SWS_SHWA_00216]). To avoid this error, prior checking using HasProperty<PropertyT>() ([AP_SWS_SHWA_00215]) is recommended.