Merge branch 'api-create-errors' into 'master'

Improve code base for create API and style

Closes #31

See merge request !46

.checkpatch.conf

@@ -10,3 +10,30 @@
 
 # better output format for CI
 --terse --no-summary
+
+# files
+include/aml.h
+include/aml/area/linux.h
+include/aml/dma/linux-seq.h
+include/aml/dma/linux-par.h
+include/aml/scratch/seq.h
+include/aml/scratch/par.h
+include/aml/tiling/1d.h
+include/aml/tiling/2d.h
+include/aml/utils/bitmap.h
+include/aml/utils/error.h
+include/aml/utils/vector.h
+src/aml.c
+src/area/area.c
+src/area/linux.c
+src/dma/dma.c
+src/dma/dma_linux_seq.c
+src/dma/dma_linux_par.c
+src/scratch/scratch.c
+src/scratch/scratch_seq.c
+src/scratch/scratch_par.c
+src/tiling/tiling.c
+src/tiling/tiling_1d.c
+src/tiling/tiling_2d.c
+src/utils/error.c
+src/utils/vector.c

.gitlab-ci.yml

@@ -52,4 +52,4 @@ repoquality:
 checkpatch:
   stage: style
   script:
-    - nix run -f "$ARGOPKGS" checkpatch --command checkpatch.pl src/aml.c include/aml.h
+    - nix run -f "$ARGOPKGS" checkpatch --command checkpatch.pl

benchmarks/dgemm_mkl.c

@@ -34,10 +34,10 @@ int main(int argc, char *argv[])
 	long int N = atol(argv[3]);
 	unsigned long memsize = sizeof(double)*N*N;
 
-	slow = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&slow, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &slowb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(slow != NULL);
-	fast = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&fast, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &fastb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(fast != NULL);
 
@@ -65,8 +65,8 @@ int main(int argc, char *argv[])
 	aml_area_munmap(slow, a, memsize);
 	aml_area_munmap(slow, b, memsize);
 	aml_area_munmap(fast, c, memsize);
-	aml_area_linux_destroy(slow);
-	aml_area_linux_destroy(fast);
+	aml_area_linux_destroy(&slow);
+	aml_area_linux_destroy(&fast);
 	aml_finalize();
 	return 0;
 }

benchmarks/dgemm_noprefetch.c

@@ -72,15 +72,15 @@ int main(int argc, char* argv[])
 	tilesize = sizeof(double)*T*T;
 
 	/* the initial tiling, of 2D square tiles */
