Macros
Config

Macros

#define CHPRINTF_USE_FLOAT   TRUE
 
#define CORTEX_SIMPLIFIED_PRIORITY   TRUE
 
#define PORT_IDLE_THREAD_STACK_SIZE   64
 
#define PORT_INT_REQUIRED_STACK   128
 

Kernel parameters and options

#define CH_FREQUENCY   10000
 System tick frequency. More...
 
#define CH_TIME_QUANTUM   4
 Round robin interval. More...
 
#define CH_MEMCORE_SIZE   0
 Managed RAM size. More...
 
#define CH_NO_IDLE_THREAD   FALSE
 Idle thread automatic spawn suppression. More...
 

Performance options

#define CH_OPTIMIZE_SPEED   TRUE
 OS optimization. More...
 

Subsystem options

#define CH_USE_REGISTRY   TRUE
 Threads registry APIs. More...
 
#define CH_USE_WAITEXIT   TRUE
 Threads synchronization APIs. More...
 
#define CH_USE_SEMAPHORES   TRUE
 Semaphores APIs. More...
 
#define CH_USE_SEMAPHORES_PRIORITY   FALSE
 Semaphores queuing mode. More...
 
#define CH_USE_SEMSW   TRUE
 Atomic semaphore API. More...
 
#define CH_USE_MUTEXES   TRUE
 Mutexes APIs. More...
 
#define CH_USE_CONDVARS   TRUE
 Conditional Variables APIs. More...
 
#define CH_USE_CONDVARS_TIMEOUT   TRUE
 Conditional Variables APIs with timeout. More...
 
#define CH_USE_EVENTS   TRUE
 Events Flags APIs. More...
 
#define CH_USE_EVENTS_TIMEOUT   TRUE
 Events Flags APIs with timeout. More...
 
#define CH_USE_MESSAGES   TRUE
 Synchronous Messages APIs. More...
 
#define CH_USE_MESSAGES_PRIORITY   FALSE
 Synchronous Messages queuing mode. More...
 
#define CH_USE_MAILBOXES   TRUE
 Mailboxes APIs. More...
 
#define CH_USE_QUEUES   TRUE
 I/O Queues APIs. More...
 
#define CH_USE_MEMCORE   TRUE
 Core Memory Manager APIs. More...
 
#define CH_USE_HEAP   TRUE
 Heap Allocator APIs. More...
 
#define CH_USE_MALLOC_HEAP   FALSE
 C-runtime allocator. More...
 
#define CH_USE_MEMPOOLS   TRUE
 Memory Pools Allocator APIs. More...
 
#define CH_USE_DYNAMIC   TRUE
 Dynamic Threads APIs. More...
 

Debug options

#define CH_DBG_SYSTEM_STATE_CHECK   FALSE
 Debug option, system state check. More...
 
#define CH_DBG_ENABLE_CHECKS   FALSE
 Debug option, parameters checks. More...
 
#define CH_DBG_ENABLE_ASSERTS   FALSE
 Debug option, consistency checks. More...
 
#define CH_DBG_ENABLE_TRACE   FALSE
 Debug option, trace buffer. More...
 
#define CH_DBG_ENABLE_STACK_CHECK   FALSE
 Debug option, stack checks. More...
 
#define CH_DBG_FILL_THREADS   FALSE
 Debug option, stacks initialization. More...
 
#define CH_DBG_THREADS_PROFILING   TRUE
 Debug option, threads profiling. More...
 

Kernel hooks

#define THREAD_EXT_FIELDS   /* Add threads custom fields here.*/
 Threads descriptor structure extension. More...
 
#define THREAD_EXT_INIT_HOOK(tp)
 Threads initialization hook. More...
 
#define THREAD_EXT_EXIT_HOOK(tp)
 Threads finalization hook. More...
 
#define THREAD_CONTEXT_SWITCH_HOOK(ntp, otp)
 Context switch hook. More...
 
#define IDLE_LOOP_HOOK()
 Idle Loop hook. More...
 
#define SYSTEM_TICK_EVENT_HOOK()
 System tick event hook. More...
 
#define SYSTEM_HALT_HOOK()
 System halt hook. More...
 

Detailed Description

Kernel related settings and hooks.

Macro Definition Documentation

#define CH_DBG_ENABLE_ASSERTS   FALSE

Debug option, consistency checks.

If enabled then all the assertions in the kernel code are activated. This includes consistency checks inside the kernel, runtime anomalies and port-defined checks.

