diff mbox

[PATCHv3,3/3] Buffer pool API Part 3 of 3: External API for Review/Approval

Message ID 1416693854-29711-3-git-send-email-bill.fischofer@linaro.org
State Superseded
Headers show

Commit Message

Bill Fischofer Nov. 22, 2014, 10:04 p.m. UTC
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
---
Merge parts 1, 2, and 3 of this patch after review.

 .../linux-generic/include/api/odp_buffer_pool.h    | 105 ++++++++++++++++++---
 1 file changed, 94 insertions(+), 11 deletions(-)

Comments

Bill Fischofer Dec. 1, 2014, 4:41 p.m. UTC | #1
This patch has been superseded and is withdrawn.

On Sat, Nov 22, 2014 at 5:04 PM, Bill Fischofer <bill.fischofer@linaro.org>
wrote:

> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
> ---
> Merge parts 1, 2, and 3 of this patch after review.
>
>  .../linux-generic/include/api/odp_buffer_pool.h    | 105
> ++++++++++++++++++---
>  1 file changed, 94 insertions(+), 11 deletions(-)
>
> diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h
> b/platform/linux-generic/include/api/odp_buffer_pool.h
> index 30b83e0..d5f138e 100644
> --- a/platform/linux-generic/include/api/odp_buffer_pool.h
> +++ b/platform/linux-generic/include/api/odp_buffer_pool.h
> @@ -36,32 +36,115 @@ extern "C" {
>  #define ODP_BUFFER_POOL_INVALID   0
>
>  /**
> + * Buffer pool parameters
> + *
> + * @param[in] buf_size   Buffer size in bytes. The maximum number
> + *                       of bytes application will store in each
> + *                       buffer.
> + *
> + * @param[in] buf_align  Minimum buffer alignment in bytes.  Valid values
> + *                       are powers of two. Use 0 for the default
> + *                       alignment. Default alignment is a multiple
> + *                       of 8.
> + *
> + * @param[in] num_bufs   Number of buffers in the pool.
> + *
> + * @param[in] buf_type   Buffer type
> + */
> +typedef struct odp_buffer_pool_param_t {
> +       size_t   buf_size;
> +       size_t   buf_align;
> +       uint32_t num_bufs;
> +       int      buf_type;
> +} odp_buffer_pool_param_t;
> +
> +/**
>   * Create a buffer pool
> + * This routine is used to create a buffer pool. It take three
> + * arguments: the optional name of the pool to be created, an optional
> shared
> + * memory handle, and a parameter struct that describes the pool to be
> + * created. If a name is not specified the result is an anonymous pool
> that
> + * cannot be referenced by odp_buffer_pool_lookup().
>   *
> - * @param name      Name of the pool (max ODP_BUFFER_POOL_NAME_LEN - 1
> chars)
> - * @param base_addr Pool base address
> - * @param size      Pool size in bytes
> - * @param buf_size  Buffer size in bytes
> - * @param buf_align Minimum buffer alignment
> - * @param buf_type  Buffer type
> + * @param[in] name     Name of the pool, max ODP_BUFFER_POOL_NAME_LEN-1
> chars.
> + *                     May be specified as NULL for anonymous pools.
>   *
> - * @return Buffer pool handle
> + * @param[in] shm      The shared memory object in which to create the
> pool.
> + *                     Use ODP_SHM_NULL to reserve default memory type
> + *                     for the buffer type.
> + *
> + * @param[in] params   Buffer pool parameters.
> + *
> + * @return Buffer pool handle or ODP_BUFFER_POOL_INVALID if call failed.
>   */
> +
>  odp_buffer_pool_t odp_buffer_pool_create(const char *name,
> -                                        void *base_addr, uint64_t size,
> -                                        size_t buf_size, size_t buf_align,
> -                                        int buf_type);
> +                                        odp_shm_t shm,
> +                                        odp_buffer_pool_param_t *params);
>
> +/**
> + * Destroy a buffer pool previously created by odp_buffer_pool_create()
> + *
> + * @param[in] pool    Handle of the buffer pool to be destroyed
> + *
> + * @return            0 on Success, -1 on Failure.
> + *
> + * @note This routine destroys a previously created buffer pool. This call
> + * does not destroy any shared memory object passed to
> + * odp_buffer_pool_create() used to store the buffer pool contents. The
> caller
> + * takes responsibility for that. If no shared memory object was passed as
> + * part of the create call, then this routine will destroy any internal
> shared
> + * memory objects associated with the buffer pool. Results are undefined
> if
> + * an attempt is made to destroy a buffer pool that contains allocated or
> + * otherwise active buffers.
> + */
> +int odp_buffer_pool_destroy(odp_buffer_pool_t pool);
>
>  /**
>   * Find a buffer pool by name
>   *
> - * @param name      Name of the pool
> + * @param[in] name      Name of the pool
>   *
>   * @return Buffer pool handle, or ODP_BUFFER_POOL_INVALID if not found.
> + *
> + * @note This routine cannot be used to look up an anonymous pool (one
> created
> + * with no name).
>   */
>  odp_buffer_pool_t odp_buffer_pool_lookup(const char *name);
>
> +/**
> + * @param[out] name   Pointer to the name of the buffer pool. NULL if this
> + *                    pool is anonymous.
> + *
> + * @param[out] shm    Handle of the shared memory object containing this
> pool,
> + *                    if pool was created from an application supplied
> shared
> + *                    memory area. Otherwise ODP_SHM_NULL.
> + *
> + * @param[out] params Copy of the odp_buffer_pool_param_t used to create
> this
> + *                    pool.
> + */
> +typedef struct odp_buffer_pool_info_t {
> +       const char *name;
> +       odp_buffer_pool_param_t params;
> +} odp_buffer_pool_info_t;
> +
> +/**
> + * Retrieve information about a buffer pool
> + *
> + * @param[in]  pool    Buffer pool handle
> + *
> + * @param[out] shm     Recieves odp_shm_t supplied by caller at
> + *                     pool creation, or ODP_SHM_NULL if the
> + *                     pool is managed internally.
> + *
> + * @param[out] info    Receives an odp_buffer_pool_info_t object
> + *                     that describes the pool.
> + *
> + * @return 0 on success, -1 if info could not be retrieved.
> + */
> +
> +int odp_buffer_pool_info(odp_buffer_pool_t pool, odp_shm_t *shm,
> +                        odp_buffer_pool_info_t *info);
>
>  /**
>   * Print buffer pool info
> --
> 1.8.3.2
>
>
diff mbox

Patch

diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h b/platform/linux-generic/include/api/odp_buffer_pool.h
index 30b83e0..d5f138e 100644
--- a/platform/linux-generic/include/api/odp_buffer_pool.h
+++ b/platform/linux-generic/include/api/odp_buffer_pool.h
@@ -36,32 +36,115 @@  extern "C" {
 #define ODP_BUFFER_POOL_INVALID   0
 
 /**
+ * Buffer pool parameters
+ *
+ * @param[in] buf_size   Buffer size in bytes. The maximum number
+ *                       of bytes application will store in each
+ *                       buffer.
+ *
+ * @param[in] buf_align  Minimum buffer alignment in bytes.  Valid values
+ *                       are powers of two. Use 0 for the default
+ *                       alignment. Default alignment is a multiple
+ *                       of 8.
+ *
+ * @param[in] num_bufs   Number of buffers in the pool.
+ *
+ * @param[in] buf_type   Buffer type
+ */
+typedef struct odp_buffer_pool_param_t {
+	size_t   buf_size;
+	size_t   buf_align;
+	uint32_t num_bufs;
+	int      buf_type;
+} odp_buffer_pool_param_t;
+
+/**
  * Create a buffer pool
+ * This routine is used to create a buffer pool. It take three
+ * arguments: the optional name of the pool to be created, an optional shared
+ * memory handle, and a parameter struct that describes the pool to be
+ * created. If a name is not specified the result is an anonymous pool that
+ * cannot be referenced by odp_buffer_pool_lookup().
  *
- * @param name      Name of the pool (max ODP_BUFFER_POOL_NAME_LEN - 1 chars)
- * @param base_addr Pool base address
- * @param size      Pool size in bytes
- * @param buf_size  Buffer size in bytes
- * @param buf_align Minimum buffer alignment
- * @param buf_type  Buffer type
+ * @param[in] name     Name of the pool, max ODP_BUFFER_POOL_NAME_LEN-1 chars.
+ *                     May be specified as NULL for anonymous pools.
  *
- * @return Buffer pool handle
+ * @param[in] shm      The shared memory object in which to create the pool.
+ *                     Use ODP_SHM_NULL to reserve default memory type
+ *                     for the buffer type.
+ *
+ * @param[in] params   Buffer pool parameters.
+ *
+ * @return Buffer pool handle or ODP_BUFFER_POOL_INVALID if call failed.
  */
