From: lottaviano Date: Wed, 10 Nov 2010 16:19:50 +0000 (+0000) Subject: doc: Added group definitions for most common modules. X-Git-Tag: 2.7.0~388 X-Git-Url: https://codewiz.org/gitweb?a=commitdiff_plain;h=1c11ac0ab0636d07db3899b02c5d89e2d0b020bc;p=bertos.git doc: Added group definitions for most common modules. git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4548 38d2e660-2303-0410-9eaa-f027e97ec537 --- diff --git a/Doxyfile-common b/Doxyfile-common index ca0a9a91..f15f7860 100644 --- a/Doxyfile-common +++ b/Doxyfile-common @@ -1245,6 +1245,7 @@ PREDEFINED = __doxygen__ \ CONFIG_XMODEM_RECV=1 \ CONFIG_XMODEM_SEND=1 \ LOG_LEVEL=3 \ + CONFIG_HEAP_MALLOC=1 \ CONFIG_I2C_DISABLE_OLD_API=0 \ COMPILER_VARIADIC_MACROS=1 diff --git a/bertos/cfg/log.h b/bertos/cfg/log.h index cd3e1f3d..1e4fc150 100644 --- a/bertos/cfg/log.h +++ b/bertos/cfg/log.h @@ -30,7 +30,9 @@ * * --> * - * \addtogroup logging + * \defgroup logging Logging facilities + * \ingroup core + * \{ * \brief Logging system module. * * This module implement a simple interface to use the multi level logging system. @@ -102,11 +104,6 @@ #include -/** - * \defgroup logging Logging facilities - * \{ - */ - // Use a default setting if nobody defined a log level #ifndef LOG_LEVEL #define LOG_LEVEL LOG_LVL_ERR diff --git a/bertos/cfg/macros.h b/bertos/cfg/macros.h index 3ec6b277..0a721ac5 100644 --- a/bertos/cfg/macros.h +++ b/bertos/cfg/macros.h @@ -30,6 +30,10 @@ * * --> * + * \defgroup macros General purpose macros + * \ingroup core + * \{ + * * \brief Common and handy function macros * * \author Bernie Innocenti @@ -359,5 +363,7 @@ */ typedef uint32_t id_t; +/** \} */ //defgroup macros + #endif /* MACROS_H */ diff --git a/bertos/drv/timer.h b/bertos/drv/timer.h index 50d118a9..83483b99 100644 --- a/bertos/drv/timer.h +++ b/bertos/drv/timer.h @@ -30,6 +30,10 @@ * Copyright 2000, 2008 Bernie Innocenti * --> * + * \defgroup drv_timers Timer module + * \ingroup core + * \{ + * * \brief Hardware independent timer driver. * * All timer related functions are implemented in this module. You have several options to use timers: @@ -313,4 +317,6 @@ INLINE void timer_setSignal(Timer *timer, struct Process *proc, sigmask_t sigs) #endif /* CONFIG_KERN_SIGNALS */ +/** \} */ //defgroup drv_timers + #endif /* DRV_TIMER_H */ diff --git a/bertos/io/kblock.h b/bertos/io/kblock.h index f2966baf..8bfe384f 100644 --- a/bertos/io/kblock.h +++ b/bertos/io/kblock.h @@ -30,10 +30,47 @@ * * --> * - * \author Francesco Sacchi + * \defgroup io_kblock KBlock interface + * \ingroup core + * \{ * * \brief KBlock interface * + * A block device is a device which can only be read/written + * with data blocks of constant size: flash memories, + * SD cards, hard disks, etc... + * This interface is designed to adapt to most block devices and + * use peculiar features in order to save CPU time and memory space. + * + * There is no init function because you do not have to use this + * structure directly, specific implementations will supply their own init + * functions. + * + * Error handling is done in a way similar to standard C library: whenever a + * function (eg. kblock_flush()) returns error, you need to check the error + * code, which is implementation specific. + * + * Example of code flow: + * \code + * // init a KBlock-derived class + * Flash fls; + * flash_init(&fls.blk, 0); + * + * // use kblock_* functions to access the derived class + * kblock_write(&fls.blk, ...); + * if (kblock_flush(&fls.blk) == EOF) + * { + * // oops, error occurred! + * int err = kblock_error(&fls.blk); + * // handle Flash specific error conditions + * // ... + * // clear error condition + * kblock_clearerr(&fls.blk); + * } + * \endcode + * + * \author Francesco Sacchi + * * $WIZ$ module_name = "kblock" */ @@ -116,15 +153,6 @@ typedef struct KBlockPriv /** * KBlock: interface for a generic block device. * - * A block device is a device which can only be read/written - * with data blocks of constant size: flash memories, - * SD cards, hard disks, etc... - * - * This interface is designed to adapt to most block devices and - * use peculiar features in order to save CPU time and memory space. - * - * You do not have to use this structure directly, specific implementations - * will be supplied in the peripheral drivers. */ typedef struct KBlock { @@ -367,4 +395,7 @@ size_t kblock_swReadBuf(struct KBlock *b, void *buf, size_t offset, size_t size) size_t kblock_swWriteBuf(struct KBlock *b, const void *buf, size_t offset, size_t size); int kblock_swClose(struct KBlock *b); +/** \} */ //defgroup io_kblock + + #endif /* IO_KBLOCK_H */ diff --git a/bertos/io/kfile.h b/bertos/io/kfile.h index c7a5bfc9..c5529822 100644 --- a/bertos/io/kfile.h +++ b/bertos/io/kfile.h @@ -31,6 +31,13 @@ * * --> * + * \defgroup core BeRTOS core functionality + * \{ + * + * \defgroup io_kfile KFile interface + * \ingroup core + * \{ + * * \brief Virtual KFile I/O interface. * * KFile is a simple, generic interface for file I/O. It uses an @@ -325,6 +332,8 @@ void kfile_resync(KFile *fd, mtime_t delay); void kfile_init(struct KFile *fd); /* @} */ +/** \} */ //Defgroup io_kfile + /* * Kfile test function. */ @@ -332,6 +341,7 @@ int kfile_testSetup(void); int kfile_testRun(void); int kfile_testRunGeneric(KFile *fd, uint8_t *test_buf, uint8_t *save_buf, size_t size); int kfile_testTearDown(void); +/** \} */ //defgroup core #endif /* KERN_KFILE_H */ diff --git a/bertos/kern/msg.h b/bertos/kern/msg.h index 2d467220..6cbcc444 100644 --- a/bertos/kern/msg.h +++ b/bertos/kern/msg.h @@ -32,15 +32,14 @@ * --> * * - * This module implements a common system for executing - * a user defined action calling a hook function. - * - * - * \author Bernie Innocenti + * \defgroup kern_msg Message box IPC + * \ingroup kern + * \{ * * \brief Simple inter-process messaging system * - * Handle queues of messages associated an action. + * This module implements a common system for executing + * a user defined action calling a hook function. * * A message port is an abstraction used to exchange information * asynchronously between processes or other entities such as @@ -179,6 +178,8 @@ * } * \endcode * + * \author Bernie Innocenti + * * $WIZ$ module_name = "msg" * $WIZ$ module_depends = "event", "signal", "kernel" */ @@ -290,6 +291,8 @@ INLINE void msg_reply(Msg *msg) msg_put(msg->replyPort, msg); } +/** \} */ //defgroup kern_msg + int msg_testRun(void); int msg_testSetup(void); int msg_testTearDown(void); diff --git a/bertos/kern/proc.h b/bertos/kern/proc.h index e1181747..13bd7bf0 100644 --- a/bertos/kern/proc.h +++ b/bertos/kern/proc.h @@ -30,6 +30,12 @@ * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti * --> * + * \defgroup kern Kernel facilities + * \{ + * + * \defgroup kern_proc Process (Threads) management + * \{ + * * \brief BeRTOS Kernel core (Process scheduler). * * \author Bernie Innocenti @@ -396,5 +402,7 @@ INLINE struct Process *proc_current(void) #error No cpu_stack_t size supported! #endif #endif +/** \} */ //defgroup kern_proc +/** \} */ //defgroup kern #endif /* KERN_PROC_H */ diff --git a/bertos/kern/sem.h b/bertos/kern/sem.h index 1f16acee..1e59c07f 100644 --- a/bertos/kern/sem.h +++ b/bertos/kern/sem.h @@ -31,6 +31,9 @@ * * --> * + * \defgroup kern_sem Mutually exclusive semaphores + * \ingroup kern + * \{ * \brief Mutually exclusive semaphores. * Shared locking not supported in this implementation. * @@ -69,6 +72,7 @@ bool sem_attempt(struct Semaphore *s); void sem_obtain(struct Semaphore *s); void sem_release(struct Semaphore *s); /* \} */ +/* \} */ //defgroup kern_sem int sem_testRun(void); int sem_testSetup(void); diff --git a/bertos/kern/signal.h b/bertos/kern/signal.h index 06c50220..408e21e9 100644 --- a/bertos/kern/signal.h +++ b/bertos/kern/signal.h @@ -31,6 +31,10 @@ * * --> * + * \defgroup kern_signal Kernel signals + * \ingroup kern + * \{ + * * \brief Signal module for IPC. * * @@ -83,4 +87,6 @@ int signal_testTearDown(void); #define SIG_SINGLE BV(7) /**< Used to wait for a single event */ /*\}*/ +/* \} */ //defgroup kern_signal + #endif /* KERN_SIGNAL_H */ diff --git a/bertos/mware/event.h b/bertos/mware/event.h index b797b7eb..e9f9e4a2 100644 --- a/bertos/mware/event.h +++ b/bertos/mware/event.h @@ -30,7 +30,9 @@ * Copyright 1999, 2001, 2003 Bernie Innocenti * --> * - * \addtogroup event_handling + * \defgroup event_handling Event handling module + * \ingroup core + * \{ * * \brief Events handling * @@ -107,12 +109,6 @@ struct Process; #endif -/** - * \defgroup event_handling Events handling module - * \{ - */ - - /// User defined callback type typedef void (*Hook)(void *); diff --git a/bertos/struct/heap.c b/bertos/struct/heap.c index 4800f1b2..4c00bd7c 100644 --- a/bertos/struct/heap.c +++ b/bertos/struct/heap.c @@ -204,6 +204,9 @@ size_t heap_freeSpace(struct Heap *h) #if CONFIG_HEAP_MALLOC +/** + * Standard malloc interface + */ void *heap_malloc(struct Heap* h, size_t size) { size_t *mem; @@ -215,6 +218,9 @@ void *heap_malloc(struct Heap* h, size_t size) return mem; } +/** + * Standard calloc interface + */ void *heap_calloc(struct Heap* h, size_t size) { void *mem; diff --git a/bertos/struct/heap.h b/bertos/struct/heap.h index fc36cc7b..9846079a 100644 --- a/bertos/struct/heap.h +++ b/bertos/struct/heap.h @@ -30,6 +30,10 @@ * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti * --> * + * \defgroup heap Embedded optimized memory allocator + * \ingroup core + * \{ + * * \brief Heap subsystem (public interface). * * \todo Heap memory could be defined as an array of MemChunk, and used @@ -101,12 +105,19 @@ size_t heap_freeSpace(struct Heap *h); #if CONFIG_HEAP_MALLOC +/** + * \name Compatibility interface with C standard library + * \{ + */ void *heap_malloc(struct Heap* heap, size_t size); void *heap_calloc(struct Heap* heap, size_t size); void heap_free(struct Heap* heap, void * mem); +/** \} */ #endif +/** \} */ //defgroup heap + int heap_testSetup(void); int heap_testRun(void); int heap_testTearDown(void);