StarPU Handbook
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
starpu_data_interfaces.h File Reference
#include <starpu.h>
#include <cuda_runtime.h>

Go to the source code of this file.

Data Structures

struct  starpu_data_copy_methods
struct  starpu_data_interface_ops
struct  starpu_matrix_interface
struct  starpu_coo_interface
struct  starpu_block_interface
struct  starpu_vector_interface
struct  starpu_variable_interface
struct  starpu_csr_interface
struct  starpu_bcsr_interface
struct  starpu_multiformat_data_interface_ops
struct  starpu_multiformat_interface

Macros

#define STARPU_MULTIFORMAT_GET_CPU_PTR(interface)
#define STARPU_MULTIFORMAT_GET_CUDA_PTR(interface)
#define STARPU_MULTIFORMAT_GET_OPENCL_PTR(interface)
#define STARPU_MULTIFORMAT_GET_MIC_PTR(interface)
#define STARPU_MULTIFORMAT_GET_NX(interface)
Accessing COO Data Interfaces
#define STARPU_COO_GET_COLUMNS(interface)
#define STARPU_COO_GET_COLUMNS_DEV_HANDLE(interface)
#define STARPU_COO_GET_ROWS(interface)
#define STARPU_COO_GET_ROWS_DEV_HANDLE(interface)
#define STARPU_COO_GET_VALUES(interface)
#define STARPU_COO_GET_VALUES_DEV_HANDLE(interface)
#define STARPU_COO_GET_OFFSET
#define STARPU_COO_GET_NX(interface)
#define STARPU_COO_GET_NY(interface)
#define STARPU_COO_GET_NVALUES(interface)
#define STARPU_COO_GET_ELEMSIZE(interface)

Typedefs

typedef cudaStream_t starpu_cudaStream_t

Enumerations

enum  starpu_data_interface_id {
  STARPU_UNKNOWN_INTERFACE_ID, STARPU_MATRIX_INTERFACE_ID, STARPU_BLOCK_INTERFACE_ID, STARPU_VECTOR_INTERFACE_ID,
  STARPU_CSR_INTERFACE_ID, STARPU_BCSR_INTERFACE_ID, STARPU_VARIABLE_INTERFACE_ID, STARPU_VOID_INTERFACE_ID,
  STARPU_MULTIFORMAT_INTERFACE_ID, STARPU_COO_INTERFACE_ID, STARPU_MAX_INTERFACE_ID
}

Functions

void starpu_multiformat_data_register (starpu_data_handle_t *handle, int home_node, void *ptr, uint32_t nobjects, struct starpu_multiformat_data_interface_ops *format_ops)
Defining Interface

Applications can provide their own interface as shown in Defining A New Data Interface.

int starpu_interface_copy (uintptr_t src, size_t src_offset, unsigned src_node, uintptr_t dst, size_t dst_offset, unsigned dst_node, size_t size, void *async_data)
uintptr_t starpu_malloc_on_node_flags (unsigned dst_node, size_t size, int flags)
uintptr_t starpu_malloc_on_node (unsigned dst_node, size_t size)
void starpu_free_on_node_flags (unsigned dst_node, uintptr_t addr, size_t size, int flags)
void starpu_free_on_node (unsigned dst_node, uintptr_t addr, size_t size)
void starpu_malloc_on_node_set_default_flags (unsigned node, int flags)
int starpu_data_interface_get_next_id (void)
Basic Data Management API

Data management is done at a high-level in StarPU: rather than accessing a mere list of contiguous buffers, the tasks may manipulate data that are described by a high-level construct which we call data interface.

An example of data interface is the "vector" interface which describes a contiguous data array on a spefic memory node. This interface is a simple structure containing the number of elements in the array, the size of the elements, and the address of the array in the appropriate address space (this address may be invalid if there is no valid copy of the array in the memory node). More informations on the data interfaces provided by StarPU are given in Data Interfaces.

When a piece of data managed by StarPU is used by a task, the task implementation is given a pointer to an interface describing a valid copy of the data that is accessible from the current processing unit.

Every worker is associated to a memory node which is a logical abstraction of the address space from which the processing unit gets its data. For instance, the memory node associated to the different CPU workers represents main memory (RAM), the memory node associated to a GPU is DRAM embedded on the device. Every memory node is identified by a logical index which is accessible from the function starpu_worker_get_memory_node(). When registering a piece of data to StarPU, the specified memory node indicates where the piece of data initially resides (we also call this memory node the home node of a piece of data).

void starpu_data_register (starpu_data_handle_t *handleptr, int home_node, void *data_interface, struct starpu_data_interface_ops *ops)
void starpu_data_ptr_register (starpu_data_handle_t handle, unsigned node)
void starpu_data_register_same (starpu_data_handle_t *handledst, starpu_data_handle_t handlesrc)
starpu_data_handle_t starpu_data_lookup (const void *ptr)
Accessing Data Interfaces

