diff --git a/demos/ARM7-AT91SAM7X-GCC/chconf.h b/demos/ARM7-AT91SAM7X-GCC/chconf.h index 57cc9d013..13c3766e4 100644 --- a/demos/ARM7-AT91SAM7X-GCC/chconf.h +++ b/demos/ARM7-AT91SAM7X-GCC/chconf.h @@ -147,6 +147,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/ARM7-AT91SAM7X-WEB-GCC/chconf.h b/demos/ARM7-AT91SAM7X-WEB-GCC/chconf.h index 57cc9d013..13c3766e4 100644 --- a/demos/ARM7-AT91SAM7X-WEB-GCC/chconf.h +++ b/demos/ARM7-AT91SAM7X-WEB-GCC/chconf.h @@ -147,6 +147,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/ARM7-LPC214x-G++/chconf.h b/demos/ARM7-LPC214x-G++/chconf.h index 292074816..3bf626af0 100644 --- a/demos/ARM7-LPC214x-G++/chconf.h +++ b/demos/ARM7-LPC214x-G++/chconf.h @@ -147,6 +147,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/ARM7-LPC214x-GCC-minimal/chconf.h b/demos/ARM7-LPC214x-GCC-minimal/chconf.h index 206272504..da927fe6a 100644 --- a/demos/ARM7-LPC214x-GCC-minimal/chconf.h +++ b/demos/ARM7-LPC214x-GCC-minimal/chconf.h @@ -147,6 +147,12 @@ * are included in the kernel.*/ //#define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +//#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/ARM7-LPC214x-GCC/chconf.h b/demos/ARM7-LPC214x-GCC/chconf.h index 57cc9d013..13c3766e4 100644 --- a/demos/ARM7-LPC214x-GCC/chconf.h +++ b/demos/ARM7-LPC214x-GCC/chconf.h @@ -147,6 +147,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/ARMCM3-STM32F103-GCC/chconf.h b/demos/ARMCM3-STM32F103-GCC/chconf.h index 57cc9d013..13c3766e4 100644 --- a/demos/ARMCM3-STM32F103-GCC/chconf.h +++ b/demos/ARMCM3-STM32F103-GCC/chconf.h @@ -147,6 +147,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/AVR-AT90CANx-GCC/chconf.h b/demos/AVR-AT90CANx-GCC/chconf.h index eca46b974..a3c3697af 100644 --- a/demos/AVR-AT90CANx-GCC/chconf.h +++ b/demos/AVR-AT90CANx-GCC/chconf.h @@ -147,6 +147,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/AVR-ATmega128-GCC/chconf.h b/demos/AVR-ATmega128-GCC/chconf.h index c44cd39d5..f3975e8a4 100644 --- a/demos/AVR-ATmega128-GCC/chconf.h +++ b/demos/AVR-ATmega128-GCC/chconf.h @@ -147,6 +147,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/MSP430-MSP430x1611-GCC/chconf.h b/demos/MSP430-MSP430x1611-GCC/chconf.h index 0d1773a6a..40a333f1c 100644 --- a/demos/MSP430-MSP430x1611-GCC/chconf.h +++ b/demos/MSP430-MSP430x1611-GCC/chconf.h @@ -148,6 +148,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/demos/Win32-MinGW/chconf.h b/demos/Win32-MinGW/chconf.h index b52281cfa..c5bbf0410 100644 --- a/demos/Win32-MinGW/chconf.h +++ b/demos/Win32-MinGW/chconf.h @@ -148,6 +148,12 @@ * are included in the kernel.*/ #define CH_USE_MEMPOOLS +/** Configuration option: if specified then the dynamic objects creation APIs + * are included in the kernel. + * @note requires \p CH_USE_WAITEXIT. + */ +#define CH_USE_DYNAMIC + /** Configuration option: Frequency of the system timer that drives the system * ticks. This also defines the system time unit.*/ #define CH_FREQUENCY 1000 diff --git a/docs/Doxyfile b/docs/Doxyfile index 4e317e174..3abb12ff1 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -260,7 +260,8 @@ PREDEFINED = __JUST_STUBS__ \ CH_USE_MESSAGES_EVENT \ CH_USE_MESSAGES_PRIORITY \ CH_USE_DEBUG \ - CH_USE_TRACE + CH_USE_TRACE \ + CH_USE_DYNAMIC EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- diff --git a/readme.txt b/readme.txt index f68d6979a..446995854 100644 --- a/readme.txt +++ b/readme.txt @@ -75,13 +75,16 @@ Win32-MinGW - ChibiOS/RT simulator and demo into a WIN32 process, ***************************************************************************** *** 0.7.1 *** -- NEW: New chThdInit() API, this API allows to quickly create threads in the - PRSUSPENDED state. This API also allows to start threads from interrupt - handlers. -- CHANGE: The chThdCreate() API no more has the mode parameter, a different - API is now used in order to start suspended threads. +- NEW: New chThdInit() and chThdCreateStatic() APIs now replace the old + chThdCreate() and chThdCreateFast() that are marked as deprecated. + The new APIs use one less parameter and are faster. +- NEW: New dynamic chThdCreateFromHeap() and chthdCreateFromMemoryPool() APIs. + The dynamic APIs are only included if the CH_USE_DYNAMIC option is specified + into the project configuration file. - FIX: The chThdCreate() had a regression in 0.7.0, the mode parameter was - ignored. Note that in this version the mode parameter had been removed. + ignored. Note that in this version the API is deprecated and the bug + documented as correct behavior. If you need to create a suspended thread + please use the new chThdInit() API. *** 0.7.0 *** - NEW: Memory Heap Allocator functionality added. The allocator implements a diff --git a/src/chinit.c b/src/chinit.c index 0063fa458..0d4aafea1 100644 --- a/src/chinit.c +++ b/src/chinit.c @@ -49,7 +49,7 @@ void chSysInit(void) { /* * Now this instructions flow becomes the main thread. */ - init_thread(NORMALPRIO, &mainthread); + init_thread(&mainthread, NORMALPRIO); mainthread.p_state = PRCURR; currp = &mainthread; @@ -61,8 +61,8 @@ void chSysInit(void) { * serve interrupts in its context while keeping the lowest energy saving * mode compatible with the system status. */ - chThdCreateFast(IDLEPRIO, waIdleThread, sizeof(waIdleThread), - (tfunc_t)_IdleThread); + chThdCreateStatic(waIdleThread, sizeof(waIdleThread), + IDLEPRIO, (tfunc_t)_IdleThread, NULL); } /** diff --git a/src/chthreads.c b/src/chthreads.c index e98bb725f..f4d355a4b 100644 --- a/src/chthreads.c +++ b/src/chthreads.c @@ -27,7 +27,7 @@ /* * Initializes a thread structure. */ -void init_thread(tprio_t prio, Thread *tp) { +void init_thread(Thread *tp, tprio_t prio) { static tid_t nextid = 0; tp->p_tid = nextid++; @@ -83,8 +83,8 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) { * @note This function can be used to start a thead from within an interrupt * handler by manually making it ready with \p chSchReadyI(). */ -Thread *chThdInit(tprio_t prio, void *workspace, - size_t wsize, tfunc_t pf, void *arg) { +Thread *chThdInit(void *workspace, size_t wsize, + tprio_t prio, tfunc_t pf, void *arg) { /* thread structure is layed out in the lower part of the thread workspace */ Thread *tp = workspace; @@ -95,15 +95,114 @@ Thread *chThdInit(tprio_t prio, void *workspace, memfill(workspace, wsize, MEM_FILL_PATTERN); #endif SETUP_CONTEXT(workspace, wsize, pf, arg); - init_thread(prio, tp); + init_thread(tp, prio); return tp; } +/** + * Creates a new thread into a static memory area. + * @param workspace pointer to a working area dedicated to the thread stack + * @param wsize size of the working area. + * @param prio the priority level for the new thread. Usually the threads are + * created with priority \p NORMALPRIO, priorities + * can range from \p LOWPRIO to \p HIGHPRIO. + * @param pf the thread function. Returning from this function automatically + * terminates the thread. + * @param arg an argument passed to the thread function. It can be \p NULL. + * @return the pointer to the \p Thread structure allocated for the + * thread into the working space area. + * @note A thread can terminate by calling \p chThdExit() or by simply + * returning from its main function. + */ +Thread *chThdCreateStatic(void *workspace, size_t wsize, + tprio_t prio, tfunc_t pf, void *arg) { + + Thread *tp = chThdInit(workspace, wsize, prio, pf, arg); + chSysLock(); + chSchWakeupS(tp, RDY_OK); + chSysUnlock(); + return tp; +} + +#if defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_HEAP) +/** + * Creates a new thread allocating the memory from the heap. + * @param wsize size of the working area to be allocated + * @param prio the priority level for the new thread. Usually the threads are + * created with priority \p NORMALPRIO, priorities + * can range from \p LOWPRIO to \p HIGHPRIO. + * @param pf the thread function. Returning from this function automatically + * terminates the thread. + * @param arg an argument passed to the thread function. It can be \p NULL. + * @return the pointer to the \p Thread structure allocated for the + * thread into the working space area or \p NULL if the memory cannot + * be allocated. + * @note A thread can terminate by calling \p chThdExit() or by simply + * returning from its main function. + * @note The memory allocated for the thread is not released when the thread + * terminates but when a \p chThdWait() is performed. + * @note The function is available only if the \p CH_USE_DYNAMIC, + * \p CH_USE_HEAP and \p CH_USE_WAITEXIT options are enabled + * in \p chconf.h. + */ +Thread *chThdCreateFromHeap(size_t wsize, tprio_t prio, + tfunc_t pf, void *arg) { + + void *workspace = chHeapAlloc(wsize); + if (workspace == NULL) + return NULL; + Thread *tp = chThdInit(workspace, wsize, prio, pf, arg); + tp->p_flags |= P_MEM_MODE_HEAP; + chSysLock(); + chSchWakeupS(tp, RDY_OK); + chSysUnlock(); + return tp; +} +#endif /* defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_HEAP) */ + +#if defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_MEMPOOLS) +/** + * Creates a new thread allocating the memory from the specified Memory Pool. + * @param mp the memory pool + * @param prio the priority level for the new thread. Usually the threads are + * created with priority \p NORMALPRIO, priorities + * can range from \p LOWPRIO to \p HIGHPRIO. + * @param pf the thread function. Returning from this function automatically + * terminates the thread. + * @param arg an argument passed to the thread function. It can be \p NULL. + * @return the pointer to the \p Thread structure allocated for the + * thread into the working space area or \p NULL if the memory cannot + * be allocated. + * @note A thread can terminate by calling \p chThdExit() or by simply + * returning from its main function. + * @note The memory allocated for the thread is not released when the thread + * terminates but when a \p chThdWait() is performed. + * @note The function is available only if the \p CH_USE_DYNAMIC, + * \p CH_USE_MEMPOOLS and \p CH_USE_WAITEXIT options are enabled + * in \p chconf.h. + */ +Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio, + tfunc_t pf, void *arg) { + + void *workspace = chPoolAlloc(mp); + if (workspace == NULL) + return NULL; + Thread *tp = chThdInit(workspace, mp->mp_object_size, prio, pf, arg); + tp->p_flags |= P_MEM_MODE_MEMPOOL; + tp->p_mpool = mp; + chSysLock(); + chSchWakeupS(tp, RDY_OK); + chSysUnlock(); + return tp; +} +#endif /* defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_MEMPOOLS) */ + /** * Creates a new thread. * @param prio the priority level for the new thread. Usually the threads are * created with priority \p NORMALPRIO, priorities * can range from \p LOWPRIO to \p HIGHPRIO. + * @param mode ignored * @param workspace pointer to a working area dedicated to the thread stack * @param wsize size of the working area. * @param pf the thread function. Returning from this function automatically @@ -113,15 +212,13 @@ Thread *chThdInit(tprio_t prio, void *workspace, * thread into the working space area. * @note A thread can terminate by calling \p chThdExit() or by simply * returning from its main function. + * @deprecated Please use \p chThdCreateStatic() or \p chThdInit() instead, + * this function will be removed in version 1.0.0. */ -Thread *chThdCreate(tprio_t prio, void *workspace, +Thread *chThdCreate(tprio_t prio, tmode_t mode, void *workspace, size_t wsize, tfunc_t pf, void *arg) { - Thread *tp = chThdInit(prio, workspace, wsize, pf, arg); - chSysLock(); - chSchWakeupS(tp, RDY_OK); - chSysUnlock(); - return tp; + return chThdCreateStatic(workspace, wsize, prio, pf, arg); } /** @@ -137,16 +234,13 @@ Thread *chThdCreate(tprio_t prio, void *workspace, * thread into the working space area. * @note A thread can terminate by calling \p chThdExit() or by simply * returning from its main function. - * @deprecated + * @deprecated Please use \p chThdCreateStatic() or \p chThdInit() instead, + * this function will be removed in version 1.0.0. */ Thread *chThdCreateFast(tprio_t prio, void *workspace, size_t wsize, tfunc_t pf) { - Thread *tp = chThdInit(prio, workspace, wsize, pf, NULL); - chSysLock(); - chSchWakeupS(tp, RDY_OK); - chSysUnlock(); - return tp; + return chThdCreateStatic(workspace, wsize, prio, pf, NULL); } /** @@ -245,9 +339,21 @@ void chThdExit(msg_t msg) { /** * Blocks the execution of the invoking thread until the specified thread * terminates then the exit code is returned. - * - * @param tp the pointer to the thread - * @return the exit code + * The memory used by the exited thread is handled in different ways depending + * on the API that spawned the thread: + *