?? group__mailbox.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: Mailboxes</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>Mailboxes</h1><table border="0" cellpadding="0" cellspacing="0"><tr><td></td></tr><tr><td colspan="2"><br><h2>Functions</h2></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top">int16_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mailbox.html#g9b7e62ecd1a61eda8cfa1229df0728ef">get_current_mbox_version</a> (<a class="el" href="structmailbox__t.html">mailbox_t</a> *mbox)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Get the current version of a mailbox. <a href="#g9b7e62ecd1a61eda8cfa1229df0728ef"></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__mailbox.html#g5dbb6937f6f93f6a1c14dec5b1c197c3">read_mbox_min_version</a> (<a class="el" href="structmailbox__t.html">mailbox_t</a> *mbox, int16_t *version)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Wait for a mailbox to reach at least a certain version, and then start reading from it. <a href="#g5dbb6937f6f93f6a1c14dec5b1c197c3"></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__mailbox.html#g86030bb5345670ca374ddd20ef8e4ff6">read_mbox</a> (<a class="el" href="structmailbox__t.html">mailbox_t</a> *mbox, int16_t *version)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Read a mailbox. <a href="#g86030bb5345670ca374ddd20ef8e4ff6"></a><br></td></tr><tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="structmailbox__t.html">mailbox_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__mailbox.html#g31b8ee5f4cd547c128143d99ea1c4a96">release_mbox_read</a> ()</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Function to call when finished reading from a mailbox. <a href="#g31b8ee5f4cd547c128143d99ea1c4a96"></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__mailbox.html#gd4cde27abfbedc7c8e854e76d71612dd">initialise_mbox</a> (<a class="el" href="structmailbox__t.html">mailbox_t</a> *mbox, void *data, const int16_t version)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Initialise a mailbox - this <b>must</b> be called on every mailbox before it is used. <a href="#gd4cde27abfbedc7c8e854e76d71612dd"></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__mailbox.html#gc75646248d03b1413198765b07ba54ad">write_mbox</a> (<a class="el" href="structmailbox__t.html">mailbox_t</a> *mbox, void *data, uint8_t wait_for_receivers, uint8_t wait_for_empty_nullify)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Write to a mailbox. <a href="#gc75646248d03b1413198765b07ba54ad"></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__mailbox.html#g87f02ab5b46654ae26b06851b2390132">write_mbox_now</a> (<a class="el" href="structmailbox__t.html">mailbox_t</a> *mbox, void *data)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Attempt to write to a mailbox. <a href="#g87f02ab5b46654ae26b06851b2390132"></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__mailbox.html#gf670250659f0942849aa85f0f94af9f0">wait_for_receiver</a> (<a class="el" href="structmailbox__t.html">mailbox_t</a> *mbox)</td></tr><tr><td class="mdescLeft"> </td><td class="mdescRight">Wait for a task to be suspended while trying to read from a mailbox. <a href="#gf670250659f0942849aa85f0f94af9f0"></a><br></td></tr></table><hr><a name="_details"></a><h2>Detailed Description</h2>Mailboxes are used to pass information between tasks.<p>Mailboxes contain a pointer to the mailbox data, and a version number. Tasks can both read from and write to mailboxes. The rules governing mailboxes are <ul><li>A task can only read from one mailbox at a time - the task must finish reading a mailbox before it can start reading another one </li><li>A task cannot write to a mailbox while there are other tasks reading from it </li><li>A mailbox can contain only one "message" at a time</li></ul>Mailboxes <b>must</b> be initialised with <a class="el" href="group__mailbox.html#gd4cde27abfbedc7c8e854e76d71612dd" title="Initialise a mailbox - this must be called on every mailbox before it is used.">initialise_mbox()</a>. Tasks can write to mailboxes with <a class="el" href="group__mailbox.html#gc75646248d03b1413198765b07ba54ad" title="Write to a mailbox.">write_mbox()</a> or <a class="el" href="group__mailbox.html#g87f02ab5b46654ae26b06851b2390132" title="Attempt to write to a mailbox.">write_mbox_now()</a>. Tasks can read from mailboxes with <a class="el" href="group__mailbox.html#g86030bb5345670ca374ddd20ef8e4ff6" title="Read a mailbox.">read_mbox()</a> or <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>, and <b>must</b> subsequently call <a class="el" href="group__mailbox.html#g31b8ee5f4cd547c128143d99ea1c4a96" title="Function to call when finished reading from a mailbox.">release_mbox_read()</a> when they are done reading from the mailbox. Other functions governing the use of mailboxes are <a class="el" href="group__mailbox.html#g9b7e62ecd1a61eda8cfa1229df0728ef" title="Get the current version of a mailbox.">get_current_mbox_version()</a> and <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>.<p>Mailboxes can be synchronous or asynchronous. When task A writes to a mailbox, its version number is incremented. If task B has been waiting for that version of the mailbox, it is immediately marked as reading the mailbox, hence other tasks are prevented from writing to the mailbox until task B has finished reading from it. Of course, if there wasn't a task B waiting for the data, then a task C could over-write what task A wrote to the mailbox without any task ever seeing what task A wrote. To mitigate this problem, task A is able to request that a certain minimum number of tasks be waiting for the mailbox to be updated before the data is written to the mailbox - hence task A is guaranteed that the data it writes is seen.<p>It is the responsibility of the task that writes to the mailbox to allocate memory for the mailbox data. To prevent problems arising from the memory allocation going out of scope before all the reading tasks have finished reading the data, a writing task is able to request that all reading tasks finish reading before control is passed back to the writing task. Not only that, but the writing task is also able to request that the mailbox data be "nullified" (i.e. that a new version of the mailbox with a null data pointer be published) as soon as all the reading tasks have finished reading, thereby ensuring that no subsequent reading tasks will attempt to read the writing tasks' data.<p>See <a class="el" href="usage-mbox.html">using mailboxes</a> for information on how to use mailboxes <hr><h2>Function Documentation</h2><a class="anchor" name="g9b7e62ecd1a61eda8cfa1229df0728ef"></a><!-- doxytag: member="task.h::get_current_mbox_version" ref="g9b7e62ecd1a61eda8cfa1229df0728ef" args="(mailbox_t *mbox)" --><div class="memitem"><div class="memproto"> <table class="memname"> <tr> <td class="memname">int16_t get_current_mbox_version </td> <td>(</td> <td class="paramtype"><a class="el" href="structmailbox__t.html">mailbox_t</a> * </td> <td class="paramname"> <em>mbox</em> </td> <td> ) </td> <td width="100%"></td> </tr> </table></div><div class="memdoc"><p>Get the current version of a mailbox. <p>This function can be called by an ISR, by any task, or even before the RTOS starts </div></div><p><a class="anchor" name="gd4cde27abfbedc7c8e854e76d71612dd"></a><!-- doxytag: member="task.h::initialise_mbox" ref="gd4cde27abfbedc7c8e854e76d71612dd" args="(mailbox_t *mbox, void *data, const int16_t version)" --><div class="memitem"><div class="memproto"> <table class="memname"> <tr> <td class="memname">void initialise_mbox </td> <td>(</td> <td class="paramtype"><a class="el" href="structmailbox__t.html">mailbox_t</a> * </td> <td class="paramname"> <em>mbox</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">void * </td> <td class="paramname"> <em>data</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">const int16_t </td> <td class="paramname"> <em>version</em></td><td> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td><td width="100%"></td> </tr> </table></div><div class="memdoc"><p>Initialise a mailbox - this <b>must</b> be called on every mailbox before it is used. <p>The arguments are <ul><li><code>mbox</code> - the mailbox to initialise </li><li><code>data</code> - the pointer to the mailbox data. This is the value that will be returned by <a class="el" href="group__mailbox.html#g86030bb5345670ca374ddd20ef8e4ff6" title="Read a mailbox.">read_mbox()</a> and <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>. It is acceptable to set this value to zero - though callers to <a class="el" href="group__mailbox.html#g86030bb5345670ca374ddd20ef8e4ff6" title="Read a mailbox.">read_mbox()</a> and <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> would need to be aware that the return value could be zero. </li><li><code>version</code> - the initial version of the mailbox </li></ul></div></div><p><a class="anchor" name="g86030bb5345670ca374ddd20ef8e4ff6"></a><!-- doxytag: member="task.h::read_mbox" ref="g86030bb5345670ca374ddd20ef8e4ff6" args="(mailbox_t *mbox, int16_t *version)" --><div class="memitem"><div class="memproto"> <table class="memname"> <tr> <td class="memname">void* read_mbox </td> <td>(</td> <td class="paramtype"><a class="el" href="structmailbox__t.html">mailbox_t</a> * </td> <td class="paramname"> <em>mbox</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">int16_t * </td> <td class="paramname"> <em>version</em></td><td> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td><td width="100%"></td> </tr> </table></div><div class="memdoc"><p>Read a mailbox. <p>This function reads a mailbox regardless of the version of the mailbox.<p><dl class="attention" compact><dt><b>Attention:</b></dt><dd>It is <b>vital</b> that <a class="el" href="group__mailbox.html#g31b8ee5f4cd547c128143d99ea1c4a96" title="Function to call when finished reading from a mailbox.">release_mbox_read()</a> be called to release the mailbox for other tasks to write to it when the calling task has finished reading the mailbox data</dd></dl>The arguments are <ul><li><code>mbox</code> - the mailbox to read </li><li><code>version</code> - if not null, the version of the mailbox will be written to this address</li></ul>The return value is a pointer to the mailbox data. Note that a zero return value does not mean that the mailbox read failed - it means that the mailbox was empty - and hence <a class="el" href="group__mailbox.html#g31b8ee5f4cd547c128143d99ea1c4a96" title="Function to call when finished reading from a mailbox.">release_mbox_read()</a> must still be called.<p>Since this function can cause a suspension (i.e. if the mailbox hasn't reached the specified version), it can only be called from a task with a non-zero priority </div></div><p><a class="anchor" name="g5dbb6937f6f93f6a1c14dec5b1c197c3"></a><!-- doxytag: member="task.h::read_mbox_min_version" ref="g5dbb6937f6f93f6a1c14dec5b1c197c3" args="(mailbox_t *mbox, int16_t *version)" --><div class="memitem"><div class="memproto"> <table class="memname"> <tr> <td class="memname">void* read_mbox_min_version </td> <td>(</td> <td class="paramtype"><a class="el" href="structmailbox__t.html">mailbox_t</a> * </td> <td class="paramname"> <em>mbox</em>, </td> </tr> <tr> <td class="paramkey"></td> <td></td> <td class="paramtype">int16_t * </td> <td class="paramname"> <em>version</em></td><td> </td> </tr> <tr> <td></td>?? 快捷鍵說明
復制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -