doxygen: define groups for microkernel objects

Also add conditionals to hide internal functions

Change-Id: I795e540ec082244f77f02cf8347b3e74916e4402
Signed-off-by: Anas Nashif <anas.nashif@intel.com>

include/microkernel/base_api.h

@@ -119,6 +119,9 @@ struct k_task {
 	struct k_args *args;
 };
 
+/**
+ * @cond internal
+ */
 struct _k_mbox_struct {
 	struct k_args *writers;
 	struct k_args *readers;
@@ -213,12 +216,6 @@ struct _k_pipe_struct {
 	int count;
 };
 
-typedef enum {
-	_0_TO_N = 0x00000001,
-	_1_TO_N = 0x00000002,
-	_ALL_N = 0x00000004
-} K_PIPE_OPTION;
-
 /* Memory map related structure */
 
 struct _k_mem_map_struct {
@@ -232,6 +229,17 @@ struct _k_mem_map_struct {
 	int count;
 };
 
+/**
+ * @endconf
+ */
+
+typedef enum {
+	_0_TO_N = 0x00000001,
+	_1_TO_N = 0x00000002,
+	_ALL_N = 0x00000004
+} K_PIPE_OPTION;
+
+
 #ifdef __cplusplus
 }
 #endif

include/microkernel/event.h

@@ -52,6 +52,24 @@ extern "C" {
 /* well-known events */
 
 #define TICK_EVENT	0
+/**
+ * @cond internal
+ */
+/**
+ *
+ * @brief Test for event request
+ *
+ * This routine tests an event to see if it has been signaled.
+ *
+ * @param event Event for which to test.
+ * @param time Maximum number of ticks to wait for event.
+ *
+ * @return RC_OK, RC_FAIL, RC_TIME on success, failure, timeout respectively
+ */
+extern int _task_event_recv(kevent_t event, int32_t time);
+/**
+ * @endcond
+ */
 
 /**
  *
@@ -112,19 +130,6 @@ extern int task_event_handler_set(kevent_t event, kevent_handler_t handler);
  */
 extern int task_event_send(kevent_t event);
 
-/**
- *
- * @brief Test for event request
- *
- * This routine tests an event to see if it has been signaled.
- *
- * @param event Event for which to test.
- * @param time Maximum number of ticks to wait for event.
- *
- * @return RC_OK, RC_FAIL, RC_TIME on success, failure, timeout respectively
- */
-extern int _task_event_recv(kevent_t event, int32_t time);
-
 /**
  *
  * @brief Test for event request

include/microkernel/fifo.h

@@ -53,10 +53,34 @@
 extern "C" {
 #endif
 
+/**
+ * @cond internal
+ */
 extern int _task_fifo_put(kfifo_t queue, void *data, int32_t time);
 extern int _task_fifo_get(kfifo_t queue, void *data, int32_t time);
 extern int _task_fifo_ioctl(kfifo_t queue, int op);
 
+/**
+ * @brief Initializer for microkernel FIFO
+ */
+#define __K_FIFO_DEFAULT(depth, width, buffer) \
+	{ \
+	  .Nelms = depth,\
+	  .element_size = width,\
+	  .base = buffer,\
+	  .end_point = (buffer + (depth * width)),\
+	  .enqueue_point = buffer,\
+	  .dequeue_point = buffer,\
+	  .waiters = NULL,\
+	  .num_used = 0,\
+	  .high_watermark = 0,\
+	  .count = 0,\
+	}
+
+/**
+ * @endcond
+ */
+
 /**
  * @brief FIFO enqueue request
  *
@@ -163,22 +187,6 @@ extern int _task_fifo_ioctl(kfifo_t queue, int op);
  */
 #define task_fifo_purge(q) _task_fifo_ioctl(q, 1)
 
-/**
- * @brief Initializer for microkernel FIFO
- */
-#define __K_FIFO_DEFAULT(depth, width, buffer) \
-	{ \
-	  .Nelms = depth,\
-	  .element_size = width,\
-	  .base = buffer,\
-	  .end_point = (buffer + (depth * width)),\
-	  .enqueue_point = buffer,\
-	  .dequeue_point = buffer,\
-	  .waiters = NULL,\
-	  .num_used = 0,\
-	  .high_watermark = 0,\
-	  .count = 0,\
-	}
 
 /**
  * @brief Define a private microkernel FIFO

include/microkernel/mailbox.h

@@ -51,6 +51,9 @@
 extern "C" {
 #endif
 
+/**
+ * @cond internal
+ */
 extern int _task_mbox_put(kmbox_t mbox,
 		                  kpriority_t prio,
 		                  struct k_msg *M,
@@ -69,6 +72,18 @@ extern int _task_mbox_data_block_get(struct k_msg *M,
 				 struct k_block *rxblock,
 				 kmemory_pool_t pid,
 				 int32_t time);
+/**
+ * @brief Initializer for microkernel mailbox
+ */
+#define __K_MAILBOX_DEFAULT \
+	{ \
+	  .writers = NULL, \
+	  .readers = NULL, \
+	  .count = 0, \
+	}
+/**
+ * @endcond
+ */
 
 /**
  * @brief Send a message to a mailbox
@@ -221,15 +236,6 @@ extern int _task_mbox_data_block_get(struct k_msg *M,
 		_task_mbox_data_block_get(m, b, p, t)
 #endif
 
-/**
- * @brief Initializer for microkernel mailbox
- */
-#define __K_MAILBOX_DEFAULT \
-	{ \
-	  .writers = NULL, \
-	  .readers = NULL, \
-	  .count = 0, \
-	}
 
 /**
  * @brief Define a private microkernel mailbox

include/microkernel/memory_map.h

@@ -32,6 +32,13 @@
  * @brief Memory map kernel services.
  */
 
+/**
+ * @brief Microkernel Memory Maps
+ * @defgroup microkernel_memorymap Microkernel Memomry Maps
+ * @ingroup microkernel_services
+ * @{
+ */
+
 #ifndef _MEMORY_MAP_H
 #define _MEMORY_MAP_H
 
@@ -41,9 +48,29 @@ extern "C" {
 
 #include <sections.h>
 
+/**
+ * @cond internal
+ */
 extern int _task_mem_map_alloc(kmemory_map_t mmap, void **mptr, int32_t time);
 extern void _task_mem_map_free(kmemory_map_t mmap, void **mptr);
 
+/**
+ * @brief Initialize a memory map struct.
+ *
+ * @param blocks Number of blocks.
+ * @param block_size Block Size (in bytes).
+ */
+#define __K_MEM_MAP_INITIALIZER(blocks, block_size, buffer) \
+	{ \
+	  .Nelms = blocks, \
+	  .element_size = block_size, \
+	  .base = buffer, \
+	}
+
+/**
+ * @endcond
+ */
+
 /**
  * @brief Read the number of used blocks in a memory map
  *
@@ -112,19 +139,6 @@ extern int task_mem_map_used_get(kmemory_map_t map);
 #define task_mem_map_alloc_wait_timeout(m, p, t) _task_mem_map_alloc(m, p, t)
 #endif
 
-/**
- * @brief Initialize a memory map struct.
- *
- * @param blocks Number of blocks.
- * @param block_size Block Size (in bytes).
- */
-#define __K_MEM_MAP_INITIALIZER(blocks, block_size, buffer) \
-	{ \
-	  .Nelms = blocks, \
-	  .element_size = block_size, \
-	  .base = buffer, \
-	}
-
 /**
  * @brief Define a private microkernel memory map.
  *
@@ -146,3 +160,6 @@ extern int task_mem_map_used_get(kmemory_map_t map);
 #endif
 
 #endif /* _MEMORY_MAP_H */
+/**
+ * @}
+ */

include/microkernel/memory_pool.h

@@ -46,10 +46,17 @@ extern "C" {
  * @ingroup microkernel_services
  * @{
  */
-
+/**
+ * @cond internal
+ */
 
 extern int _task_mem_pool_alloc(struct k_block *B, kmemory_pool_t pid, int size, int32_t time);
 
+
+/**
+ * @endcond
+ */
+
 /**
  * @brief Return memory pool block request
  *

include/microkernel/mutex.h

@@ -36,6 +36,7 @@
 /**
  * @brief Microkernel Mutexes
  * @defgroup microkernel_mutex Microkernel Mutexes
+ * @ingroup microkernel_services
  * @{
  */
 
@@ -50,6 +51,9 @@ extern "C" {
 
 #include  <microkernel/base_api.h>
 
+/**
+ * @cond internal
+ */
 /**
  * @brief This routine is the entry to the mutex lock kernel service.
  *
@@ -69,6 +73,24 @@ extern int _task_mutex_lock(kmutex_t mutex, int32_t time);
  */
 extern void _task_mutex_unlock(kmutex_t mutex);
 
+/**
+ * @brief Initializer for mutexes
+ */
+#define __MUTEX_DEFAULT \
+	{ \
+	  .owner = ANYTASK, \
+	  .current_owner_priority = 64, \
+	  .original_owner_priority = 64, \
+	  .level = 0, \
+	  .waiters = NULL, \
+	  .count = 0, \
+	  .num_conflicts = 0, \
+	}
+
+/**
+ * @endcond
+ */
+
 /**
  * @brief Try to lock mutex.
  *
@@ -119,20 +141,6 @@ extern void _task_mutex_unlock(kmutex_t mutex);
  */
 #define task_mutex_unlock(m) _task_mutex_unlock(m)
 
-/**
- * @brief Initializer for mutexes
- */
-#define __MUTEX_DEFAULT \
-	{ \
-	  .owner = ANYTASK, \
-	  .current_owner_priority = 64, \
-	  .original_owner_priority = 64, \
-	  .level = 0, \
-	  .waiters = NULL, \
-	  .count = 0, \
-	  .num_conflicts = 0, \
-	}
-
 /**
  * @brief Define a private mutex
  *

include/microkernel/pipe.h

@@ -38,14 +38,17 @@ extern "C" {
 #endif
 
 /**
- * @brief Pipes
- * @defgroup microkernel_pipes Microkernel Pipes
+ * @brief Microkernel Pipes
+ * @defgroup microkernel_pipe Microkernel Pipes
  * @ingroup microkernel_services
  * @{
  */
 
 #include <sections.h>
 
+/**
+ * @cond internal
+ */
 extern int _task_pipe_put(kpipe_t id,
 			void *pBuffer,
 			int iNbrBytesToWrite,
@@ -53,6 +56,24 @@ extern int _task_pipe_put(kpipe_t id,
 			K_PIPE_OPTION Option,
 			int32_t TimeOut);
 
+/**
+ * @internal
+ * @brief Initialize a pipe struct.
+ *
+ * @param size Size of pipe buffer.
+ * @param buffer Pointer to the buffer.
+ * @endinternal
+ */
+#define __K_PIPE_INITIALIZER(size, buffer) \
+	{ \
+	  .buffer_size = size, \
+	  .Buffer = buffer, \
+	}
+
+/**
+ * @endcond
+ */
+
 /**
  * @brief Pipe write request
  *
@@ -186,19 +207,6 @@ extern int _task_pipe_block_put(kpipe_t id,
 #define task_pipe_block_put(id, block, size, sema) \
 			_task_pipe_block_put(id, block, size, sema)
 
-/**
- * @internal
- * @brief Initialize a pipe struct.
- *
- * @param size Size of pipe buffer.
- * @param buffer Pointer to the buffer.
- * @endinternal
- */
-#define __K_PIPE_INITIALIZER(size, buffer) \
-	{ \
-	  .buffer_size = size, \
-	  .Buffer = buffer, \
-	}
 
 /**
  * @brief Define a private microkernel pipe.

include/microkernel/semaphore.h

@@ -37,6 +37,13 @@
 #ifndef _SEMAPHORE_H
 #define _SEMAPHORE_H
 
+/**
+ * @brief Microkernel Semaphores
+ * @defgroup microkernel_semaphore Microkernel Semaphores
+ * @ingroup microkernel_services
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -144,6 +151,11 @@ extern void task_sem_reset(ksem_t sema);
  */
 extern void task_sem_group_reset(ksemg_t semagroup);
 
+
+
+/**
+ * @cond internal
+ */
 /**
  *
  * @brief Test a semaphore
@@ -175,6 +187,20 @@ extern int _task_sem_take(ksem_t sema, int32_t time);
  */
 extern ksem_t _task_sem_group_take(ksemg_t semagroup, int32_t time);
 
+/**
+ * @brief Initializer for microkernel semaphores
+ */
+#define __K_SEMAPHORE_DEFAULT \
+	{ \
+	  .waiters = NULL, \
+	  .level = 0, \
+	  .count = 0, \
+	}
+
+/**
+ * @endcond
+ */
+
 /**
  *
  * @brief Test a semaphore
@@ -252,15 +278,6 @@ extern ksem_t _task_sem_group_take(ksemg_t semagroup, int32_t time);
 #define task_sem_group_take_wait_timeout(g, t) _task_sem_group_take(g, t)
 #endif
 
-/**
- * @brief Initializer for microkernel semaphores
- */
-#define __K_SEMAPHORE_DEFAULT \
-	{ \
-	  .waiters = NULL, \
-	  .level = 0, \
-	  .count = 0, \
-	}
 
 /**
  * @brief Define a private microkernel semaphore
@@ -278,4 +295,7 @@ extern ksem_t _task_sem_group_take(ksemg_t semagroup, int32_t time);
 }
 #endif
 
+/**
+ * @}
+ */
 #endif /* _SEMAPHORE_H */

include/microkernel/task.h

@@ -32,6 +32,12 @@
 
 #ifndef TASK_H
 #define TASK_H
+/**
+ * @brief Microkernel Tasks
+ * @defgroup microkernel_task Microkernel Tasks
+ * @ingroup microkernel_services
+ * @{
+ */
 
 #ifdef __cplusplus
 extern "C" {
@@ -50,11 +56,37 @@ extern "C" {
 #define USR_GROUP 2 /* TASKGROUP SYS */
 #define FPU_GROUP 4 /* TASKGROUP FPU */
 
+/**
+ * @cond internal
+ */
+
+/**
+ * @brief Initialize a struct k_task given parameters.
+ *
+ * @param ident Numeric identifier of this task object.
+ * @param priority Priority of task.
+ * @param state State of task.
+ * @param groups Groups this task belong to.
+ * @param fn_start Entry function.
+ * @param workspace Pointer to workspace (aka, stack).
+ * @param worksize Size of workspace.
+ * @param fn_abort Abort function.
+ */
+#define __K_TASK_INITIALIZER(ident, priority, state, groups, \
+			     fn_start, workspace, worksize, fn_abort) \
+	{ \
+	  NULL, NULL, priority, ident, state, ((groups) ^ SYS), \
+	  fn_start, workspace, worksize, fn_abort, NULL, \
+	}
 extern struct k_task _k_task_list[];
 
 extern void _task_ioctl(ktask_t, int);
 extern void _task_group_ioctl(ktask_group_t, int);
 
+/**
+ * @endcond
+ */
+
 /**
  * @brief Yield the CPU to another task
  *
@@ -262,24 +294,6 @@ extern void task_group_leave(uint32_t groups);
  */
 #define isr_task_group_mask_get() task_group_mask_get()
 
-/**
- * @brief Initialize a struct k_task given parameters.
- *
- * @param ident Numeric identifier of this task object.
- * @param priority Priority of task.
- * @param state State of task.
- * @param groups Groups this task belong to.
- * @param fn_start Entry function.
- * @param workspace Pointer to workspace (aka, stack).
- * @param worksize Size of workspace.
- * @param fn_abort Abort function.
- */
-#define __K_TASK_INITIALIZER(ident, priority, state, groups, \
-			     fn_start, workspace, worksize, fn_abort) \
-	{ \
-	  NULL, NULL, priority, ident, state, ((groups) ^ SYS), \
-	  fn_start, workspace, worksize, fn_abort, NULL, \
-	}
 
 /**
  * @brief Define a private microkernel task.
@@ -307,5 +321,7 @@ extern void task_group_leave(uint32_t groups);
 #ifdef __cplusplus
 }
 #endif
-
+/**
+ * @}
+ */
 #endif /* TASK_H */

include/microkernel/task_irq.h

@@ -33,6 +33,14 @@
 #ifndef TASK_IRQ_H
 #define TASK_IRQ_H
 
+
+/**
+ * @brief Microkernel Interrupt Services
+ * @defgroup microkernel_irq Microkernel Interrupt Services
+ * @ingroup microkernel_services
+ * @{
+ */
+
 #include <microkernel/base_api.h>
 
 #define INVALID_VECTOR 0xFFFFFFFF
@@ -56,8 +64,15 @@
 extern uint32_t task_irq_alloc(kirq_t irq_obj,
 				      uint32_t irq,
 				      uint32_t priority);
+/**
+ * @cond internal
+ */
 extern int _task_irq_test(kirq_t irq_ob, int32_t time);
 
+/**
+ * @endcond
+ */
+
 /**
  *
  * @brief Re-enable a task IRQ object's interrupt
@@ -119,4 +134,7 @@ extern void task_irq_free(kirq_t irq_obj);
 #define task_irq_test_wait_timeout(irq_obj, time) _task_irq_test(irq_obj, time)
 #endif
 
+/**
+ * @}
+ */
 #endif /* TASK_IRQ_H */

include/microkernel/ticks.h

@@ -33,6 +33,13 @@
 #ifndef TICKS_H
 #define TICKS_H
 
+/**
+ * @brief Microkernel Timers
+ * @defgroup microkernel_timer Microkernel Timers
+ * @ingroup microkernel_services
+ * @{
+ */
+
 #include <nanokernel.h>
 #include <sys_clock.h>
 
@@ -266,5 +273,7 @@ extern void sys_workload_time_slice_set(int32_t t);
 #ifdef __cplusplus
 }
 #endif
-
+/**
+ * @}
+ */
 #endif /* TICKS_H */