+
 odp_buffer_pool_t odp_buffer_pool_create(const char *name,
-					 void *base_addr, uint64_t size,
-					 size_t buf_size, size_t buf_align,
-					 int buf_type);
+					 odp_shm_t shm,
+					 odp_buffer_pool_param_t *params);
 
+/**
+ * Destroy a buffer pool previously created by odp_buffer_pool_create()
+ *
+ * @param[in] pool    Handle of the buffer pool to be destroyed
+ *
+ * @return            0 on Success, -1 on Failure.
+ *
+ * @note This routine destroys a previously created buffer pool. This call
+ * does not destroy any shared memory object passed to
+ * odp_buffer_pool_create() used to store the buffer pool contents. The caller
+ * takes responsibility for that. If no shared memory object was passed as
+ * part of the create call, then this routine will destroy any internal shared
+ * memory objects associated with the buffer pool. Results are undefined if
+ * an attempt is made to destroy a buffer pool that contains allocated or
+ * otherwise active buffers.
+ */
+int odp_buffer_pool_destroy(odp_buffer_pool_t pool);
 
 /**
  * Find a buffer pool by name
  *
- * @param name      Name of the pool
+ * @param[in] name      Name of the pool
  *
  * @return Buffer pool handle, or ODP_BUFFER_POOL_INVALID if not found.
+ *
+ * @note This routine cannot be used to look up an anonymous pool (one created
+ * with no name).
  */
 odp_buffer_pool_t odp_buffer_pool_lookup(const char *name);
 
