mutek/kroutine.h header reference
[Kernel services module]
The source code of this header can be browsed online.
Description [link]
This header provides a deferred callback function service where the actual execution of the function may be scheduled for execution at various times depending on the policy requested along with the callback function pointer.
This is mainly used to implement deferred interrupt processing and various device request termination callbacks.
The kroutine_init* functions are used to initialize a routine and the kroutine_exec function must be called when the routine have to be executed or scheduled for execution. The enum kroutine_policy_e enum specifies the various available execution policies.
Members [link]
Types [link]
- enum kroutine_exec_flags_e
- typedef void (kroutine_exec_t)(struct kroutine_s *kr, enum kroutine_exec_flags_e flags)
- typedef [...] * kroutine_list_item_t
- typedef [...] kroutine_list_root_t
- enum kroutine_policy_e
- struct kroutine_queue_s
- struct kroutine_s
- struct kroutine_sequence_s
Functions [link]
- bool_t kroutine_exec(struct kroutine_s *kr)
- bool_t kroutine_exec_flags(struct kroutine_s *kr, uint8_t user_flags)
- void kroutine_init(struct kroutine_s *kr, kroutine_exec_t *exec, enum kroutine_policy_e policy)
- void kroutine_init_deferred(struct kroutine_s *kr, kroutine_exec_t *exec)
- void kroutine_init_deferred_cpu(struct kroutine_s *kr, kroutine_exec_t *exec, struct cpu_tree_s *cpu)
- void kroutine_init_deferred_local(struct kroutine_s *kr, kroutine_exec_t *exec)
- void kroutine_init_deferred_seq(struct kroutine_s *kr, kroutine_exec_t *exec, struct kroutine_sequence_s *seq)
- void kroutine_init_idle(struct kroutine_s *kr, kroutine_exec_t *exec)
- void kroutine_init_immediate(struct kroutine_s *kr, kroutine_exec_t *exec)
- void kroutine_init_interruptible(struct kroutine_s *kr, kroutine_exec_t *exec)
- void kroutine_init_interruptible_cpu(struct kroutine_s *kr, kroutine_exec_t *exec, struct cpu_tree_s *cpu)
- void kroutine_init_interruptible_local(struct kroutine_s *kr, kroutine_exec_t *exec)
- void kroutine_init_interruptible_seq(struct kroutine_s *kr, kroutine_exec_t *exec, struct kroutine_sequence_s *seq)
- void kroutine_init_none(struct kroutine_s *kr)
- void kroutine_init_queue(struct kroutine_s *kr, kroutine_exec_t *exec, struct kroutine_queue_s *queue)
- void kroutine_init_sched_switch(struct kroutine_s *kr, kroutine_exec_t *exec)
- void kroutine_init_sched_switch_cpu(struct kroutine_s *kr, kroutine_exec_t *exec, struct cpu_tree_s *cpu)
- void kroutine_init_sched_switch_local(struct kroutine_s *kr, kroutine_exec_t *exec)
- void kroutine_init_sched_switch_seq(struct kroutine_s *kr, kroutine_exec_t *exec, struct kroutine_sequence_s *seq)
- void kroutine_init_trigger(struct kroutine_s *kr, kroutine_exec_t *exec)
- bool_t kroutine_postpone(struct kroutine_s *kr, enum kroutine_policy_e policy)
- void kroutine_queue_cleanup(struct kroutine_queue_s *q)
- error_t kroutine_queue_init(struct kroutine_queue_s *q, struct semaphore_s *sem)
- bool_t kroutine_queue_process(struct kroutine_queue_s *queue)
- bool_t kroutine_queue_wait(struct kroutine_queue_s *queue)
- void kroutine_seq_cleanup(struct kroutine_sequence_s *seq)
- error_t kroutine_seq_init(struct kroutine_sequence_s *seq)
- void kroutine_set_priority(struct kroutine_s *kr, uint8_t priority)
- bool_t kroutine_trigger(struct kroutine_s *kr, enum kroutine_policy_e policy)
- error_t kroutine_schedule(struct kroutine_s *kr, enum kroutine_policy_e policy)
Macros [link]
Members detail [link]
#define GCT_CONTAINER_ALGO_kroutine_list [link]
This macro is declared in mutek/kroutine.h source file, line 202.
#define GCT_CONTAINER_LOCK_kroutine_list [link]
This macro is declared in mutek/kroutine.h source file, line 203.
#define KROUTINE_CONTAINER(kr, conttype, field) [link]
This macro is declared in mutek/kroutine.h source file, line 86.
This macro can be used to retreive a pointer to the structure containing a struct kroutine_s object.
#define KROUTINE_DEFAULT_PRIORITY [link]
This macro is declared in mutek/kroutine.h source file, line 286.
#define KROUTINE_EXEC(n) [link]
This macro is declared in mutek/kroutine.h source file, line 79.
See also kroutine_exec_t.
#define MUTEK_KROUTINE_H_ [link]
This macro is declared in mutek/kroutine.h source file, line 23.
bool_t kroutine_exec(struct kroutine_s *kr) [link]
This function is declared in mutek/kroutine.h source file, line 644.
This function either schedules execution of the kroutine or executes its handler immediately depending on the policy. This function returns true if the handler has been executed immediately.
For policies other than KROUTINE_TRIGGER, it is ok to call this function multiple times before the handler is actually executed. When deferred execution is used, the handler may be executed only once in this case.
bool_t kroutine_exec_flags(struct kroutine_s *kr, uint8_t user_flags) [link]
This function is declared in mutek/kroutine.h source file, line 578.
This function acts like kroutine_exec letting the caller pass some enum kroutine_exec_flags_e user flags which will be passed to the handler.
When deferred execution is used, multiple invocation of this function before actual execution of the handler will lead to user flags being ored together. The value of user_flags can not be 0.
This is not supported when the policy is KROUTINE_TRIGGER.
enum kroutine_exec_flags_e [link]
This enum is declared in mutek/kroutine.h source file, line 58.
This enum flags are passed to the kroutine_exec_t handler
| Identifier | Description |
|---|---|
| KROUTINE_EXEC_USERFLAG_0 | This can be passed to the kroutine_exec_flags function. |
| KROUTINE_EXEC_USERFLAG_1 | This can be passed to the kroutine_exec_flags function. |
| KROUTINE_EXEC_USERFLAG_2 | This can be passed to the kroutine_exec_flags function. |
| KROUTINE_EXEC_USERFLAG_3 | This can be passed to the kroutine_exec_flags function. |
| KROUTINE_EXEC_USERFLAG_4 | This can be passed to the kroutine_exec_flags function. |
| KROUTINE_EXEC_USERFLAG_5 | This can be passed to the kroutine_exec_flags function. |
| KROUTINE_EXEC_USERFLAG_6 | This can be passed to the kroutine_exec_flags function. |
| KROUTINE_EXEC_USERFLAG_7 | This can be passed to the kroutine_exec_flags function. |
| KROUTINE_EXEC_TRIGGERED | This indicates that the kroutine handler is executed from the kroutine_trigger function. This implies that the kroutine_exec function has been called previously and the retained policy and context allow immediate execution of the kroutine handler. |
| KROUTINE_EXEC_DEFERRED | This indicates that the kroutine handler has been deferred and is therefore executed from an interruptible context. |
typedef void (kroutine_exec_t)(struct kroutine_s *kr, enum kroutine_exec_flags_e flags) [link]
This typedef is declared in mutek/kroutine.h source file, line 83.
Actual routine callback function.
This declaration involves expansion of the KROUTINE_EXEC macro.
void kroutine_init(struct kroutine_s *kr, kroutine_exec_t *exec, enum kroutine_policy_e policy) [link]
This function is declared in mutek/kroutine.h source file, line 305.
This function initializes a routine with the given callback and scheduling policy.
void kroutine_init_deferred(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 360.
This function initializes a kroutine with the KROUTINE_DEFERRED policy.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_deferred_cpu(struct kroutine_s *kr, kroutine_exec_t *exec, struct cpu_tree_s *cpu) [link]
This function is declared in mutek/kroutine.h source file, line 367.
This function initializes a kroutine with the KROUTINE_CPU_DEFERRED policy. The target processor used for execution must be specified.
This is available when CONFIG_ARCH_SMP and CONFIG_MUTEK_KROUTINE_SCHED are both defined.
void kroutine_init_deferred_local(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 384.
This function initializes a kroutine with the KROUTINE_CPU_DEFERRED policy. The execution will take place on the current processor.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_deferred_seq(struct kroutine_s *kr, kroutine_exec_t *exec, struct kroutine_sequence_s *seq) [link]
This function is declared in mutek/kroutine.h source file, line 402.
This function initializes a kroutine with the KROUTINE_CPU_DEFERRED policy. The execution will take place on the current processor.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_idle(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 529.
This function initializes a kroutine with the KROUTINE_IDLE policy.
This is available when CONFIG_MUTEK_KROUTINE_IDLE is defined.
void kroutine_init_immediate(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 328.
This function initializes a kroutine with the KROUTINE_IMMEDIATE policy.
void kroutine_init_interruptible(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 476.
This function initializes a kroutine with the KROUTINE_INTERRUPTIBLE policy.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_interruptible_cpu(struct kroutine_s *kr, kroutine_exec_t *exec, struct cpu_tree_s *cpu) [link]
This function is declared in mutek/kroutine.h source file, line 483.
This function initializes a kroutine with the KROUTINE_CPU_INTERRUPTIBLE policy. The target processor used for execution must be specified.
This is available when CONFIG_ARCH_SMP and CONFIG_MUTEK_KROUTINE_SCHED are both defined.
void kroutine_init_interruptible_local(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 500.
This function initializes a kroutine with the KROUTINE_CPU_INTERRUPTIBLE policy. The execution will take place on the current processor.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_interruptible_seq(struct kroutine_s *kr, kroutine_exec_t *exec, struct kroutine_sequence_s *seq) [link]
This function is declared in mutek/kroutine.h source file, line 519.
This function initializes a kroutine with the KROUTINE_SEQ_INTERRUPTIBLE policy. The handler will not run concurrently with kroutines associated to the same sequence.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_none(struct kroutine_s *kr) [link]
This function is declared in mutek/kroutine.h source file, line 320.
This function initializes a kroutine with the KROUTINE_NONE policy.
void kroutine_init_queue(struct kroutine_s *kr, kroutine_exec_t *exec, struct kroutine_queue_s *queue) [link]
This function is declared in mutek/kroutine.h source file, line 541.
This function initializes a kroutine with the KROUTINE_QUEUE policy.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
void kroutine_init_sched_switch(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 418.
This function initializes a kroutine with the KROUTINE_SCHED_SWITCH policy.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_sched_switch_cpu(struct kroutine_s *kr, kroutine_exec_t *exec, struct cpu_tree_s *cpu) [link]
This function is declared in mutek/kroutine.h source file, line 425.
This function initializes a kroutine with the KROUTINE_CPU_SCHED_SWITCH policy. The target processor used for execution must be specified.
This is available when CONFIG_ARCH_SMP and CONFIG_MUTEK_KROUTINE_SCHED are both defined.
void kroutine_init_sched_switch_local(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 442.
This function initializes a kroutine with the KROUTINE_CPU_SCHED_SWITCH policy. The execution will take place on the current processor.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_sched_switch_seq(struct kroutine_s *kr, kroutine_exec_t *exec, struct kroutine_sequence_s *seq) [link]
This function is declared in mutek/kroutine.h source file, line 460.
This function initializes a kroutine with the KROUTINE_CPU_SCHED_SWITCH policy. The execution will take place on the current processor.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
void kroutine_init_trigger(struct kroutine_s *kr, kroutine_exec_t *exec) [link]
This function is declared in mutek/kroutine.h source file, line 344.
This function initializes a kroutine with the KROUTINE_TRIGGER policy.
This is available when CONFIG_MUTEK_KROUTINE_TRIGGER is defined.
typedef void * kroutine_list_entry_t [link]
This typedef is declared in mutek/kroutine.h source file, line 236.
Preprocessor condition: defined( CONFIG_MUTEK_KROUTINE_QUEUE )
typedef struct kroutine_s * kroutine_list_item_t [link]
This typedef is declared in mutek/kroutine.h source file, line 252.
Preprocessor condition: defined( CONFIG_MUTEK_KROUTINE_QUEUE )
typedef void * kroutine_list_root_t [link]
This typedef is declared in mutek/kroutine.h source file, line 236.
Documentation from alternate declaration:
User defined kroutine scheduling queue.
Preprocessor condition: defined( CONFIG_MUTEK_KROUTINE_QUEUE )
See also KROUTINE_QUEUE.
typedef void kroutine_list_root_t [link]
This typedef is declared in mutek/kroutine.h source file, line 273.
User defined kroutine scheduling queue.
Preprocessor condition: not defined( CONFIG_MUTEK_KROUTINE_QUEUE )
See also KROUTINE_QUEUE.
enum kroutine_policy_e [link]
This enum is declared in mutek/kroutine.h source file, line 93.
This enum specify kroutine defered execution policies.
| Identifier | Description |
|---|---|
| KROUTINE_INVALID | |
| KROUTINE_NONE | No routine is executed. |
| KROUTINE_IMMEDIATE | This policy makes the routine execute immediately when the kroutine_exec function is called. |
| KROUTINE_TRIGGER | This policy requires an additional function call in order to allow execution of the kroutine handler. This may be used to defer execution of the handler up to a point in the code where the stack has unwound and avoid cases of deep function call nesting. The kroutine_exec function and the kroutine_trigger function have both to be called in order for the handler to be executed. |
| KROUTINE_QUEUE | This policy allows scheduling of a kroutine on a user defined queue when kroutine_exec is called. The actual routine execution will occur when either the kroutine_queue_process or kroutine_queue_wait function is called. |
| KROUTINE_SCHED_SWITCH | The kroutine is scheduled for defered execution with interrupts enabled on the stack of the idle context. The execution will not occur before the next context switch regardless of the priorities of the kroutine and current context. This policy can be used as soon as the scheduler as been initialized, before it is actually started. |
| KROUTINE_DEFERRED | The kroutine is scheduled for defered execution with interrupts enabled on the stack of the idle context. This will occur as soon as possible depending on the priorities of the kroutine and current context as well as build configuration. The CONFIG_HEXO_CONTEXT_PREEMPT and CONFIG_HEXO_CONTEXT_IRQEN features allow switching to the idle context without waiting for the next context switch. This policy can be used as soon as the scheduler as been initialized, before it is actually started but the handler execution will be postponed. |
| KROUTINE_INTERRUPTIBLE | If the kroutine_exec function is called with interrupts enabled, the kroutine handler is executed immediately on the current stack. In the other case, the kroutine is handled as if the policy were KROUTINE_DEFERRED. |
| KROUTINE_IDLE | The kroutine is scheduled for execution when the last processor of the platform becomes idle. The kroutine handler will be executed with interrupts enabled on the stack of idle context. This policy can be used as soon as the scheduler as been initialized, before it is actually started. |
| KROUTINE_CPU_INTERRUPTIBLE | This is similar to KROUTINE_INTERRUPTIBLE. On SMP platforms the execution is scheduled for execution on a specific processor. |
| KROUTINE_CPU_SCHED_SWITCH | This is similar to KROUTINE_SCHED_SWITCH. On SMP platforms the execution is scheduled for execution on a specific processor. |
| KROUTINE_CPU_DEFERRED | This is similar to KROUTINE_DEFERRED. On SMP platforms the execution is scheduled for execution on a specific processor. |
| KROUTINE_SEQ_INTERRUPTIBLE | This is similar to KROUTINE_INTERRUPTIBLE. Execution of the handler is guaranteed not to run concurrently with kroutines associated to the same sequence. |
| KROUTINE_SEQ_SCHED_SWITCH | This is similar to KROUTINE_SCHED_SWITCH. Execution of the handler is guaranteed not to run concurrently with kroutines associated to the same sequence. |
| KROUTINE_SEQ_DEFERRED | This is similar to KROUTINE_DEFERRED. Execution of the handler is guaranteed not to run concurrently with kroutines associated to the same sequence. |
| KROUTINE_CPU_INTERRUPTIBLE | |
| KROUTINE_CPU_SCHED_SWITCH | |
| KROUTINE_CPU_DEFERRED | |
| KROUTINE_SEQ_INTERRUPTIBLE | |
| KROUTINE_SEQ_SCHED_SWITCH | |
| KROUTINE_SEQ_DEFERRED |
bool_t kroutine_postpone(struct kroutine_s *kr, enum kroutine_policy_e policy) [link]
This function is declared in mutek/kroutine.h source file, line 731.
This function function is similar to kroutine_trigger but does nothing when the kroutine_exec function has already been called. The routine will only be executed if the call to kroutine_exec is performed after the call to this function.
This can be used to leave then resume a FSM loop when an asynchronous operation as not already completed.
This is available when CONFIG_MUTEK_KROUTINE_TRIGGER is defined.
void kroutine_queue_cleanup(struct kroutine_queue_s *q) [link]
This function is declared in mutek/kroutine.h source file, line 563.
This function releases resources associated to a kroutine sequence.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
error_t kroutine_queue_init(struct kroutine_queue_s *q, struct semaphore_s *sem) [link]
This function is declared in mutek/kroutine.h source file, line 556.
This function initializes a queue used to push kroutine initialized with the KROUTINE_QUEUE policy.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
bool_t kroutine_queue_process(struct kroutine_queue_s *queue) [link]
This function is declared in mutek/kroutine.h source file, line 654.
This function pops a kroutine from the queue and executes its handler. The kroutine policy is KROUTINE_QUEUE and it has been pushed on the kroutine_exec function call.
This function returns false if the queue is empty.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
struct kroutine_queue_s [link]
This struct is declared in mutek/kroutine.h source file, line 278.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
| Field | Description |
|---|---|
| kroutine_list_root_t list; | |
| struct semaphore_s * sem; |
bool_t kroutine_queue_wait(struct kroutine_queue_s *queue) [link]
This function is declared in mutek/kroutine.h source file, line 659.
This function waits on the semaphore associated to the kroutine queue then invokes the kroutine_queue_process function.
This is available when CONFIG_MUTEK_KROUTINE_SEMAPHORE is defined.
struct kroutine_s [link]
This struct is declared in mutek/kroutine.h source file, line 238.
Preprocessor condition: defined( CONFIG_MUTEK_KROUTINE_QUEUE )
| Field | Description |
|---|---|
| union <anonymous> { | |
| void * cls; | |
| struct kroutine_queue_s * queue; | |
| }; | |
| struct kroutine_sequence_s * seq; | |
| kroutine_exec_t * exec; | |
| enum kroutine_policy_e policy; | |
| atomic_fast8_t state; | |
| uint8_t priority; | |
| uint8_t pv; |
See also kroutine_list_item_t.
void kroutine_seq_cleanup(struct kroutine_sequence_s *seq) [link]
This function is declared in mutek/kroutine.h source file, line 747.
This function releases resources associated to a kroutine sequence.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
error_t kroutine_seq_init(struct kroutine_sequence_s *seq) [link]
This function is declared in mutek/kroutine.h source file, line 741.
This function initializes a kroutine sequence.
This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.
struct kroutine_sequence_s [link]
This struct is declared in mutek/kroutine.h source file, line 258.
See also kroutine_seq_init.
| Field | Description |
|---|---|
| atomic_fast8_t state; |
void kroutine_set_priority(struct kroutine_s *kr, uint8_t priority) [link]
This function is declared in mutek/kroutine.h source file, line 298.
This function changes the scheduler priority associated to a kroutine.
This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.
bool_t kroutine_trigger(struct kroutine_s *kr, enum kroutine_policy_e policy) [link]
This function is declared in mutek/kroutine.h source file, line 714.
This function should be used on a kroutine initialized with the KROUTINE_TRIGGER policy. If it is not the case, this function does nothing and returns false.
This function lets the next call to the kroutine_exec function handle the kroutine using the policy passed as argument. This function returns false if the kroutine_exec function has not been called yet.
If the kroutine_exec function has already been called, this function will take care of handling the kroutine according to the values of the policy argument. true is returned in this case.
This is available when CONFIG_MUTEK_KROUTINE_TRIGGER is defined.
error_t kroutine_schedule(struct kroutine_s *kr, enum kroutine_policy_e policy) [link]
This function is declared in mutek/kroutine.h source file, line 566.
This function is for internal use only.