1 files changed, 55 insertions, 25 deletions
diff --git a/include/odp/api/spec/buffer.h b/include/odp/api/spec/buffer.h
index 94829b324..5ce2355b8 100644
--- a/include/odp/api/spec/buffer.h
+++ b/include/odp/api/spec/buffer.h
@@ -1,37 +1,30 @@
-/* Copyright (c) 2013, Linaro Limited
- * All rights reserved.
- *
- * SPDX-License-Identifier:     BSD-3-Clause
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright (c) 2013-2018 Linaro Limited
+ * Copyright (c) 2022-2023 Nokia
  */
 
-
 /**
  * @file
  *
- * ODP buffer descriptor
+ * ODP buffer
  */
 
-#ifndef ODP_API_BUFFER_H_
-#define ODP_API_BUFFER_H_
+#ifndef ODP_API_SPEC_BUFFER_H_
+#define ODP_API_SPEC_BUFFER_H_
 #include <odp/visibility_begin.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/** @defgroup odp_buffer ODP BUFFER
- *  Operations on a buffer.
- *  @{
- */
+#include <odp/api/buffer_types.h>
+#include <odp/api/event_types.h>
+#include <odp/api/pool_types.h>
+#include <odp/api/std_types.h>
 
-/**
- * @typedef odp_buffer_t
- * ODP buffer
- */
-
-/**
- * @def ODP_BUFFER_INVALID
- * Invalid buffer
+/** @addtogroup odp_buffer
+ *  Buffer event metadata and operations.
+ *  @{
  */
 
 /**
@@ -48,6 +41,17 @@ extern "C" {
 odp_buffer_t odp_buffer_from_event(odp_event_t ev);
 
 /**
+ * Convert multiple buffer events to buffer handles
+ *
+ * All events must be of type ODP_EVENT_BUFFER.
+ *
+ * @param[out] buf  Buffer handle array for output
+ * @param      ev   Array of event handles to convert
+ * @param      num  Number of buffers and events
+ */
+void odp_buffer_from_event_multi(odp_buffer_t buf[], const odp_event_t ev[], int num);
+
+/**
  * Convert buffer handle to event
  *
  * @param buf  Buffer handle
@@ -57,6 +61,15 @@ odp_buffer_t odp_buffer_from_event(odp_event_t ev);
 odp_event_t odp_buffer_to_event(odp_buffer_t buf);
 
 /**
+ * Convert multiple buffer handles to events
+ *
+ * @param      buf  Array of buffer handles to convert
+ * @param[out] ev   Event handle array for output
+ * @param      num  Number of buffers and events
+ */
+void odp_buffer_to_event_multi(const odp_buffer_t buf[], odp_event_t ev[], int num);
+
+/**
  * Buffer start address
  *
  * @param buf      Buffer handle
@@ -75,7 +88,24 @@ void *odp_buffer_addr(odp_buffer_t buf);
 uint32_t odp_buffer_size(odp_buffer_t buf);
 
 /**
- * Tests if buffer is valid
+ * Buffer user area
+ *
+ * Returns pointer to the user area associated with the buffer. Size of the area is fixed
+ * and defined in buffer pool parameters.
+ *
+ * @param buf      Buffer handle
+ *
+ * @return       Pointer to the user area of the buffer
+ * @retval NULL  The buffer does not have user area
+ */
+void *odp_buffer_user_area(odp_buffer_t buf);
+
+/**
+ * Check that buffer is valid
+ *
+ * This function can be used for debugging purposes to check if a buffer handle represents
+ * a valid buffer. The level of error checks depends on the implementation. The call should not
+ * crash if the buffer handle is corrupted.
  *
  * @param buf      Buffer handle
  *
@@ -96,8 +126,8 @@ odp_pool_t odp_buffer_pool(odp_buffer_t buf);
 /**
  * Buffer alloc
  *
- * The validity of a buffer can be checked at any time with
- * odp_buffer_is_valid().
+ * Allocates a buffer from the pool. Returns ODP_BUFFER_INVALID when a buffer
+ * can not be allocated.
  *
  * @param pool      Pool handle
  *
@@ -108,8 +138,8 @@ odp_buffer_t odp_buffer_alloc(odp_pool_t pool);
 
 /**
  * Allocate multiple buffers
-
- * Otherwise like odp_buffer_alloc(), but allocates multiple buffers from a pool
+ *
+ * Otherwise like odp_buffer_alloc(), but allocates multiple buffers from a pool.
  *
  * @param pool      Pool handle
  * @param[out] buf  Array of buffer handles for output