+/**
+ * @param[out] name   Pointer to the name of the buffer pool. NULL if this
+ *                    pool is anonymous.
+ *
+ * @param[out] shm    Handle of the shared memory object containing this pool,
+ *                    if pool was created from an application supplied shared
+ *                    memory area. Otherwise ODP_SHM_NULL.
+ *
+ * @param[out] params Copy of the odp_buffer_pool_param_t used to create this
+ *                    pool.
+ */
+typedef struct odp_buffer_pool_info_t {
+	const char *name;
+	odp_buffer_pool_param_t params;
+} odp_buffer_pool_info_t;
+
+/**
+ * Retrieve information about a buffer pool
+ *
+ * @param[in]  pool    Buffer pool handle
+ *
+ * @param[out] shm     Recieves odp_shm_t supplied by caller at
+ *                     pool creation, or ODP_SHM_NULL if the
+ *                     pool is managed internally.
+ *
+ * @param[out] info    Receives an odp_buffer_pool_info_t object
+ *                     that describes the pool.
+ *
+ * @return 0 on success, -1 if info could not be retrieved.
+ */
+
+int odp_buffer_pool_info(odp_buffer_pool_t pool, odp_shm_t *shm,
+			 odp_buffer_pool_info_t *info);
 
 /**
  * Print buffer pool info