mirror of https://github.com/rusefi/ChibiOS.git
Documentation improvements.
git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@830 35acf78f-673a-0410-8e92-d51de3d6d3f4
This commit is contained in:
gdisirio
parent
7dbc6a7567
commit
80a8621ec0
|
|
@ -83,7 +83,8 @@ Win32-MinGW - ChibiOS/RT simulator and demo into a WIN32 process,
|
|||
- FIX: Removed unused chSysPuts() macro (bug 2672678).
|
||||
- FIX: Renamed function chSysInTimeWindow() as chTimeIsWithin() and renamed
|
||||
the macro chSysGetTime() in chTimeNow(), the old names are still recognized
|
||||
but marked as deprecated (fixes the bug 2678953 but goes a bit further).
|
||||
but marked as deprecated (fixes the bug 2678953 but goes a bit further by
|
||||
introducing a new API category "Time").
|
||||
- Removed testcond.c|h and moved the test cases into testmtx.c. Mutexes and
|
||||
condvars have to be tested together.
|
||||
- Added architecture diagram to the documentation.
|
||||
|
|
|
|||
|
|
@ -44,8 +44,8 @@ void trace_init(void) {
|
|||
/**
|
||||
* @brief Inserts in the circular debug trace buffer a context switch record.
|
||||
*
|
||||
* @param otp the thread being switched out
|
||||
* @param ntp the thread to be resumed
|
||||
* @param[in] otp the thread being switched out
|
||||
* @param[in] ntp the thread to be resumed
|
||||
*/
|
||||
void chDbgTrace(Thread *otp, Thread *ntp) {
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ char *panic_msg;
|
|||
/**
|
||||
* @brief Prints a panic message on the console and then halts the system.
|
||||
*
|
||||
* @param msg the pointer to the panic message string
|
||||
* @param[in] msg the pointer to the panic message string
|
||||
*/
|
||||
void chDbgPanic(char *msg) {
|
||||
|
||||
|
|
|
|||
12
src/chheap.c
12
src/chheap.c
|
|
@ -99,9 +99,9 @@ void heap_init(void) {
|
|||
* @details The allocated block is guaranteed to be properly aligned for a
|
||||
* pointer data type.
|
||||
*
|
||||
* @param size the size of the block to be allocated. Note that the allocated
|
||||
* block may be a bit bigger than the requested size for alignment
|
||||
* and fragmentation reasons.
|
||||
* @param[in] size the size of the block to be allocated. Note that the
|
||||
* allocated block may be a bit bigger than the requested
|
||||
* size for alignment and fragmentation reasons.
|
||||
* @return A pointer to the allocated block.
|
||||
* @retval NULL if the block cannot be allocated.
|
||||
*/
|
||||
|
|
@ -148,7 +148,7 @@ void *chHeapAlloc(size_t size) {
|
|||
/**
|
||||
* @brief Frees a previously allocated memory block.
|
||||
*
|
||||
* @param p the memory block pointer
|
||||
* @param[in] p the memory block pointer
|
||||
*/
|
||||
void chHeapFree(void *p) {
|
||||
struct header *qp, *hp;
|
||||
|
|
@ -195,8 +195,8 @@ void chHeapFree(void *p) {
|
|||
/**
|
||||
* @brief Reports the heap status.
|
||||
*
|
||||
* @param sizep pointer to a variable that will receive the total fragmented
|
||||
* free space
|
||||
* @param[in] sizep pointer to a variable that will receive the total
|
||||
* fragmented free space
|
||||
* @return The number of fragments in the heap.
|
||||
* @note This function is meant to be used in the test suite, it should not be
|
||||
* really useful for the application code.
|
||||
|
|
|
|||
|
|
@ -29,8 +29,8 @@
|
|||
/**
|
||||
* @brief Inserts a thread into a priority ordered queue.
|
||||
*
|
||||
* @param tp the pointer to the thread to be inserted in the list
|
||||
* @param tqp the pointer to the threads list header
|
||||
* @param[in] tp the pointer to the thread to be inserted in the list
|
||||
* @param[in] tqp the pointer to the threads list header
|
||||
* @note The insertion is done by scanning the list from the highest priority
|
||||
* toward the lowest.
|
||||
* @note This function is @b not an API.
|
||||
|
|
@ -52,8 +52,8 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) {
|
|||
/**
|
||||
* @brief Inserts a Thread into a queue.
|
||||
*
|
||||
* @param tp the pointer to the thread to be inserted in the list
|
||||
* @param tqp the pointer to the threads list header
|
||||
* @param[in] tp the pointer to the thread to be inserted in the list
|
||||
* @param[in] tqp the pointer to the threads list header
|
||||
* @note This function is @b not an API.
|
||||
*/
|
||||
void queue_insert(Thread *tp, ThreadsQueue *tqp) {
|
||||
|
|
@ -65,7 +65,7 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
|
|||
/**
|
||||
* @brief Removes the first-out Thread from a queue and returns it.
|
||||
*
|
||||
* @param tqp the pointer to the threads list header
|
||||
* @param[in] tqp the pointer to the threads list header
|
||||
* @return The removed thread pointer.
|
||||
* @note This function is @b not an API.
|
||||
*/
|
||||
|
|
@ -79,7 +79,7 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
|
|||
/**
|
||||
* @brief Removes the last-out Thread from a queue and returns it.
|
||||
*
|
||||
* @param tqp the pointer to the threads list header
|
||||
* @param[in] tqp the pointer to the threads list header
|
||||
* @return The removed thread pointer.
|
||||
* @note This function is @b not an API.
|
||||
*/
|
||||
|
|
@ -93,7 +93,7 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
|
|||
/**
|
||||
* @brief Removes a Thread from a FIFO list and returns it.
|
||||
*
|
||||
* @param tp the pointer to the thread to be removed from the list
|
||||
* @param[in] tp the pointer to the thread to be removed from the list
|
||||
* @return The removed thread pointer.
|
||||
* @note This function is @b not an API.
|
||||
*/
|
||||
|
|
@ -107,8 +107,8 @@ Thread *dequeue(Thread *tp) {
|
|||
/**
|
||||
* @brief Pushes a Thread on top of a stack list.
|
||||
*
|
||||
* @param tp the pointer to the thread to be inserted in the list
|
||||
* @param tlp the pointer to the threads list header
|
||||
* @param[in] tp the pointer to the thread to be inserted in the list
|
||||
* @param[in] tlp the pointer to the threads list header
|
||||
* @note This function is @b not an API.
|
||||
*/
|
||||
void list_insert(Thread *tp, ThreadsList *tlp) {
|
||||
|
|
@ -120,7 +120,7 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
|
|||
/**
|
||||
* @brief Pops a Thread from the top of a stack list and returns it.
|
||||
*
|
||||
* @param tlp the pointer to the threads list header
|
||||
* @param[in] tlp the pointer to the threads list header
|
||||
* @return The removed thread pointer.
|
||||
* @note The list must be non-empty before calling this function.
|
||||
* @note This function is @b not an API.
|
||||
|
|
|
|||
|
|
@ -27,12 +27,12 @@
|
|||
#include <ch.h>
|
||||
|
||||
#if CH_USE_MEMPOOLS
|
||||
|
||||
/**
|
||||
* @brief Initializes an empty memory pool.
|
||||
*
|
||||
* @param mp pointer to a @p MemoryPool structure
|
||||
* @param size the size of the objects contained in this memory pool
|
||||
* @param[out] mp pointer to a @p MemoryPool structure
|
||||
* @param[in] size the size of the objects contained in this memory pool,
|
||||
* the minimum accepted size is the size of a pointer to void
|
||||
*/
|
||||
void chPoolInit(MemoryPool *mp, size_t size) {
|
||||
|
||||
|
|
@ -45,7 +45,7 @@ void chPoolInit(MemoryPool *mp, size_t size) {
|
|||
/**
|
||||
* @brief Allocates an object from a memory pool.
|
||||
*
|
||||
* @param mp pointer to a @p MemoryPool structure
|
||||
* @param[in] mp pointer to a @p MemoryPool structure
|
||||
* @return The pointer to the allocated object.
|
||||
* @retval NULL if pool is empty.
|
||||
*/
|
||||
|
|
@ -63,7 +63,7 @@ void *chPoolAllocI(MemoryPool *mp) {
|
|||
/**
|
||||
* @brief Allocates an object from a memory pool.
|
||||
*
|
||||
* @param mp pointer to a @p MemoryPool structure
|
||||
* @param[in] mp pointer to a @p MemoryPool structure
|
||||
* @return The pointer to the allocated object.
|
||||
* @retval NULL if pool is empty.
|
||||
*/
|
||||
|
|
@ -79,8 +79,8 @@ void *chPoolAlloc(MemoryPool *mp) {
|
|||
/**
|
||||
* @brief Releases (or adds) an object into (to) a memory pool.
|
||||
*
|
||||
* @param mp pointer to a @p MemoryPool structure
|
||||
* @param objp the pointer to the object to be released or added
|
||||
* @param[in] mp pointer to a @p MemoryPool structure
|
||||
* @param[in] objp the pointer to the object to be released or added
|
||||
* @note the object is assumed to be of the right size for the specified
|
||||
* memory pool.
|
||||
*/
|
||||
|
|
@ -96,8 +96,8 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
|
|||
/**
|
||||
* @brief Releases (or adds) an object into (to) a memory pool.
|
||||
*
|
||||
* @param mp pointer to a @p MemoryPool structure
|
||||
* @param objp the pointer to the object to be released or added
|
||||
* @param[in] mp pointer to a @p MemoryPool structure
|
||||
* @param[in] objp the pointer to the object to be released or added
|
||||
* @note the object is assumed to be of the right size for the specified
|
||||
* memory pool.
|
||||
*/
|
||||
|
|
@ -107,7 +107,6 @@ void chPoolFree(MemoryPool *mp, void *objp) {
|
|||
chPoolFreeI(mp, objp);
|
||||
chSysUnlock();
|
||||
}
|
||||
|
||||
#endif /* CH_USE_MEMPOOLS */
|
||||
|
||||
/** @} */
|
||||
|
|
|
|||
12
src/chmsg.c
12
src/chmsg.c
|
|
@ -39,8 +39,8 @@
|
|||
* @details The sender is stopped until the receiver executes a
|
||||
* @p chMsgRelease()after receiving the message.
|
||||
*
|
||||
* @param tp the pointer to the thread
|
||||
* @param msg the message
|
||||
* @param[in] tp the pointer to the thread
|
||||
* @param[in] msg the message
|
||||
* @return The return message from @p chMsgRelease().
|
||||
*/
|
||||
msg_t chMsgSend(Thread *tp, msg_t msg) {
|
||||
|
|
@ -66,9 +66,9 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
|
|||
* @details The sender is stopped until the receiver executes a
|
||||
* @p chMsgRelease() after receiving the message.
|
||||
*
|
||||
* @param tp the pointer to the thread
|
||||
* @param msg the message
|
||||
* @param mask the event flags set to be pended
|
||||
* @param[in] tp the pointer to the thread
|
||||
* @param[in] msg the message
|
||||
* @param[in] mask the event flags set to be pended
|
||||
* @return The return message from @p chMsgRelease().
|
||||
* @note This function assumes that the receiving thread is not sleeping into
|
||||
* a @p chMsgWait(). The use case is that the server thread is waiting
|
||||
|
|
@ -136,7 +136,7 @@ msg_t chMsgGet(void) {
|
|||
/**
|
||||
* @brief Releases the thread waiting on top of the messages queue.
|
||||
*
|
||||
* @param msg the message returned to the message sender
|
||||
* @param[in] msg the message returned to the message sender
|
||||
* @note You can call this function only if there is a message already in the
|
||||
* queue else the result will be unpredictable (a crash most likely).
|
||||
* Exiting from the @p chMsgWait() ensures you have at least one
|
||||
|
|
|
|||
24
src/chmtx.c
24
src/chmtx.c
|
|
@ -31,7 +31,7 @@
|
|||
/**
|
||||
* @brief Initializes s @p Mutex structure.
|
||||
*
|
||||
* @param mp pointer to a @p Mutex structure
|
||||
* @param[out] mp pointer to a @p Mutex structure
|
||||
* @note This function can be invoked from within an interrupt handler even if
|
||||
* it is not an I-Class API because it does not touch any critical kernel
|
||||
* data structure.
|
||||
|
|
@ -47,7 +47,7 @@ void chMtxInit(Mutex *mp) {
|
|||
/**
|
||||
* @brief Locks the specified mutex.
|
||||
*
|
||||
* @param mp pointer to the @p Mutex structure
|
||||
* @param[in] mp pointer to the @p Mutex structure
|
||||
*/
|
||||
void chMtxLock(Mutex *mp) {
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ void chMtxLock(Mutex *mp) {
|
|||
/**
|
||||
* @brief Locks the specified mutex.
|
||||
*
|
||||
* @param mp pointer to the @p Mutex structure
|
||||
* @param[in] mp pointer to the @p Mutex structure
|
||||
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
|
||||
* block.
|
||||
*/
|
||||
|
|
@ -136,10 +136,10 @@ void chMtxLockS(Mutex *mp) {
|
|||
/**
|
||||
* @brief Tries to lock a mutex.
|
||||
* @details This function does not have any overhead related to
|
||||
* the priority inheritance mechanism because it does not try to enter a sleep
|
||||
* state on the mutex.
|
||||
* the priority inheritance mechanism because it does not try to
|
||||
* enter a sleep state on the mutex.
|
||||
*
|
||||
* @param mp pointer to the @p Mutex structure
|
||||
* @param[in] mp pointer to the @p Mutex structure
|
||||
* @retval TRUE if the mutex was successfully acquired
|
||||
* @retval FALSE if the lock attempt failed.
|
||||
*/
|
||||
|
|
@ -157,9 +157,9 @@ bool_t chMtxTryLock(Mutex *mp) {
|
|||
/**
|
||||
* @brief Tries to lock a mutex.
|
||||
* @details This function does not have any overhead related to
|
||||
* the priority inheritance mechanism because it does not try to enter a sleep
|
||||
* state on the mutex.
|
||||
* @param mp pointer to the @p Mutex structure
|
||||
* the priority inheritance mechanism because it does not try to
|
||||
* enter a sleep state on the mutex.
|
||||
* @param[in] mp pointer to the @p Mutex structure
|
||||
* @retval TRUE if the mutex was successfully acquired
|
||||
* @retval FALSE if the lock attempt failed.
|
||||
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
|
||||
|
|
@ -273,9 +273,9 @@ Mutex *chMtxUnlockS(void) {
|
|||
/**
|
||||
* @brief Unlocks all the mutexes owned by the invoking thread.
|
||||
* @details This function is <b>MUCH MORE</b> efficient than releasing the
|
||||
* mutexes one by one and not just because the call overhead, this function
|
||||
* does not have any overhead related to the priority inheritance mechanism
|
||||
* too.
|
||||
* mutexes one by one and not just because the call overhead,
|
||||
* this function does not have any overhead related to the priority
|
||||
* inheritance mechanism.
|
||||
*/
|
||||
void chMtxUnlockAll(void) {
|
||||
|
||||
|
|
|
|||
|
|
@ -33,11 +33,12 @@
|
|||
* @details A Semaphore is internally initialized and works as a counter of
|
||||
* the bytes contained in the queue.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param buffer pointer to a memory area allocated as queue buffer
|
||||
* @param size size of the queue buffer
|
||||
* @param inotify pointer to a callback function that is invoked when
|
||||
* some data is read from the Queue. The value can be @p NULL.
|
||||
* @param[out] qp pointer to a @p Queue structure
|
||||
* @param[in] buffer pointer to a memory area allocated as queue buffer
|
||||
* @param[in] size size of the queue buffer
|
||||
* @param[in] inotify pointer to a callback function that is invoked when
|
||||
* some data is read from the Queue. The value can be
|
||||
* @p NULL.
|
||||
*/
|
||||
void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) {
|
||||
|
||||
|
|
@ -51,7 +52,7 @@ void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) {
|
|||
* @brief Resets an input queue.
|
||||
* @details All the data is lost and the waiting threads resumed.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
*/
|
||||
void chIQReset(Queue *qp) {
|
||||
|
||||
|
|
@ -66,8 +67,8 @@ void chIQReset(Queue *qp) {
|
|||
/**
|
||||
* @brief Inserts a byte into an input queue.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param b the byte value to be written
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
* @param[in] b the byte value to be written
|
||||
* @retval Q_OK if the operation is successful.
|
||||
* @retval Q_FULL if the queue is full.
|
||||
* @note This function is the lower side endpoint of the Input Queue.
|
||||
|
|
@ -91,7 +92,7 @@ msg_t chIQPutI(Queue *qp, uint8_t b) {
|
|||
* @details If the queue is empty then the calling thread is suspended until
|
||||
* a byte arrives in the queue.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
* @return A byte value from the queue.
|
||||
* @retval Q_RESET if the queue was reset.
|
||||
*/
|
||||
|
|
@ -122,8 +123,8 @@ msg_t chIQGet(Queue *qp) {
|
|||
* @details If the queue is empty then the calling thread is suspended until
|
||||
* a byte arrives in the queue or the specified time expires.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param time the number of ticks before the operation timeouts
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
* @param[in] time the number of ticks before the operation timeouts
|
||||
* @return A byte value from the queue.
|
||||
* @retval Q_TIMEOUT if the specified time expired.
|
||||
* @retval Q_RESET if the queue was reset.
|
||||
|
|
@ -158,9 +159,9 @@ msg_t chIQGetTimeout(Queue *qp, systime_t time) {
|
|||
* @details The function is non-blocking and can return zero if the queue is
|
||||
* empty.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param buffer the data buffer
|
||||
* @param n the maximum amount of data to be read
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
* @param[out] buffer the data buffer
|
||||
* @param[in] n the maximum amount of data to be read
|
||||
* @return The number of bytes read.
|
||||
* @note This function is the upper side endpoint of the input queue.
|
||||
* @note The function is not atomic, if you need atomicity it is suggested
|
||||
|
|
@ -202,11 +203,12 @@ size_t chIQRead(Queue *qp, uint8_t *buffer, size_t n) {
|
|||
* @details A Semaphore is internally initialized and works as a counter of the
|
||||
* free bytes in the queue.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param buffer pointer to a memory area allocated as queue buffer
|
||||
* @param size size of the queue buffer
|
||||
* @param onotify pointer to a callback function that is invoked when
|
||||
* some data is written in the Queue. The value can be @p NULL.
|
||||
* @param[out] qp pointer to a @p Queue structure
|
||||
* @param[in] buffer pointer to a memory area allocated as queue buffer
|
||||
* @param[in] size size of the queue buffer
|
||||
* @param[in] onotify pointer to a callback function that is invoked when
|
||||
* some data is written in the Queue. The value can be
|
||||
* @p NULL.
|
||||
*/
|
||||
void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) {
|
||||
|
||||
|
|
@ -220,7 +222,7 @@ void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) {
|
|||
* @brief Resets an Output Queue.
|
||||
* @details All the data is lost and the waiting threads resumed.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
*/
|
||||
void chOQReset(Queue *qp) {
|
||||
|
||||
|
|
@ -237,8 +239,8 @@ void chOQReset(Queue *qp) {
|
|||
* @details If the queue is full then the thread is suspended until the queue
|
||||
* has free space available.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param b the byte value to be written
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
* @param[in] b the byte value to be written
|
||||
*/
|
||||
void chOQPut(Queue *qp, uint8_t b) {
|
||||
|
||||
|
|
@ -258,7 +260,7 @@ void chOQPut(Queue *qp, uint8_t b) {
|
|||
/**
|
||||
* @brief Gets a byte from an output queue.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
* @return The byte value from the queue.
|
||||
* @retval Q_EMPTY if the queue is empty.
|
||||
* @note This function is the lower side endpoint of the output queue.
|
||||
|
|
@ -283,9 +285,9 @@ msg_t chOQGetI(Queue *qp) {
|
|||
* @details The function is non-blocking and can return zero if the queue is
|
||||
* full.
|
||||
*
|
||||
* @param qp pointer to a @p Queue structure
|
||||
* @param buffer the data buffer
|
||||
* @param n the maximum amount of data to be written
|
||||
* @param[in] qp pointer to a @p Queue structure
|
||||
* @param[in] buffer the data buffer
|
||||
* @param[in] n the maximum amount of data to be written
|
||||
* @return The number of written bytes.
|
||||
* @note This function is the upper side endpoint of the output queue.
|
||||
* @note The function is not atomic, if you need atomicity it is suggested
|
||||
|
|
@ -327,13 +329,15 @@ size_t chOQWrite(Queue *qp, uint8_t *buffer, size_t n) {
|
|||
/**
|
||||
* @brief Initializes an half duplex queue.
|
||||
*
|
||||
* @param qp pointer to the @p HalfDuplexQueue structure
|
||||
* @param buffer pointer to a memory area allocated as buffer for the queue
|
||||
* @param size the size of the queue buffer
|
||||
* @param inotify pointer to a callback function that is invoked when
|
||||
* some data is read from the queue. The value can be @p NULL.
|
||||
* @param onotify pointer to a callback function that is invoked when
|
||||
* some data is written to the queue. The value can be @p NULL.
|
||||
* @param[out] qp pointer to the @p HalfDuplexQueue structure
|
||||
* @param[in] buffer pointer to a memory area allocated as buffer for the queue
|
||||
* @param[in] size the size of the queue buffer
|
||||
* @param[in] inotify pointer to a callback function that is invoked when
|
||||
* some data is read from the queue. The value can be
|
||||
* @p NULL.
|
||||
* @param[in] onotify pointer to a callback function that is invoked when
|
||||
* some data is written to the queue. The value can be
|
||||
* @p NULL.
|
||||
*/
|
||||
void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size,
|
||||
qnotify_t inotify, qnotify_t onotify) {
|
||||
|
|
@ -351,7 +355,7 @@ void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size,
|
|||
* @details If the queue is empty or is in transmission mode then the invoking
|
||||
* thread is suspended.
|
||||
*
|
||||
* @param qp pointer to a @p HalfDuplexQueue structure
|
||||
* @param[in] qp pointer to a @p HalfDuplexQueue structure
|
||||
* @return The byte value.
|
||||
* @retval Q_RESET if the queue was reset.
|
||||
*/
|
||||
|
|
@ -386,8 +390,8 @@ msg_t chHDQGetReceive(HalfDuplexQueue *qp) {
|
|||
* @details If the queue is empty or is in transmission mode then the invoking
|
||||
* thread is suspended.
|
||||
*
|
||||
* @param qp pointer to a @p HalfDuplexQueue structure
|
||||
* @param time the number of ticks before the operation timouts
|
||||
* @param[in] qp pointer to a @p HalfDuplexQueue structure
|
||||
* @param[in] time the number of ticks before the operation timouts
|
||||
* @return The byte value.
|
||||
* @retval Q_TIMEOUT if a timeout occurs.
|
||||
* @note The function is available only if the @p CH_USE_QUEUES_TIMEOUT and
|
||||
|
|
@ -425,8 +429,8 @@ msg_t chHDQGetReceiveTimeout(HalfDuplexQueue *qp, systime_t time) {
|
|||
* @details If the buffer contains unread input data then the the buffer is
|
||||
* cleared and the queue goes in transmission mode.
|
||||
*
|
||||
* @param qp pointer to a @p HalfDuplexQueue structure
|
||||
* @param b the byte value to be written
|
||||
* @param[in] qp pointer to a @p HalfDuplexQueue structure
|
||||
* @param[in] b the byte value to be written
|
||||
*/
|
||||
void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {
|
||||
|
||||
|
|
@ -457,7 +461,7 @@ void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {
|
|||
/**
|
||||
* @brief Gets a byte from the transmit queue.
|
||||
*
|
||||
* @param qp pointer to a @p HalfDuplexQueue structure
|
||||
* @param[in] qp pointer to a @p HalfDuplexQueue structure
|
||||
* @return The byte value.
|
||||
* @retval Q_EMPTY if the transmit queue is empty (not in transmission mode).
|
||||
* @note This function must be called with interrupts disabled or from an
|
||||
|
|
@ -480,8 +484,8 @@ msg_t chHDQGetTransmitI(HalfDuplexQueue *qp) {
|
|||
* @brief Writes a byte into the receive queue.
|
||||
* @details If the queue is in transmission mode then the byte is lost.
|
||||
*
|
||||
* @param qp pointer to a @p HalfDuplexQueue structure
|
||||
* @param b the byte value to be written
|
||||
* @param[in] qp pointer to a @p HalfDuplexQueue structure
|
||||
* @param[in] b the byte value to be written
|
||||
* @retval Q_OK if the operation is successful.
|
||||
* @retval Q_FULL if the driver is in transmit mode or the receive queue is full.
|
||||
* @note This function must be called with interrupts disabled or from an
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ Thread *chSchReadyI(Thread *tp) {
|
|||
* @details The next highest priority thread becomes running. The threads
|
||||
* states are described into @p threads.h.
|
||||
*
|
||||
* @param newstate the new thread state
|
||||
* @param[in] newstate the new thread state
|
||||
* @note The function must be called in the system mutex zone.
|
||||
* @note The function is not meant to be used in the user code directly.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -136,6 +136,7 @@ msg_t chSemWaitS(Semaphore *sp) {
|
|||
* the following special values are allowed:
|
||||
* - @a TIME_IMMEDIATE immediate timeout.
|
||||
* - @a TIME_INFINITE no timeout.
|
||||
* .
|
||||
* @retval RDY_OK if the semaphore was signaled or not taken.
|
||||
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
|
||||
* @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the
|
||||
|
|
|
|||
|
|
@ -32,15 +32,17 @@
|
|||
* @details The HW dependent part of the initialization has to be performed
|
||||
* outside, usually in the hardware initialization code.
|
||||
*
|
||||
* @param sd pointer to a @p FullDuplexDriver structure
|
||||
* @param ib pointer to a memory area allocated for the Input Queue buffer
|
||||
* @param isize size of the Input Queue buffer
|
||||
* @param inotify pointer to a callback function that is invoked when
|
||||
* some data is read from the Queue. The value can be @p NULL.
|
||||
* @param ob pointer to a memory area allocated for the Output Queue buffer
|
||||
* @param osize size of the Output Queue buffer
|
||||
* @param onotify pointer to a callback function that is invoked when
|
||||
* some data is written in the Queue. The value can be @p NULL.
|
||||
* @param[out] sd pointer to a @p FullDuplexDriver structure
|
||||
* @param[in] ib pointer to a memory area allocated for the Input Queue buffer
|
||||
* @param[in] isize size of the Input Queue buffer
|
||||
* @param[in] inotify pointer to a callback function that is invoked when
|
||||
* some data is read from the Queue. The value can be
|
||||
* @p NULL.
|
||||
* @param[in] ob pointer to a memory area allocated for the Output Queue buffer
|
||||
* @param[in] osize size of the Output Queue buffer
|
||||
* @param[in] onotify pointer to a callback function that is invoked when
|
||||
* some data is written in the Queue. The value can be
|
||||
* @p NULL.
|
||||
*/
|
||||
void chFDDInit(FullDuplexDriver *sd,
|
||||
uint8_t *ib, size_t isize, qnotify_t inotify,
|
||||
|
|
@ -60,9 +62,10 @@ void chFDDInit(FullDuplexDriver *sd,
|
|||
/**
|
||||
* @brief Handles incoming data.
|
||||
* @details This function must be called from the input interrupt service
|
||||
* routine in order to enqueue incoming data and generate the related events.
|
||||
* @param sd pointer to a @p FullDuplexDriver structure
|
||||
* @param b the byte to be written in the driver's Input Queue
|
||||
* routine in order to enqueue incoming data and generate the
|
||||
* related events.
|
||||
* @param[in] sd pointer to a @p FullDuplexDriver structure
|
||||
* @param[in] b the byte to be written in the driver's Input Queue
|
||||
*/
|
||||
void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
|
||||
|
||||
|
|
@ -77,7 +80,7 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
|
|||
* @details Must be called from the output interrupt service routine in order
|
||||
* to get the next byte to be transmitted.
|
||||
*
|
||||
* @param sd pointer to a @p FullDuplexDriver structure
|
||||
* @param[in] sd pointer to a @p FullDuplexDriver structure
|
||||
* @return The byte value read from the driver's output queue.
|
||||
* @retval Q_EMPTY if the queue is empty (the lower driver usually disables
|
||||
* the interrupt source when this happens).
|
||||
|
|
@ -95,8 +98,8 @@ msg_t chFDDRequestDataI(FullDuplexDriver *sd) {
|
|||
* @details Must be called from the I/O interrupt service routine in order to
|
||||
* notify I/O conditions as errors, signals change etc.
|
||||
*
|
||||
* @param sd pointer to a @p FullDuplexDriver structure
|
||||
* @param mask condition flags to be added to the mask
|
||||
* @param[in] sd pointer to a @p FullDuplexDriver structure
|
||||
* @param[in] mask condition flags to be added to the mask
|
||||
*/
|
||||
void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {
|
||||
|
||||
|
|
@ -107,7 +110,7 @@ void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {
|
|||
/**
|
||||
* @brief Returns and clears the errors mask associated to the driver.
|
||||
*
|
||||
* @param sd pointer to a @p FullDuplexDriver structure
|
||||
* @param[in] sd pointer to a @p FullDuplexDriver structure
|
||||
* @return The condition flags modified since last time this function was
|
||||
* invoked.
|
||||
*/
|
||||
|
|
@ -126,13 +129,15 @@ dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) {
|
|||
* @details The HW dependent part of the initialization has to be performed
|
||||
* outside, usually in the hardware initialization code.
|
||||
*
|
||||
* @param sd pointer to a @p HalfDuplexDriver structure
|
||||
* @param b pointer to a memory area allocated for the queue buffer
|
||||
* @param size the buffer size
|
||||
* @param inotify pointer to a callback function that is invoked when
|
||||
* some data is read from the queue. The value can be @p NULL.
|
||||
* @param onotify pointer to a callback function that is invoked when
|
||||
* some data is written in the queue. The value can be @p NULL.
|
||||
* @param[out] sd pointer to a @p HalfDuplexDriver structure
|
||||
* @param[in] b pointer to a memory area allocated for the queue buffer
|
||||
* @param[in] size the buffer size
|
||||
* @param[in] inotify pointer to a callback function that is invoked when
|
||||
* some data is read from the queue. The value can be
|
||||
* @p NULL.
|
||||
* @param[in] onotify pointer to a callback function that is invoked when
|
||||
* some data is written in the queue. The value can be
|
||||
* @p NULL.
|
||||
*/
|
||||
void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size,
|
||||
qnotify_t inotify, qnotify_t onotify) {
|
||||
|
|
@ -149,9 +154,10 @@ void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size,
|
|||
/**
|
||||
* @brief Handles incoming data.
|
||||
* @details This function must be called from the input interrupt service
|
||||
* routine in order to enqueue incoming data and generate the related events.
|
||||
* @param sd pointer to a @p FullDuplexDriver structure
|
||||
* @param b the byte to be written in the driver's input queue
|
||||
* routine in order to enqueue incoming data and generate the
|
||||
* related events.
|
||||
* @param[in] sd pointer to a @p FullDuplexDriver structure
|
||||
* @param[in] b the byte to be written in the driver's input queue
|
||||
*/
|
||||
void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
|
||||
|
||||
|
|
@ -163,10 +169,10 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
|
|||
|
||||
/**
|
||||
* @brief Handles outgoing data.
|
||||
* @brief Must be called from the output interrupt service routine in order
|
||||
* @details Must be called from the output interrupt service routine in order
|
||||
* to get the next byte to be transmitted.
|
||||
*
|
||||
* @param sd pointer to a @p HalfDuplexDriver structure
|
||||
* @param[in] sd pointer to a @p HalfDuplexDriver structure
|
||||
* @return The byte value read from the driver's output queue.
|
||||
* @retval Q_EMPTY if the queue is empty (the lower driver usually disables
|
||||
* the interrupt source when this happens).
|
||||
|
|
@ -184,8 +190,8 @@ msg_t chHDDRequestDataI(HalfDuplexDriver *sd) {
|
|||
* @details Must be called from the I/O interrupt service routine in order to
|
||||
* notify I/O conditions as errors, signals change etc.
|
||||
*
|
||||
* @param sd pointer to a @p HalfDuplexDriver structure
|
||||
* @param mask condition flags to be added to the mask
|
||||
* @param[in] sd pointer to a @p HalfDuplexDriver structure
|
||||
* @param[in] mask condition flags to be added to the mask
|
||||
*/
|
||||
void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {
|
||||
|
||||
|
|
@ -196,7 +202,7 @@ void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {
|
|||
/**
|
||||
* @brief Returns and clears the errors mask associated to the driver.
|
||||
*
|
||||
* @param sd pointer to a @p HalfDuplexDriver structure
|
||||
* @param[in] sd pointer to a @p HalfDuplexDriver structure
|
||||
* @return The condition flags modified since last time this function was
|
||||
* invoked.
|
||||
*/
|
||||
|
|
|
|||
14
src/chsys.c
14
src/chsys.c
|
|
@ -32,12 +32,11 @@ static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE);
|
|||
* @brief This function implements the idle thread infinite loop.
|
||||
* @details The function puts the processor in the lowest power mode capable
|
||||
* to serve interrupts.<br>
|
||||
* The priority is internally set to the minimum system value so that this
|
||||
* thread is executed only if there are no other ready threads in the system.
|
||||
* The priority is internally set to the minimum system value so
|
||||
* that this thread is executed only if there are no other ready
|
||||
* threads in the system.
|
||||
*
|
||||
* @param p the thread parameter, unused in this scenario
|
||||
* @note Implementation should declare this function as a weak symbol in order
|
||||
* to allow applications to re-implement it.
|
||||
* @param[in] p the thread parameter, unused in this scenario
|
||||
*/
|
||||
static void idle_thread(void *p) {
|
||||
|
||||
|
|
@ -88,8 +87,9 @@ void chSysInit(void) {
|
|||
/**
|
||||
* @brief Handles time ticks for round robin preemption and timer increments.
|
||||
* @details Decrements the remaining time quantum of the running thread
|
||||
* and preempts it when the quantum is used up. Increments system time and
|
||||
* manages the timers.
|
||||
* and preempts it when the quantum is used up. Increments system
|
||||
* time and manages the timers.
|
||||
*
|
||||
* @note The frequency of the timer determines the system tick granularity and,
|
||||
* together with the @p CH_TIME_QUANTUM macro, the round robin interval.
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue