Finally revised API after learning/uses

Author: hfp

README.md

@@ -19,9 +19,9 @@ typedef struct libxstream_event_t libxstream_event_t;
 ```C
 int libxstream_init(void);
 int libxstream_finalize(void);
-int libxstream_get_ndevices(int* ndevices);
-int libxstream_set_active_device(int device_id);
-int libxstream_device_synchronize(void);
+int libxstream_device_count(int* ndevices);
+int libxstream_device_set_active(int device_id);
+int libxstream_device_sync(void);
 ```
 
 ### Streams
@@ -40,22 +40,22 @@ int libxstream_event_create(libxstream_event_t** event_p);
 int libxstream_event_destroy(libxstream_event_t* event);
 int libxstream_event_record(libxstream_event_t* event, libxstream_stream_t* stream);
 int libxstream_event_query(libxstream_event_t* event, libxstream_bool_t* has_occurred);
-int libxstream_event_synchronize(libxstream_event_t* event);
+int libxstream_event_sync(libxstream_event_t* event);
 ```
 
 ### Memory
 
 Device and host memory allocation, transfers (H2D, D2H, D2D), and initialization. Memory pointers remain untyped (`void*`); stream parameters use the opaque stream type.
 
 ```C
-void* libxstream_memdev_allocate(size_t nbytes);
-void libxstream_memdev_deallocate(void* dev_mem);
-void* libxstream_memhst_allocate(size_t nbytes, libxstream_stream_t* stream);
-int libxstream_memhst_deallocate(void* host_mem, libxstream_stream_t* stream);
-int libxstream_memcpy_h2d(const void* host_mem, void* dev_mem, size_t nbytes, libxstream_stream_t* stream);
-int libxstream_memcpy_d2h(const void* dev_mem, void* host_mem, size_t nbytes, libxstream_stream_t* stream);
-int libxstream_memcpy_d2d(const void* devmem_src, void* devmem_dst, size_t nbytes, libxstream_stream_t* stream);
-int libxstream_memset_zero(void* dev_mem, size_t offset, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_allocate(void** dev_mem, size_t nbytes);
+int libxstream_mem_deallocate(void* dev_mem);
+int libxstream_mem_host_allocate(void** host_mem, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_host_deallocate(void* host_mem, libxstream_stream_t* stream);
+int libxstream_mem_copy_h2d(const void* host_mem, void* dev_mem, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_copy_d2h(const void* dev_mem, void* host_mem, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_copy_d2d(const void* devmem_src, void* devmem_dst, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_zero(void* dev_mem, size_t offset, size_t nbytes, libxstream_stream_t* stream);
 ```
 
 ### DBCSR Compatibility

include/libxstream.h

@@ -26,9 +26,9 @@ int libxstream_init(void);
 int libxstream_finalize(void);
 
 /** devices */
-int libxstream_get_ndevices(int* ndevices);
-int libxstream_set_active_device(int device_id);
-int libxstream_device_synchronize(void);
+int libxstream_device_count(int* ndevices);
+int libxstream_device_set_active(int device_id);
+int libxstream_device_sync(void);
 
 /** streams */
 int libxstream_stream_priority_range(int* least, int* greatest);
@@ -44,19 +44,19 @@ int libxstream_event_create(libxstream_event_t** event_p);
 int libxstream_event_destroy(libxstream_event_t* event);
 int libxstream_event_record(libxstream_event_t* event, libxstream_stream_t* stream);
 int libxstream_event_query(libxstream_event_t* event, libxstream_bool_t* has_occurred);
-int libxstream_event_synchronize(libxstream_event_t* event);
+int libxstream_event_sync(libxstream_event_t* event);
 
 /** memory */
-void* libxstream_memdev_allocate(size_t nbytes);
-void libxstream_memdev_deallocate(void* dev_mem);
-int libxstream_memdev_set_ptr(void** dev_mem, void* other, size_t lb);
-int libxstream_memdev_info(size_t* mem_free, size_t* mem_total);
-void* libxstream_memhst_allocate(size_t nbytes, libxstream_stream_t* stream);
-int libxstream_memhst_deallocate(void* host_mem, libxstream_stream_t* stream);
-int libxstream_memcpy_h2d(const void* host_mem, void* dev_mem, size_t nbytes, libxstream_stream_t* stream);
-int libxstream_memcpy_d2h(const void* dev_mem, void* host_mem, size_t nbytes, libxstream_stream_t* stream);
-int libxstream_memcpy_d2d(const void* devmem_src, void* devmem_dst, size_t nbytes, libxstream_stream_t* stream);
-int libxstream_memset_zero(void* dev_mem, size_t offset, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_allocate(void** dev_mem, size_t nbytes);
+int libxstream_mem_deallocate(void* dev_mem);
+int libxstream_mem_offset(void** dev_mem, void* other, size_t lb);
+int libxstream_mem_info(size_t* mem_free, size_t* mem_total);
+int libxstream_mem_host_allocate(void** host_mem, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_host_deallocate(void* host_mem, libxstream_stream_t* stream);
+int libxstream_mem_copy_h2d(const void* host_mem, void* dev_mem, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_copy_d2h(const void* dev_mem, void* host_mem, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_copy_d2d(const void* devmem_src, void* devmem_dst, size_t nbytes, libxstream_stream_t* stream);
+int libxstream_mem_zero(void* dev_mem, size_t offset, size_t nbytes, libxstream_stream_t* stream);
 
 #if defined(__cplusplus)
 }

include/libxstream_opencl.h

@@ -192,7 +192,7 @@ struct libxstream_event_t {
   cl_event cl_evt;
 };
 
-/** Settings updated during libxstream_set_active_device. */
+/** Settings updated during libxstream_device_set_active. */
 typedef struct libxstream_opencl_device_t {
   /** Activated device context. */
   cl_context context;
@@ -255,7 +255,7 @@ typedef enum libxstream_opencl_atomic_fp_t {
 
 /**
  * Settings discovered/setup during libxstream_init (independent of the device)
- * and settings updated during libxstream_set_active_device (devinfo).
+ * and settings updated during libxstream_device_set_active (devinfo).
  */
 typedef struct libxstream_opencl_config_t {
   /** Table of ordered viable/discovered devices (matching criterion). */
@@ -332,7 +332,7 @@ int libxstream_opencl_info_devptr(
 const libxstream_opencl_stream_t* libxstream_opencl_stream(libxs_lock_t* lock, int thread_id);
 /** Determines default-stream (see libxstream_opencl_device_t::stream). */
 const libxstream_opencl_stream_t* libxstream_opencl_stream_default(void);
-/** Like libxstream_memset_zero, but supporting an arbitrary value used as initialization pattern. */
+/** Like libxstream_mem_zero, but supporting an arbitrary value used as initialization pattern. */
 int libxstream_opencl_memset(void* dev_mem, int value, size_t offset, size_t nbytes, libxstream_stream_t* stream);
 /** Amount of device memory; local memory is only non-zero if separate from global. */
 int libxstream_opencl_info_devmem(cl_device_id device, size_t* mem_free, size_t* mem_total, size_t* mem_local, int* mem_unified);
@@ -352,7 +352,7 @@ int libxstream_opencl_device_level(
 int libxstream_opencl_device_ext(cl_device_id device, const char* const extnames[], int num_exts);
 /** Create context for given device. */
 int libxstream_opencl_create_context(cl_device_id device_id, cl_context* context);
-/** Internal variant of libxstream_set_active_device. */
+/** Internal variant of libxstream_device_set_active. */
 int libxstream_opencl_set_active_device(libxs_lock_t* lock, int device_id);
 /** Assemble flags to support atomic operations. */
 int libxstream_opencl_flags_atomics(const libxstream_opencl_device_t* devinfo, libxstream_opencl_atomic_fp_t kind,
@@ -373,7 +373,7 @@ int libxstream_opencl_kernel_flags(const char build_params[], const char build_o
 int libxstream_opencl_kernel(size_t source_kind, const char source[], const char kernel_name[], const char build_params[],
   const char build_options[], const char try_build_options[], int* try_ok, const char* const extnames[], size_t num_exts,
   cl_kernel* kernel);
-/** Per-thread variant of libxstream_device_synchronize. */
+/** Per-thread variant of libxstream_device_sync. */
 int libxstream_opencl_device_synchronize(libxs_lock_t* lock, int thread_id);
 /** To support USM, call this function for pointer arguments instead of clSetKernelArg. */
 int libxstream_opencl_set_kernel_ptr(cl_kernel kernel, cl_uint arg_index, const void* arg_value);

samples/ozaki/README.md

@@ -87,7 +87,7 @@ eliminating per-call allocation overhead for repeated GEMM calls.  With the pool
 active, `ozaki_gemm` returns without synchronizing — the caller is responsible
 for syncing the stream.  On the rare grow path (larger problem size), the
 wrapped deallocator syncs all streams before reallocating.  The pool falls back
-to direct `libxstream_memdev_allocate` transparently if USM/SVM is not supported.
+to direct `libxstream_mem_allocate` transparently if USM/SVM is not supported.
 
 ## Build
 

samples/ozaki/ozaki_bench.c

@@ -77,9 +77,9 @@ int main(int argc, char* argv[])
     if (EXIT_SUCCESS == result) {
       int ndevices = 0;
       initialized = 1;
-      result = libxstream_get_ndevices(&ndevices);
+      result = libxstream_device_count(&ndevices);
       if (EXIT_SUCCESS == result && 0 < ndevices) {
-        result = libxstream_set_active_device(0);
+        result = libxstream_device_set_active(0);
       }
       else if (EXIT_SUCCESS == result) {
         fprintf(stderr, "ERROR: no ACC device found\n");
@@ -136,11 +136,11 @@ int main(int argc, char* argv[])
   if (EXIT_SUCCESS == result) {
     const int a_rows = (0 == ta ? M : K), a_cols = (0 == ta ? K : M);
     const int b_rows = (0 == tb ? K : N), b_cols = (0 == tb ? N : K);
-    a = libxstream_memhst_allocate((size_t)lda * a_cols * elem_size, stream);
-    if (NULL != a) b = libxstream_memhst_allocate((size_t)ldb * b_cols * elem_size, stream);
-    if (NULL != b) c_oz = libxstream_memhst_allocate((size_t)ldc * N * elem_size, stream);
-    if (NULL != c_oz) c_ref = libxstream_memhst_allocate((size_t)ldc * N * elem_size, stream);
-    if (NULL == a || NULL == b || NULL == c_oz || NULL == c_ref) {
+    result = libxstream_mem_host_allocate((void**)&a, (size_t)lda * a_cols * elem_size, stream);
+    if (EXIT_SUCCESS == result) result = libxstream_mem_host_allocate((void**)&b, (size_t)ldb * b_cols * elem_size, stream);
+    if (EXIT_SUCCESS == result) result = libxstream_mem_host_allocate((void**)&c_oz, (size_t)ldc * N * elem_size, stream);
+    if (EXIT_SUCCESS == result) result = libxstream_mem_host_allocate((void**)&c_ref, (size_t)ldc * N * elem_size, stream);
+    if (EXIT_SUCCESS != result) {
       fprintf(stderr, "ERROR: out of memory\n");
       result = EXIT_FAILURE;
     }
@@ -219,10 +219,10 @@ int main(int argc, char* argv[])
   }
 
   if (0 != initialized) {
-    if (NULL != a) libxstream_memhst_deallocate(a, stream);
-    if (NULL != b) libxstream_memhst_deallocate(b, stream);
-    if (NULL != c_oz) libxstream_memhst_deallocate(c_oz, stream);
-    if (NULL != c_ref) libxstream_memhst_deallocate(c_ref, stream);
+    if (NULL != a) libxstream_mem_host_deallocate(a, stream);
+    if (NULL != b) libxstream_mem_host_deallocate(b, stream);
+    if (NULL != c_oz) libxstream_mem_host_deallocate(c_oz, stream);
+    if (NULL != c_ref) libxstream_mem_host_deallocate(c_ref, stream);
     if (NULL != stream) libxstream_stream_destroy(stream);
     ozaki_destroy(&ctx);
     libxstream_finalize();

samples/ozaki/ozaki_opencl.c

@@ -25,17 +25,17 @@
 # define OZAKI_DEV_ALLOC(PTR, SIZE) ( \
   (NULL != pool) \
     ? ((*(PTR) = libxs_malloc(pool, SIZE, LIBXS_MALLOC_NATIVE)) != NULL ? EXIT_SUCCESS : EXIT_FAILURE) \
-    : ((*(PTR) = libxstream_memdev_allocate(SIZE)) != NULL ? EXIT_SUCCESS : EXIT_FAILURE))
+    : libxstream_mem_allocate((void**)(PTR), SIZE))
 # define OZAKI_DEV_FREE(PTR) do { \
   if (NULL != (PTR)) { \
-    if (NULL != pool) libxs_free(PTR); else libxstream_memdev_deallocate(PTR); \
+    if (NULL != pool) libxs_free(PTR); else libxstream_mem_deallocate(PTR); \
   } \
 } while (0)
 #else
 # define OZAKI_DEV_ALLOC(PTR, SIZE) \
-  ((*(PTR) = libxstream_memdev_allocate(SIZE)) != NULL ? EXIT_SUCCESS : EXIT_FAILURE)
+  libxstream_mem_allocate((void**)(PTR), SIZE)
 # define OZAKI_DEV_FREE(PTR) do { \
-  if (NULL != (PTR)) libxstream_memdev_deallocate(PTR); \
+  if (NULL != (PTR)) libxstream_mem_deallocate(PTR); \
 } while (0)
 #endif
 
@@ -51,8 +51,10 @@
 /* Wrapped allocator for libxs_malloc_xpool: delegates to device allocator. */
 static void* ozaki_dev_allocate(size_t size, const void* extra)
 {
+  void* result = NULL;
   (void)extra;
-  return libxstream_memdev_allocate(size);
+  libxstream_mem_allocate(&result, size);
+  return result;
 }
 
 /* Wrapped deallocator: syncs all streams before freeing device memory.
@@ -63,7 +65,7 @@ static void ozaki_dev_deallocate(void* pointer, const void* extra)
   if (NULL != ctx->stream)   libxstream_stream_sync(ctx->stream);
   if (NULL != ctx->stream_a) libxstream_stream_sync(ctx->stream_a);
   if (NULL != ctx->stream_b) libxstream_stream_sync(ctx->stream_b);
-  libxstream_memdev_deallocate(pointer);
+  libxstream_mem_deallocate(pointer);
 }
 #endif
 
@@ -457,9 +459,9 @@ int ozaki_gemm(ozaki_context_t* ctx, libxstream_stream_t* stream,
     if (EXIT_SUCCESS == result) result = OZAKI_DEV_ALLOC(&d_b, b_nbytes);
     if (EXIT_SUCCESS == result) result = OZAKI_DEV_ALLOC(&d_c, c_nbytes);
     /* Overlapped H2D: A via stream_a, B via stream_b, C via main */
-    if (EXIT_SUCCESS == result) result = libxstream_memcpy_h2d(a, d_a, a_nbytes, stream_a);
-    if (EXIT_SUCCESS == result) result = libxstream_memcpy_h2d(b, d_b, b_nbytes, stream_b);
-    if (EXIT_SUCCESS == result) result = libxstream_memcpy_h2d(c, d_c, c_nbytes, stream);
+    if (EXIT_SUCCESS == result) result = libxstream_mem_copy_h2d(a, d_a, a_nbytes, stream_a);
+    if (EXIT_SUCCESS == result) result = libxstream_mem_copy_h2d(b, d_b, b_nbytes, stream_b);
+    if (EXIT_SUCCESS == result) result = libxstream_mem_copy_h2d(c, d_c, c_nbytes, stream);
   }
 
   /* Pre-allocate double-buffered preprocessing buffers (max batch size) */
@@ -640,7 +642,7 @@ int ozaki_gemm(ozaki_context_t* ctx, libxstream_stream_t* stream,
   }
 
   /* Read back result C; caller is responsible for syncing the stream */
-  if (EXIT_SUCCESS == result) result = libxstream_memcpy_d2h(d_c, c, c_nbytes, stream);
+  if (EXIT_SUCCESS == result) result = libxstream_mem_copy_d2h(d_c, c, c_nbytes, stream);
 
   /* Return buffers to pool (no deallocation, no sync needed) or free directly */
   { int s;

src/libxstream.c

@@ -756,15 +756,15 @@ int libxstream_opencl_use_cmem(const libxstream_opencl_device_t* devinfo) {
 }
 
 
-int libxstream_get_ndevices(int* ndevices) {
+int libxstream_device_count(int* ndevices) {
   int result;
 #  if defined(__DBCSR_ACC) /* lazy initialization */
-  /* DBCSR calls libxstream_get_ndevices before calling libxstream_init. */
+  /* DBCSR calls libxstream_device_count before calling libxstream_init. */
   result = libxstream_init();
   if (EXIT_SUCCESS == result)
 #  endif
   {
-    if (NULL != ndevices && 0 != libxstream_opencl_config.ndevices) {
+    if (NULL != ndevices) {
       *ndevices = (0 < libxstream_opencl_config.ndevices ? libxstream_opencl_config.ndevices : 0);
       result = EXIT_SUCCESS;
     }
@@ -1212,7 +1212,7 @@ int libxstream_opencl_set_active_device(libxs_lock_t* lock, int device_id) {
 }
 
 
-int libxstream_set_active_device(int device_id) {
+int libxstream_device_set_active(int device_id) {
   int result = EXIT_SUCCESS;
   if (0 <= device_id) {
 #  if defined(__DBCSR_ACC) && defined(__OFFLOAD_OPENCL)