Programming with DaCS

DaCS API functions

The DaCS library API services are provided as functions in the C language. The protocols and constants required are made available to the compiler by including the DaCS header file dacs.h as:

#include <dacs.h>

In general the return value from these functions is an error code (see Error codes). Data is returned within parameters passed to the functions.

Note: Implementations may provide options, restrictions and error codes that are not specified here.

Note: When more than one error condition is present it is not guaranteed which one will be reported.

Process management model

When working with the host and accelerators there has to be a way to uniquely identify the participants that are communicating. From an architectural perspective, each accelerator could have multiple processes simultaneously running, so it is not enough simply to identify the accelerator. Instead the unit of execution on the accelerator (the DaCS Process) must be identified using its DaCS Element Id (DE id) and its Process Id (Pid). The DE Id is retrieved when the accelerator is reserved (using dacs_reserve_children()) and the Pid when the process is started (using dacs_de_start()). Since the parent is not reserved, and no process is started on it, two constants are provided to identify the parent: DACS_DE_PARENT and DACS_PID_PARENT. Similarly, to identify the calling process itself, the constants DACS_DE_SELF and DACS_PID_SELF are provided.

Resource sharing model

The APIs supporting the locking primitives, remote memory access and groups follow a consistent pattern of creation, sharing, usage and destruction:

Creation: An object is created which will be shared with other DEs, for example with dacs_remote_mem_create().
Sharing: The object created is then shared by linked share and accept calls. The creator shares the item (for instance with dacs_remote_mem_share()), and the DE it is shared with accepts it (in this example with dacs_remote_mem_accept()). These calls must be paired. When one is invoked it waits for the other to occur. This is done for each DE the share is actioned with.
Usage: This may require closure (such as in the case of groups) or the object may immediately be available for use. For instance remote memory can immediately be used for put and get.
Destruction: The DEs that have accepted an item can release the item when they are done with it (for example by calling dacs_remote_mem_release()). The release does not block, but notifies the creator that it is not longer being used and cleans up any local storage. The creator does a destroy (in this case dacs_remote_mem_destroy()) which will wait for all of the DEs it has shared with to release the item, and then destroy the shared item.

API environment

To make these services accessible to the runtime code each process must create a DaCS environment. This is done by calling the special initialization service dacs_runtime_init(). When this service returns the environment is set up so that all other DaCS function calls can be invoked.

When the DaCS environment is no longer required the process must call dacs_runtime_exit() to free all resources used by the environment.

Building a DaCS application

Three versions of the DaCS libraries are provided with the DaCS packages: optimized, debug and traced. The optimized libraries have minimal error checking and are intended for production use. The debug libraries have much more error checking than the optimized libraries and are intended to be used during application development. The traced libraries are the optimized libraries with performance and debug trace hooks in them. These are intended to be used to debug functional and performance problems that might be encountered. The traced libraries use the interfaces provided by the Performance Debug Tool (PDT) and require that this tool be installed. See Performance and debug trace for more information on configuring and using traced libraries.

Both static and shared libraries are provided for the PPU but only static libraries are provided for the SPU. The desired library is selected by linking to the chosen library in the appropriate path. The static library is named libdacs.a, and the shared library is libdacs.so. The locations of these are:

Table 1.
Description	PPU Library Path	SPU Library Path
Optimized	/usr/lib64	/usr/spu/lib
Debug	/usr/lib64/dacs/debug	/usr/spu/lib/dacs/debug
Traced	/usr/lib64/dacs/trace	/usr/spu/lib/dacs/trace