microbit-dal/inc/MicroBitFiber.h

273 lines
9 KiB
C
Raw Normal View History

/**
* Definitions for the MicroBit Fiber scheduler.
*
* This lightweight, non-preemptive scheduler provides a simple threading mechanism for two main purposes:
*
* 1) To provide a clean abstraction for application languages to use when building async behaviour (callbacks).
* 2) To provide ISR decoupling for Messagebus events generted in an ISR context.
*/
#ifndef MICROBIT_FIBER_H
#define MICROBIT_FIBER_H
#include "mbed.h"
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
#include "MicroBitConfig.h"
microbit: Added configurable concurrency modes for MicroBitMessageBus handlers. MessageBus handlers can now have one of four concurrency modes for the eventuality of an event being raised whilst a previous event is still being processed. An additional (optional) parameter is provided to the listen() functions to allow this to be selected on a per event handler basis. The permissable options are: MESSAGE_BUS_LISTENER_REENTRANT: The event handler is fired with the new event, regardless of whether or not a previous event is still be processed by that handler. MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY: The new event is queued until such a time as the previous event has completed execution. The new event is then processed. This option does not preclude the processing of the new event by other event handlers. MESSAGE_BUS_LISTENER_DROP_IF_BUSY: The new event is dropped, and will never be processed the the event handler. This option does not preclude the processing of the new event by other event handlers. MESSAGE_BUS_LISTENER_NONBLOCKING: The event handler is self-declaring that it never blocks. This flag is used purely for optimisation, as it permits direct execution of the event hadnelr without inducing any overhead from the scheduler. In addition, the following minor revisions were made in this release: * Cleanup of the #include dependencies contained in the microbit-dal .h files * Bugfix to the scheduler block on event matching code. * Introduced a MICROBIT_ID_ALERT MessageBus channel, for general purpose eventing using nonces.
2015-09-11 15:39:38 +00:00
#include "MicroBitEvent.h"
// TODO: Consider a split mode scheduler, that monitors used stack size, and maintains a dedicated, persistent
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
// stack for any long lived fibers with large stack
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
// Fiber Scheduler Flags
#define MICROBIT_FLAG_DATA_READY 0x01
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
// Fiber Flags
#define MICROBIT_FIBER_FLAG_FOB 0x01
#define MICROBIT_FIBER_FLAG_PARENT 0x02
#define MICROBIT_FIBER_FLAG_CHILD 0x04
#define MICROBIT_FIBER_FLAG_DO_NOT_PAGE 0x08
/**
* Thread Context for an ARM Cortex M0 core.
*
* This is probably overkill, but the ARMCC compiler uses a lot register optimisation
* in its calling conventions, so better safe than sorry. :-)
*
*/
struct Cortex_M0_TCB
{
uint32_t R0;
uint32_t R1;
uint32_t R2;
uint32_t R3;
uint32_t R4;
uint32_t R5;
uint32_t R6;
uint32_t R7;
uint32_t R8;
uint32_t R9;
uint32_t R10;
uint32_t R11;
uint32_t R12;
uint32_t SP;
uint32_t LR;
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
uint32_t stack_base;
};
/**
* Representation of a single Fiber
*/
struct Fiber
{
Cortex_M0_TCB tcb; // Thread context when last scheduled out.
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
uint32_t stack_bottom; // The start sddress of this Fiber's stack. Stack is heap allocated, and full descending.
uint32_t stack_top; // The end address of this Fiber's stack.
uint32_t context; // Context specific information.
uint32_t flags; // Information about this fiber.
Fiber **queue; // The queue this fiber is stored on.
Fiber *next, *prev; // Position of this Fiber on the run queues.
};
extern Fiber *currentFiber;
/**
* Initialises the Fiber scheduler.
* Creates a Fiber context around the calling thread, and adds it to the run queue as the current thread.
*
* This function must be called once only from the main thread, and before any other Fiber operation.
*/
void scheduler_init();
/**
* Exit point for all fibers.
* Any fiber reaching the end of its entry function will return here for recycling.
*/
void release_fiber(void);
void release_fiber(void *param);
/**
* Launches a fiber
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
*/
void launch_new_fiber(void (*ep)(void), void (*cp)(void))
#ifdef __GCC__
__attribute__((naked))
#endif
;
void launch_new_fiber_param(void (*ep)(void *), void (*cp)(void *), void *pm)
#ifdef __GCC__
__attribute__((naked))
#endif
;
/**
* Creates a new Fiber, and launches it.
*
* @param entry_fn The function the new Fiber will begin execution in.
* @param completion_fn The function called when the thread completes execution of entry_fn.
* @return The new Fiber.
*/
Fiber *create_fiber(void (*entry_fn)(void), void (*completion_fn)(void) = release_fiber);
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
/**
* Creates a new parameterised Fiber, and launches it.
*
* @param entry_fn The function the new Fiber will begin execution in.
* @param param an untyped parameter passed into the entry_fn anf completion_fn.
* @param completion_fn The function called when the thread completes execution of entry_fn.
* @return The new Fiber.
*/
Fiber *create_fiber(void (*entry_fn)(void *), void *param, void (*completion_fn)(void *) = release_fiber);
/**
* Calls the Fiber scheduler.
* The calling Fiber will likely be blocked, and control given to another waiting fiber.
* Call this to yield control of the processor when you have nothing more to do.
*/
void schedule();
/**
* Blocks the calling thread for the given period of time.
* The calling thread will be immediatley descheduled, and placed onto a
* wait queue until the requested amount of time has elapsed.
*
* n.b. the fiber will not be be made runnable until after the elasped time, but there
* are no guarantees precisely when the fiber will next be scheduled.
*
* @param t The period of time to sleep, in milliseconds.
*/
void fiber_sleep(unsigned long t);
/**
* Timer callback. Called from interrupt context, once every FIBER_TICK_PERIOD_MS milliseconds.
* Simply checks to determine if any fibers blocked on the sleep queue need to be woken up
* and made runnable.
*/
void scheduler_tick();
/**
* Blocks the calling thread until the specified event is raised.
* The calling thread will be immediatley descheduled, and placed onto a
* wait queue until the requested event is received.
*
* n.b. the fiber will not be be made runnable until after the event is raised, but there
* are no guarantees precisely when the fiber will next be scheduled.
*
* @param id The ID field of the event to listen for (e.g. MICROBIT_ID_BUTTON_A)
* @param value The VALUE of the event to listen for (e.g. MICROBIT_BUTTON_EVT_CLICK)
*/
void fiber_wait_for_event(uint16_t id, uint16_t value);
/**
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
* Executes the given function asynchronously if necessary.
*
* Fibers are often used to run event handlers, however many of these event handlers are very simple functions
* that complete very quickly, bringing unecessary RAM overhead.
*
* This function takes a snapshot of the current processor context, then attempts to optimistically call the given function directly.
* We only create an additional fiber if that function performs a block operation.
*
* @param entry_fn The function to execute.
*/
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
void invoke(void (*entry_fn)(void));
/**
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
* Executes the given function asynchronously if necessary.
*
* Fibers are often used to run event handlers, however many of these event handlers are very simple functions
* that complete very quickly, bringing unecessary RAM. overhead
*
* This function takes a snapshot of the current fiber context, then attempt to optimistically call the given function directly.
* We only create an additional fiber if that function performs a block operation.
*
* @param entry_fn The function to execute.
* @param param an untyped parameter passed into the entry_fn anf completion_fn.
*/
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
void invoke(void (*entry_fn)(void *), void *param);
/**
* Resizes the stack allocation of the current fiber if necessary to hold the system stack.
*
* If the stack allocaiton is large enough to hold the current system stack, then this function does nothing.
* Otherwise, the the current allocation of the fiber is freed, and a larger block is allocated.
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
*
* @param f The fiber context to verify.
* @return The stack depth of the given fiber.
*/
inline void verify_stack_size(Fiber *f);
/**
* Event callback. Called from the message bus whenever an event is raised.
* Checks to determine if any fibers blocked on the wait queue need to be woken up
* and made runnable due to the event.
*/
void scheduler_event(MicroBitEvent evt);
microbit: Memory Optimisation Mega Update This release contains a widespread set of updates and optimisations to the micro:bit runtime, with a view to reducing the SRAM footprint of the whole system. This is to provide as much usable HEAP storage for application programs as possible. Specific updates and optimisations include: - Additional compilation flags to allow the core micro:bit runtime to be configured. These are defined in MicroBitConfig.h - A custom heap allocator. This is now included for two reasons: 1) To provide a simple mechanism to to utilise both the mbed heap space and other memory regions (such as unused memory in the SoftDevice region) as a single virtual heap. 2) To address some issues that have been noted that are attributable to heap fragmentation. The micro:bit heap allocator has a simple algorithm, but one that is chosen to respond well to the relativelt high 'heap churn' found in the micro:bit environment. All micro:bit components and user programs now use this heap allocator trasparently. - Updates to BLE services to remove persistent references to their GATT services. This consumes vast amounts SRAM, rather unecessarily. Instead only handles to the relevant GATT characteristics are now stored. This specifically includes: + MicroBitDFUService + MicroBitEventService + DeviceInformationService - Updates to the Fiber scheduler to save SRAM. More specifically: + Removed the need to hold an empty processor context to intialise fibers. + The IDLE fiber now runs without a stack + fiber stacks are now only created when a fiber is descheduled for the first time, thereby reducing heap churn. + the 'main' fiber is now recycled into the fiber_pool if it leaves app_main() + fibers created through invoke() now only maintains the necessary part of teh parent stack that is needed, thereby reducing the stack size of spawned fibers. - Updates to the Message Bus to reduce the overall memory footprint of processing events. More specifically: + Event handlers are now always called using invoke(), such that non-blocking event handlers no longer need a dedicated fiber to execute - thereby saving SRAM and processor time. + Processing of events from the event queue is now rate paced. Events only continue to be processed as long as there are no fibers on the run queue. i.e. event processing is no longer greedy, thereby reducing the number of fibers created on the runqueue. - Updates to BLUEZOENE code to bring up core BLE services even if they are not enabled by default. This allows programs that do not require BLE to operate to benefit from the full range of SRAM, whilst still allowing the device to be programmed over BLE. - Updates to the Soft Device initialisation configuration, reducing the size of the GATT table held in the top 1.8K of its 8K memory region to around 800 bytes. This is sufficient to run the default set of BLE services on the micro:bit so the additional memory is configured as HEAP storage by MicroBitHeapAllocator. - Minor changes to a range of components to integrate with the above changes. + rename of free() to release() in DynamicPWM to avoid namespace collision with MicroBitHeap free() + rename of fork_on_block to invoke() to enhance readbility. - Many code cleanups and updates to out of date comments.
2015-08-31 22:25:10 +00:00
/**
* Determines if any fibers are waiting to be scheduled.
* @return The number of fibers currently on the run queue
*/
int scheduler_runqueue_empty();
/**
* Utility function to add the currenty running fiber to the given queue.
* Perform a simple add at the head, to avoid complexity,
* Queues are normally very short, so maintaining a doubly linked, sorted list typically outweighs the cost of
* brute force searching.
*
* @param f The fiber to add to the queue
* @param queue The run queue to add the fiber to.
*/
void queue_fiber(Fiber *f, Fiber **queue);
/**
* Utility function to the given fiber from whichever queue it is currently stored on.
* @param f the fiber to remove.
*/
void dequeue_fiber(Fiber *f);
/**
* Set of tasks to perform when idle.
* Service any background tasks that are required, and attmept power efficient sleep.
*/
void idle();
/**
* IDLE task.
* Only scheduled for execution when the runqueue is empty. Typically calls idle().
*/
void idle_task();
/**
* Determines if the processor is executing in interrupt context.
* @return true if any the processor is currently executing any interrupt service routine. False otherwise.
*/
inline int inInterruptContext()
{
return (((int)__get_IPSR()) & 0x003F) > 0;
}
/**
* Assembler Context switch routing.
* Defined in CortexContextSwitch.s
*/
extern "C" void swap_context(Cortex_M0_TCB *from, Cortex_M0_TCB *to, uint32_t from_stack, uint32_t to_stack);
extern "C" void save_context(Cortex_M0_TCB *tcb, uint32_t stack);
extern "C" void save_register_context(Cortex_M0_TCB *tcb);
extern "C" void restore_register_context(Cortex_M0_TCB *tcb);
/**
* Time since power on. Measured in milliseconds.
* When stored as an unsigned long, this gives us approx 50 days between rollover, which is ample. :-)
*/
extern unsigned long ticks;
/**
* This variable is used to prioritise the systems' idle fibre to execute essential tasks.
*/
extern uint8_t fiber_flags;
#endif