Each data interface is provided with a set of field access functions. The ones using a void * parameter aimed to be used in codelet implementations (see for example the code in Vector Scaling Using StarPU's API).

void * starpu_data_handle_to_pointer (starpu_data_handle_t handle, unsigned node)
void * starpu_data_get_local_ptr (starpu_data_handle_t handle)
enum starpu_data_interface_id starpu_data_get_interface_id (starpu_data_handle_t handle)
int starpu_data_pack (starpu_data_handle_t handle, void **ptr, starpu_ssize_t *count)
int starpu_data_unpack (starpu_data_handle_t handle, void *ptr, size_t count)
size_t starpu_data_get_size (starpu_data_handle_t handle)
Registering Data

There are several ways to register a memory region so that it can be managed by StarPU. The functions below allow the registration of vectors, 2D matrices, 3D matrices as well as BCSR and CSR sparse matrices.

void * starpu_data_get_interface_on_node (starpu_data_handle_t handle, unsigned memory_node)
void starpu_matrix_data_register (starpu_data_handle_t *handle, int home_node, uintptr_t ptr, uint32_t ld, uint32_t nx, uint32_t ny, size_t elemsize)
void starpu_matrix_ptr_register (starpu_data_handle_t handle, unsigned node, uintptr_t ptr, uintptr_t dev_handle, size_t offset, uint32_t ld)
void starpu_coo_data_register (starpu_data_handle_t *handleptr, int home_node, uint32_t nx, uint32_t ny, uint32_t n_values, uint32_t *columns, uint32_t *rows, uintptr_t values, size_t elemsize)
void starpu_block_data_register (starpu_data_handle_t *handle, int home_node, uintptr_t ptr, uint32_t ldy, uint32_t ldz, uint32_t nx, uint32_t ny, uint32_t nz, size_t elemsize)
void starpu_block_ptr_register (starpu_data_handle_t handle, unsigned node, uintptr_t ptr, uintptr_t dev_handle, size_t offset, uint32_t ldy, uint32_t ldz)
void starpu_vector_data_register (starpu_data_handle_t *handle, int home_node, uintptr_t ptr, uint32_t nx, size_t elemsize)
void starpu_vector_ptr_register (starpu_data_handle_t handle, unsigned node, uintptr_t ptr, uintptr_t dev_handle, size_t offset)
void starpu_variable_data_register (starpu_data_handle_t *handle, int home_node, uintptr_t ptr, size_t size)
void starpu_variable_ptr_register (starpu_data_handle_t handle, unsigned node, uintptr_t ptr, uintptr_t dev_handle, size_t offset)
void starpu_void_data_register (starpu_data_handle_t *handle)
void starpu_csr_data_register (starpu_data_handle_t *handle, int home_node, uint32_t nnz, uint32_t nrow, uintptr_t nzval, uint32_t *colind, uint32_t *rowptr, uint32_t firstentry, size_t elemsize)
void starpu_bcsr_data_register (starpu_data_handle_t *handle, int home_node, uint32_t nnz, uint32_t nrow, uintptr_t nzval, uint32_t *colind, uint32_t *rowptr, uint32_t firstentry, uint32_t r, uint32_t c, size_t elemsize)

Variables

struct starpu_data_interface_ops starpu_interface_matrix_ops
struct starpu_data_interface_ops starpu_interface_coo_ops
struct starpu_data_interface_ops starpu_interface_block_ops
struct starpu_data_interface_ops starpu_interface_vector_ops
struct starpu_data_interface_ops starpu_interface_variable_ops
struct starpu_data_interface_ops starpu_interface_void_ops
struct starpu_data_interface_ops starpu_interface_csr_ops
struct starpu_data_interface_ops starpu_interface_bcsr_ops

Accessing Variable Data Interfaces

#define STARPU_VARIABLE_GET_PTR(interface)
#define STARPU_VARIABLE_GET_OFFSET(interface)
#define STARPU_VARIABLE_GET_ELEMSIZE(interface)
#define STARPU_VARIABLE_GET_DEV_HANDLE(interface)
size_t starpu_variable_get_elemsize (starpu_data_handle_t handle)
uintptr_t starpu_variable_get_local_ptr (starpu_data_handle_t handle)

Accessing Vector Data Interfaces

#define STARPU_VECTOR_GET_PTR(interface)
#define STARPU_VECTOR_GET_DEV_HANDLE(interface)
#define STARPU_VECTOR_GET_OFFSET(interface)
#define STARPU_VECTOR_GET_NX(interface)
#define STARPU_VECTOR_GET_ELEMSIZE(interface)
#define STARPU_VECTOR_GET_SLICE_BASE(interface)
uint32_t starpu_vector_get_nx (starpu_data_handle_t handle)
size_t starpu_vector_get_elemsize (starpu_data_handle_t handle)
uintptr_t starpu_vector_get_local_ptr (starpu_data_handle_t handle)

Accessing Matrix Data Interfaces

#define STARPU_MATRIX_GET_PTR(interface)
#define STARPU_MATRIX_GET_DEV_HANDLE(interface)
#define STARPU_MATRIX_GET_OFFSET(interface)
#define STARPU_MATRIX_GET_NX(interface)
#define STARPU_MATRIX_GET_NY(interface)
#define STARPU_MATRIX_GET_LD(interface)
#define STARPU_MATRIX_GET_ELEMSIZE(interface)
uint32_t starpu_matrix_get_nx (starpu_data_handle_t handle)
uint32_t starpu_matrix_get_ny (starpu_data_handle_t handle)
uint32_t starpu_matrix_get_local_ld (starpu_data_handle_t handle)
uintptr_t starpu_matrix_get_local_ptr (starpu_data_handle_t handle)
size_t starpu_matrix_get_elemsize (starpu_data_handle_t handle)

Accessing Block Data Interfaces

#define STARPU_BLOCK_GET_PTR(interface)
#define STARPU_BLOCK_GET_DEV_HANDLE(interface)
#define STARPU_BLOCK_GET_OFFSET(interface)
#define STARPU_BLOCK_GET_NX(interface)
#define STARPU_BLOCK_GET_NY(interface)
#define STARPU_BLOCK_GET_NZ(interface)
#define STARPU_BLOCK_GET_LDY(interface)
#define STARPU_BLOCK_GET_LDZ(interface)
#define STARPU_BLOCK_GET_ELEMSIZE(interface)
uint32_t starpu_block_get_nx (starpu_data_handle_t handle)
uint32_t starpu_block_get_ny (starpu_data_handle_t handle)
uint32_t starpu_block_get_nz (starpu_data_handle_t handle)
uint32_t starpu_block_get_local_ldy (starpu_data_handle_t handle)
uint32_t starpu_block_get_local_ldz (starpu_data_handle_t handle)
uintptr_t starpu_block_get_local_ptr (starpu_data_handle_t handle)
size_t starpu_block_get_elemsize (starpu_data_handle_t handle)

Accessing BCSR Data Interfaces

#define STARPU_BCSR_GET_NNZ(interface)
#define STARPU_BCSR_GET_NZVAL(interface)
#define STARPU_BCSR_GET_NZVAL_DEV_HANDLE(interface)
#define STARPU_BCSR_GET_COLIND(interface)
#define STARPU_BCSR_GET_COLIND_DEV_HANDLE(interface)
#define STARPU_BCSR_GET_ROWPTR(interface)
#define STARPU_BCSR_GET_ROWPTR_DEV_HANDLE(interface)
#define STARPU_BCSR_GET_OFFSET
uint32_t starpu_bcsr_get_nnz (starpu_data_handle_t handle)
uint32_t starpu_bcsr_get_nrow (starpu_data_handle_t handle)
uint32_t starpu_bcsr_get_firstentry (starpu_data_handle_t handle)
uintptr_t starpu_bcsr_get_local_nzval (starpu_data_handle_t handle)
uint32_t * starpu_bcsr_get_local_colind (starpu_data_handle_t handle)
uint32_t * starpu_bcsr_get_local_rowptr (starpu_data_handle_t handle)
uint32_t starpu_bcsr_get_r (starpu_data_handle_t handle)
uint32_t starpu_bcsr_get_c (starpu_data_handle_t handle)
size_t starpu_bcsr_get_elemsize (starpu_data_handle_t handle)

Accessing CSR Data Interfaces

#define STARPU_CSR_GET_NNZ(interface)
#define STARPU_CSR_GET_NROW(interface)
#define STARPU_CSR_GET_NZVAL(interface)
#define STARPU_CSR_GET_NZVAL_DEV_HANDLE(interface)
#define STARPU_CSR_GET_COLIND(interface)
#define STARPU_CSR_GET_COLIND_DEV_HANDLE(interface)
#define STARPU_CSR_GET_ROWPTR(interface)
#define STARPU_CSR_GET_ROWPTR_DEV_HANDLE(interface)
#define STARPU_CSR_GET_OFFSET
#define STARPU_CSR_GET_FIRSTENTRY(interface)
#define STARPU_CSR_GET_ELEMSIZE(interface)
uint32_t starpu_csr_get_nnz (starpu_data_handle_t handle)
uint32_t starpu_csr_get_nrow (starpu_data_handle_t handle)
uint32_t starpu_csr_get_firstentry (starpu_data_handle_t handle)
uintptr_t starpu_csr_get_local_nzval (starpu_data_handle_t handle)
uint32_t * starpu_csr_get_local_colind (starpu_data_handle_t handle)
uint32_t * starpu_csr_get_local_rowptr (starpu_data_handle_t handle)
size_t starpu_csr_get_elemsize (starpu_data_handle_t handle)

Detailed Description