Note
The default is FALSE.
#define CH_DBG_ENABLE_CHECKS   FALSE

Debug option, parameters checks.

If enabled then the checks on the API functions input parameters are activated.

Note
The default is FALSE.
#define CH_DBG_ENABLE_STACK_CHECK   FALSE

Debug option, stack checks.

If enabled then a runtime stack check is performed.

Note
The default is FALSE.
The stack check is performed in a architecture/port dependent way. It may not be implemented or some ports.
The default failure mode is to halt the system with the global panic_msg variable set to NULL.
#define CH_DBG_ENABLE_TRACE   FALSE

Debug option, trace buffer.

If enabled then the context switch circular trace buffer is activated.

Note
The default is FALSE.
#define CH_DBG_FILL_THREADS   FALSE

Debug option, stacks initialization.

If enabled then the threads working area is filled with a byte value when a thread is created. This can be useful for the runtime measurement of the used stack.

Note
The default is FALSE.
#define CH_DBG_SYSTEM_STATE_CHECK   FALSE

Debug option, system state check.

If enabled the correct call protocol for system APIs is checked at runtime.

Note
The default is FALSE.
#define CH_DBG_THREADS_PROFILING   TRUE

Debug option, threads profiling.

If enabled then a field is added to the Thread structure that counts the system ticks occurred while executing the thread.

Note
The default is TRUE.
This debug option is defaulted to TRUE because it is required by some test cases into the test suite.
#define CH_FREQUENCY   10000

System tick frequency.

Frequency of the system timer that drives the system ticks. This setting also defines the system tick time unit.

#define CH_MEMCORE_SIZE   0

Managed RAM size.

Size of the RAM area to be managed by the OS. If set to zero then the whole available RAM is used. The core memory is made available to the heap allocator and/or can be used directly through the simplified core memory allocator.

Note
In order to let the OS manage the whole RAM the linker script must provide the heap_base and heap_end symbols.
Requires CH_USE_MEMCORE.
#define CH_NO_IDLE_THREAD   FALSE

Idle thread automatic spawn suppression.

When this option is activated the function chSysInit() does not spawn the idle thread automatically. The application has then the responsibility to do one of the following:

  • Spawn a custom idle thread at priority IDLEPRIO.
  • Change the main() thread priority to IDLEPRIO then enter an endless loop. In this scenario the main() thread acts as the idle thread.
Note
Unless an idle thread is spawned the main() thread must not enter a sleep state.
#define CH_OPTIMIZE_SPEED   TRUE

OS optimization.

If enabled then time efficient rather than space efficient code is used when two possible implementations exist.

Note
This is not related to the compiler optimization options.
The default is TRUE.
#define CH_TIME_QUANTUM   4

Round robin interval.

This constant is the number of system ticks allowed for the threads before preemption occurs. Setting this value to zero disables the preemption for threads with equal priority and the round robin becomes cooperative. Note that higher priority threads can still preempt, the kernel is always preemptive.

Note
Disabling the round robin preemption makes the kernel more compact and generally faster.
#define CH_USE_CONDVARS   TRUE

Conditional Variables APIs.

If enabled then the conditional variables APIs are included in the kernel.

Note
The default is TRUE.
Requires CH_USE_MUTEXES.
#define CH_USE_CONDVARS_TIMEOUT   TRUE

Conditional Variables APIs with timeout.

If enabled then the conditional variables APIs with timeout specification are included in the kernel.

Note
The default is TRUE.
Requires CH_USE_CONDVARS.
#define CH_USE_DYNAMIC   TRUE

Dynamic Threads APIs.

If enabled then the dynamic threads creation APIs are included in the kernel.

Note
The default is TRUE.
Requires CH_USE_WAITEXIT.
Requires CH_USE_HEAP and/or CH_USE_MEMPOOLS.
#define CH_USE_EVENTS   TRUE

Events Flags APIs.

If enabled then the event flags APIs are included in the kernel.

Note
The default is TRUE.
#define CH_USE_EVENTS_TIMEOUT   TRUE

Events Flags APIs with timeout.

If enabled then the events APIs with timeout specification are included in the kernel.

Note
The default is TRUE.
Requires CH_USE_EVENTS.
#define CH_USE_HEAP   TRUE

Heap Allocator APIs.

If enabled then the memory heap allocator APIs are included in the kernel.

Note
The default is TRUE.
Requires CH_USE_MEMCORE and either CH_USE_MUTEXES or CH_USE_SEMAPHORES.
Mutexes are recommended.
#define CH_USE_MAILBOXES   TRUE