-	assert(!aml_tiling_init(&tiling_row, AML_TILING_TYPE_2D_ROWMAJOR,
+	assert(!aml_tiling_2d_init(&tiling_row, AML_TILING_TYPE_2D_ROWMAJOR,
 				tilesize, memsize, N/T , N/T));
-	assert(!aml_tiling_init(&tiling_col, AML_TILING_TYPE_2D_COLMAJOR,
+	assert(!aml_tiling_2d_init(&tiling_col, AML_TILING_TYPE_2D_COLMAJOR,
 				tilesize, memsize, N/T , N/T));
 
-	slow = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&slow, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &slowb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(slow != NULL);
-	fast = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&fast, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &fastb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(fast != NULL);
 
@@ -154,10 +154,10 @@ int main(int argc, char* argv[])
 	aml_area_munmap(slow, a, memsize);
 	aml_area_munmap(slow, b, memsize);
 	aml_area_munmap(fast, c, memsize);
-	aml_area_linux_destroy(slow);
-	aml_area_linux_destroy(fast);
-	aml_tiling_destroy(&tiling_row, AML_TILING_TYPE_2D_ROWMAJOR);
-	aml_tiling_destroy(&tiling_col, AML_TILING_TYPE_2D_ROWMAJOR);
+	aml_area_linux_destroy(&slow);
+	aml_area_linux_destroy(&fast);
+	aml_tiling_2d_fini(&tiling_row);
+	aml_tiling_2d_fini(&tiling_col);
 	aml_finalize();
 	return 0;
 }

benchmarks/dgemm_prefetch.c

@@ -97,18 +97,18 @@ int main(int argc, char* argv[])
 	tilesize = sizeof(double)*T*T;
 
 	/* the initial tiling, 2d grid of tiles */
-	assert(!aml_tiling_init(&tiling_row, AML_TILING_TYPE_2D_ROWMAJOR,
+	assert(!aml_tiling_2d_init(&tiling_row, AML_TILING_TYPE_2D_ROWMAJOR,
 				tilesize, memsize, N/T , N/T));
-	assert(!aml_tiling_init(&tiling_col, AML_TILING_TYPE_2D_COLMAJOR,
+	assert(!aml_tiling_2d_init(&tiling_col, AML_TILING_TYPE_2D_COLMAJOR,
 				tilesize, memsize, N/T , N/T));
 	/* the prefetch tiling, 1D sequence of columns of tiles */
-	assert(!aml_tiling_init(&tiling_prefetch, AML_TILING_TYPE_1D,
+	assert(!aml_tiling_1d_init(&tiling_prefetch,
 				tilesize*(N/T), memsize));
 
-	slow = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&slow, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &slowb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(slow != NULL);
-	fast = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&fast, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &fastb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(fast != NULL);
 	
@@ -182,17 +182,17 @@ int main(int argc, char* argv[])
 	/* print the flops in GFLOPS */
 	printf("dgemm-prefetch: %llu %lld %lld %f\n", N, memsize, time,
 	       flops/1e9);
-	aml_scratch_par_destroy(&sa);
-	aml_scratch_par_destroy(&sb);
-	aml_dma_linux_seq_destroy(&dma);
+	aml_scratch_par_fini(&sa);
+	aml_scratch_par_fini(&sb);
+	aml_dma_linux_seq_fini(&dma);
 	aml_area_munmap(slow, a, memsize);
 	aml_area_munmap(slow, b, memsize);
 	aml_area_munmap(fast, c, memsize);
-	aml_area_linux_destroy(slow);
-	aml_area_linux_destroy(fast);
-	aml_tiling_destroy(&tiling_row, AML_TILING_TYPE_2D_ROWMAJOR);
-	aml_tiling_destroy(&tiling_col, AML_TILING_TYPE_2D_ROWMAJOR);
-	aml_tiling_destroy(&tiling_prefetch, AML_TILING_TYPE_1D);
+	aml_area_linux_destroy(&slow);
+	aml_area_linux_destroy(&fast);
+	aml_tiling_2d_fini(&tiling_row);
+	aml_tiling_2d_fini(&tiling_col);
+	aml_tiling_1d_fini(&tiling_prefetch);
 	aml_finalize();
 	return 0;
 }

benchmarks/stream_add_omp_mt.c

@@ -63,11 +63,11 @@ int main(int argc, char *argv[])
 	}
 
 	/* initialize all the supporting struct */
-	assert(!aml_tiling_init(&tiling, AML_TILING_TYPE_1D, tilesz, memsize));
-	slow = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	assert(!aml_tiling_1d_init(&tiling, tilesz, memsize));
+	aml_area_linux_create(&slow, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &slowb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(slow != NULL);
-	fast = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&fast, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &fastb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(fast != NULL);
 	assert(!aml_dma_linux_par_init(&dma, numthreads*2, numthreads));
@@ -118,15 +118,15 @@ int main(int argc, char *argv[])
 		assert(c[i] == esize);
 	}
 
-	aml_scratch_seq_destroy(&sa);
-	aml_scratch_seq_destroy(&sb);
-	aml_dma_linux_par_destroy(&dma);
+	aml_scratch_seq_fini(&sa);
+	aml_scratch_seq_fini(&sb);
+	aml_dma_linux_par_fini(&dma);
 	aml_area_munmap(slow, a, memsize);
 	aml_area_munmap(slow, b, memsize);
 	aml_area_munmap(fast, c, memsize);
-	aml_area_linux_destroy(slow);
-	aml_area_linux_destroy(fast);
-	aml_tiling_destroy(&tiling, AML_TILING_TYPE_1D);
+	aml_area_linux_destroy(&slow);
+	aml_area_linux_destroy(&fast);
+	aml_tiling_1d_fini(&tiling);
 	aml_finalize();
 	return 0;
 }

benchmarks/stream_add_omp_st.c

@@ -93,12 +93,12 @@ int main(int argc, char *argv[])
 	}
 
 	/* initialize all the supporting struct */
-	assert(!aml_tiling_init(&tiling, AML_TILING_TYPE_1D, tilesz, memsize));
+	assert(!aml_tiling_1d_init(&tiling, tilesz, memsize));
 
-	slow = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&slow, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &slowb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(slow != NULL);
-	fast = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&fast, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &fastb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(fast != NULL);
 	assert(!aml_dma_linux_seq_init(&dma, numthreads*2));
@@ -131,15 +131,15 @@ int main(int argc, char *argv[])
 		assert(c[i] == esize);
 	}
 
-	aml_scratch_par_destroy(&sa);
-	aml_scratch_par_destroy(&sb);
-	aml_dma_linux_seq_destroy(&dma);
+	aml_scratch_par_fini(&sa);
+	aml_scratch_par_fini(&sb);
+	aml_dma_linux_seq_fini(&dma);
 	aml_area_munmap(slow, a, memsize);
 	aml_area_munmap(slow, b, memsize);
 	aml_area_munmap(fast, c, memsize);
-	aml_area_linux_destroy(slow);
-	aml_area_linux_destroy(fast);
-	aml_tiling_destroy(&tiling, AML_TILING_TYPE_1D);
+	aml_area_linux_destroy(&slow);
+	aml_area_linux_destroy(&fast);
+	aml_tiling_1d_fini(&tiling);
 	aml_finalize();
 	return 0;
 }

benchmarks/stream_add_pth_st.c

@@ -100,11 +100,11 @@ int main(int argc, char *argv[])
 	}
 
 	/* initialize all the supporting struct */
-	assert(!aml_tiling_init(&tiling, AML_TILING_TYPE_1D, tilesz, memsize));
-	slow = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	assert(!aml_tiling_1d_init(&tiling, tilesz, memsize));
+	aml_area_linux_create(&slow, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &slowb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(slow != NULL);
-	fast = aml_area_linux_create(AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
+	aml_area_linux_create(&fast, AML_AREA_LINUX_MMAP_FLAG_PRIVATE,
 				     &fastb, AML_AREA_LINUX_BINDING_FLAG_BIND);
 	assert(fast != NULL);
 	assert(!aml_dma_linux_seq_init(&dma, (size_t)numthreads*4));
@@ -142,15 +142,15 @@ int main(int argc, char *argv[])
 		assert(c[i] == esize);
 	}
 
-	aml_scratch_par_destroy(&sa);
-	aml_scratch_par_destroy(&sb);
-	aml_dma_linux_seq_destroy(&dma);
+	aml_scratch_par_fini(&sa);
+	aml_scratch_par_fini(&sb);
+	aml_dma_linux_seq_fini(&dma);
 	aml_area_munmap(slow, a, memsize);
 	aml_area_munmap(slow, b, memsize);
 	aml_area_munmap(fast, c, memsize);
-	aml_area_linux_destroy(slow);
-	aml_area_linux_destroy(fast);
-	aml_tiling_destroy(&tiling, AML_TILING_TYPE_1D);
+	aml_area_linux_destroy(&slow);
+	aml_area_linux_destroy(&fast);
+	aml_tiling_1d_fini(&tiling);
 	aml_finalize();
 	return 0;
 }

include/aml.h

@@ -139,6 +139,12 @@ aml_area_munmap(const struct aml_area *area,
  * Representation of a data structure organization in memory.
  ******************************************************************************/
 
+/* Tiling types passed to the tiling create()/init()/vinit() routines.  */
+/* Regular, linear tiling with uniform tile sizes.  */
+#define AML_TILING_TYPE_1D 0
+#define AML_TILING_TYPE_2D_ROWMAJOR 1
+#define AML_TILING_TYPE_2D_COLMAJOR 2
+
 /* opaque handle to all tilings */
 struct aml_tiling_data;
 struct aml_tiling_iterator_data;
@@ -154,8 +160,10 @@ struct aml_tiling_ops {
 			       int flags);
 	int (*init_iterator)(struct aml_tiling_data *tiling,
 			     struct aml_tiling_iterator *iterator, int flags);
-	int (*destroy_iterator)(struct aml_tiling_data *tiling,
+	int (*fini_iterator)(struct aml_tiling_data *tiling,
 				struct aml_tiling_iterator *iterator);
+	int (*destroy_iterator)(struct aml_tiling_data *tiling,
+				struct aml_tiling_iterator **iterator);
 	int (*tileid)(const struct aml_tiling_data *tiling, va_list coords);
 	size_t (*tilesize)(const struct aml_tiling_data *tiling, int tileid);
 	void* (*tilestart)(const struct aml_tiling_data *tiling,
@@ -231,14 +239,22 @@ int aml_tiling_create_iterator(struct aml_tiling *tiling,
  */
 int aml_tiling_init_iterator(struct aml_tiling *tiling,
 			     struct aml_tiling_iterator *iterator, int flags);
+
+/*
+ * Finalize an initialized tiling iterator.
+ * "tiling": an initialized tiling structure.
+ * "iterator": an initialized tiling iterator structure.
+ */
+void aml_tiling_fini_iterator(struct aml_tiling *tiling,
+			      struct aml_tiling_iterator *iterator);
 /*
  * Tears down an initialized tiling iterator.
  * "tiling": an initialized tiling structure.
  * "iterator": an initialized tiling iterator structure.
  * Returns 0 if successful; an error code otherwise.
  */
-int aml_tiling_destroy_iterator(struct aml_tiling *tiling,
-				struct aml_tiling_iterator *iterator);
+void aml_tiling_destroy_iterator(struct aml_tiling *tiling,
+				struct aml_tiling_iterator **iterator);
 
 struct aml_tiling_iterator_ops {
 	int (*reset)(struct aml_tiling_iterator_data *iterator);
@@ -282,56 +298,6 @@ int aml_tiling_iterator_end(const struct aml_tiling_iterator *iterator);
  */
 int aml_tiling_iterator_get(const struct aml_tiling_iterator *iterator, ...);
 
-/* Tiling types passed to the tiling create()/init()/vinit() routines.  */
-/* Regular, linear tiling with uniform tile sizes.  */
-#define AML_TILING_TYPE_1D 0
-#define AML_TILING_TYPE_2D_ROWMAJOR 1
-#define AML_TILING_TYPE_2D_COLMAJOR 2
-
-/*
- * Allocates and initializes a new tiling.
- * "tiling": an address where the pointer to the newly allocated tiling
- *           structure will be stored.
- * "type": see AML_TILING_TYPE_*.
- * Variadic arguments:
- * - if "type" equals AML_TILING_TYPE_1D, two additional arguments are needed:
- *   - "tilesize": an argument of type size_t; provides the size of each tile.
- *   - "totalsize": an argument of type size_t; provides the size of the
- *                  complete user data structure to be tiled.
- * - if "type" equals AML_TILING_TYPE_2D, four additional arguments are needed:
- *   - "tilesize": an argument of type size_t; provides the size of a tile.
- *   - "totalsize": an argument of type size_t; provides the size of the
- *                  complete user data structure to be tiled.
- *   - "rowsize": an argument of type size_t; the number of tiles in a row
- *   - "colsize": an argument of type size_t; the number of tiles in a column
- * Returns 0 if successful; an error code otherwise.
- */
-int aml_tiling_create(struct aml_tiling **tiling, int type, ...);
-/*
- * Initializes a tiling.  This is a varargs-variant of the aml_tiling_vinit()
- * routine.
- * "tiling": an allocated tiling structure.
- * "type": see aml_tiling_create().
- * Variadic arguments: see aml_tiling_create().
- * Returns 0 if successful; an error code otherwise.
- */
-int aml_tiling_init(struct aml_tiling *tiling, int type, ...);
-/*
- * Initializes a tiling.
- * "tiling": an allocated tiling structure.
- * "type": see aml_tiling_create().
- * "args": see the variadic arguments of aml_tiling_create().
- * Returns 0 if successful; an error code otherwise.
- */
-int aml_tiling_vinit(struct aml_tiling *tiling, int type, va_list args);
-/*
- * Tears down an initialized tiling.
- * "tiling": an initialized tiling structure.
- * "type": see aml_tiling_create().
- * Returns 0 if successful; an error code otherwise.
- */
-int aml_tiling_destroy(struct aml_tiling *tiling, int type);
-
 /*******************************************************************************
  * DMA:
  * Management of low-level movement of memory.

include/aml/area/linux.h

@@ -37,38 +37,12 @@ struct aml_area_linux_data {
 };
 
 /* Default linux area with private mapping and no binding. */
-extern const struct aml_area aml_area_linux;
+extern struct aml_area aml_area_linux;
 
-#define AML_AREA_LINUX_DECL(name) \
-	struct aml_area_linux_data __ ##name## _inner_data; \
-	struct aml_area name = { \
-		&aml_area_linux_ops, \
-		(struct aml_area_data *)&__ ## name ## _inner_data, \
-	}
 
-#define AML_AREA_LINUX_ALLOCSIZE \
-	(sizeof(struct aml_area_linux_data) + \
-	 sizeof(struct aml_area))
-
-
-/** 
- * Initialize area data with struct aml_area_linux_binding. Subsequent calls to
- * aml_area_mmap() with this returned area will apply binding settings.
- * Returns NULL on failure with aml_errno set to:
- * - AML_AREA_ENOMEM if there is not enough memory available for the operation
- * - AML_AREA_EINVAL flags were not one of linux area flags.
- * - AML_AREA_EDOM if binding nodeset is out of allowed nodeset.
- **/
-struct aml_area* aml_area_linux_create(const int mmap_flags,
-				       const struct aml_bitmap *nodemask,
-				       const int binding_flags);
-
-
-/** 
- * Destroy area data containing struct aml_area_linux_binding 
- **/
-void
-aml_area_linux_destroy(struct aml_area* area);
+/*******************************************************************************
+ * Linux operators
+*******************************************************************************/
 
 /**
  * Bind memory of size "size" pointed by "ptr" to binding set in "bind".
@@ -80,10 +54,10 @@ aml_area_linux_mbind(struct aml_area_linux_data    *bind,
 		     void                          *ptr,
 		     size_t                         size);
 
-/** 
- * Function to check whether binding of a ptr obtained with 
- * aml_area_linux_mmap() then aml_area_linux_mbind() match area settings. 
- * Returns 1 if mapped memory binding in ptr match area_data binding settings, 
+/**
+ * Function to check whether binding of a ptr obtained with
+ * aml_area_linux_mmap() then aml_area_linux_mbind() match area settings.
+ * Returns 1 if mapped memory binding in ptr match area_data binding settings,
  * else 0.
  **/
 int
@@ -91,7 +65,7 @@ aml_area_linux_check_binding(struct aml_area_linux_data *area_data,
 			     void                       *ptr,
 			     size_t                      size);
 
-/** 
+/**
  * mmap hook for aml area.
  * Fails with AML_FAILURE. On failure errno should be checked for further
  * error investigations.
@@ -101,14 +75,70 @@ aml_area_linux_mmap(const struct aml_area_data  *area_data,
 		    void                        *ptr,
 		    size_t                       size);
 
-/** 
+/**
  * munmap hook for aml area, to unmap memory mapped with aml_area_linux_mmap().
  * Fails with AML_FAILURE. On failure errno should be checked for further
  * error investigations.
  **/
 int
-aml_area_linux_munmap(const struct aml_area_data* area_data,
+aml_area_linux_munmap(const struct aml_area_data *area_data,
 		      void *ptr,
 		      const size_t size);
 
+/*******************************************************************************
+ * create/destroy and others
+*******************************************************************************/
+
+
+#define AML_AREA_LINUX_DECL(name) \
+	struct aml_area_linux_data __ ##name## _inner_data; \
+	struct aml_area name = { \
+		&aml_area_linux_ops, \
+		(struct aml_area_data *)&__ ## name ## _inner_data, \
+	}
+
+#define AML_AREA_LINUX_ALLOCSIZE \
+	(sizeof(struct aml_area_linux_data) + \
+	 sizeof(struct aml_area))
+
+
+/**
+ * Allocate and initialize a struct aml_area implemented by aml_area_linux
+ * operations.
+ * @param[out] area pointer to an uninitialized struct aml_area pointer to
+ * receive the new area.
+ * @param[in] mmap_flags flags to use when retrieving virtual memory with mmap
+ * @param[in] binding_flags, flags to use when binding memory.
+ * @param[in] nodemask list of memory nodes to use. Default to allowed memory
+ * nodes if NULL.
+ * @return On success, returns 0 and area points to the new aml_area.
+ * @return On failure, sets area to NULL and returns one of AML error codes:
+ * - AML_ENOMEM if there wasn't enough memory available.
+ * - AML_EINVAL if inputs flags were invalid.
+ * - AML_EDOM the nodemask provided is out of bounds (allowed nodeset).
+ **/
+int aml_area_linux_create(struct aml_area **area, const int mmap_flags,
+			  const struct aml_bitmap *nodemask,
+			  const int binding_flags);
+
+/**
+ * Initialize a struct aml_area declared using the AML_AREA_LINUX_DECL macro.
+ * See aml_area_linux_create for details on arguments.
+ */
+int aml_area_linux_init(struct aml_area *area, const int mmap_flags,
+			const struct aml_bitmap *nodemask,
+			const int binding_flags);
+/**
+ * Finalize a struct aml_area initialized with aml_area_linux_init.
+ */
+void aml_area_linux_fini(struct aml_area *area);
+
+/**
+ * Destroy (finalize and free resources) a struct aml_area created by
+ * aml_area_linux_create.
+ *
+ * @param area is NULL after this call.
+ **/
+void aml_area_linux_destroy(struct aml_area **area);
+
 #endif //AML_AREA_LINUX_NUMA_H

include/aml/dma/linux-par.h

@@ -41,9 +41,9 @@ struct aml_dma_linux_par_data {
 };
 
 struct aml_dma_linux_par_ops {
-	void *(*do_thread)(void *);
-	int (*do_copy)(struct aml_dma_linux_par_data *,
-		       struct aml_dma_request_linux_par *, int tid);
+	void *(*do_thread)(void *thread_data);
+	int (*do_copy)(struct aml_dma_linux_par_data *data,
+		       struct aml_dma_request_linux_par *request, int tid);
 };
 
 struct aml_dma_linux_par {
@@ -62,39 +62,42 @@ struct aml_dma_linux_par {
 	(sizeof(struct aml_dma_linux_par) + \
 	 sizeof(struct aml_dma))
 
-/*
+/**
  * Allocates and initializes a new parallel DMA.
- * "dma": an address where the pointer to the newly allocated DMA structure
- *        will be stored.
- * Variadic arguments:
- * - "nbreqs": an argument of type size_t; the initial number of slots for
- *             asynchronous request that are in-flight (will be increased
- *             automatically if necessary).
- * - "nbthreads": an argument of type size_t; the number of threads to launch
- *                for each request.
- * Returns 0 if successful; an error code otherwise.
- */
-int aml_dma_linux_par_create(struct aml_dma **, ...);
-/*
- * Initializes a new parallel DMA.  This is a varargs-variant of the
- * aml_dma_linux_par_vinit() routine.
- * "dma": an allocated DMA structure.
- * Variadic arguments: see aml_dma_linux_par_create().
- * Returns 0 if successful; an error code otherwise.
- */
-int aml_dma_linux_par_init(struct aml_dma *, ...);
-/*
+ *
+ * @param dma an address where the pointer to the newly allocated DMA structure
+ * will be stored.
+ * @param nbreqs the initial number of slots for asynchronous requests that are
+ * in-flight (will be increased automatically if necessary).
+ * @param nbthreads the number of threads to launch for each request.
+ *
+ * @return 0 if successful; an error code otherwise.
+ **/
+int aml_dma_linux_par_create(struct aml_dma **dma, size_t nbreqs,
+			     size_t nbthreads);
+
+/**
  * Initializes a new parallel DMA.
- * "dma": an allocated DMA structure.
- * "args": see the variadic arguments of aml_dma_linux_par_create().
- * Returns 0 if successful; an error code otherwise.
- */
-int aml_dma_linux_par_vinit(struct aml_dma *, va_list);
-/*
- * Tears down an initialized parallel DMA.
- * "dma": an initialized DMA structure.
- * Returns 0 if successful; an error code otherwise.
+ *
+ * @param dma a pointer to a dma declared with the AML_DMA_LINUX_PAR_DECL macro
+ * @param nbreqs the initial number of slots for asynchronous requests that are
+ * in-flight (will be increased automatically if necessary).
+ * @param nbthreads the number of threads to launch for each request.
+ *
+ * @return 0 if successful; an error code otherwise.
+ **/
+int aml_dma_linux_par_init(struct aml_dma *dma, size_t nbreqs,
+			   size_t nbthreads);
+
+/**
+ * Finalize a parallel DMA
+ **/
+void aml_dma_linux_par_fini(struct aml_dma *dma);
+
+/**
+ * Tears down a parallel DMA created with aml_dma_linux_par_create.
+ * @param dma the address of a pointer to a parallel dma. Will be NULL after.
  */
-int aml_dma_linux_par_destroy(struct aml_dma *);
+void aml_dma_linux_par_destroy(struct aml_dma **dma);
 
 #endif // AML_LINUX_DMA_LINUX_PAR_H

include/aml/dma/linux-seq.h

@@ -52,38 +52,38 @@ struct aml_dma_linux_seq {
 	(sizeof(struct aml_dma_linux_seq) + \
 	 sizeof(struct aml_dma))
 
-/*
+/**
  * Allocates and initializes a new sequential DMA.
- * "dma": an address where the pointer to the newly allocated DMA structure
- *        will be stored.
- * Variadic arguments:
- * - "nbreqs": an argument of type size_t; the initial number of slots for
- *             asynchronous request that are in-flight (will be increased
- *             automatically if necessary).
- * Returns 0 if successful; an error code otherwise.
- */
-int aml_dma_linux_seq_create(struct aml_dma **dma, ...);
-/*
- * Initializes a new sequential DMA.  This is a varargs-variant of the
- * aml_dma_linux_seq_vinit() routine.
- * "dma": an allocated DMA structure.
- * Variadic arguments: see aml_dma_linux_seq_create().
- * Returns 0 if successful; an error code otherwise.
- */