OS Task

API 介绍

This section introduces os task reference api.

Defines

TASK_MAX_PRIORITY

Priority definition. Higer number has higer priority. OS specific code can map them to OS defined priority accordingly. task max priority for os system.

os_create_task(fn, arg, prio)

This function is used to create a task.

参数:

  • fn -- is the function pointer of the task.

  • arg -- is the parameter passed to the function call.

  • prio -- is the task priority.

返回:

NULL(failure), otherwise(task handle).

Typedefs

typedef void *os_task_h

TASK define task handle.

typedef void (*os_task_func_t)(void *arg)

This function is used to define task routing function pointer type.

Param arg:

is the parameter is registered when creating a task.

typedef struct task_info task_info_t
typedef struct _task_priority_t task_priority_t
typedef struct _task_snapshot_t task_snapshot_t

Enums

enum OS_TASK_STATE

TASK state.

Values:

enumerator OS_TASK_STATE_RUN

A task is querying the state of itself, so must be running.

enumerator OS_TASK_STATE_READY

The task being queried is in a read or pending ready list.

enumerator OS_TASK_STATE_BLOCK

The task being queried is in the Blocked state.

enumerator OS_TASK_STATE_SUSPEND

The task being queried is in the Suspended state, or is in the Blocked state with an infinite time out.

enumerator OS_TASK_STATE_DELETE

The task being queried has been deleted, but its TCB has not yet been freed.

enumerator OS_TASK_STATE_INVALID

Used as an 'invalid state' value.

enum OS_STATUS

OS scheduler status.

Values:

enumerator OS_STATUS_SUSPENDED

The task scheduler status is in suspended state.

enumerator OS_STATUS_NOT_STARTED

The task scheduler is not ready.

enumerator OS_STATUS_RUNNING

The task scheduler is running.

enumerator OS_STATUS_UNKNOWN

Used as an 'invalid state' value.

Functions

os_task_h os_create_task_ext(os_task_func_t fn, void *arg, uint8_t prio, uint32_t stack_size, const char *name)

This function is used to create a task.

参数:

  • fn -- is the function pointer of the task.

  • arg -- is the parameter passed to the function call.

  • prio -- is the task priority.

  • stack_size -- is the required stack size for this task. if set to 0, default stack size will be used. unit is 4 bytes.

  • name -- is task name string.

返回:

NULL(failure), otherwise(task handle).

void os_delete_task(os_task_h handle)

This function is used to delete a task.

参数:

handle -- is the handle of the task to be deleted. Passing NULL will cause the calling task to be deleted.

void os_set_task_prio(os_task_h handle, uint8_t prio)

This function is used to set priority of a task.

参数:

  • handle -- is the handle of the task to be set.

  • prio -- is the task priority.

void os_set_task_event(os_task_h handle)

This function is used to set task event.

参数:

handle -- is the handle of the task to be set.

void os_wait_task_event(void)

This function is used to wait for task event. a task can call this funtion to wait for others to call os_set_task_event or os_set_task_event_with_v to wake it up.

void os_set_task_event_with_v(os_task_h handle, uint32_t v)

This function is used to set task event with value transferred to the task. if the task haven't gotten the value through os_wait_task_event_with_v yet, then value of multiple calls will be OR-ed.

参数:

  • handle -- is the handle of the task to be set.

  • v -- is the value to be transferred.

void os_set_task_event_with_v_from_isr(os_task_h handle, uint32_t v)

This function is used to set task event with value transferred to the task from ISR context. if the task haven't gotten the value through os_wait_task_event_with_v yet, then value of multiple calls will be OR-ed. Note that this function can only be called from ISR context.

参数:

  • handle -- is the handle of the task to be set.

  • v -- is the value to be transferred.

uint32_t os_wait_task_event_with_v(uint32_t time_to_wait)

This function is used to wait task event and get the value. a task can call this function to wait for others to call os_set_task_event or os_set_task_event_with_v to wake it up. in addition, the value set by os_set_task_event_with_v will be returned.

参数:

time_to_wait -- is time to wait before timeout.

返回:

uint32_t the received value from os_set_task_event_with_v.

uint32_t os_task_get_task_number(void)

This function is used to get the count of tasks.

返回:

uint32_t the count of all tasks.

uint32_t os_task_get_all_task_info(task_info_t *task_buf, uint32_t task_num, uint32_t *total_time)

This function is used to get task information.

参数:

  • task_buf -- [out] is the task info save buffer.

  • task_num -- [in] the count of task_buf.

  • total_time -- [out] total run time after last info get.

返回:

uint32_t number of tasks we got actually.

uint32_t os_get_cpu_utilization(void)

This function is used to get latest 5s' CPU utilization percentage.

返回:

uint32_t get CPU utilization percentage * 100.

uint32_t os_get_mem_utilization(void)

This function is used to get memory utilization percentage.

返回:

uint32_t get memory utilization percentage * 100.

os_task_h os_get_current_task_handle(void)

This function is used to get current task handle.

返回:

os_task_h task handle.

uint32_t os_get_task_id(os_task_h handle)

This function is used to get task's task number.

参数:

handle -- is task's handle.

返回:

uint32_t task id.

void os_task_yield(void)

This function is used to current task yield and high priority task get scheduled.

void os_start_kernel(void)

This function is used to start the FreeRtos.

void os_start_scheduler(void)

This function is used to start the scheduler.

OS_STATUS os_get_scheduler_state(void)

This function is used to return OS scheduler's state.

参见

OS_STATUS

返回:

OS_STATUS

void os_task_switch_context(void)

This function is used to OS's task context switch.

void os_task_init(const task_priority_t *list, uint32_t len)

This function is used to init task list and defined task's priority.

参数:

  • list -- is task list.

  • len -- is task element number.

uint32_t os_task_snapshot_all(task_snapshot_t *const pxTaskSnapshotArray, const uint32_t uxArraySize, uint32_t *pxTcbSz)

This function is used to get all task's stack snap shot.

参数:

  • pxTaskSnapshotArray -- is the pointer to array of TaskSnapshot_t structures to store tasks snapshot data.

  • uxArraySize -- is the size of tasks snapshots array.

  • pxTcbSz -- is the pointer to store size of TCB.

返回:

uint32_t the number of elements stored in array.

uint32_t *os_task_get_stack_watermark(os_task_h handle)

This function is used to get task's highest waternark of stack pointer.

参数:

handle -- is task's handle.if current task,handle can be set to NULL.

返回:

Return the pointer point to the stack high water mark of a task given by the handle.

void os_task_suspend_all(void)

This function is used to suspend all tasks, and this means disable task's scheduler.

void os_task_resume_all(void)

This function is used to resume all tasks, and this means enable task's scheduler.

struct task_info

Public Members

uint32_t id

A number unique to the task.

uint32_t priority

The priority at which the task was running.

OS_TASK_STATE status

Refer from OS_STATUS.

void *stack_base

Points to the lowest address of the task's stack area.

uint32_t stack_size

The minimum amount of stack space that has remained for the task since the task was created.

uint32_t cpu_ts

The total run time allocated to the task so far, as defined by the run time stats clock.

const char *name

A pointer to the task's name.

struct _task_priority_t

Public Members

char *name

A pointer to the task's name.

uint8_t priority

The priority at which the task was running.

struct _task_snapshot_t

Public Members

void *tcb_ptr

Address of task control block.

uint32_t task_id

Task id for snapshot

uint32_t *stack_start

Points to the location of the last item placed on the tasks stack.

uint32_t *stack_end

Points to the end of the stack.