*/


/**



\page rev Revision History

\section rev17 Version 1.7, 2008 Mar 01
\li Moving out of beta

\section rev16b2 Version 1.6b2, 2008 Jan 25
\li Spotted a potential problem with reserve_task() and mailboxes

\section rev16b1 Version 1.6b1, 2008 Jan 21
\li Fixed another race condition with mailboxes that was leading to deadlock

\section rev15b1 Version 1.5b1, 2008 Jan 20
\li I now have just one ISR-related macro - TASK_ISR() - and ISRs may now decide if a task switch should occur

\section rev14b1 Version 1.4b1, 2008 Jan 17
\li Added \c init_data to the tasks - the task function now takes a void * argument

\section rev13b2 Version 1.3b2, 2008 Jan 17
\li Fixed a bug with write_mbox() and wait_for_receiver() - an incorrect algorithm was being used to see if another task
    was waiting on the mailbox, which could (and did) lead to deadlock.

\section rev13b1 Version 1.3b1, 2008 Jan 14
\li \c wait_for_mutexes no longer ignored when stop_task() is called on \c current_task

\section rev12b1 Version 1.2b1, 2008 Jan 13
\li Added the \c memory_mutex argument to create_task() and reserve_task()

\section rev11b1 Version 1.1b1, 2008 Jan 11
\li Added \c wait_for_mutexes to stop_task()
\li Changed write_mbox() so that the number of receivers could be specified, and added the "nullify" feature
\li Updated and re-organised the documentation

\section rev10b1 Version 1.0b1, 2008 Jan 09
\li Removed noticeboards, and replaced them with proper mailboxes
\li Fixed a few bugs
\li Started proper doxygen documentation

\section rev04 Version 0.4, 2008 Jan 07
\li If a task is stopped while holding mutexes, the mutexes will be released

\section rev03 Version 0.3, 2008 Jan 07
\li Fixed a memory leak bug with non-empty mailboxes on stopping tasks

\section rev02 Version 0.2, 2007 Dec 31
\li Added noticeboards

\section rev01 Version 0.1, 2007 Dec 29
\li Initial release


*/


/**



\page api-usage-restrictions API Usage Restrictions

\htmlonly
<table border="1" bordercolor="#000000" cellpadding="4" cellspacing="0" frame="below" width="100%">
  <col width="73*"> <col width="15*"> <col width="20*"> <col width="22*"> <col width="27*"> <col width="24*"> <col width="27*"> <col width="21*"> <col width="27*"> <thead> <tr valign="bottom">
    <td width="28%">
    <p align="center"><br>
    </p>
    </td>
    <td colspan="5" width="42%">
    <p align="center"><font size="2">Callable
by</font></p>
    </td>
    <td colspan="2" width="19%">
    <p align="center"><font size="2">Callable
on</font></p>
    </td>
    <td width="11%">
    <p align="center"><br>
    </p>
    </td>
  </tr>
  </thead> <tbody>
    <tr valign="bottom">
      <td width="28%">
      <p align="center"><b>API call</b></p>
      </td>
      <td width="6%">
      <p align="center"><font size="2">ISR</font></p>
      </td>
      <td width="8%">
      <p align="center"><font size="2">Idle
task</font></p>
      </td>
      <td width="9%">
      <p align="center"><font size="2">Non-idle
task</font></p>
      </td>
      <td width="11%">
      <p align="center"><font size="2">Lower-priority
task</font></p>
      </td>
      <td width="9%">
      <p align="center"><font size="2">Before
RTOS start</font></p>
      </td>
      <td width="11%">
      <p align="center"><font size="2">Current
task</font></p>
      </td>
      <td width="8%">
      <p align="center"><font size="2">Idle
task</font></p>
      </td>
      <td width="11%">
      <p align="center"><font size="2">Could
switch tasks</font></p>
      </td>
    </tr>
    <tr valign="top">
      <td width="28%">
\endhtmlonly
reserve_task()
\htmlonly
      </td>
      <td width="6%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
    </tr>
    <tr valign="top">
	<td>
\endhtmlonly
create_task()
\htmlonly
      </td>
      <td width="6%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
    </tr>
    <tr valign="top">
      <td width="28%">
\endhtmlonly
stop_task()
\htmlonly
      </td>
      <td width="6%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
    </tr>
    <tr valign="top">
      <td width="28%">
\endhtmlonly
lock_on()
\htmlonly
      </td>
      <td width="6%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
    </tr>
    <tr valign="top">
      <td width="28%">
\endhtmlonly
lock_off()
\htmlonly
      </td>
      <td width="6%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">N</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
    </tr>
    <tr valign="top">
      <td width="28%">
\endhtmlonly
get_current_mbox_version()
\htmlonly
      </td>
      <td width="6%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="8%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>
      </td>
      <td width="11%">
      <p align="center"><font face="Times New Roman, serif">n/a</font></p>
      </td>
      <td width="9%">
      <p align="center"><font face="Times New Roman, serif">Y</font></p>