Mailboxes APIs.

If enabled then the asynchronous messages (mailboxes) APIs are included in the kernel.

Note
The default is TRUE.
Requires CH_USE_SEMAPHORES.
#define CH_USE_MALLOC_HEAP   FALSE

C-runtime allocator.

If enabled the the heap allocator APIs just wrap the C-runtime malloc() and free() functions.

Note
The default is FALSE.
Requires CH_USE_HEAP.
The C-runtime may or may not require CH_USE_MEMCORE, see the appropriate documentation.
#define CH_USE_MEMCORE   TRUE

Core Memory Manager APIs.

If enabled then the core memory manager APIs are included in the kernel.

Note
The default is TRUE.
#define CH_USE_MEMPOOLS   TRUE

Memory Pools Allocator APIs.

If enabled then the memory pools allocator APIs are included in the kernel.

Note
The default is TRUE.
#define CH_USE_MESSAGES   TRUE

Synchronous Messages APIs.

If enabled then the synchronous messages APIs are included in the kernel.

Note
The default is TRUE.
#define CH_USE_MESSAGES_PRIORITY   FALSE

Synchronous Messages queuing mode.

If enabled then messages are served by priority rather than in FIFO order.

Note
The default is FALSE. Enable this if you have special requirements.
Requires CH_USE_MESSAGES.
#define CH_USE_MUTEXES   TRUE

Mutexes APIs.

If enabled then the mutexes APIs are included in the kernel.

Note
The default is TRUE.
#define CH_USE_QUEUES   TRUE

I/O Queues APIs.

If enabled then the I/O queues APIs are included in the kernel.

Note
The default is TRUE.
#define CH_USE_REGISTRY   TRUE

Threads registry APIs.

If enabled then the registry APIs are included in the kernel.

Note
The default is TRUE.
#define CH_USE_SEMAPHORES   TRUE

Semaphores APIs.

If enabled then the Semaphores APIs are included in the kernel.

Note
The default is TRUE.
#define CH_USE_SEMAPHORES_PRIORITY   FALSE

Semaphores queuing mode.

If enabled then the threads are enqueued on semaphores by priority rather than in FIFO order.

Note
The default is FALSE. Enable this if you have special requirements.
Requires CH_USE_SEMAPHORES.
#define CH_USE_SEMSW   TRUE

Atomic semaphore API.

If enabled then the semaphores the chSemSignalWait() API is included in the kernel.

Note
The default is TRUE.
Requires CH_USE_SEMAPHORES.
#define CH_USE_WAITEXIT   TRUE

Threads synchronization APIs.

If enabled then the chThdWait() function is included in the kernel.

Note
The default is TRUE.
#define CHPRINTF_USE_FLOAT   TRUE
#define CORTEX_SIMPLIFIED_PRIORITY   TRUE
#define IDLE_LOOP_HOOK ( )
Value:
{ \
/* Idle loop code here.*/ \
}

Idle Loop hook.

This hook is continuously invoked by the idle thread loop.

#define PORT_IDLE_THREAD_STACK_SIZE   64
#define PORT_INT_REQUIRED_STACK   128
#define SYSTEM_HALT_HOOK ( )
Value:
{ \
/* System halt code here.*/ \
}

System halt hook.

This hook is invoked in case to a system halting error before the system is halted.

#define SYSTEM_TICK_EVENT_HOOK ( )
Value:
{ \
/* System tick event code here.*/ \
}

System tick event hook.

This hook is invoked in the system tick handler immediately after processing the virtual timers queue.

#define THREAD_CONTEXT_SWITCH_HOOK (   ntp,
  otp 
)
Value:
{ \
/* System halt code here.*/ \
}

Context switch hook.

This hook is invoked just before switching between threads.

#define THREAD_EXT_EXIT_HOOK (   tp)
Value:
{ \
/* Add threads finalization code here.*/ \
}

Threads finalization hook.

User finalization code added to the chThdExit() API.

Note
It is inserted into lock zone.
It is also invoked when the threads simply return in order to terminate.
#define THREAD_EXT_FIELDS   /* Add threads custom fields here.*/

Threads descriptor structure extension.

User fields added to the end of the Thread structure.

#define THREAD_EXT_INIT_HOOK (   tp)
Value:
{ \
/* Add threads initialization code here.*/ \
}

Threads initialization hook.

User initialization code added to the chThdInit() API.

Note
It is invoked from within chThdInit() and implicitly from all the threads creation APIs.