📄 group__task.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"><title>YAVRTOS: Tasks</title><link href="doxygen.css" rel="stylesheet" type="text/css"><link href="tabs.css" rel="stylesheet" type="text/css"></head><body><!-- Generated by Doxygen 1.5.4 --><div class="tabs"> <ul> <li><a href="index.html"><span>Main Page</span></a></li> <li><a href="modules.html"><span>Modules</span></a></li> <li><a href="annotated.html"><span>Data Structures</span></a></li> <li><a href="files.html"><span>Files</span></a></li> <li><a href="pages.html"><span>Related Pages</span></a></li> </ul></div><h1>Tasks</h1><table border="0" cellpadding="0" cellspacing="0"><tr><td></td></tr><tr><td colspan="2"><br><h2>Defines</h2></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#g42c4528688cb31827aa5efb696995642">interrupt_store_t</a> uint8_t</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">A flag indicating whether interrupts were enabled - used by <a class="el" href="group__task.html#g6984a5336b36a4ca99682a2cf5ae044f" title="Disable interrupts system-wide.">disable_interrupts()</a> and <a class="el" href="group__task.html#gecf8a8e43c2afae89e46503ff1c887bf" title="Restore the state of the system-wide interrupts.">restore_interrupts()</a>. <a href="#g42c4528688cb31827aa5efb696995642"></a><br></td></tr><tr><td colspan="2"><br><h2>Functions</h2></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="structtask__t.html">task_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#g934155282a1d689b554e90b5138e5135">reserve_task</a> (uint16_t stacklen, uint8_t pri, <a class="el" href="structmutex__t.html">mutex_t</a> *memory_mutex)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Tasks are kept in a linked list in memory - this function reserves an "empty" task on that list, ready to be subsequently utilised by a call to <a class="el" href="group__task.html#g9b849c9a0e0b29417cf47da99226dcc3" title="Create a task, ready to be run.">create_task()</a>. <a href="#g934155282a1d689b554e90b5138e5135"></a><br></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="structtask__t.html">task_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#g9b849c9a0e0b29417cf47da99226dcc3">create_task</a> (void(*proc)(void *), void(*cleanup)(), void *init_data, uint16_t stacklen, uint8_t pri, <a class="el" href="structmutex__t.html">mutex_t</a> *memory_mutex)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Create a task, ready to be run. <a href="#g9b849c9a0e0b29417cf47da99226dcc3"></a><br></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top">int8_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ge1337adc1d63d7cd874a376d6513c04a">stop_task</a> (<a class="el" href="structtask__t.html">task_t</a> *t, uint8_t wait_for_mutexes)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Stop a task. <a href="#ge1337adc1d63d7cd874a376d6513c04a"></a><br></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#g1a2a5bbefa85516b8c1d0e0361a834db">yield</a> () __attribute__((naked))</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Stop executing the current task and try and execute a higher-priority task or another task of the same priority. <a href="#g1a2a5bbefa85516b8c1d0e0361a834db"></a><br></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#g1398c4d9f97349ea3fa7d91349298521">task_switcher_start</a> (void(*idle)(void *), void *idle_data, uint16_t idle_stacklen, uint16_t system_stacklen) __attribute__((naked))</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Start the whole process running. <a href="#g1398c4d9f97349ea3fa7d91349298521"></a><br></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top">interrupt_store_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#g6984a5336b36a4ca99682a2cf5ae044f">disable_interrupts</a> ()</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Disable interrupts system-wide. <a href="#g6984a5336b36a4ca99682a2cf5ae044f"></a><br></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gecf8a8e43c2afae89e46503ff1c887bf">restore_interrupts</a> (interrupt_store_t interrupts)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Restore the state of the system-wide interrupts. <a href="#gecf8a8e43c2afae89e46503ff1c887bf"></a><br></td></tr><tr><td colspan="2"><br><h2>Variables</h2></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="structtask__t.html">task_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#g4743b3673a8794b8e7bd0b6c91a63cd5">current_task</a></td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">The current task. <a href="#g4743b3673a8794b8e7bd0b6c91a63cd5"></a><br></td></tr></table><hr><a name="_details"></a><h2>Detailed Description</h2>A task performs a function in the application, and an application can have a number of tasks running "simultaneously". Tasks are a function with the signature <code>void task_func(void *init)</code>, and optionally a "cleanup" function <code>void task_cleanup()</code> that is called when the task is exiting. The value of the <code>init</code> argument to the task function is specified when the task is created.<p>Tasks are created by <a class="el" href="group__task.html#g9b849c9a0e0b29417cf47da99226dcc3" title="Create a task, ready to be run.">create_task()</a>, and can be stopped by <a class="el" href="group__task.html#ge1337adc1d63d7cd874a376d6513c04a" title="Stop a task.">stop_task()</a>. Tasks are held in memory in a linked list - spaces may be reserved on that list for future tasks using <a class="el" href="group__task.html#g934155282a1d689b554e90b5138e5135" title="Tasks are kept in a linked list in memory - this function reserves an "empty"...">reserve_task()</a>.<p>Tasks can suspend themselves when they are unable to do any work (e.g. a task that reads a microcontroller peripheral could suspend itself when the peripheral has no data available), hence allowing other tasks that can do work to run, and hence the application as a whole can get the maximum use of the CPU's processing power. The ways a task can suspend itself are <ul><li>by calling <a class="el" href="group__mutex.html#gdff77e0b451c30c07d2990e669f937c5" title="Lock on a mutex.">lock_on()</a> on a <a class="el" href="group__mutex.html">mutex</a> that another task has already locked on to. Note that <a class="el" href="group__task.html#g9b849c9a0e0b29417cf47da99226dcc3" title="Create a task, ready to be run.">create_task()</a> and <a class="el" href="group__task.html#g934155282a1d689b554e90b5138e5135" title="Tasks are kept in a linked list in memory - this function reserves an "empty"...">reserve_task()</a> can decide to lock on to a supplied "memory mutex" - see <a class="el" href="group__task.html#g9b849c9a0e0b29417cf47da99226dcc3" title="Create a task, ready to be run.">create_task()</a>, <a class="el" href="group__task.html#g934155282a1d689b554e90b5138e5135" title="Tasks are kept in a linked list in memory - this function reserves an "empty"...">reserve_task()</a> and <a class="el" href="howdoi.html#malloc">How do I use malloc() and free() safely?</a> </li><li>by calling <a class="el" href="group__semaphore.html#g45243d3de7a253445deeb57ee4c8cc96" title="Wait for a semaphore to reach at least a particular value.">wait_for_min_value()</a> on a <a class="el" href="group__semaphore.html">semaphore</a> that hasn't yet reached the specified value </li><li>by calling <a class="el" href="group__semaphore.html#g291edcd883e2d0bc17f85419e21069ff" title="Wait for a semaphore to increment its value by a certain amount.">wait_for_increment_of()</a> on a <a class="el" href="group__semaphore.html">semaphore</a> </li><li>by calling <a class="el" href="group__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3" title="Wait for a mailbox to reach at least a certain version, and then start reading from...">read_mbox_min_version()</a> on a <a class="el" href="group__mailbox.html">mailbox</a> that hasn't yet reached the specified version </li><li>by calling <a class="el" href="group__mailbox.html#gc75646248d03b1413198765b07ba54ad" title="Write to a mailbox.">write_mbox()</a> - see <a class="el" href="group__mailbox.html#gc75646248d03b1413198765b07ba54ad" title="Write to a mailbox.">write_mbox()</a> for the conditions under which a task will be suspended </li><li>by calling <a class="el" href="group__mailbox.html#gf670250659f0942849aa85f0f94af9f0" title="Wait for a task to be suspended while trying to read from a mailbox.">wait_for_receiver()</a> on a <a class="el" href="group__mailbox.html">mailbox</a> that no-one is waiting to read from </li><li>a temporary suspension can be caused by calling <a class="el" href="group__task.html#g1a2a5bbefa85516b8c1d0e0361a834db" title="Stop executing the current task and try and execute a higher-priority task or another...">yield()</a> - if there are other schedulable tasks, they will run, but the calling task will eventually be re-scheduled to run </li><li>by waiting for another task to stop - see <a class="el" href="group__task.html#ge1337adc1d63d7cd874a376d6513c04a" title="Stop a task.">stop_task()</a> for more information</li></ul>Every task has a priority. The rule is that the RTOS will not allow the lowest-priority tasks to run until all higher-priority tasks have suspended themselves. If there are more than one highest-priority not-suspended tasks, then the RTOS will switch between them once every tick interrupt (and/or whenever one of the tasks calls <a class="el" href="group__task.html#g1a2a5bbefa85516b8c1d0e0361a834db" title="Stop executing the current task and try and execute a higher-priority task or another...">yield()</a>).<p>A priority of zero indicates an "idle" task - a task that is run when there are no other tasks that can run. There must always be at least one idle task, and idle tasks can neither be stopped nor can they do anything to suspend themselves (e.g. they cannot wait for a mutex to be released), as the microcontroller needs at least one task to be always available for scheduling. Usually there is just one idle task that just sleeps the CPU. A recommended idle task is <div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> idle_task(<span class="keywordtype">void</span> *p) { set_sleep_mode(SLEEP_MODE_IDLE); sleep_enable(); sei(); sleep_cpu();}</pre></div><p>A task switch can occur <ul><li>whenever anything happens to a mutex, semaphore or mailbox that may cancel the suspension of a higher priority task (e.g. when a semaphore has its value increased) </li><li>when a task calls <a class="el" href="group__task.html#g1a2a5bbefa85516b8c1d0e0361a834db" title="Stop executing the current task and try and execute a higher-priority task or another...">yield()</a> </li><li>when the system tick interrupt happens - see <a class="el" href="group__isr.html">Interrupt Service Routines</a> for more information about the tick interrupt.</li></ul>From the point of view of the RTOS, the microcontroller can be doing one of three things <ul><li>executing code before the RTOS has been started with a call to <a class="el" href="group__task.html#g1398c4d9f97349ea3fa7d91349298521" title="Start the whole process running.">task_switcher_start()</a>. When the microcontroller is in this state, the RTOS is obviously unable to "suspend" what the microcontroller is doing, and hence none of the API calls that could cause such a suspension may be used </li><li>executing a task, which can be an "idle" task of zero priority, or a "non-idle" task of non-zero priority. When executing an idle task, a task suspension is disallowed (as there must always be something that the microcontroller can do when it is otherwise unable to do anything). </li><li>executing an ISR, including the tick interrupt ISR. Again, the RTOS is unable to suspend the ISR.</li></ul>Therefore there are restrictions on when certain API calls may be made - these restrictions are summarised on the <a class="el" href="api-usage-restrictions.html">api usage restrictions</a> page.<p>See the <a class="el" href="example.html">example application</a> for an example of how to start and run some simple tasks.<p>Tasks can be stopped by other tasks or by ISRs - see <a class="el" href="group__task.html#ge1337adc1d63d7cd874a376d6513c04a" title="Stop a task.">stop_task()</a>. When a task is stopped, mutexes and mailboxes are released - see <a class="el" href="task_8c.html#b1c4cc247bd379e340e25bd86911919d" title="The entry point for all tasks that are stopping">task_stopper()</a> <hr><h2>Define Documentation</h2><a class="anchor" name="g42c4528688cb31827aa5efb696995642"></a><!-- doxytag: member="task.h::interrupt_store_t" ref="g42c4528688cb31827aa5efb696995642" args="" --><div class="memitem"><div class="memproto"> <table class="memname"> <tr> <td class="memname">#define interrupt_store_t uint8_t </td> </tr> </table></div><div class="memdoc"><p>A flag indicating whether interrupts were enabled - used by <a class="el" href="group__task.html#g6984a5336b36a4ca99682a2cf5ae044f" title="Disable interrupts system-wide.">disable_interrupts()</a> and <a class="el" href="group__task.html#gecf8a8e43c2afae89e46503ff1c887bf" title="Restore the state of the system-wide interrupts.">restore_interrupts()</a>. <p></div></div><p><hr><h2>Function Documentation</h2><a class="anchor" name="g9b849c9a0e0b29417cf47da99226dcc3"></a><!-- doxytag: member="task.h::create_task" ref="g9b849c9a0e0b29417cf47da99226dcc3" args="(void(*proc)(void *), void(*cleanup)(), void *init_data, uint16_t stacklen, uint8_t pri, mutex_t *memory_mutex)" --><div class="memitem"><div class="memproto"> <table class="memname"> <tr> <td class="memname"><a class="el" href="structtask__t.html">task_t</a>* create_task </td> <td>(</td> <td class="paramtype">void(*)(void *) </td> <td class="paramname"> <em>proc</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">void(*)() </td> <td class="paramname"> <em>cleanup</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">void * </td> <td class="paramname"> <em>init_data</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">uint16_t </td> <td class="paramname"> <em>stacklen</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">uint8_t </td>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -