You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/03/09 07:24:23 UTC
[16/17] incubator-mynewt-site git commit: added time functions from
pull request #43 and 44. changed community page layout,
font sizes across site etc.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/565bf1bc/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json
index 754510d..547ef59 100644
--- a/mkdocs/search_index.json
+++ b/mkdocs/search_index.json
@@ -62,12 +62,12 @@
},
{
"location": "/community/",
- "text": "Mailing Lists\n\n\nTo subscribe to a mailing list, you simply send an email to a special subscription address. For example, to subscribe to the dev list, send an email to \ndev-subscribe@mynewt.incubator.apache.org\n.\n\n\nThe following mailing lists can be used to get help with MyNewt.",
+ "text": "Mailing Lists\n\n\nWe welcome you to join our mailing lists and get in touch with us! \n\n \nTo complete your subscription you have to confirm it by replying to the response sent to you when you email your subscription request!",
"title": "Community"
},
{
"location": "/community/#mailing-lists",
- "text": "To subscribe to a mailing list, you simply send an email to a special subscription address. For example, to subscribe to the dev list, send an email to dev-subscribe@mynewt.incubator.apache.org . The following mailing lists can be used to get help with MyNewt.",
+ "text": "We welcome you to join our mailing lists and get in touch with us! To complete your subscription you have to confirm it by replying to the response sent to you when you email your subscription request!",
"title": "Mailing Lists"
},
{
@@ -572,8 +572,8 @@
},
{
"location": "/os/core_os/context_switch/context_switch/",
- "text": "Scheduler/Context Switching\n\n\nScheduler's job is to maintain the list of tasks and decide which one should be running next.\n\n\nDescription\n\n\nTask states can be \nrunning\n, \nready to run\n or \nsleeping\n.\n\n\nWhen task is \nrunning\n, CPU is executing in that task's context. The program counter (PC) is pointing to instructions task wants to execute and stack pointer (SP) is pointing to task's stack.\n\n\nTask which is \nready to run\n wants to get on the CPU to do its work.\n\n\nTask which is \nsleeping\n has no more work to do. It's waiting for someone else to wake it up.\n\n\nScheduler algorithm is simple: from among the tasks which are ready to run, pick the the one with highest priority (lowest numeric value in task's t_prio field), and make its state \nrunning\n.\n\n\nTasks which are either \nrunning\n or \nready to run\n are kept in linked list \ng_os_run_list\n. This list is ordered by priority.\n\n\nTasks which are \nsleeping\n are kept in lin
ked list \ng_os_sleep_list\n.\n\n\nScheduler has a CPU architecture specific component; this code is responsible for swapping in the task which should be \nrunning\n. This process is called context switch. During context switching the state of the CPU (e.g. registers) for the currently \nrunning\n task is stored and the new task is swapped in.\n\n\nData structures\n\n\nList of Functions\n\n\nThe functions available in context_switch are:\n\n\n\n\nos_sched\n\n\nos_arch_ctx_sw\n\n\nos_arch_ctx_sw_isr\n\n\nos_sched_ctx_sw_hook\n\n\nos_sched_get_current_task\n\n\nos_sched_insert\n\n\nos_sched_next_task\n\n\nos_sched_os_timer_exp\n\n\nos_sched_resort\n\n\nos_sched_set_current_task\n\n\nos_sched_sleep\n\n\nos_sched_wakeup",
- "title": "Overview"
+ "text": "Scheduler/Context Switching\n\n\nScheduler's job is to maintain the list of tasks and decide which one should be running next.\n\n\nDescription\n\n\nTask states can be \nrunning\n, \nready to run\n or \nsleeping\n.\n\n\nWhen task is \nrunning\n, CPU is executing in that task's context. The program counter (PC) is pointing to instructions task wants to execute and stack pointer (SP) is pointing to task's stack.\n\n\nTask which is \nready to run\n wants to get on the CPU to do its work.\n\n\nTask which is \nsleeping\n has no more work to do. It's waiting for someone else to wake it up.\n\n\nScheduler algorithm is simple: from among the tasks which are ready to run, pick the the one with highest priority (lowest numeric value in task's t_prio field), and make its state \nrunning\n.\n\n\nTasks which are either \nrunning\n or \nready to run\n are kept in linked list \ng_os_run_list\n. This list is ordered by priority.\n\n\nTasks which are \nsleeping\n are kept in lin
ked list \ng_os_sleep_list\n.\n\n\nScheduler has a CPU architecture specific component; this code is responsible for swapping in the task which should be \nrunning\n. This process is called context switch. During context switching the state of the CPU (e.g. registers) for the currently \nrunning\n task is stored and the new task is swapped in.\n\n\nData structures\n\n\nList of Functions\n\n\nThe functions available in context_switch are:\n\n\n\n\nos_sched\n\n\nos_arch_ctx_sw\n\n\nos_sched_ctx_sw_hook\n\n\nos_sched_get_current_task\n\n\nos_sched_insert\n\n\nos_sched_next_task\n\n\nos_sched_os_timer_exp\n\n\nos_sched_resort\n\n\nos_sched_set_current_task\n\n\nos_sched_sleep\n\n\nos_sched_wakeup",
+ "title": "toc"
},
{
"location": "/os/core_os/context_switch/context_switch/#schedulercontext-switching",
@@ -592,22 +592,22 @@
},
{
"location": "/os/core_os/context_switch/context_switch/#list-of-functions",
- "text": "The functions available in context_switch are: os_sched os_arch_ctx_sw os_arch_ctx_sw_isr os_sched_ctx_sw_hook os_sched_get_current_task os_sched_insert os_sched_next_task os_sched_os_timer_exp os_sched_resort os_sched_set_current_task os_sched_sleep os_sched_wakeup",
+ "text": "The functions available in context_switch are: os_sched os_arch_ctx_sw os_sched_ctx_sw_hook os_sched_get_current_task os_sched_insert os_sched_next_task os_sched_os_timer_exp os_sched_resort os_sched_set_current_task os_sched_sleep os_sched_wakeup",
"title": "List of Functions"
},
{
"location": "/os/core_os/context_switch/os_sched/",
- "text": "os_sched \n\n\nvoid os_sched(struct os_task *next_t, int isr)\n\n\n\n\nPerforms context switch if needed. If \nnext_t\n is set, that task will be made \nrunning\n. If \nnext_t\n is NULL, highest priority \nready to run\n is swapped in. This function can be called when new tasks were made \nready to run\n or if the current task is moved to \nsleeping\n state.\n\n\nThis function will call the architecture specific routine to swap in the new task.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnext_t\n\n\nPointer to task which must run next (optional)\n\n\n\n\n\n\nisr\n\n\nFlag indicating whether function is called from interrupt handler or not\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nInterrupts must be disabled when calling this.\n\n\nExample\n\n\n\n\nos_error_t\nos_mutex_release(struct os_mutex *mu)\n{\n ...\n OS_EXIT_CRITICAL(sr);\n\n /* Re-schedule if needed */\n if (resched) {\n os_sched(rdy,
0);\n }\n\n return OS_OK;\n\n}",
+ "text": "os_sched \n\n\nvoid os_sched(struct os_task *next_t)\n\n\n\n\nPerforms context switch if needed. If \nnext_t\n is set, that task will be made \nrunning\n. If \nnext_t\n is NULL, highest priority \nready to run\n is swapped in. This function can be called when new tasks were made \nready to run\n or if the current task is moved to \nsleeping\n state.\n\n\nThis function will call the architecture specific routine to swap in the new task.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnext_t\n\n\nPointer to task which must run next (optional)\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nInterrupts must be disabled when calling this.\n\n\nExample\n\n\n\n\nos_error_t\nos_mutex_release(struct os_mutex *mu)\n{\n ...\n OS_EXIT_CRITICAL(sr);\n\n /* Re-schedule if needed */\n if (resched) {\n os_sched(rdy);\n }\n\n return OS_OK;\n\n}",
"title": "os_sched"
},
{
"location": "/os/core_os/context_switch/os_sched/#os_sched",
- "text": "void os_sched(struct os_task *next_t, int isr) Performs context switch if needed. If next_t is set, that task will be made running . If next_t is NULL, highest priority ready to run is swapped in. This function can be called when new tasks were made ready to run or if the current task is moved to sleeping state. This function will call the architecture specific routine to swap in the new task.",
+ "text": "void os_sched(struct os_task *next_t) Performs context switch if needed. If next_t is set, that task will be made running . If next_t is NULL, highest priority ready to run is swapped in. This function can be called when new tasks were made ready to run or if the current task is moved to sleeping state. This function will call the architecture specific routine to swap in the new task.",
"title": " os_sched "
},
{
"location": "/os/core_os/context_switch/os_sched/#arguments",
- "text": "Arguments Description next_t Pointer to task which must run next (optional) isr Flag indicating whether function is called from interrupt handler or not",
+ "text": "Arguments Description next_t Pointer to task which must run next (optional)",
"title": "Arguments"
},
{
@@ -622,12 +622,12 @@
},
{
"location": "/os/core_os/context_switch/os_sched/#example",
- "text": "os_error_t\nos_mutex_release(struct os_mutex *mu)\n{\n ...\n OS_EXIT_CRITICAL(sr);\n\n /* Re-schedule if needed */\n if (resched) {\n os_sched(rdy, 0);\n }\n\n return OS_OK;\n\n}",
+ "text": "os_error_t\nos_mutex_release(struct os_mutex *mu)\n{\n ...\n OS_EXIT_CRITICAL(sr);\n\n /* Re-schedule if needed */\n if (resched) {\n os_sched(rdy);\n }\n\n return OS_OK;\n\n}",
"title": "Example"
},
{
"location": "/os/core_os/context_switch/os_arch_ctx_sw/",
- "text": "os_arch_ctx_sw \n\n\nvoid os_arch_ctx_sw(struct os_task *next_t)\n\n\n\n\nChange the state of task pointed by \nnext_t\n to be \nrunning\n.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnext_t\n\n\nPointer to task which must run next\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nThis would get called from another task's context.\n\n\nExample\n\n\n\n\nvoid\nos_sched(struct os_task *next_t, int isr) \n{\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\n\n if (!next_t) {\n next_t = os_sched_next_task();\n }\n\n if (next_t != g_current_task) {\n OS_EXIT_CRITICAL(sr);\n if (isr) {\n os_arch_ctx_sw_isr(next_t);\n } else {\n os_arch_ctx_sw(next_t);\n }\n\n } else {\n OS_EXIT_CRITICAL(sr);\n }\n}",
+ "text": "os_arch_ctx_sw \n\n\nvoid os_arch_ctx_sw(struct os_task *next_t)\n\n\n\n\nChange the state of task pointed by \nnext_t\n to be \nrunning\n.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnext_t\n\n\nPointer to task which must run next\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nThis would get called from another task's context.\n\n\nExample\n\n\n\n\nvoid\nos_sched(struct os_task *next_t)\n{\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\n\n if (!next_t) {\n next_t = os_sched_next_task();\n }\n\n if (next_t != g_current_task) {\n os_arch_ctx_sw(next_t);\n }\n\n OS_EXIT_CRITICAL(sr);\n}",
"title": "os_arch_ctx_sw"
},
{
@@ -652,47 +652,17 @@
},
{
"location": "/os/core_os/context_switch/os_arch_ctx_sw/#example",
- "text": "void\nos_sched(struct os_task *next_t, int isr) \n{\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\n\n if (!next_t) {\n next_t = os_sched_next_task();\n }\n\n if (next_t != g_current_task) {\n OS_EXIT_CRITICAL(sr);\n if (isr) {\n os_arch_ctx_sw_isr(next_t);\n } else {\n os_arch_ctx_sw(next_t);\n }\n\n } else {\n OS_EXIT_CRITICAL(sr);\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw_isr/",
- "text": "os_arch_ctx_sw_isr \n\n\nvoid os_arch_ctx_sw_isr(struct os_task *next_t)\n\n\n\n\nChange the state of task pointed by \nnext_t\n to be \nrunning\n.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnext_t\n\n\nPointer to task which must run next\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nThis would get called from interrupt context.\n\n\nExample\n\n\n\n\nvoid\nos_sched(struct os_task *next_t, int isr) \n{\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\n\n if (!next_t) {\n next_t = os_sched_next_task();\n }\n\n if (next_t != g_current_task) {\n OS_EXIT_CRITICAL(sr);\n if (isr) {\n os_arch_ctx_sw_isr(next_t);\n } else {\n os_arch_ctx_sw(next_t);\n }\n\n } else {\n OS_EXIT_CRITICAL(sr);\n }\n}",
- "title": "os_arch_ctx_sw_isr"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw_isr/#os_arch_ctx_sw_isr",
- "text": "void os_arch_ctx_sw_isr(struct os_task *next_t) Change the state of task pointed by next_t to be running .",
- "title": " os_arch_ctx_sw_isr "
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw_isr/#arguments",
- "text": "Arguments Description next_t Pointer to task which must run next",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw_isr/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw_isr/#notes",
- "text": "This would get called from interrupt context.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw_isr/#example",
- "text": "void\nos_sched(struct os_task *next_t, int isr) \n{\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\n\n if (!next_t) {\n next_t = os_sched_next_task();\n }\n\n if (next_t != g_current_task) {\n OS_EXIT_CRITICAL(sr);\n if (isr) {\n os_arch_ctx_sw_isr(next_t);\n } else {\n os_arch_ctx_sw(next_t);\n }\n\n } else {\n OS_EXIT_CRITICAL(sr);\n }\n}",
+ "text": "void\nos_sched(struct os_task *next_t)\n{\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\n\n if (!next_t) {\n next_t = os_sched_next_task();\n }\n\n if (next_t != g_current_task) {\n os_arch_ctx_sw(next_t);\n }\n\n OS_EXIT_CRITICAL(sr);\n}",
"title": "Example"
},
{
"location": "/os/core_os/context_switch/os_sched_ctx_sw_hook/",
- "text": "os_sched_ctx_sw_hook \n\n\nvoid os_sched_ctx_sw_hook(struct os_task *next_t)\n\n\n\n\nPerforms task accounting when context switching.\n\n\nThis function must be called from the architecture specific context switching routines \nos_arch_ctx_sw_isr()\n and \nos_arch_ctx_sw()\n before they resume execution of the \nrunning\n task.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\nos_arch_ctx_sw(struct os_task *t)\n{\n os_sched_ctx_sw_hook(t);\n\n /* Set PendSV interrupt pending bit to force context switch */\n SCB-\nICSR = SCB_ICSR_PENDSVSET_Msk;\n}",
+ "text": "os_sched_ctx_sw_hook \n\n\nvoid os_sched_ctx_sw_hook(struct os_task *next_t)\n\n\n\n\nPerforms task accounting when context switching.\n\n\nThis function must be called from the architecture specific context switching routine \nos_arch_ctx_sw()\n before resuming execution of the \nrunning\n task.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\nos_arch_ctx_sw(struct os_task *t)\n{\n os_sched_ctx_sw_hook(t);\n\n /* Set PendSV interrupt pending bit to force context switch */\n SCB-\nICSR = SCB_ICSR_PENDSVSET_Msk;\n}",
"title": "os_sched_ctx_sw_hook"
},
{
"location": "/os/core_os/context_switch/os_sched_ctx_sw_hook/#os_sched_ctx_sw_hook",
- "text": "void os_sched_ctx_sw_hook(struct os_task *next_t) Performs task accounting when context switching. This function must be called from the architecture specific context switching routines os_arch_ctx_sw_isr() and os_arch_ctx_sw() before they resume execution of the running task.",
+ "text": "void os_sched_ctx_sw_hook(struct os_task *next_t) Performs task accounting when context switching. This function must be called from the architecture specific context switching routine os_arch_ctx_sw() before resuming execution of the running task.",
"title": " os_sched_ctx_sw_hook "
},
{
@@ -717,7 +687,7 @@
},
{
"location": "/os/core_os/context_switch/os_sched_get_current_task/",
- "text": "os_sched_get_current_task \n\n\nstruct os_task *os_sched_get_current_task(void)\n\n\n\n\nReturns the pointer to task which is currently \nrunning\n.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nSee description.\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\nos_time_delay(int32_t osticks)\n{\n os_sr_t sr;\n\n if (osticks \n 0) {\n OS_ENTER_CRITICAL(sr);\n os_sched_sleep(os_sched_get_current_task(), (os_time_t)osticks);\n OS_EXIT_CRITICAL(sr);\n os_sched(NULL, 0);\n }\n}",
+ "text": "os_sched_get_current_task \n\n\nstruct os_task *os_sched_get_current_task(void)\n\n\n\n\nReturns the pointer to task which is currently \nrunning\n.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nSee description.\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\nos_time_delay(int32_t osticks)\n{\n os_sr_t sr;\n\n if (osticks \n 0) {\n OS_ENTER_CRITICAL(sr);\n os_sched_sleep(os_sched_get_current_task(), (os_time_t)osticks);\n OS_EXIT_CRITICAL(sr);\n os_sched(NULL);\n }\n}",
"title": "os_sched_get_current_task"
},
{
@@ -742,7 +712,7 @@
},
{
"location": "/os/core_os/context_switch/os_sched_get_current_task/#example",
- "text": "void\nos_time_delay(int32_t osticks)\n{\n os_sr_t sr;\n\n if (osticks 0) {\n OS_ENTER_CRITICAL(sr);\n os_sched_sleep(os_sched_get_current_task(), (os_time_t)osticks);\n OS_EXIT_CRITICAL(sr);\n os_sched(NULL, 0);\n }\n}",
+ "text": "void\nos_time_delay(int32_t osticks)\n{\n os_sr_t sr;\n\n if (osticks 0) {\n OS_ENTER_CRITICAL(sr);\n os_sched_sleep(os_sched_get_current_task(), (os_time_t)osticks);\n OS_EXIT_CRITICAL(sr);\n os_sched(NULL);\n }\n}",
"title": "Example"
},
{
@@ -797,7 +767,7 @@
},
{
"location": "/os/core_os/context_switch/os_sched_os_timer_exp/",
- "text": "os_sched_os_timer_exp \n\n\nvoid os_sched_os_timer_exp(void)\n\n\n\n\nInform scheduler that OS time has moved forward, and it should inspect tasks which are \nsleeping\n to check whether they should be moved to \ng_run_list\n or not.\n\n\nThis function should be called from code which handles moving OS time forward. After calling it, the highest priority task which is \nready to run\n might've changed, so call to \nos_sched()\n should be done.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\ntimer_handler(void)\n{\n os_time_tick();\n os_callout_tick();\n os_sched_os_timer_exp();\n os_sched(NULL, 1);\n}",
+ "text": "os_sched_os_timer_exp \n\n\nvoid os_sched_os_timer_exp(void)\n\n\n\n\nInform scheduler that OS time has moved forward, and it should inspect tasks which are \nsleeping\n to check whether they should be moved to \ng_run_list\n or not.\n\n\nThis function should be called from code which handles moving OS time forward. After calling it, the highest priority task which is \nready to run\n might've changed, so call to \nos_sched()\n should be done.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\ntimer_handler(void)\n{\n os_time_tick();\n os_callout_tick();\n os_sched_os_timer_exp();\n os_sched(NULL);\n}",
"title": "os_sched_os_timer_exp"
},
{
@@ -822,7 +792,7 @@
},
{
"location": "/os/core_os/context_switch/os_sched_os_timer_exp/#example",
- "text": "void\ntimer_handler(void)\n{\n os_time_tick();\n os_callout_tick();\n os_sched_os_timer_exp();\n os_sched(NULL, 1);\n}",
+ "text": "void\ntimer_handler(void)\n{\n os_time_tick();\n os_callout_tick();\n os_sched_os_timer_exp();\n os_sched(NULL);\n}",
"title": "Example"
},
{
@@ -882,7 +852,7 @@
},
{
"location": "/os/core_os/context_switch/os_sched_sleep/",
- "text": "os_sched_sleep \n\n\nint\nos_sched_sleep(struct os_task *t, os_time_t nticks)\n\n\n\n\nTask 't' state is changed from \nready to run\n to \nsleeping\n. Sleep time will be specified in \nnticks\n.\n\n\nTask will be woken up after sleep timer expires, unless there are other signals causing it to wake up.\n\n\nIf \nnticks\n is set to \nOS_TIMEOUT_NEVER\n, task never wakes up with a sleep timer.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\nnticks\n\n\nNumber of ticks to sleep in OS ticks\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\n\n\nNotes\n\n\nMust be called with interrupts disabled.\n\n\nExample\n\n\n\n\nstruct os_event *\nos_eventq_get(struct os_eventq *evq)\n{\n struct os_event *ev;\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\npull_one:\n ev = STAILQ_FIRST(\nevq-\nevq_list);\n if (ev) {\n STAILQ_REMOVE(\nevq-\nevq_list, ev, os_event, ev_next);\n ev
-\nev_queued = 0;\n } else {\n evq-\nevq_task = os_sched_get_current_task();\n os_sched_sleep(evq-\nevq_task, OS_TIMEOUT_NEVER);\n OS_EXIT_CRITICAL(sr);\n\n os_sched(NULL, 0);\n\n OS_ENTER_CRITICAL(sr);\n evq-\nevq_task = NULL;\n goto pull_one;\n }\n OS_EXIT_CRITICAL(sr);\n\n return (ev);\n}",
+ "text": "os_sched_sleep \n\n\nint\nos_sched_sleep(struct os_task *t, os_time_t nticks)\n\n\n\n\nTask 't' state is changed from \nready to run\n to \nsleeping\n. Sleep time will be specified in \nnticks\n.\n\n\nTask will be woken up after sleep timer expires, unless there are other signals causing it to wake up.\n\n\nIf \nnticks\n is set to \nOS_TIMEOUT_NEVER\n, task never wakes up with a sleep timer.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\nnticks\n\n\nNumber of ticks to sleep in OS ticks\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\n\n\nNotes\n\n\nMust be called with interrupts disabled.\n\n\nExample\n\n\n\n\nstruct os_event *\nos_eventq_get(struct os_eventq *evq)\n{\n struct os_event *ev;\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\npull_one:\n ev = STAILQ_FIRST(\nevq-\nevq_list);\n if (ev) {\n STAILQ_REMOVE(\nevq-\nevq_list, ev, os_event, ev_next);\n ev
-\nev_queued = 0;\n } else {\n evq-\nevq_task = os_sched_get_current_task();\n os_sched_sleep(evq-\nevq_task, OS_TIMEOUT_NEVER);\n OS_EXIT_CRITICAL(sr);\n\n os_sched(NULL);\n\n OS_ENTER_CRITICAL(sr);\n evq-\nevq_task = NULL;\n goto pull_one;\n }\n OS_EXIT_CRITICAL(sr);\n\n return (ev);\n}",
"title": "os_sched_sleep"
},
{
@@ -907,12 +877,12 @@
},
{
"location": "/os/core_os/context_switch/os_sched_sleep/#example",
- "text": "struct os_event *\nos_eventq_get(struct os_eventq *evq)\n{\n struct os_event *ev;\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\npull_one:\n ev = STAILQ_FIRST( evq- evq_list);\n if (ev) {\n STAILQ_REMOVE( evq- evq_list, ev, os_event, ev_next);\n ev- ev_queued = 0;\n } else {\n evq- evq_task = os_sched_get_current_task();\n os_sched_sleep(evq- evq_task, OS_TIMEOUT_NEVER);\n OS_EXIT_CRITICAL(sr);\n\n os_sched(NULL, 0);\n\n OS_ENTER_CRITICAL(sr);\n evq- evq_task = NULL;\n goto pull_one;\n }\n OS_EXIT_CRITICAL(sr);\n\n return (ev);\n}",
+ "text": "struct os_event *\nos_eventq_get(struct os_eventq *evq)\n{\n struct os_event *ev;\n os_sr_t sr;\n\n OS_ENTER_CRITICAL(sr);\npull_one:\n ev = STAILQ_FIRST( evq- evq_list);\n if (ev) {\n STAILQ_REMOVE( evq- evq_list, ev, os_event, ev_next);\n ev- ev_queued = 0;\n } else {\n evq- evq_task = os_sched_get_current_task();\n os_sched_sleep(evq- evq_task, OS_TIMEOUT_NEVER);\n OS_EXIT_CRITICAL(sr);\n\n os_sched(NULL);\n\n OS_ENTER_CRITICAL(sr);\n evq- evq_task = NULL;\n goto pull_one;\n }\n OS_EXIT_CRITICAL(sr);\n\n return (ev);\n}",
"title": "Example"
},
{
"location": "/os/core_os/context_switch/os_sched_wakeup/",
- "text": "os_sched_wakeup \n\n\nint\nos_sched_wakeup(struct os_task *t)\n\n\n\n\nCalled to make task \nready to run\n. If task is \nsleeping\n, it is woken up.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\nos_eventq_put2(struct os_eventq *evq, struct os_event *ev, int isr)\n{\n ....\n /* If task waiting on event, wake it up. */\n resched = 0;\n if (evq-\nevq_task) {\n os_sched_wakeup(evq-\nevq_task);\n evq-\nevq_task = NULL;\n resched = 1;\n }\n ....\n}",
+ "text": "os_sched_wakeup \n\n\nint\nos_sched_wakeup(struct os_task *t)\n\n\n\n\nCalled to make task \nready to run\n. If task is \nsleeping\n, it is woken up.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\nos_eventq_put(struct os_eventq *evq, struct os_event *ev)\n{\n ....\n /* If task waiting on event, wake it up. */\n resched = 0;\n if (evq-\nevq_task) {\n os_sched_wakeup(evq-\nevq_task);\n evq-\nevq_task = NULL;\n resched = 1;\n }\n ....\n}",
"title": "os_sched_wakeup"
},
{
@@ -937,37 +907,37 @@
},
{
"location": "/os/core_os/context_switch/os_sched_wakeup/#example",
- "text": "void\nos_eventq_put2(struct os_eventq *evq, struct os_event *ev, int isr)\n{\n ....\n /* If task waiting on event, wake it up. */\n resched = 0;\n if (evq- evq_task) {\n os_sched_wakeup(evq- evq_task);\n evq- evq_task = NULL;\n resched = 1;\n }\n ....\n}",
+ "text": "void\nos_eventq_put(struct os_eventq *evq, struct os_event *ev)\n{\n ....\n /* If task waiting on event, wake it up. */\n resched = 0;\n if (evq- evq_task) {\n os_sched_wakeup(evq- evq_task);\n evq- evq_task = NULL;\n resched = 1;\n }\n ....\n}",
"title": "Example"
},
{
"location": "/os/core_os/time/os_time/",
- "text": "OS_Time\n\n\nThe system time for ther Mynewt OS.\n\n\nDescription\n\n\nThe Mynewt OS contains an incrementing time that drives the OS scheduler and time delays. The time is a fixed size (e.g. 32 bits) and will eventually wrap back to zero. The time to wrap from zero back to zero is called the \nOS time epoch\n. \n\n\nThe frequency of the OS time tick is specified in the architecture-specific OS code \nos_arch.h\n and is named \nOS_TICKS_PER_SEC\n.\n\n\nData Structures\n\n\nTime is stored in Mynewt as an \nos_time_t\n value. \n\n\nList of Functions\n\n\nThe functions available in time are:\n\n\n\n\nos_time_delay\n\n\nos_time_get\n\n\nos_time_tick\n\n\n\n\nList of Macros\n\n\nSeveral macros help with the evalution of times with respect to each other.\n\n\n\n\nOS_TIME_TICK_LT(t1,t2)\n -- evaluates to true if t1 is before t2 in time.\n\n\nOS_TIME_TICK_GT(t1,t2)\n -- evaluates to true if t1 is after t2 in time \n\n\nOS_TIME_TICK_GEQ(t1,t2)\n -- evaluates to true if t
1 is on or after t2 in time.\n\n\n\n\nNOTE: For all of these macros the calculations are done modulo 'os_time_t'. \n\n\nEnsure that comparison of OS time always uses the macros above (to compensate for the possible wrap of OS time)\n\n\nSpecial Notes\n\n\nIts important to understand how quickly the time wraps especially when doing time comparison using the macros above (or by any other means). \n\n\nFor example, if a tick is 1 millisecond and \nos_time_t\n is 32-bits the OS time will wrap back to zero in about 49.7 days or stated another way, the OS time epoch is 49.7 days.\n\n\nIf two times are more than 1/2 the OS time epoch apart, any time comparison will be incorrect. Ensure at design time that comparisons will not occur between times that are more than half the OS time epoch.",
- "title": "Overview"
+ "text": "OS_Time\n\n\nThe system time for the Mynewt OS.\n\n\nDescription\n\n\nThe Mynewt OS contains an incrementing time that drives the OS scheduler and time delays. The time is a fixed size (e.g. 32 bits) and will eventually wrap back to zero. The time to wrap from zero back to zero is called the \nOS time epoch\n. \n\n\nThe frequency of the OS time tick is specified in the architecture-specific OS code \nos_arch.h\n and is named \nOS_TICKS_PER_SEC\n.\n\n\nThe Mynewt OS also provides APIs for setting and retrieving the wallclock time (also known as local time or time-of-day in other operating systems).\n\n\nData Structures\n\n\nTime is stored in Mynewt as an \nos_time_t\n value. \n\n\nWallclock time is represented using the \nstruct os_timeval\n and \nstruct os_timezone\n tuple.\n\n\nstruct os_timeval\n represents the number of seconds elapsed since 00:00:00 Jan 1, 1970 UTC.\n\n\nstruct os_timeval {\n int64_t tv_sec; /\n seconds since Jan 1 1970 UTC \n/\n int3
2_t tv_usec; /\n fractional seconds \n/\n};\n\n\nstruct os_timeval tv = { 1457400000, 0 }; /\n 01:20:00 Mar 8 2016 UTC \n/\n\n\n\nstruct os_timezone\n is used to specify the offset of local time from UTC and whether daylight savings is in effect. Note that \ntz_minuteswest\n is a positive number if the local time is \nbehind\n UTC and a negative number if the local time is \nahead\n of UTC.\n\n\nstruct os_timezone {\n int16_t tz_minuteswest;\n int16_t tz_dsttime;\n};\n\n\n/\n Pacific Standard Time is 08:00 hours west of UTC \n/\nstruct os_timezone PST = { 480, 0 };\nstruct os_timezone PDT = { 480, 1 };\n\n\n/\n Indian Standard Time is 05:30 hours east of UTC \n/\nstruct os_timezone IST = { -330, 0 };\n\n\n\nList of Functions\n\n\nThe functions available in time are:\n\n\n\n\nos_time_delay\n\n\nos_time_get\n\n\nos_time_tick\n\n\nos_settimeofday\n\n\nos_gettimeofday\n\n\n\n\nList of Macros\n\n\nSeveral macros help with the evalution of times with respect to each other.\n\n\n\n\
nOS_TIME_TICK_LT(t1,t2)\n -- evaluates to true if t1 is before t2 in time.\n\n\nOS_TIME_TICK_GT(t1,t2)\n -- evaluates to true if t1 is after t2 in time \n\n\nOS_TIME_TICK_GEQ(t1,t2)\n -- evaluates to true if t1 is on or after t2 in time.\n\n\n\n\nNOTE: For all of these macros the calculations are done modulo 'os_time_t'. \n\n\nEnsure that comparison of OS time always uses the macros above (to compensate for the possible wrap of OS time).\n\n\nThe following macros help adding or subtracting time when represented as \nstruct os_timeval\n. All parameters to the following macros are pointers to \nstruct os_timeval\n.\n\n\n\n\nos_timeradd(tvp, uvp, vvp)\n -- Add \nuvp\n to \ntvp\n and store result in \nvvp\n.\n\n\nos_timersub(tvp, uvp, vvp)\n -- Subtract \nuvp\n from \ntvp\n and store result in \nvvp\n.\n\n\n\n\nSpecial Notes\n\n\nIts important to understand how quickly the time wraps especially when doing time comparison using the macros above (or by any other means). \n\n\nFor examp
le, if a tick is 1 millisecond and \nos_time_t\n is 32-bits the OS time will wrap back to zero in about 49.7 days or stated another way, the OS time epoch is 49.7 days.\n\n\nIf two times are more than 1/2 the OS time epoch apart, any time comparison will be incorrect. Ensure at design time that comparisons will not occur between times that are more than half the OS time epoch.",
+ "title": "toc"
},
{
"location": "/os/core_os/time/os_time/#os_time",
- "text": "The system time for ther Mynewt OS.",
+ "text": "The system time for the Mynewt OS.",
"title": "OS_Time"
},
{
"location": "/os/core_os/time/os_time/#description",
- "text": "The Mynewt OS contains an incrementing time that drives the OS scheduler and time delays. The time is a fixed size (e.g. 32 bits) and will eventually wrap back to zero. The time to wrap from zero back to zero is called the OS time epoch . The frequency of the OS time tick is specified in the architecture-specific OS code os_arch.h and is named OS_TICKS_PER_SEC .",
+ "text": "The Mynewt OS contains an incrementing time that drives the OS scheduler and time delays. The time is a fixed size (e.g. 32 bits) and will eventually wrap back to zero. The time to wrap from zero back to zero is called the OS time epoch . The frequency of the OS time tick is specified in the architecture-specific OS code os_arch.h and is named OS_TICKS_PER_SEC . The Mynewt OS also provides APIs for setting and retrieving the wallclock time (also known as local time or time-of-day in other operating systems).",
"title": "Description"
},
{
"location": "/os/core_os/time/os_time/#data-structures",
- "text": "Time is stored in Mynewt as an os_time_t value.",
+ "text": "Time is stored in Mynewt as an os_time_t value. Wallclock time is represented using the struct os_timeval and struct os_timezone tuple. struct os_timeval represents the number of seconds elapsed since 00:00:00 Jan 1, 1970 UTC. \nstruct os_timeval {\n int64_t tv_sec; / seconds since Jan 1 1970 UTC /\n int32_t tv_usec; / fractional seconds /\n}; struct os_timeval tv = { 1457400000, 0 }; / 01:20:00 Mar 8 2016 UTC / struct os_timezone is used to specify the offset of local time from UTC and whether daylight savings is in effect. Note that tz_minuteswest is a positive number if the local time is behind UTC and a negative number if the local time is ahead of UTC. \nstruct os_timezone {\n int16_t tz_minuteswest;\n int16_t tz_dsttime;\n}; / Pacific Standard Time is 08:00 hours west of UTC /\nstruct os_timezone PST = { 480, 0 };\nstruct os_timezone PDT = { 480, 1 }; / Indian Standard Time is 05:30 hours east of UTC /\nstruct o
s_timezone IST = { -330, 0 };",
"title": "Data Structures"
},
{
"location": "/os/core_os/time/os_time/#list-of-functions",
- "text": "The functions available in time are: os_time_delay os_time_get os_time_tick",
+ "text": "The functions available in time are: os_time_delay os_time_get os_time_tick os_settimeofday os_gettimeofday",
"title": "List of Functions"
},
{
"location": "/os/core_os/time/os_time/#list-of-macros",
- "text": "Several macros help with the evalution of times with respect to each other. OS_TIME_TICK_LT(t1,t2) -- evaluates to true if t1 is before t2 in time. OS_TIME_TICK_GT(t1,t2) -- evaluates to true if t1 is after t2 in time OS_TIME_TICK_GEQ(t1,t2) -- evaluates to true if t1 is on or after t2 in time. NOTE: For all of these macros the calculations are done modulo 'os_time_t'. Ensure that comparison of OS time always uses the macros above (to compensate for the possible wrap of OS time)",
+ "text": "Several macros help with the evalution of times with respect to each other. OS_TIME_TICK_LT(t1,t2) -- evaluates to true if t1 is before t2 in time. OS_TIME_TICK_GT(t1,t2) -- evaluates to true if t1 is after t2 in time OS_TIME_TICK_GEQ(t1,t2) -- evaluates to true if t1 is on or after t2 in time. NOTE: For all of these macros the calculations are done modulo 'os_time_t'. Ensure that comparison of OS time always uses the macros above (to compensate for the possible wrap of OS time). The following macros help adding or subtracting time when represented as struct os_timeval . All parameters to the following macros are pointers to struct os_timeval . os_timeradd(tvp, uvp, vvp) -- Add uvp to tvp and store result in vvp . os_timersub(tvp, uvp, vvp) -- Subtract uvp from tvp and store result in vvp .",
"title": "List of Macros"
},
{
@@ -1066,9 +1036,69 @@
"title": "Example"
},
{
+ "location": "/os/core_os/time/os_gettimeofday/",
+ "text": "os_gettimeofday\n\n\nint os_gettimeofday(struct os_timeval *utctime, struct os_timezone *timezone); \n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nutctime\n\n\nUTC time corresponding to wallclock time\n\n\n\n\n\n\ntimezone\n\n\nTimezone to convert UTC time to wallclock time\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success and non-zero on failure.\n\n\nNotes\n\n\nutctime\n or \ntimezone\n may be NULL.\n\n\nThe function is a no-op if both \nutctime\n and \ntimezone\n are NULL.\n\n\nExample\n\n\n\n\n /*\n * Display wallclock time on the console.\n */\n int rc;\n struct os_timeval utc;\n struct os_timezone tz;\n char buf[DATETIME_BUFSIZE];\n\n rc = os_gettimeofday(\nutc, \ntz);\n if (rc == 0) {\n format_datetime(\nutc, \ntz, buf, sizeof(buf));\n console_printf(\n%s\\n\n, buf);\n }",
+ "title": "os_gettimeofday"
+ },
+ {
+ "location": "/os/core_os/time/os_gettimeofday/#os_gettimeofday",
+ "text": "int os_gettimeofday(struct os_timeval *utctime, struct os_timezone *timezone);",
+ "title": "os_gettimeofday"
+ },
+ {
+ "location": "/os/core_os/time/os_gettimeofday/#arguments",
+ "text": "Arguments Description utctime UTC time corresponding to wallclock time timezone Timezone to convert UTC time to wallclock time",
+ "title": "Arguments"
+ },
+ {
+ "location": "/os/core_os/time/os_gettimeofday/#returned-values",
+ "text": "Returns 0 on success and non-zero on failure.",
+ "title": "Returned values"
+ },
+ {
+ "location": "/os/core_os/time/os_gettimeofday/#notes",
+ "text": "utctime or timezone may be NULL. The function is a no-op if both utctime and timezone are NULL.",
+ "title": "Notes"
+ },
+ {
+ "location": "/os/core_os/time/os_gettimeofday/#example",
+ "text": "/*\n * Display wallclock time on the console.\n */\n int rc;\n struct os_timeval utc;\n struct os_timezone tz;\n char buf[DATETIME_BUFSIZE];\n\n rc = os_gettimeofday( utc, tz);\n if (rc == 0) {\n format_datetime( utc, tz, buf, sizeof(buf));\n console_printf( %s\\n , buf);\n }",
+ "title": "Example"
+ },
+ {
+ "location": "/os/core_os/time/os_settimeofday/",
+ "text": "os_settimeofday\n\n\nint os_settimeofday(struct os_timeval *utctime, struct os_timezone *timezone);\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nutctime\n\n\nUTC time corresponding to the wallclock time\n\n\n\n\n\n\ntimezone\n\n\nTimezone associated with the wallclock time\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success and non-zero on failure.\n\n\nNotes\n\n\nutctime\n may be NULL if only the timezone needs to be changed. This is useful when adjusting the \ntimezone\n to account for daylight savings.\n\n\ntimezone\n may be NULL if only the UTC time needs to be changed. This is useful when synchronizing Mynewt's time with an external time source like NTP.\n\n\nThe function is a no-op if both \nutctime\n and \ntimezone\n are NULL.\n\n\nExample\n\n\n\n\n int rc;\n parse_datetime(datestr, \nutctime, \ntz);\n rc = os_settimeofday(\nutctime, \ntz);\n if (rc == 0) {\n /* success */\n }",
+ "title": "os_settimeofday"
+ },
+ {
+ "location": "/os/core_os/time/os_settimeofday/#os_settimeofday",
+ "text": "int os_settimeofday(struct os_timeval *utctime, struct os_timezone *timezone);",
+ "title": "os_settimeofday"
+ },
+ {
+ "location": "/os/core_os/time/os_settimeofday/#arguments",
+ "text": "Arguments Description utctime UTC time corresponding to the wallclock time timezone Timezone associated with the wallclock time",
+ "title": "Arguments"
+ },
+ {
+ "location": "/os/core_os/time/os_settimeofday/#returned-values",
+ "text": "Returns 0 on success and non-zero on failure.",
+ "title": "Returned values"
+ },
+ {
+ "location": "/os/core_os/time/os_settimeofday/#notes",
+ "text": "utctime may be NULL if only the timezone needs to be changed. This is useful when adjusting the timezone to account for daylight savings. timezone may be NULL if only the UTC time needs to be changed. This is useful when synchronizing Mynewt's time with an external time source like NTP. The function is a no-op if both utctime and timezone are NULL.",
+ "title": "Notes"
+ },
+ {
+ "location": "/os/core_os/time/os_settimeofday/#example",
+ "text": "int rc;\n parse_datetime(datestr, utctime, tz);\n rc = os_settimeofday( utctime, tz);\n if (rc == 0) {\n /* success */\n }",
+ "title": "Example"
+ },
+ {
"location": "/os/core_os/task/task/",
"text": "Task\n\n\nA task, along with the scheduler, forms the basis of the Mynewt OS. A task \nconsists of two basic elements: a task stack and a task function. The task \nfunction is basically a forever loop, waiting for some \"event\" to wake it up. \nThere are two methods used to signal a task that it has work to do: event queues \nand semaphores (see the appropriate manual sections for descriptions of these \nfeatures).\n\n\nThe Mynewt OS is a multi-tasking, preemptive OS. Every task is assigned a task \npriority (from 0 to 255), with 0 being the highest priority task. If a higher \npriority task than the current task wants to run, the scheduler preempts the \ncurrently running task and switches context to the higher priority task. This is \njust a fancy way of saying that the processor stack pointer now points to the \nstack of the higher priority task and the task resumes execution where it left \noff.\n\n\nTasks run to completion unless they are preempted by a hi
gher priority task. The \ndeveloper must insure that tasks eventually \"sleep\"; otherwise lower priority \ntasks will never get a chance to run (actually, any task lower in priority than \nthe task that never sleeps). A task will be put to sleep in the following cases: \nit puts itself to sleep using \nos_time_delay()\n, it waits on an event queue \nwhich is empty or attempts to obtain a mutex or a semaphore that is currently \nowned by another task.\n\n\nNote that other sections of the manual describe these OS features in more \ndetail.\n\n\nDescription\n\n\nIn order to create a task two data structures need to be defined: the task \nobject (struct os_task) and its associated stack. Determining the stack size can \nbe a bit tricky; generally developers should not declare large local variables \non the stack so that task stacks can be of limited size. However, all \napplications are different and the developer must choose the stack size \naccordingly. NOTE: be careful when declarin
g your stack! The stack is in units \nof \nos_stack_t\n sized elements (generally 32-bits). Looking at the example given \nbelow and assuming \nos_stack_t\n is defined to be a 32-bit unsigned value, \n\"my_task_stack\" will use 256 bytes. \n\n\nA task must also have an associated \"task function\". This is the function that \nwill be called when the task is first run. This task function should never \nreturn!\n\n\nIn order to inform the Mynewt OS of the new task and to have it added to the \nscheduler, the \nos_task_init()\n function is called. Once \nos_task_init()\n is \ncalled, the task is made ready to run and is added to the active task list. Note \nthat a task can be initialized (started) before or after the os has started \n(i.e. before \nos_start()\n is called) but must be initialized after the os has \nbeen initialized (i.e. 'os_init' has been called). In most of the examples and \ncurrent Mynewt projects, the os is initialized, tasks are initialized, and the \nthe os is st
arted. Once the os has started, the highest priority task will be \nthe first task set to run.\n\n\nInformation about a task can be obtained using the \nos_task_info_get_next()\n \nAPI. Developers can walk the list of tasks to obtain information on all created \ntasks. This information is of type \nos_task_info\n and is described below.\n\n\nThe following is a very simple example showing a single application task. This \ntask simply toggles an LED at a one second interval.\n\n\n/* Create a simple \nproject\n with a task that blinks a LED every second */\n\n/* Define task stack and task object */\n#define MY_TASK_PRI (OS_TASK_PRI_HIGHEST) \n#define MY_STACK_SIZE (64) \nstruct os_task my_task; \nos_stack_t my_task_stack[MY_STACK_SIZE]; \n\n/* This is the task function */\nvoid my_task_func(void *arg) {\n /* Set the led pin as an output */\n hal_gpio_init_out(LED_BLINK_PIN, 1);\n\n /* The task is a forever loop that does not return */\n while (1) {\n /*
Wait one second */ \n os_time_delay(1000);\n\n /* Toggle the LED */ \n hal_gpio_toggle(LED_BLINK_PIN);\n }\n}\n\n/* This is the main function for the project */\nint main(void) {\n int rc;\n\n /* Initialize OS */\n os_init();\n\n /* Initialize the task */\n os_task_init(\nmy_task, \nmy_task\n, my_task_func, NULL, MY_TASK_PRIO, \n OS_WAIT_FOREVER, my_task_stack, MY_STACK_SIZE);\n\n /* Start the OS */\n os_start();\n\n /* os start should never return. If it does, this should be an error */\n assert(0);\n\n return rc;\n}\n\n\n\n\nData structures\n\n\n/* The highest and lowest task priorities */\n#define OS_TASK_PRI_HIGHEST (0)\n#define OS_TASK_PRI_LOWEST (0xff)\n\n/* Task states */\ntypedef enum os_task_state {\n OS_TASK_READY = 1, \n OS_TASK_SLEEP = 2\n} os_task_state_t;\n\n/* Task flags */\n#define OS_TASK_FLAG_NO_TIMEOUT (0x0001U)\n#define OS_TASK_FLAG_SEM_WAIT (0x0002U)\n#define
OS_TASK_FLAG_MUTEX_WAIT (0x0004U)\n\ntypedef void (*os_task_func_t)(void *);\n\n#define OS_TASK_MAX_NAME_LEN (32)\n\n\n\n\n\n\nstruct os_task {\n os_stack_t *t_stackptr;\n os_stack_t *t_stacktop;\n\n uint16_t t_stacksize;\n uint16_t t_flags;\n\n uint8_t t_taskid;\n uint8_t t_prio;\n uint8_t t_state;\n uint8_t t_pad;\n\n char *t_name;\n os_task_func_t t_func;\n void *t_arg;\n\n void *t_obj;\n\n struct os_sanity_check t_sanity_check; \n\n os_time_t t_next_wakeup;\n os_time_t t_run_time;\n uint32_t t_ctx_sw_cnt;\n\n /* Global list of all tasks, irrespective of run or sleep lists */\n STAILQ_ENTRY(os_task) t_os_task_list;\n\n /* Used to chain task to either the run or sleep list */ \n TAILQ_ENTRY(os_task) t_os_list;\n\n /* Used to chain task to an object such as a semaphore or mutex */\n SLIST_ENTRY(os_task) t_obj_list;\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt_stackptr\n\n\nCurrent stac
k pointer\n\n\n\n\n\n\nt_stacktop\n\n\nThe address of the top of the task stack. The stack grows downward\n\n\n\n\n\n\nt_stacksize\n\n\nThe size of the stack, in units of os_stack_t (not bytes!)\n\n\n\n\n\n\nt_flags\n\n\nTask flags (see flag definitions)\n\n\n\n\n\n\nt_taskid\n\n\nA numeric id assigned to each task\n\n\n\n\n\n\nt_prio\n\n\nThe priority of the task. The lower the number, the higher the priority\n\n\n\n\n\n\nt_state\n\n\nThe task state (see state definitions)\n\n\n\n\n\n\nt_pad\n\n\npadding (for alignment)\n\n\n\n\n\n\nt_name\n\n\nName of task\n\n\n\n\n\n\nt_func\n\n\nPointer to task function\n\n\n\n\n\n\nt_obj\n\n\nGeneric object used by mutexes and semaphores when the task is waiting on a mutex or semaphore\n\n\n\n\n\n\nt_sanity_check\n\n\nSanity task data structure\n\n\n\n\n\n\nt_next_wakeup\n\n\nOS time when task is next scheduled to wake up\n\n\n\n\n\n\nt_run_time\n\n\nThe amount of os time ticks this task has been running\n\n\n\n\n\n\nt_ctx_sw_cnt\n\n\nThe numbe
r of times that this task has been run\n\n\n\n\n\n\nt_os_task_list\n\n\nList pointer for global task list. All tasks are placed on this list\n\n\n\n\n\n\nt_os_list\n\n\nList pointer used by either the active task list or the sleeping task list\n\n\n\n\n\n\nt_obj_list\n\n\nList pointer for tasks waiting on a semaphore or mutex\n\n\n\n\n\n\n\n\n\n\nstruct os_task_info {\n uint8_t oti_prio;\n uint8_t oti_taskid;\n uint8_t oti_state;\n uint8_t oti_flags;\n uint16_t oti_stkusage;\n uint16_t oti_stksize;\n uint32_t oti_cswcnt;\n uint32_t oti_runtime;\n os_time_t oti_last_checkin;\n os_time_t oti_next_checkin;\n\n char oti_name[OS_TASK_MAX_NAME_LEN];\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\noti_prio\n\n\nTask priority\n\n\n\n\n\n\noti_taskid\n\n\nTask id\n\n\n\n\n\n\noti_state\n\n\nTask state\n\n\n\n\n\n\noti_flags\n\n\nTask flags\n\n\n\n\n\n\noti_stkusage\n\n\nAmount of stack used by the task (in os_stack_t units)\n\n\n\n\n\n\
noti_stksize\n\n\nThe size of the stack (in os_stack_t units)\n\n\n\n\n\n\noti_cswcnt\n\n\nThe context switch count\n\n\n\n\n\n\noti_runtime\n\n\nThe amount of time that the task has run (in os time ticks)\n\n\n\n\n\n\noti_last_checkin\n\n\nThe time (os time) at which this task last checked in to the sanity task\n\n\n\n\n\n\noti_next_checkin\n\n\nThe time (os time) at which this task last checked in to the sanity task\n\n\n\n\n\n\noti_name\n\n\nName of the task\n\n\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in task are:\n\n\n\n\nos_task_init\n\n\nos_task_count\n\n\nos_task_info_get_next",
- "title": "Overview"
+ "title": "toc"
},
{
"location": "/os/core_os/task/task/#task",
@@ -1167,8 +1197,8 @@
},
{
"location": "/os/core_os/event_queue/event_queue/",
- "text": "Event Queues\n\n\nEvent queue is a way of serializing events arring to a task. This makes it easy to queue processing to happen inside task's context. This would be done either from an interrupt handler, or from another task.\n\n\nEvents arrive in a form of a data structure \nstruct os_event\n.\n\n\nDescription\n\n\nEvents are in form of a data structure \nstruct os_event\n, and they are queued to data structure \nstruct os_eventq\n.\n\n\nQueue must be initialized before trying to add events to it. This is done using \nos_eventq_init()\n.\n\n\nCommon way of using event queues is to have a task loop while calling \nos_eventq_get()\n, waiting for work to do.\nOther tasks (or interrupts) then call \nos_eventq_put()\n to wake it up. Once event has been queued task waiting on that queue is woken up, and will get a pointer to queued event structure.\nProcessing task would then act according to event type.\n\n\nWhen \nos_event\n is queued, it should not be freed until
processing task is done with it.\n\n\nIt is assumed that there is only one task consuming events from an event queue. Only one task should be sleeping on a particular \nos_eventq\n at a time.\n\n\nNote that os_callout subsystem assumes that event queue is used as the wakeup mechanism.\n\n\nData structures\n\n\nstruct os_event {\n uint8_t ev_queued;\n uint8_t ev_type;\n void *ev_arg;\n STAILQ_ENTRY(os_event) ev_next;\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nev_queued\n\n\nInternal field, which tells whether event is linked into an \nos_eventq\n already\n\n\n\n\n\n\nev_type\n\n\nType of an event. This should be unique, as it should be used by processing task to figure out what the event means\n\n\n\n\n\n\nev_arg\n\n\nCan be used further as input to task processing this event\n\n\n\n\n\n\nev_next\n\n\nLinkage attaching this event to an event queue\n\n\n\n\n\n\n\n\nstruct os_eventq {\n struct os_task *evq_task;\n STAILQ_HEAD(, os_event) ev
q_list;\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq_task\n\n\nPointer to task if there is task sleeping on \nos_eventq_get()\n\n\n\n\n\n\nevq_list\n\n\nQueue head for list of events in this queue\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in event queue feature are:\n\n\n\n\nos_eventq_get\n\n\nos_eventq_init\n\n\nos_eventq_put\n\n\nos_eventq_put2\n\n\nos_eventq_remove",
- "title": "Overview"
+ "text": "Event Queues\n\n\nEvent queue is a way of serializing events arring to a task. This makes it easy to queue processing to happen inside task's context. This would be done either from an interrupt handler, or from another task.\n\n\nEvents arrive in a form of a data structure \nstruct os_event\n.\n\n\nDescription\n\n\nEvents are in form of a data structure \nstruct os_event\n, and they are queued to data structure \nstruct os_eventq\n.\n\n\nQueue must be initialized before trying to add events to it. This is done using \nos_eventq_init()\n.\n\n\nCommon way of using event queues is to have a task loop while calling \nos_eventq_get()\n, waiting for work to do.\nOther tasks (or interrupts) then call \nos_eventq_put()\n to wake it up. Once event has been queued task waiting on that queue is woken up, and will get a pointer to queued event structure.\nProcessing task would then act according to event type.\n\n\nWhen \nos_event\n is queued, it should not be freed until
processing task is done with it.\n\n\nIt is assumed that there is only one task consuming events from an event queue. Only one task should be sleeping on a particular \nos_eventq\n at a time.\n\n\nNote that os_callout subsystem assumes that event queue is used as the wakeup mechanism.\n\n\nData structures\n\n\nstruct os_event {\n uint8_t ev_queued;\n uint8_t ev_type;\n void *ev_arg;\n STAILQ_ENTRY(os_event) ev_next;\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nev_queued\n\n\nInternal field, which tells whether event is linked into an \nos_eventq\n already\n\n\n\n\n\n\nev_type\n\n\nType of an event. This should be unique, as it should be used by processing task to figure out what the event means\n\n\n\n\n\n\nev_arg\n\n\nCan be used further as input to task processing this event\n\n\n\n\n\n\nev_next\n\n\nLinkage attaching this event to an event queue\n\n\n\n\n\n\n\n\nstruct os_eventq {\n struct os_task *evq_task;\n STAILQ_HEAD(, os_event) ev
q_list;\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq_task\n\n\nPointer to task if there is task sleeping on \nos_eventq_get()\n\n\n\n\n\n\nevq_list\n\n\nQueue head for list of events in this queue\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in event queue feature are:\n\n\n\n\nos_eventq_get\n\n\nos_eventq_init\n\n\nos_eventq_put\n\n\nos_eventq_remove",
+ "title": "toc"
},
{
"location": "/os/core_os/event_queue/event_queue/#event-queues",
@@ -1187,7 +1217,7 @@
},
{
"location": "/os/core_os/event_queue/event_queue/#list-of-functions",
- "text": "The functions available in event queue feature are: os_eventq_get os_eventq_init os_eventq_put os_eventq_put2 os_eventq_remove",
+ "text": "The functions available in event queue feature are: os_eventq_get os_eventq_init os_eventq_put os_eventq_remove",
"title": "List of Functions"
},
{
@@ -1252,7 +1282,7 @@
},
{
"location": "/os/core_os/event_queue/os_eventq_put/",
- "text": "os_eventq_put\n\n\nvoid\nos_eventq_put(struct os_eventq *evq, struct os_event *ev)\n\n\n\n\nQueues an event to tail of the event queue.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nQueue where event is being placed\n\n\n\n\n\n\nev\n\n\nEvent which is being queued\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nFunctionality is of \nos_eventq_put2()\n, but this is to be called from a task context only.\n\n\nExample\n\n\n\nThis is used to pass info about an event to a task handling it.\n\n\n /* Get an event structure off the queue */\n ev = (struct os_event *)os_memblock_get(\ng_hci_os_event_pool);\n if (!ev) {\n err = os_memblock_put(\ng_hci_cmd_pool, hci_ev);\n assert(err == OS_OK);\n return -1;\n }\n\n /* Fill out the event and post to Link Layer */\n ev-\nev_queued = 0;\n ev-\nev_type = BLE_HOST_HCI_EVENT_CTLR_EVENT;\n ev-\nev_arg = hci_ev;\n os_eventq_put(\nb
le_hs_evq, ev);",
+ "text": "os_eventq_put\n\n\nvoid\nos_eventq_put(struct os_eventq *evq, struct os_event *ev)\n\n\n\n\nQueues an event to tail of the event queue.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nQueue where event is being placed\n\n\n\n\n\n\nev\n\n\nEvent which is being queued\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nExample\n\n\n\nThis is used to pass info about an event to a task handling it.\n\n\n /* Get an event structure off the queue */\n ev = (struct os_event *)os_memblock_get(\ng_hci_os_event_pool);\n if (!ev) {\n err = os_memblock_put(\ng_hci_cmd_pool, hci_ev);\n assert(err == OS_OK);\n return -1;\n }\n\n /* Fill out the event and post to Link Layer */\n ev-\nev_queued = 0;\n ev-\nev_type = BLE_HOST_HCI_EVENT_CTLR_EVENT;\n ev-\nev_arg = hci_ev;\n os_eventq_put(\nble_hs_evq, ev);",
"title": "os_eventq_put"
},
{
@@ -1271,46 +1301,11 @@
"title": "Returned values"
},
{
- "location": "/os/core_os/event_queue/os_eventq_put/#notes",
- "text": "Functionality is of os_eventq_put2() , but this is to be called from a task context only.",
- "title": "Notes"
- },
- {
"location": "/os/core_os/event_queue/os_eventq_put/#example",
"text": "This is used to pass info about an event to a task handling it. /* Get an event structure off the queue */\n ev = (struct os_event *)os_memblock_get( g_hci_os_event_pool);\n if (!ev) {\n err = os_memblock_put( g_hci_cmd_pool, hci_ev);\n assert(err == OS_OK);\n return -1;\n }\n\n /* Fill out the event and post to Link Layer */\n ev- ev_queued = 0;\n ev- ev_type = BLE_HOST_HCI_EVENT_CTLR_EVENT;\n ev- ev_arg = hci_ev;\n os_eventq_put( ble_hs_evq, ev);",
"title": "Example"
},
{
- "location": "/os/core_os/event_queue/os_eventq_put2/",
- "text": "os_eventq_put2\n\n\nvoid\nos_eventq_put2(struct os_eventq *evq, struct os_event *ev, int isr)\n\n\n\n\nQueues an event to tail of the event queue.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nQueue where event is being placed\n\n\n\n\n\n\nev\n\n\nEvent which is being queued\n\n\n\n\n\n\nisr\n\n\nTells whether call is being made from within interrupt handler or not\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nIf the event has already been queued, nothing happens. Including event's relative position within the queue itself.\n\n\nThis can be called either from interrupt handler (in which case \nisr\n should be set to 1), or from another task context (in which case *isr should be set as 0).\n\n\nExample\n\n\nThis wakes up the task waiting on task1_evq, which processes console input (console input comes from UART, and is passed in in interrupt context).\n\n\nstatic void\nmy_cons_input(int full_line)\n{\n os_
eventq_put2(\ntask1_evq, \ncons_ev, 1);\n}",
- "title": "os_eventq_put2"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put2/#os_eventq_put2",
- "text": "void\nos_eventq_put2(struct os_eventq *evq, struct os_event *ev, int isr) Queues an event to tail of the event queue.",
- "title": " os_eventq_put2"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put2/#arguments",
- "text": "Arguments Description evq Queue where event is being placed ev Event which is being queued isr Tells whether call is being made from within interrupt handler or not",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put2/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put2/#notes",
- "text": "If the event has already been queued, nothing happens. Including event's relative position within the queue itself. This can be called either from interrupt handler (in which case isr should be set to 1), or from another task context (in which case *isr should be set as 0).",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put2/#example",
- "text": "This wakes up the task waiting on task1_evq, which processes console input (console input comes from UART, and is passed in in interrupt context). static void\nmy_cons_input(int full_line)\n{\n os_eventq_put2( task1_evq, cons_ev, 1);\n}",
- "title": "Example"
- },
- {
"location": "/os/core_os/event_queue/os_eventq_remove/",
"text": "os_eventq_remove\n\n\nvoid\nos_eventq_remove(struct os_eventq *evq, struct os_event *ev)\n\n\n\n\nRemoves an event which has been placed in a queue.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nQueue where event is being removed from\n\n\n\n\n\n\nev\n\n\nEvent which is being removed\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\nThis is from os_callout_stop(). User wants to stop a callout from getting passed to a task. If the event has already been queued, then remove it before it is seen.\n\n\n if (c-\nc_evq) {\n os_eventq_remove(c-\nc_evq, \nc-\nc_ev);\n }",
"title": "os_eventq_remove"
@@ -1343,7 +1338,7 @@
{
"location": "/os/core_os/semaphore/semaphore/",
"text": "Semaphore\n\n\nA semaphore is a structure used for gaining exclusive access (much like a mutex), synchronizing task operations and/or use in a \"producer/consumer\" roles. Semaphores like the ones used by the myNewt OS are called \"counting\" semaphores as they are allowed to have more than one token (explained below).\n\n\nDescription\n\n\nA semaphore is a fairly simple construct consisting of a queue for waiting tasks and the number of tokens currently owned by the semaphore. A semaphore can be obtained as long as there are tokens in the semaphore. Any task can add tokens to the semaphore and any task can request the semaphore, thereby removing tokens. When creating the semaphore, the initial number of tokens can be set as well.\n\n\nWhen used for exclusive access to a shared resource the semaphore only needs a single token. In this case, a single task \"creates\" the semaphore by calling \nos_sem_init\n with a value of one (1) for the token. When a task desir
es exclusive access to the shared resource it requests the semaphore by calling \nos_sem_pend\n. If there is a token the requesting task will acquire the semaphore and continue operation. If no tokens are available the task will be put to sleep until there is a token. A common \"problem\" with using a semaphore for exclusive access is called \npriority inversion\n. Consider the following scenario: a high and low priority task both share a resource which is locked using a semaphore. If the low priority task obtains the semaphore and then the high priority task requests the semaphore, the high priority task is now blocked until the low priority task releases the semaphore. Now suppose that there are tasks between the low priority task and the high priority task that want to run. These tasks will preempt the low priority task which owns the semaphore. Thus, the high priority task is blocked waiting for the low priority task to finish using the semaphore but the low priority task cannot
run since other tasks are running. Thus, the high priority tasks is \"inverted\" in priority; in effect running at a much lower priority as normally it would preempt the other (lower priority) tasks. If this is an issue a mutex should be used instead of a semaphore.\n\n\nSemaphores can also be used for task synchronization. A simple example of this would be the following. A task creates a semaphore and initializes it with no tokens. The task then waits on the semaphore, and since there are no tokens, the task is put to sleep. When other tasks want to wake up the sleeping task they simply add a token by calling \nos_sem_release\n. This will cause the sleeping task to wake up (instantly if no other higher priority tasks want to run).\n\n\nThe other common use of a counting semaphore is in what is commonly called a \"producer/consumer\" relationship. The producer adds tokens (by calling \nos_sem_release\n) and the consumer consumes them by calling \nos_sem_pend\n. In this relationship
, the producer has work for the consumer to do. Each token added to the semaphore will cause the consumer to do whatever work is required. A simple example could be the following: every time a button is pressed there is some work to do (ring a bell). Each button press causes the producer to add a token. Each token consumed rings the bell. There will exactly the same number of bell rings as there are button presses. In other words, each call to \nos_sem_pend\n subtracts exactly one token and each call to \nos_sem_release\n adds exactly one token.\n\n\nData structures\n\n\nstruct os_sem\n{\n SLIST_HEAD(, os_task) sem_head; /* chain of waiting tasks */\n uint16_t _pad;\n uint16_t sem_tokens; /* # of tokens */\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsem_head\n\n\nQueue head for list of tasks waiting on semaphore\n\n\n\n\n\n\n_pad\n\n\nPadding for alignment\n\n\n\n\n\n\nsem_tokens\n\n\nCurrent number of tokens\n\n\n\n\n\n\n\n\
nList of Functions\n\n\nThe functions available in semaphore are:\n\n\n\n\nos_sem_init\n\n\nos_sem_pend\n\n\nos_sem_release",
- "title": "Overview"
+ "title": "toc"
},
{
"location": "/os/core_os/semaphore/semaphore/#semaphore",
@@ -1458,7 +1453,7 @@
{
"location": "/os/core_os/mutex/mutex/",
"text": "Mutex\n\n\nMutex is short for \"mutual exclusion\"; a mutex provides mutually exclusive access to a shared resource. A mutex provides \npriority inheritance\n in order to prevent \npriority inversion\n. Priority inversion occurs when a higher priority task is waiting on a resource owned by a lower priority task. Using a mutex, the lower priority task will inherit the highest priority of any task waiting on the mutex. \n\n\nDescription\n\n\nThe first order of business when using a mutex is to declare the mutex globally. The mutex needs to be initialized before it is used (see the examples). It is generally a good idea to initialize the mutex before tasks start running in order to avoid a task possibly using the mutex before it is initialized.\n\n\nWhen a task wants exclusive access to a shared resource it needs to obtain the mutex by calling \nos_mutex_pend\n. If the mutex is currently owned by a different task (a lower priority task), the requesting task will be
put to sleep and the owners priority will be elevated to the priority of the requesting task. Note that multiple tasks can request ownership and the current owner is elevated to the highest priority of any task waitin on the mutex. When the task is done using the shared resource, it needs to release the mutex by called \nos_mutex_release\n. There needs to be one release per call to pend. Note that nested calls to \nos_mutex_pend\n are allowed but there needs to be one release per pend.\n\n\nThe following example will illustrate how priority inheritance works. In this example, the task number is the same as its priority. Remember that the lower the number, the higher the priority (i.e. priority 0 is higher priority than priority 1). Suppose that task 5 gets ownership of a mutex but is preempted by task 4. Task 4 attempts to gain ownership of the mutex but cannot as it is owned by task 5. Task 4 is put to sleep and task 5 is temporarily raised to priority 4. Before task 5 can release
the mutex, task 3 runs and attempts to acquire the mutex. At this point, both task 3 and task 4 are waiting on the mutex (sleeping). Task 5 now runs at priority 3 (the highest priority of all the tasks waiting on the mutex). When task 5 finally releases the mutex it will be preempted as two higher priority tasks are waiting for it. \n\n\nNote that when multiple tasks are waiting on a mutex owned by another task, once the mutex is released the highest priority task waiting on the mutex is run. \n\n\nData structures\n\n\nstruct os_mutex\n{\n SLIST_HEAD(, os_task) mu_head;\n uint8_t _pad;\n uint8_t mu_prio;\n uint16_t mu_level;\n struct os_task *mu_owner;\n};\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmu_head\n\n\nQueue head for list of tasks waiting on mutex\n\n\n\n\n\n\n_pad\n\n\nPadding\n\n\n\n\n\n\nmu_prio\n\n\nDefault priority of owner of mutex. Used to reset priority of task when mutex released\n\n\n\n\n\n\nmu_level\n\n\nCall nes
ting level (for nested calls)\n\n\n\n\n\n\nmu_owner\n\n\nPointer to task structure which owns mutex\n\n\n\n\n\n\n\n\nList of Functions\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\nos_mutex_init\n\n\nos_mutex_pend\n\n\nos_mutex_release",
- "title": "Overview"
+ "title": "toc"
},
{
"location": "/os/core_os/mutex/mutex/#mutex",
@@ -1538,7 +1533,7 @@
{
"location": "/os/core_os/memory_pool/memory_pool/",
"text": "Memory Pools\n\n\nA memory pool is a collection of fixed sized elements called memory blocks. Generally, memory pools are used when the developer wants to allocate a certain amount of memory to a given feature. Unlike the heap, where a code module is at the mercy of other code modules to insure there is sufficient memory, memory pools can insure sufficient memory allocation.\n\n\nDescription\n\n\nIn order to create a memory pool the developer needs to do a few things. The first task is to define the memory pool itself. This is a data structure which contains information about the pool itself (i.e. number of blocks, size of the blocks, etc).\n\n\nstruct os_mempool my_pool;\n\n\n\n\n\nThe next order of business is to allocate the memory used by the memory pool. This memory can either be statically allocated (i.e. a global variable) or dynamically allocated (i.e. from the heap). When determining the amount of memory required for the memory pool, simply multiplying
the number of blocks by the size of each block is not sufficient as the OS may have alignment requirements. The alignment size definition is named \nOS_ALIGNMENT\n and can be found in os_arch.h as it is architecture specific. The memory block alignment is usually for efficiency but may be due to other reasons. Generally, blocks are aligned on 32-bit boundaries. Note that memory blocks must also be of sufficient size to hold a list pointer as this is needed to chain memory blocks on the free list.\n\n\nIn order to simplify this for the user two macros have been provided: \nOS_MEMPOOL_BYTES(n, blksize)\n and \nOS_MEMPOOL_SIZE(n, blksize)\n. The first macro returns the number of bytes needed for the memory pool while the second returns the number of \nos_membuf_t\n elements required by the memory pool. The \nos_membuf_t\n type is used to guarantee that the memory buffer used by the memory pool is aligned on the correct boundary. \n\n\nHere are some examples. Note that if a custom mallo
c implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. OS_ALIGNMENT).\n\n\nvoid *my_memory_buffer;\nmy_memory_buffer = malloc(OS_MEMPOOL_BYTES(NUM_BLOCKS, BLOCK_SIZE));\n\n\n\n\nos_membuf_t my_memory_buffer[OS_MEMPOOL_SIZE(NUM_BLOCKS, BLOCK_SIZE)];\n\n\n\n\n\nNow that the memory pool has been defined as well as the memory required for the memory blocks which make up the pool the user needs to initialize the memory pool by calling \nos_mempool_init\n.\n\n\nos_mempool_init(\nmy_pool, NUM_BLOCKS, BLOCK_SIZE, my_memory_buffer,\n \nMyPool\n);\n\n\n\n\n\nOnce the memory pool has been initialized the developer can allocate memory blocks from the pool by calling \nos_memblock_get\n. When the memory block is no longer needed the memory can be freed by calling \nos_memblock_put\n. \n\n\nData structures\n\n\nstruct os_mempool {\n int mp_block_size;\n int mp_num_blocks;\n int mp_num_free;\n
uint32_t mp_membuf_addr;\n STAILQ_ENTRY(os_mempool) mp_list; \n SLIST_HEAD(,os_memblock);\n char *name;\n};\n\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp_block_size\n\n\nSize of the memory blocks, in bytes. This is not the actual number of bytes used by each block; it is the requested size of each block. The actual memory block size will be aligned to OS_ALIGNMENT bytes\n\n\n\n\n\n\nmp_num_blocks\n\n\nNumber of memory blocks in the pool\n\n\n\n\n\n\nmp_num_free\n\n\nNumber of free blocks left\n\n\n\n\n\n\nmp_membuf_addr\n\n\nThe address of the memory block. This is used to check that a valid memory block is being freed.\n\n\n\n\n\n\nmp_list\n\n\nList pointer to chain memory pools so they can be displayed by newt tools\n\n\n\n\n\n\nSLIST_HEAD(,os_memblock)\n\n\nList pointer to chain free memory blocks\n\n\n\n\n\n\nname\n\n\nName for the memory block\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in mem_pool are:\n\n\n\n\nos_
memblock_get\n\n\nos_mempool_init\n\n\nos_memblock_put\n\n\nOS_MEMPOOL_BYTES\n\n\nOS_MEMPOOL_SIZE",
- "title": "Overview"
+ "title": "toc"
},
{
"location": "/os/core_os/memory_pool/memory_pool/#memory-pools",
@@ -1708,7 +1703,7 @@
{
"location": "/os/core_os/heap/heap/",
"text": "Heap\n\n\nAPI for doing dynamic memory allocation.\n\n\nDescription\n\n\nThis provides malloc()/free() functionality with locking. The shared resource heap needs to be protected from concurrent access when OS has been started. \nos_malloc()\n function grabs a mutex before calling \nmalloc()\n.\n\n\nData structures\n\n\nN/A\n\n\nList of Functions\n\n\nThe functions available in heap are:\n\n\n\n\nos_free\n\n\nos_malloc\n\n\nos_realloc",
- "title": "Overview"
+ "title": "toc"
},
{
"location": "/os/core_os/heap/heap/#heap",
@@ -1823,7 +1818,7 @@
{
"location": "/os/core_os/mbuf/mbuf/",
"text": "Mbufs\n\n\nThe mbuf (short for memory buffer) is a common concept in networking stacks. The mbuf is used to hold packet data as it traverses the stack. The mbuf also generally stores header information or other networking stack information that is carried around with the packet. The mbuf and its associated library of functions were developed to make common networking stack operations (like stripping and adding protocol headers) efficient and as copy-free as possible.\n\n\nIn its simplest form, an mbuf is a memory block with some space reserved for internal information and a pointer which is used to \"chain\" memory blocks together in order to create a \"packet\". This is a very important aspect of the mbuf: the ability to chain mbufs together to create larger \"packets\" (chains of mbufs).\n\n\nWhy use mbufs?\n\n\nThe main reason is to conserve memory. Consider a networking protocol that generally sends small packets but occasionally sends large ones. The Blueto
oth Low Energy (BLE) protocol is one such example. A flat buffer would need to be sized so that the maximum packet size could be contained by the buffer. With the mbuf, a number of mbufs can be chained together so that the occasional large packet can be handled while leaving more packet buffers available to the networking stack for smaller packets.\n\n\nPacket Header mbuf\n\n\nNot all mbufs are created equal. The first mbuf in a chain of mbufs is a special mbuf called a \"packet header mbuf\". The reason that this mbuf is special is that it contains the length of all the data contained by the chain of mbufs (the packet length, in other words). The packet header mbuf may also contain a user defined structure (called a \"user header\") so that networking protocol specific information can be conveyed to various layers of the networking stack. Any mbufs that are part of the packet (i.e. in the mbuf chain but not the first one) are \"normal\" (i.e. non-packet header) mbufs. A normal mbuf
does not have any packet header or user packet header structures in them; they only contain the basic mbuf header (\nstruct os_mbuf\n). Figure 1 illustrates these two types of mbufs. Note that the numbers/text in parentheses denote the size of the structures/elements (in bytes) and that MBLEN is the memory block length of the memory pool used by the mbuf pool.\n\n\n\n\nNormal mbuf\n\n\nNow let's take a deeper dive into the mbuf structure. Figure 2 illustrates a normal mbuf and breaks out the various fields in the \nos_mbuf\n structure. \n\n\n\n\nThe \nom_data\n field is a pointer to where the data starts inside the data buffer. Typically, mbufs that are allocated from the mbuf pool (discussed later) have their om_data pointer set to the start of the data buffer but there are cases where this may not be desirable (added a protocol header to a packet, for example). \n\n\nThe \nom_flags\n field is a set of flags used internally by the mbuf library. Currently, no flags have been define
d. \n\n\nThe \nom_pkthdr_len\n field is the total length of all packet headers in the mbuf. For normal mbufs this is set to 0 as there is no packet or user packet headers. For packet header mbufs, this would be set to the length of the packet header structure (16) plus the size of the user packet header (if any). Note that it is this field which differentiates packet header mbufs from normal mbufs (i.e. if \nom_pkthdr_len\n is zero, this is a normal mbuf; otherwise it is a packet header mbuf). \n\n\nThe \nom_len\n field contains the amount of user data in the data buffer. When initially allocated, this field is 0 as there is no user data in the mbuf. \n\n\nThe \nomp_pool\n field is a pointer to the pool from which this mbuf has been allocated. This is used internally by the mbuf library. \n\n\nThe \nomp_next\n field is a linked list element which is used to chain mbufs.\n\n\n\n\nFigure 2 also shows a normal mbuf with actual values in the \nos_mbuf\n structure. This mbuf starts at ad
dress 0x1000 and is 256 bytes in total length. In this example, the user has copied 33 bytes into the data buffer starting at address 0x1010 (this is where om_data points). Note that the packet header length in this mbuf is 0 as it is not a packet header mbuf.\n\n\n\n\nFigure 3 illustrates the packet header mbuf along with some chained mbufs (i.e a \"packet\"). In this example, the user header structure is defined to be 8 bytes. Note that in figure 3 we show a number of different mbufs with varying \nom_data\n pointers and lengths since we want to show various examples of valid mbufs. For all the mbufs (both packet header and normal ones) the total length of the memory block is 128 bytes.\n\n\n\n\nMbuf pools\n\n\nMbufs are collected into \"mbuf pools\" much like memory blocks. The mbuf pool itself contains a pointer to a memory pool. The memory blocks in this memory pool are the actual mbufs; both normal and packet header mbufs. Thus, the memory block (and corresponding memory pool)
must be sized correctly. In other words, the memory blocks which make up the memory pool used by the mbuf pool must be at least: sizeof(struct os_mbuf) + sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_defined_header) + desired minimum data buffer length. For example, if the developer wants mbufs to contain at least 64 bytes of user data and they have a user header of 12 bytes, the size of the memory block would be (at least): 64 + 12 + 16 + 8, or 100 bytes. Yes, this is a fair amount of overhead. However, the flexibility provided by the mbuf library usually outweighs overhead concerns.\n\n\nCreate mbuf pool\n\n\nCreating an mbuf pool is fairly simple: create a memory pool and then create the mbuf pool using that memory pool. Once the developer has determined the size of the user data needed per mbuf (this is based on the application/networking stack and is outside the scope of this discussion) and the size of the user header (if any), the memory blocks can be sized. In the exam
ple shown below, the application requires 64 bytes of user data per mbuf and also allocates a user header (called struct user_hdr). Note that we do not show the user header data structure as there really is no need; all we need to do is to account for it when creating the memory pool. In the example, we use the macro \nMBUF_PKTHDR_OVERHEAD\n to denote the amount of packet header overhead per mbuf and \nMBUF_MEMBLOCK_OVERHEAD\n to denote the total amount of overhead required per memory block. The macro \nMBUF_BUF_SIZE\n is used to denote the amount of payload that the application requires (aligned on a 32-bit boundary in this case). All this leads to the total memory block size required, denoted by the macro \nMBUF_MEMBLOCK_OVERHEAD\n.\n\n\n\n#define MBUF_PKTHDR_OVERHEAD sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_hdr)\n#define MBUF_MEMBLOCK_OVERHEAD sizeof(struct os_mbuf) + MBUF_PKTHDR_OVERHEAD\n\n#define MBUF_NUM_MBUFS (32)\n#define MBUF_PAYLOAD_SIZE (64)\n#define
MBUF_BUF_SIZE OS_ALIGN(MBUF_PAYLOAD_SIZE, 4)\n#define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + MBUF_MEMBLOCK_OVERHEAD)\n#define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE)\n\nstruct os_mbuf_pool g_mbuf_pool; \nstruct os_mempool g_mbuf_mempool;\nos_membuf_t g_mbuf_buffer[MBUF_MEMPOOL_SIZE];\n\nvoid\ncreate_mbuf_pool(void)\n{\n int rc;\n\n rc = os_mempool_init(\ng_mbuf_mempool, MBUF_NUM_MBUFS, \n MBUF_MEMBLOCK_SIZE, \ng_mbuf_buffer[0], \nmbuf_pool\n);\n assert(rc == 0);\n\n rc = os_mbuf_pool_init(\ng_mbuf_pool, \ng_mbuf_mempool, MBUF_MEMBLOCK_SIZE, \n MBUF_NUM_MBUFS);\n assert(rc == 0);\n}\n\n\n\n\n\nUsing mbufs\n\n\nThe following examples illustrate typical mbuf usage. There are two basic mbuf allocation API: \nos_mbuf_get()\n and \nos_mbuf_get_pkthdr()\n. The first API obtains a normal mbuf whereas the latter obtains a packet header mbuf. Typically, application developers use \nos_mbuf_g
et_pkthdr()\n and rarely, if ever, need to call \nos_mbuf_get()\n as the rest of the mbuf API (e.g. \nos_mbuf_append()\n, \nos_mbuf_copyinto()\n, etc.) typically deal with allocating and chaining mbufs. It is recommended to use the provided API to copy data into/out of mbuf chains and/or manipulate mbufs.\n\n\nIn \nexample1\n, the developer creates a packet and then sends the packet to a networking interface. The code sample also provides an example of copying data out of an mbuf as well as use of the \"pullup\" api (another very common mbuf api).\n\n\n\nvoid\nmbuf_usage_example1(uint8_t *mydata, int mydata_length)\n{\n int rc;\n struct os_mbuf *om;\n\n /* get a packet header mbuf */\n om = os_mbuf_get_pkthdr(\ng_mbuf_pool, sizeof(struct user_hdr));\n if (om) {\n /* \n * Copy user data into mbuf. NOTE: if mydata_length is greater than the\n * mbuf payload size (64 bytes using above example), mbufs are allocated\n * and chained together t
o accommodate the total packet length.\n */\n rc = os_mbuf_copyinto(om, 0, mydata, len);\n if (rc) {\n /* Error! Could not allocate enough mbufs for total packet length */\n return -1;\n }\n\n /* Send packet to networking interface */\n send_pkt(om);\n }\n}\n\n\n\n\nIn \nexample2\n we show use of the pullup api as this illustrates some of the typical pitfalls developers encounter when using mbufs. The first pitfall is one of alignment/padding. Depending on the processor and/or compiler, the sizeof() a structure may vary. Thus, the size of \nmy_protocol_header\n may be different inside the packet data of the mbuf than the size of the structure on the stack or as a global variable, for instance. While some networking protcols may align protocol information on convenient processor boundaries many others try to conserve bytes \"on the air\" (i.e inside the packet data). Typical methods used to deal with this are \"packi
ng\" the structure (i.e. force compiler to not pad) or creating protocol headers that do not require padding. \nexample2\n assumes that one of these methods was used when defining the \nmy_protocol_header\n structure.\n\n\nAnother common pitfall occurs around endianness. A network protocol may be little endian or big endian; it all depends on the protocol specification. Processors also have an endianness; this means that the developer has to be careful that the processor endianness and the protocol endianness are handled correctly. In \nexample2\n, some common networking functions are used: \nntohs()\n and \nntohl()\n. These are shorthand for \"network order to host order, short\" and \"network order to host order, long\". Basically, these functions convert data of a certain size (i.e. 16 bits, 32 bits, etc) to the endianness of the host. Network byte order is big-endian (most significant byte first), so these functions convert big-endian byte order to host order (thus, the implemen
tation of these functions is host dependent). Note that the BLE networking stack \"on the air\" format is least signigicant byte first (i.e. little endian), so a \"bletoh\" function would have to take little endian format and convert to host format.\n\n\nA long story short: the developer must take care when copying structure data to/from mbufs and flat buffers!\n\n\nA final note: these examples assume the same mbuf struture and definitions used in the first example. \n\n\nvoid\nmbuf_usage_example2(struct mbuf *rxpkt)\n{\n int rc;\n uint8_t packet_data[16];\n struct mbuf *om;\n struct my_protocol_header *phdr;\n\n /* Make sure that \nmy_protocol_header\n bytes are contiguous in mbuf */\n om = os_mbuf_pullup(\ng_mbuf_pool, sizeof(struct my_protocol_header));\n if (!om) {\n /* Not able to pull up data into contiguous area */\n return -1;\n }\n\n /* \n * Get the protocol information from the packet. In this example we presume that we\n *
are interested in protocol types that are equal to MY_PROTOCOL_TYPE, are not zero\n * length, and
<TRUNCATED>