api: queue: split queue spec header file

Split typedefs into a separate header file, so that queue functions
can be inlined. API content was not changed, only moved it.

Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org>
Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

3 files changed, 313 insertions, 276 deletions

diff --git a/include/Makefile.am b/include/Makefile.am
index 512002f87..97f528408 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -82,6 +82,7 @@ odpapispecinclude_HEADERS = \
 		  odp/api/spec/packet_io_stats.h \
 		  odp/api/spec/pool.h \
 		  odp/api/spec/queue.h \
+		  odp/api/spec/queue_types.h \
 		  odp/api/spec/random.h \
 		  odp/api/spec/rwlock.h \
 		  odp/api/spec/rwlock_recursive.h \
diff --git a/include/odp/api/spec/queue.h b/include/odp/api/spec/queue.h
index 3015d7799..2f5e1230f 100644
--- a/include/odp/api/spec/queue.h
+++ b/include/odp/api/spec/queue.h
@@ -19,8 +19,8 @@
 extern "C" {
 #endif
 
-#include <odp/api/schedule_types.h>
 #include <odp/api/event.h>
+#include <odp/api/spec/queue_types.h>
 
 /** @defgroup odp_queue ODP QUEUE
  *  Macros and operation on a queue.
@@ -43,272 +43,6 @@ extern "C" {
  */
 
 /**
- * Queue type
- */
-typedef enum odp_queue_type_t {
-	/** Plain queue
-	  *
-	  * Plain queues offer simple FIFO storage of events. Application may
-	  * dequeue directly from these queues. */
-	ODP_QUEUE_TYPE_PLAIN = 0,
-
-	/** Scheduled queue
-	  *
-	  * Scheduled queues are connected to the scheduler. Application must
-	  * not dequeue events directly from these queues but use the scheduler
-	  * instead. */
-	ODP_QUEUE_TYPE_SCHED
-} odp_queue_type_t;
-
-/**
- * Queue operation mode
- */
-typedef enum odp_queue_op_mode_t {
-	/** Multithread safe operation
-	  *
-	  * Queue operation (enqueue or dequeue) is multithread safe. Any
-	  * number of application threads may perform the operation
-	  * concurrently. */
-	ODP_QUEUE_OP_MT = 0,
-
-	/** Not multithread safe operation
-	  *
-	  * Queue operation (enqueue or dequeue) may not be multithread safe.
-	  * Application ensures synchronization between threads so that
-	  * simultaneously only single thread attempts the operation on
-	  * the same queue. */
-	ODP_QUEUE_OP_MT_UNSAFE,
-
-	/** Disabled
-	  *
-	  * Direct enqueue or dequeue operation from application is disabled.
-	  * An attempt to enqueue/dequeue directly will result undefined
-	  * behaviour. Various ODP functions (e.g. packet input, timer,
-	  * crypto, scheduler, etc) are able to perform enqueue or
-	  * dequeue operations normally on the queue.
-	  * */
-	ODP_QUEUE_OP_DISABLED
-
-} odp_queue_op_mode_t;
-
-/**
- * Non-blocking level
- *
- * A non-blocking level defines implementation guarantees for application
- * progress when multiple threads operate on the same resource (e.g. a queue)
- * simultaneously. The first level (ODP_BLOCKING) does not have any block
- * freedom guarantees, but a suspending thread may block the other threads for
- * the entire time it remains suspended (infinitely if crashed).
- * On the contrary, actual non-blocking levels provide guarantees of progress:
- *
- * ODP_NONBLOCKING_LF:  A non-blocking and lock-free implementation guarantees
- *                      that at least one of the threads successfully completes
- *                      its operations, regardless of what other threads do.
- *                      Application progress is guaranteed, but individual
- *                      threads may starve while trying to execute their
- *                      operations on the shared resource.
- *
- * ODP_NONBLOCKING_WF:  A non-blocking and wait-free implementation guarantees
- *                      application progress with starvation freedom. All
- *                      threads are guaranteed to complete their operations in
- *                      a bounded number of steps, regardless of what other
- *                      threads do.
- *
- * Non-blocking levels are listed from the weakest to the strongest guarantee of
- * block freedom. Performance of a non-blocking implementation may be lower than
- * the blocking one. Non-blocking guarantees are important e.g. for real-time
- * applications when real-time and non real-time threads share a resource.
- */
-typedef enum odp_nonblocking_t {
-	/** Blocking implementation. A suspeding thread may block all other
-	 *  threads, i.e. no block freedom guarantees. This is the lowest level.
-	 */
-	ODP_BLOCKING = 0,
-
-	/** Non-blocking and lock-free implementation. Other threads can make
-	 *  progress while a thread is suspended. Starvation freedom is not
-	 *  guaranteed.
-	 */
-	ODP_NONBLOCKING_LF,
-
-	/** Non-blocking and wait-free implementation. Other threads can make
-	 *  progress while a thread is suspended. Starvation freedom is
-	 *  guaranteed.
-	 */
-	ODP_NONBLOCKING_WF
-
-} odp_nonblocking_t;
-
-/**
- * Queue capabilities
- */
-typedef struct odp_queue_capability_t {
-	/** Maximum number of event queues of any type (default size). Use
-	  * this in addition to queue type specific 'max_num', if both queue
-	  * types are used simultaneously. */
-	uint32_t max_queues;
-
-	/** Maximum number of ordered locks per queue */
-	uint32_t max_ordered_locks;
-
-	/** Maximum number of scheduling groups */
-	unsigned max_sched_groups;
-
-	/** Number of scheduling priorities */
-	unsigned sched_prios;
-
-	/** Plain queue capabilities */
-	struct {
-		/** Maximum number of plain (ODP_BLOCKING) queues of the
-		  * default size. */
-		uint32_t max_num;
-
-		/** Maximum number of events a plain (ODP_BLOCKING) queue can
-		  * store simultaneously. The value of zero means that plain
-		  * queues do not have a size limit, but a single queue can
-		  * store all available events. */
-		uint32_t max_size;
-
-		/** Lock-free (ODP_NONBLOCKING_LF) implementation capabilities.
-		  * The specification is the same as for the blocking
-		  * implementation. */
-		struct {
-			/** Maximum number of queues. Lock-free queues are not
-			  * supported when zero. */
-			uint32_t max_num;
-
-			/** Maximum queue size */
-			uint32_t max_size;
-
-		} lockfree;
-
-		/** Wait-free (ODP_NONBLOCKING_WF) implementation capabilities.
-		  * The specification is the same as for the blocking
-		  * implementation. */
-		struct {
-			/** Maximum number of queues. Wait-free queues are not
-			  * supported when zero. */
-			uint32_t max_num;
-
-			/** Maximum queue size */
-			uint32_t max_size;
-
-		} waitfree;
-
-	} plain;
-
-	/** Scheduled queue capabilities */
-	struct {
-		/** Maximum number of scheduled (ODP_BLOCKING) queues of the
-		  * default size. */
-		uint32_t max_num;
-
-		/** Maximum number of events a scheduled (ODP_BLOCKING) queue
-		  * can store simultaneously. The value of zero means that
-		  * scheduled queues do not have a size limit, but a single
-		  * queue can store all available events. */
-		uint32_t max_size;
-
-		/** Lock-free (ODP_NONBLOCKING_LF) implementation capabilities.
-		  * The specification is the same as for the blocking
-		  * implementation. */
-		struct {
-			/** Maximum number of queues. Lock-free queues are not
-			  * supported when zero. */
-			uint32_t max_num;
-
-			/** Maximum queue size */
-			uint32_t max_size;
-
-		} lockfree;
-
-		/** Wait-free (ODP_NONBLOCKING_WF) implementation capabilities.
-		  * The specification is the same as for the blocking
-		  * implementation. */
-		struct {
-			/** Maximum number of queues. Wait-free queues are not
-			  * supported when zero. */
-			uint32_t max_num;
-
-			/** Maximum queue size */
-			uint32_t max_size;
-
-		} waitfree;
-
-	} sched;
-
-} odp_queue_capability_t;
-
-/**
- * ODP Queue parameters
- */
-typedef struct odp_queue_param_t {
-	/** Queue type
-	  *
-	  * Valid values for other parameters in this structure depend on
-	  * the queue type. */
-	odp_queue_type_t type;
-
-	/** Enqueue mode
-	  *
-	  * Default value for both queue types is ODP_QUEUE_OP_MT. Application
-	  * may enable performance optimizations by defining MT_UNSAFE or
-	  * DISABLED modes when applicable. */
-	odp_queue_op_mode_t enq_mode;
-
-	/** Dequeue mode
-	  *
-	  * For PLAIN queues, the default value is ODP_QUEUE_OP_MT. Application
-	  * may enable performance optimizations by defining MT_UNSAFE or
-	  * DISABLED modes when applicable. However, when a plain queue is input
-	  * to the implementation (e.g. a queue for packet output), the
-	  * parameter is ignored in queue creation and the value is
-	  * ODP_QUEUE_OP_DISABLED.
-	  *
-	  * For SCHED queues, the parameter is ignored in queue creation and
-	  * the value is ODP_QUEUE_OP_DISABLED. */
-	odp_queue_op_mode_t deq_mode;
-
-	/** Scheduler parameters
-	  *
-	  * These parameters are considered only when queue type is
-	  * ODP_QUEUE_TYPE_SCHED. */
-	odp_schedule_param_t sched;
-
-	/** Non-blocking level
-	  *
-	  * Queue implementation must guarantee at least this level of block
-	  * freedom for queue enqueue and dequeue/schedule operations.
-	  * The default value is ODP_BLOCKING. */
-	odp_nonblocking_t nonblocking;
-
-	/** Queue context pointer
-	  *
-	  * User defined context pointer associated with the queue. The same
-	  * pointer can be accessed with odp_queue_context() and
-	  * odp_queue_context_set() calls. The implementation may read the
-	  * pointer for prefetching the context data. Default value of the
-	  * pointer is NULL. */
-	void *context;
-
-	/** Queue context data length
-	  *
-	  * User defined context data length in bytes for prefetching.
-	  * The implementation may use this value as a hint for the number of
-	  * context data bytes to prefetch. Default value is zero (no hint). */
-	uint32_t context_len;
-
-	/** Queue size
-	  *
-	  * The queue must be able to store at minimum this many events
-	  * simultaneously. The value must not exceed 'max_size' queue
-	  * capability. The value of zero means implementation specific
-	  * default size. */
-	uint32_t size;
-
-} odp_queue_param_t;
-
-/**
  * Queue create
  *
  * Create a queue according to the queue parameters. Queue type is specified by
@@ -528,15 +262,6 @@ uint64_t odp_queue_to_u64(odp_queue_t hdl);
 void odp_queue_param_init(odp_queue_param_t *param);
 
 /**
- * Queue information
- * Retrieve information about a queue with odp_queue_info()
- */
-typedef struct odp_queue_info_t {
-	const char *name;         /**< queue name */
-	odp_queue_param_t param;  /**< queue parameters */
-} odp_queue_info_t;
-
-/**
  * Retrieve information about a queue
  *
  * Invalid queue handles or handles to free/destroyed queues leads to
diff --git a/include/odp/api/spec/queue_types.h b/include/odp/api/spec/queue_types.h
new file mode 100644
index 000000000..be7e79a81
--- /dev/null
+++ b/include/odp/api/spec/queue_types.h
@@ -0,0 +1,311 @@
+/* Copyright (c) 2018, Linaro Limited
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier:     BSD-3-Clause
+ */
+
+/**
+ * @file
+ *
+ * ODP queue types
+ */
+
+#ifndef ODP_API_SPEC_QUEUE_TYPES_H_
+#define ODP_API_SPEC_QUEUE_TYPES_H_
+#include <odp/visibility_begin.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <odp/api/schedule_types.h>
+
+/** @addtogroup odp_queue
+ *  @{
+ */
+
+/**
+ * Queue type
+ */
+typedef enum odp_queue_type_t {
+	/** Plain queue
+	  *
+	  * Plain queues offer simple FIFO storage of events. Application may
+	  * dequeue directly from these queues. */
+	ODP_QUEUE_TYPE_PLAIN = 0,
+
+	/** Scheduled queue
+	  *
+	  * Scheduled queues are connected to the scheduler. Application must
+	  * not dequeue events directly from these queues but use the scheduler
+	  * instead. */
+	ODP_QUEUE_TYPE_SCHED
+} odp_queue_type_t;
+
+/**
+ * Queue operation mode
+ */
+typedef enum odp_queue_op_mode_t {
+	/** Multithread safe operation
+	  *
+	  * Queue operation (enqueue or dequeue) is multithread safe. Any
+	  * number of application threads may perform the operation
+	  * concurrently. */
+	ODP_QUEUE_OP_MT = 0,
+
+	/** Not multithread safe operation
+	  *
+	  * Queue operation (enqueue or dequeue) may not be multithread safe.
+	  * Application ensures synchronization between threads so that
+	  * simultaneously only single thread attempts the operation on
+	  * the same queue. */
+	ODP_QUEUE_OP_MT_UNSAFE,
+
+	/** Disabled
+	  *
+	  * Direct enqueue or dequeue operation from application is disabled.
+	  * An attempt to enqueue/dequeue directly will result undefined
+	  * behaviour. Various ODP functions (e.g. packet input, timer,
+	  * crypto, scheduler, etc) are able to perform enqueue or
+	  * dequeue operations normally on the queue.
+	  * */
+	ODP_QUEUE_OP_DISABLED
+
+} odp_queue_op_mode_t;
+
+/**
+ * Non-blocking level
+ *
+ * A non-blocking level defines implementation guarantees for application
+ * progress when multiple threads operate on the same resource (e.g. a queue)
+ * simultaneously. The first level (ODP_BLOCKING) does not have any block
+ * freedom guarantees, but a suspending thread may block the other threads for
+ * the entire time it remains suspended (infinitely if crashed).
+ * On the contrary, actual non-blocking levels provide guarantees of progress:
+ *
+ * ODP_NONBLOCKING_LF:  A non-blocking and lock-free implementation guarantees
+ *                      that at least one of the threads successfully completes
+ *                      its operations, regardless of what other threads do.
+ *                      Application progress is guaranteed, but individual
+ *                      threads may starve while trying to execute their
+ *                      operations on the shared resource.
+ *
+ * ODP_NONBLOCKING_WF:  A non-blocking and wait-free implementation guarantees
+ *                      application progress with starvation freedom. All
+ *                      threads are guaranteed to complete their operations in
+ *                      a bounded number of steps, regardless of what other
+ *                      threads do.
+ *
+ * Non-blocking levels are listed from the weakest to the strongest guarantee of
+ * block freedom. Performance of a non-blocking implementation may be lower than
+ * the blocking one. Non-blocking guarantees are important e.g. for real-time
+ * applications when real-time and non real-time threads share a resource.
+ */
+typedef enum odp_nonblocking_t {
+	/** Blocking implementation. A suspeding thread may block all other
+	 *  threads, i.e. no block freedom guarantees. This is the lowest level.
+	 */
+	ODP_BLOCKING = 0,
+
+	/** Non-blocking and lock-free implementation. Other threads can make
+	 *  progress while a thread is suspended. Starvation freedom is not
+	 *  guaranteed.
+	 */
+	ODP_NONBLOCKING_LF,
+
+	/** Non-blocking and wait-free implementation. Other threads can make
+	 *  progress while a thread is suspended. Starvation freedom is
+	 *  guaranteed.
+	 */
+	ODP_NONBLOCKING_WF
+
+} odp_nonblocking_t;
+
+/**
+ * Queue capabilities
+ */
+typedef struct odp_queue_capability_t {
+	/** Maximum number of event queues of any type (default size). Use
+	  * this in addition to queue type specific 'max_num', if both queue
+	  * types are used simultaneously. */
+	uint32_t max_queues;
+
+	/** Maximum number of ordered locks per queue */
+	uint32_t max_ordered_locks;
+
+	/** Maximum number of scheduling groups */
+	unsigned max_sched_groups;
+
+	/** Number of scheduling priorities */
+	unsigned sched_prios;
+
+	/** Plain queue capabilities */
+	struct {
+		/** Maximum number of plain (ODP_BLOCKING) queues of the
+		  * default size. */
+		uint32_t max_num;
+
+		/** Maximum number of events a plain (ODP_BLOCKING) queue can
+		  * store simultaneously. The value of zero means that plain
+		  * queues do not have a size limit, but a single queue can
+		  * store all available events. */
+		uint32_t max_size;
+
+		/** Lock-free (ODP_NONBLOCKING_LF) implementation capabilities.
+		  * The specification is the same as for the blocking
+		  * implementation. */
+		struct {
+			/** Maximum number of queues. Lock-free queues are not
+			  * supported when zero. */
+			uint32_t max_num;
+
+			/** Maximum queue size */
+			uint32_t max_size;
+
+		} lockfree;
+
+		/** Wait-free (ODP_NONBLOCKING_WF) implementation capabilities.
+		  * The specification is the same as for the blocking
+		  * implementation. */
+		struct {
+			/** Maximum number of queues. Wait-free queues are not
+			  * supported when zero. */
+			uint32_t max_num;
+
+			/** Maximum queue size */
+			uint32_t max_size;
+
+		} waitfree;
+
+	} plain;
+
+	/** Scheduled queue capabilities */
+	struct {
+		/** Maximum number of scheduled (ODP_BLOCKING) queues of the
+		  * default size. */
+		uint32_t max_num;
+
+		/** Maximum number of events a scheduled (ODP_BLOCKING) queue
+		  * can store simultaneously. The value of zero means that
+		  * scheduled queues do not have a size limit, but a single
+		  * queue can store all available events. */
+		uint32_t max_size;
+
+		/** Lock-free (ODP_NONBLOCKING_LF) implementation capabilities.
+		  * The specification is the same as for the blocking
+		  * implementation. */
+		struct {
+			/** Maximum number of queues. Lock-free queues are not
+			  * supported when zero. */
+			uint32_t max_num;
+
+			/** Maximum queue size */
+			uint32_t max_size;
+
+		} lockfree;
+
+		/** Wait-free (ODP_NONBLOCKING_WF) implementation capabilities.
+		  * The specification is the same as for the blocking
+		  * implementation. */
+		struct {
+			/** Maximum number of queues. Wait-free queues are not
+			  * supported when zero. */
+			uint32_t max_num;
+
+			/** Maximum queue size */
+			uint32_t max_size;
+
+		} waitfree;
+
+	} sched;
+
+} odp_queue_capability_t;
+
+/**
+ * ODP Queue parameters
+ */
+typedef struct odp_queue_param_t {
+	/** Queue type
+	  *
+	  * Valid values for other parameters in this structure depend on
+	  * the queue type. */
+	odp_queue_type_t type;
+
+	/** Enqueue mode
+	  *
+	  * Default value for both queue types is ODP_QUEUE_OP_MT. Application
+	  * may enable performance optimizations by defining MT_UNSAFE or
+	  * DISABLED modes when applicable. */
+	odp_queue_op_mode_t enq_mode;
+
+	/** Dequeue mode
+	  *
+	  * For PLAIN queues, the default value is ODP_QUEUE_OP_MT. Application
+	  * may enable performance optimizations by defining MT_UNSAFE or
+	  * DISABLED modes when applicable. However, when a plain queue is input
+	  * to the implementation (e.g. a queue for packet output), the
+	  * parameter is ignored in queue creation and the value is
+	  * ODP_QUEUE_OP_DISABLED.
+	  *
+	  * For SCHED queues, the parameter is ignored in queue creation and
+	  * the value is ODP_QUEUE_OP_DISABLED. */
+	odp_queue_op_mode_t deq_mode;
+
+	/** Scheduler parameters
+	  *
+	  * These parameters are considered only when queue type is
+	  * ODP_QUEUE_TYPE_SCHED. */
+	odp_schedule_param_t sched;
+
+	/** Non-blocking level
+	  *
+	  * Queue implementation must guarantee at least this level of block
+	  * freedom for queue enqueue and dequeue/schedule operations.
+	  * The default value is ODP_BLOCKING. */
+	odp_nonblocking_t nonblocking;
+
+	/** Queue context pointer
+	  *
+	  * User defined context pointer associated with the queue. The same
+	  * pointer can be accessed with odp_queue_context() and
+	  * odp_queue_context_set() calls. The implementation may read the
+	  * pointer for prefetching the context data. Default value of the
+	  * pointer is NULL. */
+	void *context;
+
+	/** Queue context data length
+	  *
+	  * User defined context data length in bytes for prefetching.
+	  * The implementation may use this value as a hint for the number of
+	  * context data bytes to prefetch. Default value is zero (no hint). */
+	uint32_t context_len;
+
+	/** Queue size
+	  *
+	  * The queue must be able to store at minimum this many events
+	  * simultaneously. The value must not exceed 'max_size' queue
+	  * capability. The value of zero means implementation specific
+	  * default size. */
+	uint32_t size;
+
+} odp_queue_param_t;
+
+/**
+ * Queue information
+ * Retrieve information about a queue with odp_queue_info()
+ */
+typedef struct odp_queue_info_t {
+	const char *name;         /**< queue name */
+	odp_queue_param_t param;  /**< queue parameters */
+} odp_queue_info_t;
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#include <odp/visibility_end.h>
+#endif