doc/generated/html/api/group__task.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   5 <title>Xenomai API: Task management services.</title>
   6 <link href="tabs.css" rel="stylesheet" type="text/css"/>
   7 <link href="doxygen.css" rel="stylesheet" type="text/css"/>
   8 </head>
   9 <body>
  10 <!-- Generated by Doxygen 1.7.1 -->
  11 <div class="navigation" id="top">
  12   <div class="tabs">
  13     <ul class="tablist">
  14       <li><a href="main.html"><span>Main&nbsp;Page</span></a></li>
  15       <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  16       <li><a href="modules.html"><span>Modules</span></a></li>
  17       <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
  18       <li><a href="files.html"><span>Files</span></a></li>
  19       <li><a href="examples.html"><span>Examples</span></a></li>
  20     </ul>
  21   </div>
  22 </div>
  23 <div class="header">
  24   <div class="summary">
  25 <a href="#files">Files</a> &#124;
  26 <a href="#func-members">Functions</a>  </div>
  27   <div class="headertitle">
  28 <h1>Task management services.<br/>
  29 <small>
  30 [<a class="el" href="group__native.html">Native Xenomai API.</a>]</small>
  31 </h1>  </div>
  32 </div>
  33 <div class="contents">
  34
  35 <p><div class="dynheader">
  36 Collaboration diagram for Task management services.:</div>
  37 <div class="dyncontent">
  38 <center><table><tr><td><img src="group__task.png" border="0" alt="" usemap="#group____task"/>
  39 <map name="group____task" id="group____task">
  40 <area shape="rect" id="node1" href="group__native.html" title="Native Xenomai API." alt="" coords="7,5,159,35"/></map>
  41 </td></tr></table></center>
  42 </div>
  43 </p>
  44 <table class="memberdecls">
  45 <tr><td colspan="2"><h2><a name="files"></a>
  46 Files</h2></td></tr>
  47 <tr><td class="memItemLeft" align="right" valign="top">file &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ksrc_2skins_2native_2task_8c.html">task.c</a></td></tr>
  48
  49 <p><tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight"><p>This file is part of the Xenomai project. </p>
  50 <br/></td></tr>
  51 </p>
  52 <tr><td colspan="2"><h2><a name="func-members"></a>
  53 Functions</h2></td></tr>
  54 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga03387550693c21d0223f739570ccd992">rt_task_create</a> (RT_TASK *task, const char *name, int stksize, int prio, int mode)</td></tr>
  55 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Create a new real-time task.  <a href="#ga03387550693c21d0223f739570ccd992"></a><br/></td></tr>
  56 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gac9638918b8310a430088f5c9a04d2bb7">rt_task_start</a> (RT_TASK *task, void(*entry)(void *cookie), void *cookie)</td></tr>
  57 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Start a real-time task.  <a href="#gac9638918b8310a430088f5c9a04d2bb7"></a><br/></td></tr>
  58 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga926a4b10e3631f76c5f38910e6eea24c">rt_task_suspend</a> (RT_TASK *task)</td></tr>
  59 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Suspend a real-time task.  <a href="#ga926a4b10e3631f76c5f38910e6eea24c"></a><br/></td></tr>
  60 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga1fab1aa24ef6f199546fd9669ae711be">rt_task_resume</a> (RT_TASK *task)</td></tr>
  61 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Resume a real-time task.  <a href="#ga1fab1aa24ef6f199546fd9669ae711be"></a><br/></td></tr>
  62 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gab6e0d411830710e8cc82d77b9df19510">rt_task_delete</a> (RT_TASK *task)</td></tr>
  63 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Delete a real-time task.  <a href="#gab6e0d411830710e8cc82d77b9df19510"></a><br/></td></tr>
  64 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga31e44b069b2486c2d2bdfb8a0a3557c8">rt_task_yield</a> (void)</td></tr>
  65 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Manual round-robin.  <a href="#ga31e44b069b2486c2d2bdfb8a0a3557c8"></a><br/></td></tr>
  66 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gababee94264156693cd4f5b9b70d3c5a1">rt_task_set_periodic</a> (RT_TASK *task, RTIME idate, RTIME period)</td></tr>
  67 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Make a real-time task periodic.  <a href="#gababee94264156693cd4f5b9b70d3c5a1"></a><br/></td></tr>
  68 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga1645d3a072ef3cefeed3bcbb27dcf108">rt_task_wait_period</a> (unsigned long *overruns_r)</td></tr>
  69 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Wait for the next periodic release point.  <a href="#ga1645d3a072ef3cefeed3bcbb27dcf108"></a><br/></td></tr>
  70 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga3bed8d001e212a3328a4e7e73f1765e8">rt_task_set_priority</a> (RT_TASK *task, int prio)</td></tr>
  71 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Change the base priority of a real-time task.  <a href="#ga3bed8d001e212a3328a4e7e73f1765e8"></a><br/></td></tr>
  72 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gad5225e5fb8d583fbdfa5299f322b8366">rt_task_sleep</a> (RTIME delay)</td></tr>
  73 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Delay the calling task (relative).  <a href="#gad5225e5fb8d583fbdfa5299f322b8366"></a><br/></td></tr>
  74 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga0dc2deebe7500c9d21ff05d51d5efaa8">rt_task_sleep_until</a> (RTIME date)</td></tr>
  75 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Delay the calling task (absolute).  <a href="#ga0dc2deebe7500c9d21ff05d51d5efaa8"></a><br/></td></tr>
  76 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1">rt_task_unblock</a> (RT_TASK *task)</td></tr>
  77 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Unblock a real-time task.  <a href="#ga770281eeca009c0a08a7c4a9fd849ac1"></a><br/></td></tr>
  78 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga53bad6acf5496f8008e594954507dce8">rt_task_inquire</a> (RT_TASK *task, <a class="el" href="structrt__task__info.html">RT_TASK_INFO</a> *info)</td></tr>
  79 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Inquire about a real-time task.  <a href="#ga53bad6acf5496f8008e594954507dce8"></a><br/></td></tr>
  80 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga7452f367f9e17bf2fc0b70f717b96dd8">rt_task_add_hook</a> (int type, void(*routine)(void *cookie))</td></tr>
  81 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Install a task hook.  <a href="#ga7452f367f9e17bf2fc0b70f717b96dd8"></a><br/></td></tr>
  82 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga585bcffb3757845534eed69edd1a27d2">rt_task_remove_hook</a> (int type, void(*routine)(void *cookie))</td></tr>
  83 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Remove a task hook.  <a href="#ga585bcffb3757845534eed69edd1a27d2"></a><br/></td></tr>
  84 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga8e17be7a49ac32bbeb3085b3cd1a9915">rt_task_catch</a> (void(*handler)(rt_sigset_t))</td></tr>
  85 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Install a signal handler.  <a href="#ga8e17be7a49ac32bbeb3085b3cd1a9915"></a><br/></td></tr>
  86 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga70e65c2efb499c48c6d15010a1c630a3">rt_task_notify</a> (RT_TASK *task, rt_sigset_t signals)</td></tr>
  87 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Send signals to a task.  <a href="#ga70e65c2efb499c48c6d15010a1c630a3"></a><br/></td></tr>
  88 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga915e7edfb0aaddb643794d7abc7093bf">rt_task_set_mode</a> (int clrmask, int setmask, int *mode_r)</td></tr>
  89 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Change task mode bits.  <a href="#ga915e7edfb0aaddb643794d7abc7093bf"></a><br/></td></tr>
  90 <tr><td class="memItemLeft" align="right" valign="top">RT_TASK *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gaaf5467af966c9980da9e489aeacf9aa3">rt_task_self</a> (void)</td></tr>
  91 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Retrieve the current task.  <a href="#gaaf5467af966c9980da9e489aeacf9aa3"></a><br/></td></tr>
  92 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga9250436d7bd9e49a0320161d2e9373ae">rt_task_slice</a> (RT_TASK *task, RTIME quantum)</td></tr>
  93 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Set a task's round-robin quantum.  <a href="#ga9250436d7bd9e49a0320161d2e9373ae"></a><br/></td></tr>
  94 <tr><td class="memItemLeft" align="right" valign="top">ssize_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga99a89c21c9866e2784860e100a444b49">rt_task_send</a> (RT_TASK *task, <a class="el" href="structrt__task__mcb.html">RT_TASK_MCB</a> *mcb_s, <a class="el" href="structrt__task__mcb.html">RT_TASK_MCB</a> *mcb_r, RTIME timeout)</td></tr>
  95 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Send a message to a task.  <a href="#ga99a89c21c9866e2784860e100a444b49"></a><br/></td></tr>
  96 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gaa152f8f41876fc3a828a8eba74d493fe">rt_task_receive</a> (<a class="el" href="structrt__task__mcb.html">RT_TASK_MCB</a> *mcb_r, RTIME timeout)</td></tr>
  97 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Receive a message from a task.  <a href="#gaa152f8f41876fc3a828a8eba74d493fe"></a><br/></td></tr>
  98 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gacd8a4fb2d11f0548bd053dfbf92f9e9d">rt_task_reply</a> (int flowid, <a class="el" href="structrt__task__mcb.html">RT_TASK_MCB</a> *mcb_s)</td></tr>
  99 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Reply to a task.  <a href="#gacd8a4fb2d11f0548bd053dfbf92f9e9d"></a><br/></td></tr>
 100 <tr><td class="memItemLeft" align="right" valign="top">static int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga520e6fad1decc5beff58b394ff443265">rt_task_spawn</a> (RT_TASK *task, const char *name, int stksize, int prio, int mode, void(*entry)(void *cookie), void *cookie)</td></tr>
 101 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Spawn a new real-time task.  <a href="#ga520e6fad1decc5beff58b394ff443265"></a><br/></td></tr>
 102 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga72e0a9355d06c346a95bf88b857a9749">rt_task_shadow</a> (RT_TASK *task, const char *name, int prio, int mode)</td></tr>
 103 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Turns the current Linux task into a native Xenomai task.  <a href="#ga72e0a9355d06c346a95bf88b857a9749"></a><br/></td></tr>
 104 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gab6bd973c22a6f66e28653922c53e0385">rt_task_bind</a> (RT_TASK *task, const char *name, RTIME timeout)</td></tr>
 105 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Bind to a real-time task.  <a href="#gab6bd973c22a6f66e28653922c53e0385"></a><br/></td></tr>
 106 <tr><td class="memItemLeft" align="right" valign="top">static int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga2038cbe2350a8e2558330a3f45953865">rt_task_unbind</a> (RT_TASK *task)</td></tr>
 107 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Unbind from a real-time task.  <a href="#ga2038cbe2350a8e2558330a3f45953865"></a><br/></td></tr>
 108 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#ga8c77d57638578a126812e29429f61fe7">rt_task_join</a> (RT_TASK *task)</td></tr>
 109 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Wait on the termination of a real-time task.  <a href="#ga8c77d57638578a126812e29429f61fe7"></a><br/></td></tr>
 110 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__task.html#gaf6e313941a3fea606be8d0f66380e922">rt_task_same</a> (RT_TASK *task1, RT_TASK *task2)</td></tr>
 111 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Compare two task descriptors.  <a href="#gaf6e313941a3fea606be8d0f66380e922"></a><br/></td></tr>
 112 </table>
 113 <hr/><a name="_details"></a><h2>Detailed Description</h2>
 114 <p>Xenomai provides a set of multitasking mechanisms. The basic process object performing actions in Xenomai is a task, a logically complete path of application code. Each Xenomai task is an independent portion of the overall application code embodied in a C procedure, which executes on its own stack context.</p>
 115 <p>The Xenomai scheduler ensures that concurrent tasks are run according to one of the supported scheduling policies. Currently, the Xenomai scheduler supports fixed priority-based FIFO and round-robin policies. </p>
 116 <hr/><h2>Function Documentation</h2>
 117 <a class="anchor" id="ga7452f367f9e17bf2fc0b70f717b96dd8"></a><!-- doxytag: member="task.c::rt_task_add_hook" ref="ga7452f367f9e17bf2fc0b70f717b96dd8" args="(int type, void(*routine)(void *cookie))" -->
 118 <div class="memitem">
 119 <div class="memproto">
 120       <table class="memname">
 121         <tr>
 122           <td class="memname">int rt_task_add_hook </td>
 123           <td>(</td>
 124           <td class="paramtype">int&nbsp;</td>
 125           <td class="paramname"> <em>type</em>, </td>
 126         </tr>
 127         <tr>
 128           <td class="paramkey"></td>
 129           <td></td>
 130           <td class="paramtype">void(*)(void *cookie)&nbsp;</td>
 131           <td class="paramname"> <em>routine</em></td><td>&nbsp;</td>
 132         </tr>
 133         <tr>
 134           <td></td>
 135           <td>)</td>
 136           <td></td><td></td><td></td>
 137         </tr>
 138       </table>
 139 </div>
 140 <div class="memdoc">
 141
 142 <p>Install a task hook. </p>
 143 <p>The real-time kernel allows to register user-defined routines which get called whenever a specific scheduling event occurs. Multiple hooks can be chained for a single event type, and get called on a FIFO basis.</p>
 144 <p>The scheduling is locked while a hook is executing.</p>
 145 <dl><dt><b>Parameters:</b></dt><dd>
 146   <table border="0" cellspacing="2" cellpadding="0">
 147     <tr><td valign="top"></td><td valign="top"><em>type</em>&nbsp;</td><td>Defines the kind of hook to install:</td></tr>
 148   </table>
 149   </dd>
 150 </dl>
 151 <ul>
 152 <li>T_HOOK_START: The user-defined routine will be called on behalf of the starter task whenever a new task starts. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the started task through the T_DESC() macro.</li>
 153 </ul>
 154 <ul>
 155 <li>T_HOOK_DELETE: The user-defined routine will be called on behalf of the deletor task whenever a task is deleted. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the deleted task through the T_DESC() macro.</li>
 156 </ul>
 157 <ul>
 158 <li>T_HOOK_SWITCH: The user-defined routine will be called on behalf of the resuming task whenever a context switch takes place. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the task which has been switched in through the T_DESC() macro.</li>
 159 </ul>
 160 <dl><dt><b>Parameters:</b></dt><dd>
 161   <table border="0" cellspacing="2" cellpadding="0">
 162     <tr><td valign="top"></td><td valign="top"><em>routine</em>&nbsp;</td><td>The address of the user-supplied routine to call.</td></tr>
 163   </table>
 164   </dd>
 165 </dl>
 166 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise, one of the following error codes indicates the cause of the failure:</dd></dl>
 167 <ul>
 168 <li>-EINVAL is returned if <em>type</em> is incorrect.</li>
 169 </ul>
 170 <ul>
 171 <li>-ENOMEM is returned if not enough memory is available from the system heap to add the new hook.</li>
 172 </ul>
 173 <p>Environments:</p>
 174 <p>This service can be called from:</p>
 175 <ul>
 176 <li>Kernel module initialization/cleanup code</li>
 177 <li>Interrupt service routine</li>
 178 <li>Kernel-based task</li>
 179 </ul>
 180 <p>Rescheduling: never. </p>
 181
 182 <p>References <a class="el" href="group__pod.html#ga96e6b70fb05da3603bebacde76b16f22">xnpod_add_hook()</a>.</p>
 183
 184 </div>
 185 </div>
 186 <a class="anchor" id="gab6bd973c22a6f66e28653922c53e0385"></a><!-- doxytag: member="task.h::rt_task_bind" ref="gab6bd973c22a6f66e28653922c53e0385" args="(RT_TASK *task, const char *name, RTIME timeout)" -->
 187 <div class="memitem">
 188 <div class="memproto">
 189       <table class="memname">
 190         <tr>
 191           <td class="memname">int rt_task_bind </td>
 192           <td>(</td>
 193           <td class="paramtype">RT_TASK *&nbsp;</td>
 194           <td class="paramname"> <em>task</em>, </td>
 195         </tr>
 196         <tr>
 197           <td class="paramkey"></td>
 198           <td></td>
 199           <td class="paramtype">const char *&nbsp;</td>
 200           <td class="paramname"> <em>name</em>, </td>
 201         </tr>
 202         <tr>
 203           <td class="paramkey"></td>
 204           <td></td>
 205           <td class="paramtype">RTIME&nbsp;</td>
 206           <td class="paramname"> <em>timeout</em></td><td>&nbsp;</td>
 207         </tr>
 208         <tr>
 209           <td></td>
 210           <td>)</td>
 211           <td></td><td></td><td></td>
 212         </tr>
 213       </table>
 214 </div>
 215 <div class="memdoc">
 216
 217 <p>Bind to a real-time task. </p>
 218 <p>This user-space only service retrieves the uniform descriptor of a given Xenomai task identified by its symbolic name. If the task does not exist on entry, this service blocks the caller until a task of the given name is created.</p>
 219 <dl><dt><b>Parameters:</b></dt><dd>
 220   <table border="0" cellspacing="2" cellpadding="0">
 221     <tr><td valign="top"></td><td valign="top"><em>name</em>&nbsp;</td><td>A valid NULL-terminated name which identifies the task to bind to.</td></tr>
 222     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The address of a task descriptor retrieved by the operation. Contents of this memory is undefined upon failure.</td></tr>
 223     <tr><td valign="top"></td><td valign="top"><em>timeout</em>&nbsp;</td><td>The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.</td></tr>
 224   </table>
 225   </dd>
 226 </dl>
 227 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
 228 <ul>
 229 <li>-EFAULT is returned if <em>task</em> or <em>name</em> is referencing invalid memory.</li>
 230 </ul>
 231 <ul>
 232 <li>-EINTR is returned if <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> has been called for the waiting task before the retrieval has completed.</li>
 233 </ul>
 234 <ul>
 235 <li>-EWOULDBLOCK is returned if <em>timeout</em> is equal to TM_NONBLOCK and the searched object is not registered on entry.</li>
 236 </ul>
 237 <ul>
 238 <li>-ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.</li>
 239 </ul>
 240 <ul>
 241 <li>-EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime context).</li>
 242 </ul>
 243 <p>Environments:</p>
 244 <p>This service can be called from:</p>
 245 <ul>
 246 <li>User-space task (switches to primary mode)</li>
 247 </ul>
 248 <p>Rescheduling: always unless the request is immediately satisfied or <em>timeout</em> specifies a non-blocking operation.</p>
 249 <dl class="note"><dt><b>Note:</b></dt><dd>The <em>timeout</em> value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise. </dd></dl>
 250 <dl><dt><b>Examples: </b></dt><dd><a class="el" href="bound__task_8c-example.html#a0">bound_task.c</a>.</dd>
 251 </dl>
 252 </div>
 253 </div>
 254 <a class="anchor" id="ga8e17be7a49ac32bbeb3085b3cd1a9915"></a><!-- doxytag: member="task.c::rt_task_catch" ref="ga8e17be7a49ac32bbeb3085b3cd1a9915" args="(void(*handler)(rt_sigset_t))" -->
 255 <div class="memitem">
 256 <div class="memproto">
 257       <table class="memname">
 258         <tr>
 259           <td class="memname">int rt_task_catch </td>
 260           <td>(</td>
 261           <td class="paramtype">void(*)(rt_sigset_t)&nbsp;</td>
 262           <td class="paramname"> <em>handler</em></td>
 263           <td>&nbsp;)&nbsp;</td>
 264           <td></td>
 265         </tr>
 266       </table>
 267 </div>
 268 <div class="memdoc">
 269
 270 <p>Install a signal handler. </p>
 271 <p>This service installs a signal handler for the current task. Signals are discrete events tasks can receive each time they resume execution. When signals are pending upon resumption, <em>handler</em> is fired to process them. Signals can be sent using <a class="el" href="group__task.html#ga70e65c2efb499c48c6d15010a1c630a3" title="Send signals to a task.">rt_task_notify()</a>. A task can block the signal delivery by passing the T_NOSIG bit to <a class="el" href="group__task.html#ga915e7edfb0aaddb643794d7abc7093bf" title="Change task mode bits.">rt_task_set_mode()</a>.</p>
 272 <p>Calling this service implicitely unblocks the signal delivery for the caller.</p>
 273 <dl><dt><b>Parameters:</b></dt><dd>
 274   <table border="0" cellspacing="2" cellpadding="0">
 275     <tr><td valign="top"></td><td valign="top"><em>handler</em>&nbsp;</td><td>The address of the user-supplied routine to fire when signals are pending for the task. This handler is passed the set of pending signals as its first and only argument.</td></tr>
 276   </table>
 277   </dd>
 278 </dl>
 279 <dl class="return"><dt><b>Returns:</b></dt><dd>0 upon success, or:</dd></dl>
 280 <ul>
 281 <li>-EPERM is returned if this service was not called from a real-time task context.</li>
 282 </ul>
 283 <p>Environments:</p>
 284 <p>This service can be called from:</p>
 285 <ul>
 286 <li>Kernel-based task</li>
 287 </ul>
 288 <p>Rescheduling: possible. </p>
 289
 290 <p>References <a class="el" href="group__pod.html#gacf5b53f0405351327b89b0cc4976b962">xnpod_schedule()</a>.</p>
 291
 292 </div>
 293 </div>
 294 <a class="anchor" id="ga03387550693c21d0223f739570ccd992"></a><!-- doxytag: member="task.c::rt_task_create" ref="ga03387550693c21d0223f739570ccd992" args="(RT_TASK *task, const char *name, int stksize, int prio, int mode)" -->
 295 <div class="memitem">
 296 <div class="memproto">
 297       <table class="memname">
 298         <tr>
 299           <td class="memname">int rt_task_create </td>
 300           <td>(</td>
 301           <td class="paramtype">RT_TASK *&nbsp;</td>
 302           <td class="paramname"> <em>task</em>, </td>
 303         </tr>
 304         <tr>
 305           <td class="paramkey"></td>
 306           <td></td>
 307           <td class="paramtype">const char *&nbsp;</td>
 308           <td class="paramname"> <em>name</em>, </td>
 309         </tr>
 310         <tr>
 311           <td class="paramkey"></td>
 312           <td></td>
 313           <td class="paramtype">int&nbsp;</td>
 314           <td class="paramname"> <em>stksize</em>, </td>
 315         </tr>
 316         <tr>
 317           <td class="paramkey"></td>
 318           <td></td>
 319           <td class="paramtype">int&nbsp;</td>
 320           <td class="paramname"> <em>prio</em>, </td>
 321         </tr>
 322         <tr>
 323           <td class="paramkey"></td>
 324           <td></td>
 325           <td class="paramtype">int&nbsp;</td>
 326           <td class="paramname"> <em>mode</em></td><td>&nbsp;</td>
 327         </tr>
 328         <tr>
 329           <td></td>
 330           <td>)</td>
 331           <td></td><td></td><td></td>
 332         </tr>
 333       </table>
 334 </div>
 335 <div class="memdoc">
 336
 337 <p>Create a new real-time task. </p>
 338 <p>Creates a real-time task, either running in a kernel module or in user-space depending on the caller's context.</p>
 339 <dl><dt><b>Parameters:</b></dt><dd>
 340   <table border="0" cellspacing="2" cellpadding="0">
 341     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The address of a task descriptor Xenomai will use to store the task-related data. This descriptor must always be valid while the task is active therefore it must be allocated in permanent memory.</td></tr>
 342   </table>
 343   </dd>
 344 </dl>
 345 <p>The task is left in an innocuous state until it is actually started by <a class="el" href="group__task.html#gac9638918b8310a430088f5c9a04d2bb7" title="Start a real-time task.">rt_task_start()</a>.</p>
 346 <dl><dt><b>Parameters:</b></dt><dd>
 347   <table border="0" cellspacing="2" cellpadding="0">
 348     <tr><td valign="top"></td><td valign="top"><em>name</em>&nbsp;</td><td>An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created task.</td></tr>
 349     <tr><td valign="top"></td><td valign="top"><em>stksize</em>&nbsp;</td><td>The size of the stack (in bytes) for the new task. If zero is passed, a reasonable pre-defined size will be substituted.</td></tr>
 350     <tr><td valign="top"></td><td valign="top"><em>prio</em>&nbsp;</td><td>The base priority of the new task. This value must range from [0 .. 99] (inclusive) where 0 is the lowest effective priority.</td></tr>
 351     <tr><td valign="top"></td><td valign="top"><em>mode</em>&nbsp;</td><td>The task creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new task:</td></tr>
 352   </table>
 353   </dd>
 354 </dl>
 355 <ul>
 356 <li>T_FPU allows the task to use the FPU whenever available on the platform. This flag is forced for user-space tasks.</li>
 357 </ul>
 358 <ul>
 359 <li>T_SUSP causes the task to start in suspended mode. In such a case, the thread will have to be explicitly resumed using the <a class="el" href="group__task.html#ga1fab1aa24ef6f199546fd9669ae711be" title="Resume a real-time task.">rt_task_resume()</a> service for its execution to actually begin.</li>
 360 </ul>
 361 <ul>
 362 <li>T_CPU(cpuid) makes the new task affine to CPU # <b>cpuid</b>. CPU identifiers range from 0 to RTHAL_NR_CPUS - 1 (inclusive).</li>
 363 </ul>
 364 <ul>
 365 <li>T_JOINABLE (user-space only) allows another task to wait on the termination of the new task. This implies that <a class="el" href="group__task.html#ga8c77d57638578a126812e29429f61fe7" title="Wait on the termination of a real-time task.">rt_task_join()</a> is actually called for this task to clean up any user-space located resources after its termination.</li>
 366 </ul>
 367 <p>Passing T_FPU|T_CPU(1) in the <em>mode</em> parameter thus creates a task with FPU support enabled and which will be affine to CPU #1.</p>
 368 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
 369 <ul>
 370 <li>-ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to create or register the task.</li>
 371 </ul>
 372 <ul>
 373 <li>-EEXIST is returned if the <em>name</em> is already in use by some registered object.</li>
 374 </ul>
 375 <ul>
 376 <li>-EPERM is returned if this service was called from an asynchronous context.</li>
 377 </ul>
 378 <p>Environments:</p>
 379 <p>This service can be called from:</p>
 380 <ul>
 381 <li>Kernel module initialization/cleanup code</li>
 382 <li>Kernel-based task</li>
 383 <li>User-space task</li>
 384 </ul>
 385 <p>Rescheduling: possible.</p>
 386 <dl class="note"><dt><b>Note:</b></dt><dd></dd></dl>
 387 <p>When creating or shadowing a Xenomai thread for the first time in user-space, Xenomai installs a handler for the SIGWINCH signal. If you had installed a handler before that, it will be automatically called by Xenomai for SIGWINCH signals that it has not sent.</p>
 388 <p>If, however, you install a signal handler for SIGWINCH after creating or shadowing the first Xenomai thread, you have to explicitly call the function xeno_sigwinch_handler at the beginning of your signal handler, using its return to know if the signal was in fact an internal signal of Xenomai (in which case it returns 1), or if you should handle the signal (in which case it returns 0). xeno_sigwinch_handler prototype is:</p>
 389 <p><b>int xeno_sigwinch_handler(int sig, siginfo_t *si, void *ctxt);</b></p>
 390 <p>Which means that you should register your handler with sigaction, using the SA_SIGINFO flag, and pass all the arguments you received to xeno_sigwinch_handler. </p>
 391
 392 <p>References <a class="el" href="group__posix__threadattr.html#ga0b85ebb1e3aac081a4c0a5e85ae3cbe9">pthread_attr_init()</a>, <a class="el" href="group__posix__threadattr.html#gae6ee78c307d8467b34a9b0c330993a54">pthread_attr_setdetachstate()</a>, <a class="el" href="group__posix__threadattr.html#gad437fe8caa3ef9f0cb7d69f6f6479df9">pthread_attr_setinheritsched()</a>, <a class="el" href="group__posix__threadattr.html#ga7d0bf4f0734aca888f89f7341b1df222">pthread_attr_setschedparam()</a>, <a class="el" href="group__posix__threadattr.html#ga79b4c9e71486a87ef3014f1c660b33eb">pthread_attr_setschedpolicy()</a>, <a class="el" href="group__posix__threadattr.html#ga812a9a455ae2ef2bb0dca4fff201a281">pthread_attr_setstacksize()</a>, <a class="el" href="group__posix__thread.html#gaa79c99cc7b194918a2def257246f11c6">pthread_join()</a>, <a class="el" href="group__nucleus__state__flags.html#ga6b2ca9336a15f94f3a2e0665982ed081">XNFPU</a>, <a class="el" href="group__heap.html#gaaa8ae99881c9e6a4f8b56aa79f983bdb">xnheap_alloc()</a>, <a class="el" href="group__pod.html#gad2b761fb70cad30339f092edb4a89587">xnpod_delete_thread()</a>, <a class="el" href="group__pod.html#gad71ebccc5b7b3d367f65127a8849c036">xnpod_init_thread()</a>, <a class="el" href="group__nucleus__state__flags.html#gac664c3bae93da4141d2fc8e88a91afd8">XNSHADOW</a>, and <a class="el" href="group__synch.html#ga4c07b8ec87b14cf18ef512f0e0aade51">xnsynch_init()</a>.</p>
 393
 394 <p>Referenced by <a class="el" href="group__task.html#ga520e6fad1decc5beff58b394ff443265">rt_task_spawn()</a>.</p>
 395
 396 </div>
 397 </div>
 398 <a class="anchor" id="gab6e0d411830710e8cc82d77b9df19510"></a><!-- doxytag: member="task.c::rt_task_delete" ref="gab6e0d411830710e8cc82d77b9df19510" args="(RT_TASK *task)" -->
 399 <div class="memitem">
 400 <div class="memproto">
 401       <table class="memname">
 402         <tr>
 403           <td class="memname">int rt_task_delete </td>
 404           <td>(</td>
 405           <td class="paramtype">RT_TASK *&nbsp;</td>
 406           <td class="paramname"> <em>task</em></td>
 407           <td>&nbsp;)&nbsp;</td>
 408           <td></td>
 409         </tr>
 410       </table>
 411 </div>
 412 <div class="memdoc">
 413
 414 <p>Delete a real-time task. </p>
 415 <p>Terminate a task and release all the real-time kernel resources it currently holds. A task exists in the system since <a class="el" href="group__task.html#ga03387550693c21d0223f739570ccd992" title="Create a new real-time task.">rt_task_create()</a> has been called to create it, so this service must be called in order to destroy it afterwards.</p>
 416 <p>Native tasks implement a mechanism by which they are immune from deletion by other tasks while they run into a deemed safe section of code. This feature is used internally by the native skin in order to prevent tasks from being deleted in the middle of a critical section, without resorting to interrupt masking when the latter is not an option. For this reason, the caller of <a class="el" href="group__task.html#gab6e0d411830710e8cc82d77b9df19510" title="Delete a real-time task.">rt_task_delete()</a> might be blocked and a rescheduling take place, waiting for the target task to exit such critical section.</p>
 417 <p>The DELETE hooks are called on behalf of the calling context (if any). The information stored in the task control block remains valid until all hooks have been called.</p>
 418 <dl><dt><b>Parameters:</b></dt><dd>
 419   <table border="0" cellspacing="2" cellpadding="0">
 420     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task. If <em>task</em> is NULL, the current task is deleted.</td></tr>
 421   </table>
 422   </dd>
 423 </dl>
 424 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
 425 <ul>
 426 <li>-EINVAL is returned if <em>task</em> is not a task descriptor.</li>
 427 </ul>
 428 <ul>
 429 <li>-EPERM is returned if <em>task</em> is NULL but not called from a task context, or this service was called from an asynchronous context.</li>
 430 </ul>
 431 <ul>
 432 <li>-EINTR is returned if <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> has been invoked for the caller while it was waiting for <em>task</em> to exit a safe section. In such a case, the deletion process has been aborted and <em>task</em> remains unaffected.</li>
 433 </ul>
 434 <ul>
 435 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
 436 </ul>
 437 <p>Environments:</p>
 438 <p>This service can be called from:</p>
 439 <ul>
 440 <li>Kernel module initialization/cleanup code only if <em>task</em> is non-NULL.</li>
 441 </ul>
 442 <ul>
 443 <li>Kernel-based task</li>
 444 <li>Any user-space context (conforming call)</li>
 445 </ul>
 446 <p>Rescheduling: always if <em>task</em> is NULL, and possible if the deleted task is currently running into a safe section.</p>
 447 <dl class="note"><dt><b>Note:</b></dt><dd>A task that was successfully joined via <a class="el" href="group__task.html#ga8c77d57638578a126812e29429f61fe7" title="Wait on the termination of a real-time task.">rt_task_join()</a> must not be explicitly deleted afterwards. However, invoking <a class="el" href="group__task.html#ga8c77d57638578a126812e29429f61fe7" title="Wait on the termination of a real-time task.">rt_task_join()</a> remains mandatory for every joinable task even after calling <a class="el" href="group__task.html#gab6e0d411830710e8cc82d77b9df19510" title="Delete a real-time task.">rt_task_delete()</a>. </dd></dl>
 448
 449 <p>References <a class="el" href="group__posix__cancel.html#ga9e77a80c073787bf9a593e9c619dce27">pthread_cancel()</a>, <a class="el" href="group__posix__thread.html#ga090bdc13141e76205fab4cb3c5fab0e4">pthread_exit()</a>, <a class="el" href="group__task.html#gaaf5467af966c9980da9e489aeacf9aa3">rt_task_self()</a>, and <a class="el" href="group__pod.html#gad2b761fb70cad30339f092edb4a89587">xnpod_delete_thread()</a>.</p>
 450
 451 </div>
 452 </div>
 453 <a class="anchor" id="ga53bad6acf5496f8008e594954507dce8"></a><!-- doxytag: member="task.c::rt_task_inquire" ref="ga53bad6acf5496f8008e594954507dce8" args="(RT_TASK *task, RT_TASK_INFO *info)" -->
 454 <div class="memitem">
 455 <div class="memproto">
 456       <table class="memname">
 457         <tr>
 458           <td class="memname">int rt_task_inquire </td>
 459           <td>(</td>
 460           <td class="paramtype">RT_TASK *&nbsp;</td>
 461           <td class="paramname"> <em>task</em>, </td>
 462         </tr>
 463         <tr>
 464           <td class="paramkey"></td>
 465           <td></td>
 466           <td class="paramtype"><a class="el" href="structrt__task__info.html">RT_TASK_INFO</a> *&nbsp;</td>
 467           <td class="paramname"> <em>info</em></td><td>&nbsp;</td>
 468         </tr>
 469         <tr>
 470           <td></td>
 471           <td>)</td>
 472           <td></td><td></td><td></td>
 473         </tr>
 474       </table>
 475 </div>
 476 <div class="memdoc">
 477
 478 <p>Inquire about a real-time task. </p>
 479 <p>Return various information about the status of a given task.</p>
 480 <dl><dt><b>Parameters:</b></dt><dd>
 481   <table border="0" cellspacing="2" cellpadding="0">
 482     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the inquired task. If <em>task</em> is NULL, the current task is inquired.</td></tr>
 483     <tr><td valign="top"></td><td valign="top"><em>info</em>&nbsp;</td><td>The address of a structure the task information will be written to. Passing NULL is valid, in which case the system is only probed for existence of the specified task.</td></tr>
 484   </table>
 485   </dd>
 486 </dl>
 487 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned if the task exists, and status information is written to the structure pointed at by <em>info</em> if non-NULL. Otherwise:</dd></dl>
 488 <ul>
 489 <li>-EINVAL is returned if <em>task</em> is not a task descriptor.</li>
 490 </ul>
 491 <ul>
 492 <li>-EPERM is returned if <em>task</em> is NULL but not called from a task context.</li>
 493 </ul>
 494 <ul>
 495 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
 496 </ul>
 497 <p>Environments:</p>
 498 <p>This service can be called from:</p>
 499 <ul>
 500 <li>Kernel module initialization/cleanup code</li>
 501 <li>Interrupt service routine only if <em>task</em> is non-NULL.</li>
 502 </ul>
 503 <ul>
 504 <li>Kernel-based task</li>
 505 <li>User-space task</li>
 506 </ul>
 507 <p>Rescheduling: never. </p>
 508
 509 <p>References <a class="el" href="structrt__task__info.html#a75aa05f8471ed352adb2794dbafc0f45">rt_task_info::bprio</a>, <a class="el" href="structrt__task__info.html#a159bfc58b34dbbcaaf66611d57b63744">rt_task_info::cprio</a>, <a class="el" href="structrt__task__info.html#a8d72c536900a743d462c8566ec28cab8">rt_task_info::ctxswitches</a>, <a class="el" href="structrt__task__info.html#a8d0ffbec875bf6d244615fd13f38fa84">rt_task_info::exectime</a>, <a class="el" href="structrt__task__info.html#a382062c780d746bccb35f979f15930ae">rt_task_info::modeswitches</a>, <a class="el" href="structrt__task__info.html#abd05201330a19e4265ae93209e42409b">rt_task_info::name</a>, <a class="el" href="structrt__task__info.html#a3f9b8fd89cf5bea035e0e0157f1214c8">rt_task_info::pagefaults</a>, <a class="el" href="structrt__task__info.html#a92b8ccc740f106def2c64a7f994b6132">rt_task_info::relpoint</a>, <a class="el" href="structrt__task__info.html#ab69a77b449b4eb66ee402165c393d228">rt_task_info::status</a>, and <a class="el" href="group__timer.html#gae87b875cf9f6831afffcfee8dabd67a8">xntimer_get_date()</a>.</p>
 510
 511 </div>
 512 </div>
 513 <a class="anchor" id="ga8c77d57638578a126812e29429f61fe7"></a><!-- doxytag: member="task.h::rt_task_join" ref="ga8c77d57638578a126812e29429f61fe7" args="(RT_TASK *task)" -->
 514 <div class="memitem">
 515 <div class="memproto">
 516       <table class="memname">
 517         <tr>
 518           <td class="memname">int rt_task_join </td>
 519           <td>(</td>
 520           <td class="paramtype">RT_TASK *&nbsp;</td>
 521           <td class="paramname"> <em>task</em></td>
 522           <td>&nbsp;)&nbsp;</td>
 523           <td></td>
 524         </tr>
 525       </table>
 526 </div>
 527 <div class="memdoc">
 528
 529 <p>Wait on the termination of a real-time task. </p>
 530 <p>This user-space only service blocks the caller in non-real-time context until <em>task</em> has terminated. All real-time kernel resources are released after successful completion of this service. Note that the specified task must have been created by the same process that wants to join it, and the T_JOINABLE mode flag must have been set on creation.</p>
 531 <dl><dt><b>Parameters:</b></dt><dd>
 532   <table border="0" cellspacing="2" cellpadding="0">
 533     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The address of a task descriptor to join.</td></tr>
 534   </table>
 535   </dd>
 536 </dl>
 537 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
 538 <ul>
 539 <li>-EINVAL is returned if the task was not created with T_JOINABLE set or some other task is already waiting on the termination.</li>
 540 </ul>
 541 <ul>
 542 <li>-EDEADLK is returned if <em>task</em> refers to the caller.</li>
 543 </ul>
 544 <ul>
 545 <li>-ESRCH is returned if <em>task</em> no longer exists or refers to task created by a different process.</li>
 546 </ul>
 547 <p>This service can be called from:</p>
 548 <ul>
 549 <li>User-space task.</li>
 550 </ul>
 551 <p>Rescheduling: always unless the task was already terminated.</p>
 552 <dl class="note"><dt><b>Note:</b></dt><dd>After successful completion of this service it is neither required nor valid to additionally invoke <a class="el" href="group__task.html#gab6e0d411830710e8cc82d77b9df19510" title="Delete a real-time task.">rt_task_delete()</a> on the same task. </dd></dl>
 553
 554 <p>References <a class="el" href="group__posix__thread.html#gaa79c99cc7b194918a2def257246f11c6">pthread_join()</a>.</p>
 555
 556 </div>
 557 </div>
 558 <a class="anchor" id="ga70e65c2efb499c48c6d15010a1c630a3"></a><!-- doxytag: member="task.c::rt_task_notify" ref="ga70e65c2efb499c48c6d15010a1c630a3" args="(RT_TASK *task, rt_sigset_t signals)" -->
 559 <div class="memitem">
 560 <div class="memproto">
 561       <table class="memname">
 562         <tr>
 563           <td class="memname">int rt_task_notify </td>
 564           <td>(</td>
 565           <td class="paramtype">RT_TASK *&nbsp;</td>
 566           <td class="paramname"> <em>task</em>, </td>
 567         </tr>
 568         <tr>
 569           <td class="paramkey"></td>
 570           <td></td>
 571           <td class="paramtype">rt_sigset_t&nbsp;</td>
 572           <td class="paramname"> <em>signals</em></td><td>&nbsp;</td>
 573         </tr>
 574         <tr>
 575           <td></td>
 576           <td>)</td>
 577           <td></td><td></td><td></td>
 578         </tr>
 579       </table>
 580 </div>
 581 <div class="memdoc">
 582
 583 <p>Send signals to a task. </p>
 584 <p>This service sends a set of signals to a given task. A task can install a signal handler using the <a class="el" href="group__task.html#ga8e17be7a49ac32bbeb3085b3cd1a9915" title="Install a signal handler.">rt_task_catch()</a> service to process them.</p>
 585 <dl><dt><b>Parameters:</b></dt><dd>
 586   <table border="0" cellspacing="2" cellpadding="0">
 587     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task which must have been previously created by the <a class="el" href="group__task.html#ga03387550693c21d0223f739570ccd992" title="Create a new real-time task.">rt_task_create()</a> service.</td></tr>
 588     <tr><td valign="top"></td><td valign="top"><em>signals</em>&nbsp;</td><td>The set of signals to make pending for the task. This set is OR'ed with the current set of pending signals for the task; there is no count of occurence maintained for each available signal, which is either pending or cleared.</td></tr>
 589   </table>
 590   </dd>
 591 </dl>
 592 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
 593 <ul>
 594 <li>-EINVAL is returned if <em>task</em> is not a task descriptor.</li>
 595 </ul>
 596 <ul>
 597 <li>-EPERM is returned if <em>task</em> is NULL but not called from a real-time task context.</li>
 598 </ul>
 599 <ul>
 600 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
 601 </ul>
 602 <ul>
 603 <li>-ESRCH is returned if <em>task</em> has not set any signal handler.</li>
 604 </ul>
 605 <p>Environments:</p>
 606 <p>This service can be called from:</p>
 607 <ul>
 608 <li>Kernel module initialization/cleanup code</li>
 609 <li>Interrupt service routine only if <em>task</em> is non-NULL.</li>
 610 </ul>
 611 <ul>
 612 <li>Kernel-based task</li>
 613 <li>User-space task</li>
 614 </ul>
 615 <p>Rescheduling: possible. </p>
 616
 617 <p>References <a class="el" href="group__pod.html#gacf5b53f0405351327b89b0cc4976b962">xnpod_schedule()</a>.</p>
 618
 619 </div>
 620 </div>
 621 <a class="anchor" id="gaa152f8f41876fc3a828a8eba74d493fe"></a><!-- doxytag: member="task.c::rt_task_receive" ref="gaa152f8f41876fc3a828a8eba74d493fe" args="(RT_TASK_MCB *mcb_r, RTIME timeout)" -->
 622 <div class="memitem">
 623 <div class="memproto">
 624       <table class="memname">
 625         <tr>
 626           <td class="memname">int rt_task_receive </td>
 627           <td>(</td>
 628           <td class="paramtype"><a class="el" href="structrt__task__mcb.html">RT_TASK_MCB</a> *&nbsp;</td>
 629           <td class="paramname"> <em>mcb_r</em>, </td>
 630         </tr>
 631         <tr>
 632           <td class="paramkey"></td>
 633           <td></td>
 634           <td class="paramtype">RTIME&nbsp;</td>
 635           <td class="paramname"> <em>timeout</em></td><td>&nbsp;</td>
 636         </tr>
 637         <tr>
 638           <td></td>
 639           <td>)</td>
 640           <td></td><td></td><td></td>
 641         </tr>
 642       </table>
 643 </div>
 644 <div class="memdoc">
 645
 646 <p>Receive a message from a task. </p>
 647 <p>This service is part of the synchronous message passing support available to Xenomai tasks. It allows the caller to receive a variable-sized message sent from another task using the <a class="el" href="group__task.html#ga99a89c21c9866e2784860e100a444b49" title="Send a message to a task.">rt_task_send()</a> service. The sending task is blocked until the caller invokes <a class="el" href="group__task.html#gacd8a4fb2d11f0548bd053dfbf92f9e9d" title="Reply to a task.">rt_task_reply()</a> to finish the transaction.</p>
 648 <p>A basic message control block is used to store the location and size of the data area to receive from the client, in addition to a user-defined operation code.</p>
 649 <dl><dt><b>Parameters:</b></dt><dd>
 650   <table border="0" cellspacing="2" cellpadding="0">
 651     <tr><td valign="top"></td><td valign="top"><em>mcb_r</em>&nbsp;</td><td>The address of a message control block referring to the receive message area. The fields from this control block should be set as follows:</td></tr>
 652   </table>
 653   </dd>
 654 </dl>
 655 <ul>
 656 <li>mcb_r-&gt;data should contain the address of a buffer large enough to collect the data sent by the remote task;</li>
 657 </ul>
 658 <ul>
 659 <li>mcb_r-&gt;size should contain the size in bytes of the buffer space pointed at by mcb_r-&gt;data. If mcb_r-&gt;size is lower than the actual size of the received message, no data copy takes place and -ENOBUFS is returned to the caller. See note.</li>
 660 </ul>
 661 <p>Upon return, mcb_r-&gt;opcode will contain the operation code sent from the remote task using <a class="el" href="group__task.html#ga99a89c21c9866e2784860e100a444b49" title="Send a message to a task.">rt_task_send()</a>.</p>
 662 <dl><dt><b>Parameters:</b></dt><dd>
 663   <table border="0" cellspacing="2" cellpadding="0">
 664     <tr><td valign="top"></td><td valign="top"><em>timeout</em>&nbsp;</td><td>The number of clock ticks to wait for receiving a message (see note). Passing TM_INFINITE causes the caller to block indefinitely until a remote task eventually sends a message. Passing TM_NONBLOCK causes the service to return immediately without waiting if no remote task is currently waiting for sending a message.</td></tr>
 665   </table>
 666   </dd>
 667 </dl>
 668 <dl class="return"><dt><b>Returns:</b></dt><dd>A strictly positive value is returned upon success, representing a flow identifier for the opening transaction; this token should be passed to <a class="el" href="group__task.html#gacd8a4fb2d11f0548bd053dfbf92f9e9d" title="Reply to a task.">rt_task_reply()</a>, in order to send back a reply to and unblock the remote task appropriately. Otherwise:</dd></dl>
 669 <ul>
 670 <li>-ENOBUFS is returned if <em>mcb_r</em> does not point at a message area large enough to collect the remote task's message.</li>
 671 </ul>
 672 <ul>
 673 <li>-EWOULDBLOCK is returned if <em>timeout</em> is equal to TM_NONBLOCK and no remote task is currently waiting for sending a message to the caller.</li>
 674 </ul>
 675 <ul>
 676 <li>-ETIMEDOUT is returned if no message was received within the <em>timeout</em>.</li>
 677 </ul>
 678 <ul>
 679 <li>-EINTR is returned if <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> has been called for the caller before any message was available.</li>
 680 </ul>
 681 <ul>
 682 <li>-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).</li>
 683 </ul>
 684 <p>Environments:</p>
 685 <p>This service can be called from:</p>
 686 <ul>
 687 <li>Kernel-based task</li>
 688 <li>User-space task (switches to primary mode)</li>
 689 </ul>
 690 <p>Rescheduling: Always.</p>
 691 <dl class="note"><dt><b>Note:</b></dt><dd>The <em>timeout</em> value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.</dd>
 692 <dd>
 693 When called from a user-space task, this service may need to allocate some temporary buffer space from the system heap to hold the received data if the size of the latter exceeds a certain amount; the threshold before allocation is currently set to 64 bytes. </dd></dl>
 694
 695 <p>References <a class="el" href="structrt__task__mcb.html#a99ea768acdf624f0e902e7a5bf8f6c34">rt_task_mcb::data</a>, <a class="el" href="structrt__task__mcb.html#a031bcf333a820d4854fdbf19d0dd8ac3">rt_task_mcb::opcode</a>, <a class="el" href="structrt__task__mcb.html#adb07bafe0574adca45ef82f7c8d5a4d9">rt_task_mcb::size</a>, <a class="el" href="group__nucleus__info__flags.html#ga6aa575e1a99b9c931d3b1feb8bc7a36f">XNBREAK</a>, <a class="el" href="group__synch.html#ga2747e9834546af461f118e7c90c9613e">xnsynch_sleep_on()</a>, and <a class="el" href="group__nucleus__info__flags.html#gaa11d7fc754db50d3a1f1e41611d324e9">XNTIMEO</a>.</p>
 696
 697 </div>
 698 </div>
 699 <a class="anchor" id="ga585bcffb3757845534eed69edd1a27d2"></a><!-- doxytag: member="task.c::rt_task_remove_hook" ref="ga585bcffb3757845534eed69edd1a27d2" args="(int type, void(*routine)(void *cookie))" -->
 700 <div class="memitem">
 701 <div class="memproto">
 702       <table class="memname">
 703         <tr>
 704           <td class="memname">int rt_task_remove_hook </td>
 705           <td>(</td>
 706           <td class="paramtype">int&nbsp;</td>
 707           <td class="paramname"> <em>type</em>, </td>
 708         </tr>
 709         <tr>
 710           <td class="paramkey"></td>
 711           <td></td>
 712           <td class="paramtype">void(*)(void *cookie)&nbsp;</td>
 713           <td class="paramname"> <em>routine</em></td><td>&nbsp;</td>
 714         </tr>
 715         <tr>
 716           <td></td>
 717           <td>)</td>
 718           <td></td><td></td><td></td>
 719         </tr>
 720       </table>
 721 </div>
 722 <div class="memdoc">
 723
 724 <p>Remove a task hook. </p>
 725 <p>This service allows to remove a task hook previously registered using <a class="el" href="group__task.html#ga7452f367f9e17bf2fc0b70f717b96dd8" title="Install a task hook.">rt_task_add_hook()</a>.</p>
 726 <dl><dt><b>Parameters:</b></dt><dd>
 727   <table border="0" cellspacing="2" cellpadding="0">
 728     <tr><td valign="top"></td><td valign="top"><em>type</em>&nbsp;</td><td>Defines the kind of hook to uninstall. Possible values are:</td></tr>
 729   </table>
 730   </dd>
 731 </dl>
 732 <ul>
 733 <li>T_HOOK_START</li>
 734 <li>T_HOOK_DELETE</li>
 735 <li>T_HOOK_SWITCH</li>
 736 </ul>
 737 <dl><dt><b>Parameters:</b></dt><dd>
 738   <table border="0" cellspacing="2" cellpadding="0">
 739     <tr><td valign="top"></td><td valign="top"><em>routine</em>&nbsp;</td><td>The address of the user-supplied routine to remove from the hook list.</td></tr>
 740   </table>
 741   </dd>
 742 </dl>
 743 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise, one of the following error codes indicates the cause of the failure:</dd></dl>
 744 <ul>
 745 <li>-EINVAL is returned if <em>type</em> is incorrect.</li>
 746 </ul>
 747 <p>Environments:</p>
 748 <p>This service can be called from:</p>
 749 <ul>
 750 <li>Kernel module initialization/cleanup code</li>
 751 <li>Interrupt service routine</li>
 752 <li>Kernel-based task</li>
 753 </ul>
 754 <p>Rescheduling: never. </p>
 755
 756 <p>References <a class="el" href="group__pod.html#gace800481d23255eebe45f969e9434adf">xnpod_remove_hook()</a>.</p>
 757
 758 </div>
 759 </div>
 760 <a class="anchor" id="gacd8a4fb2d11f0548bd053dfbf92f9e9d"></a><!-- doxytag: member="task.c::rt_task_reply" ref="gacd8a4fb2d11f0548bd053dfbf92f9e9d" args="(int flowid, RT_TASK_MCB *mcb_s)" -->
 761 <div class="memitem">
 762 <div class="memproto">
 763       <table class="memname">
 764         <tr>
 765           <td class="memname">int rt_task_reply </td>
 766           <td>(</td>
 767           <td class="paramtype">int&nbsp;</td>
 768           <td class="paramname"> <em>flowid</em>, </td>
 769         </tr>
 770         <tr>
 771           <td class="paramkey"></td>
 772           <td></td>
 773           <td class="paramtype"><a class="el" href="structrt__task__mcb.html">RT_TASK_MCB</a> *&nbsp;</td>
 774           <td class="paramname"> <em>mcb_s</em></td><td>&nbsp;</td>
 775         </tr>
 776         <tr>
 777           <td></td>
 778           <td>)</td>
 779           <td></td><td></td><td></td>
 780         </tr>
 781       </table>
 782 </div>
 783 <div class="memdoc">
 784
 785 <p>Reply to a task. </p>
 786 <p>This service is part of the synchronous message passing support available to Xenomai tasks. It allows the caller to send back a variable-sized message to the client task, once the initial message from this task has been pulled using <a class="el" href="group__task.html#gaa152f8f41876fc3a828a8eba74d493fe" title="Receive a message from a task.">rt_task_receive()</a> and processed. As a consequence of this call, the remote task will be unblocked from the <a class="el" href="group__task.html#ga99a89c21c9866e2784860e100a444b49" title="Send a message to a task.">rt_task_send()</a> service.</p>
 787 <p>A basic message control block is used to store the location and size of the data area to send back, in addition to a user-defined status code.</p>
 788 <dl><dt><b>Parameters:</b></dt><dd>
 789   <table border="0" cellspacing="2" cellpadding="0">
 790     <tr><td valign="top"></td><td valign="top"><em>flowid</em>&nbsp;</td><td>The flow identifier returned by a previous call to <a class="el" href="group__task.html#gaa152f8f41876fc3a828a8eba74d493fe" title="Receive a message from a task.">rt_task_receive()</a> which uniquely identifies the current transaction.</td></tr>
 791     <tr><td valign="top"></td><td valign="top"><em>mcb_s</em>&nbsp;</td><td>The address of an optional message control block referring to the message to be sent back. If <em>mcb_s</em> is NULL, the client will be unblocked without getting any reply data. When <em>mcb_s</em> is valid, the fields from this control block should be set as follows:</td></tr>
 792   </table>
 793   </dd>
 794 </dl>
 795 <ul>
 796 <li>mcb_s-&gt;data should contain the address of the payload data to send to the remote task.</li>
 797 </ul>
 798 <ul>
 799 <li>mcb_s-&gt;size should contain the size in bytes of the payload data pointed at by mcb_s-&gt;data. 0 is a legitimate value, and indicates that no payload data will be transferred. In the latter case, mcb_s-&gt;data will be ignored. See note.</li>
 800 </ul>
 801 <ul>
 802 <li>mcb_s-&gt;opcode is an opaque status code carried during the message transfer the caller can fill with any appropriate value. It will be made available "as is" to the remote task into the status code field by the <a class="el" href="group__task.html#ga99a89c21c9866e2784860e100a444b49" title="Send a message to a task.">rt_task_send()</a> service. If <em>mcb_s</em> is NULL, 0 will be returned to the client into the status code field.</li>
 803 </ul>
 804 <dl class="return"><dt><b>Returns:</b></dt><dd>Zero is returned upon success. Otherwise:</dd></dl>
 805 <ul>
 806 <li>-EINVAL is returned if <em>flowid</em> is invalid.</li>
 807 </ul>
 808 <ul>
 809 <li>-ENXIO is returned if <em>flowid</em> does not match the expected identifier returned from the latest call of the current task to <a class="el" href="group__task.html#gaa152f8f41876fc3a828a8eba74d493fe" title="Receive a message from a task.">rt_task_receive()</a>, or if the remote task stopped waiting for the reply in the meantime (e.g. the client could have been deleted or forcibly unblocked).</li>
 810 </ul>
 811 <ul>
 812 <li>-EPERM is returned if this service was called from an invalid context (e.g. interrupt, or non-primary).</li>
 813 </ul>
 814 <p>Environments:</p>
 815 <p>This service can be called from:</p>
 816 <ul>
 817 <li>Kernel-based task</li>
 818 <li>User-space task (switches to primary mode)</li>
 819 </ul>
 820 <p>Rescheduling: Always.</p>
 821 <dl class="note"><dt><b>Note:</b></dt><dd>When called from a user-space task, this service may need to allocate some temporary buffer space from the system heap to hold the reply data if the size of the latter exceeds a certain amount; the threshold before allocation is currently set to 64 bytes. </dd></dl>
 822
 823 <p>References <a class="el" href="structrt__task__mcb.html#a99ea768acdf624f0e902e7a5bf8f6c34">rt_task_mcb::data</a>, <a class="el" href="structrt__task__mcb.html#a031bcf333a820d4854fdbf19d0dd8ac3">rt_task_mcb::opcode</a>, <a class="el" href="structrt__task__mcb.html#adb07bafe0574adca45ef82f7c8d5a4d9">rt_task_mcb::size</a>, <a class="el" href="group__pod.html#gacf5b53f0405351327b89b0cc4976b962">xnpod_schedule()</a>, and <a class="el" href="group__pod.html#gae5f0d19e7a499b9b262f68a43ab545dd">xnpod_unblock_thread()</a>.</p>
 824
 825 </div>
 826 </div>
 827 <a class="anchor" id="ga1fab1aa24ef6f199546fd9669ae711be"></a><!-- doxytag: member="task.c::rt_task_resume" ref="ga1fab1aa24ef6f199546fd9669ae711be" args="(RT_TASK *task)" -->
 828 <div class="memitem">
 829 <div class="memproto">
 830       <table class="memname">
 831         <tr>
 832           <td class="memname">int rt_task_resume </td>
 833           <td>(</td>
 834           <td class="paramtype">RT_TASK *&nbsp;</td>
 835           <td class="paramname"> <em>task</em></td>
 836           <td>&nbsp;)&nbsp;</td>
 837           <td></td>
 838         </tr>
 839       </table>
 840 </div>
 841 <div class="memdoc">
 842
 843 <p>Resume a real-time task. </p>
 844 <p>Forcibly resume the execution of a task which has been previously suspended by a call to <a class="el" href="group__task.html#ga926a4b10e3631f76c5f38910e6eea24c" title="Suspend a real-time task.">rt_task_suspend()</a>.</p>
 845 <p>The suspension nesting count is decremented so that <a class="el" href="group__task.html#ga1fab1aa24ef6f199546fd9669ae711be" title="Resume a real-time task.">rt_task_resume()</a> will only resume the task if this count falls down to zero as a result of the current invocation.</p>
 846 <dl><dt><b>Parameters:</b></dt><dd>
 847   <table border="0" cellspacing="2" cellpadding="0">
 848     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task.</td></tr>
 849   </table>
 850   </dd>
 851 </dl>
 852 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
 853 <ul>
 854 <li>-EINVAL is returned if <em>task</em> is not a task descriptor.</li>
 855 </ul>
 856 <ul>
 857 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
 858 </ul>
 859 <p>Environments:</p>
 860 <p>This service can be called from:</p>
 861 <ul>
 862 <li>Kernel module initialization/cleanup code</li>
 863 <li>Interrupt service routine</li>
 864 <li>Kernel-based task</li>
 865 <li>User-space task</li>
 866 </ul>
 867 <p>Rescheduling: possible if the suspension nesting level falls down to zero as a result of the current invocation. </p>
 868
 869 <p>References <a class="el" href="group__pod.html#gac3a7bf9e973782a8cfd6495a1786e812">xnpod_resume_thread()</a>, <a class="el" href="group__pod.html#gacf5b53f0405351327b89b0cc4976b962">xnpod_schedule()</a>, and <a class="el" href="group__nucleus__state__flags.html#ga6b605ad2bb16ae2386821be8ce8d341b">XNSUSP</a>.</p>
 870
 871 </div>
 872 </div>
 873 <a class="anchor" id="gaf6e313941a3fea606be8d0f66380e922"></a><!-- doxytag: member="task.h::rt_task_same" ref="gaf6e313941a3fea606be8d0f66380e922" args="(RT_TASK *task1, RT_TASK *task2)" -->
 874 <div class="memitem">
 875 <div class="memproto">
 876       <table class="memname">
 877         <tr>
 878           <td class="memname">int rt_task_same </td>
 879           <td>(</td>
 880           <td class="paramtype">RT_TASK *&nbsp;</td>
 881           <td class="paramname"> <em>task1</em>, </td>
 882         </tr>
 883         <tr>
 884           <td class="paramkey"></td>
 885           <td></td>
 886           <td class="paramtype">RT_TASK *&nbsp;</td>
 887           <td class="paramname"> <em>task2</em></td><td>&nbsp;</td>
 888         </tr>
 889         <tr>
 890           <td></td>
 891           <td>)</td>
 892           <td></td><td></td><td></td>
 893         </tr>
 894       </table>
 895 </div>
 896 <div class="memdoc">
 897
 898 <p>Compare two task descriptors. </p>
 899 <p>This service checks whether two task descriptors refer to the same task. This service is particularly useful in user-space, since <a class="el" href="group__task.html#gaaf5467af966c9980da9e489aeacf9aa3" title="Retrieve the current task.">rt_task_self()</a> does return a task descriptor which is different from the original descriptor used by the application, but still refers to the same task internally.</p>
 900 <dl><dt><b>Parameters:</b></dt><dd>
 901   <table border="0" cellspacing="2" cellpadding="0">
 902     <tr><td valign="top"></td><td valign="top"><em>task1</em>&nbsp;</td><td>The address of the first task descriptor to compare. </td></tr>
 903     <tr><td valign="top"></td><td valign="top"><em>task2</em>&nbsp;</td><td>The address of the second task descriptor to compare.</td></tr>
 904   </table>
 905   </dd>
 906 </dl>
 907 <dl class="return"><dt><b>Returns:</b></dt><dd>non-zero whenever the two task descriptors refer to the same task, zero otherwise.</dd></dl>
 908 <p>This service can be called from:</p>
 909 <ul>
 910 <li>Kernel-based task.</li>
 911 <li>User-space task.</li>
 912 </ul>
 913 <p>Rescheduling: never. </p>
 914
 915 </div>
 916 </div>
 917 <a class="anchor" id="gaaf5467af966c9980da9e489aeacf9aa3"></a><!-- doxytag: member="task.c::rt_task_self" ref="gaaf5467af966c9980da9e489aeacf9aa3" args="(void)" -->
 918 <div class="memitem">
 919 <div class="memproto">
 920       <table class="memname">
 921         <tr>
 922           <td class="memname">RT_TASK* rt_task_self </td>
 923           <td>(</td>
 924           <td class="paramtype">void&nbsp;</td>
 925           <td class="paramname"></td>
 926           <td>&nbsp;)&nbsp;</td>
 927           <td></td>
 928         </tr>
 929       </table>
 930 </div>
 931 <div class="memdoc">
 932
 933 <p>Retrieve the current task. </p>
 934 <p>Return the current task descriptor address.</p>
 935 <dl class="return"><dt><b>Returns:</b></dt><dd>The address of the caller's task descriptor is returned upon success, or NULL if the calling context is asynchronous (i.e. not a Xenomai task).</dd></dl>
 936 <p>Environments:</p>
 937 <p>This service can be called from:</p>
 938 <ul>
 939 <li>Kernel module initialization/cleanup code</li>
 940 <li>Interrupt service routine Those will cause a NULL return.</li>
 941 </ul>
 942 <ul>
 943 <li>Kernel-based task</li>
 944 <li>User-space task</li>
 945 </ul>
 946 <p>Rescheduling: never. </p>
 947
 948 <p>References <a class="el" href="group__posix__tsd.html#ga31469375891078185bda93f0e4411a2c">pthread_getspecific()</a>.</p>
 949
 950 <p>Referenced by <a class="el" href="group__task.html#gab6e0d411830710e8cc82d77b9df19510">rt_task_delete()</a>.</p>
 951
 952 </div>
 953 </div>
 954 <a class="anchor" id="ga99a89c21c9866e2784860e100a444b49"></a><!-- doxytag: member="task.c::rt_task_send" ref="ga99a89c21c9866e2784860e100a444b49" args="(RT_TASK *task, RT_TASK_MCB *mcb_s, RT_TASK_MCB *mcb_r, RTIME timeout)" -->
 955 <div class="memitem">
 956 <div class="memproto">
 957       <table class="memname">
 958         <tr>
 959           <td class="memname">ssize_t rt_task_send </td>
 960           <td>(</td>
 961           <td class="paramtype">RT_TASK *&nbsp;</td>
 962           <td class="paramname"> <em>task</em>, </td>
 963         </tr>
 964         <tr>
 965           <td class="paramkey"></td>
 966           <td></td>
 967           <td class="paramtype"><a class="el" href="structrt__task__mcb.html">RT_TASK_MCB</a> *&nbsp;</td>
 968           <td class="paramname"> <em>mcb_s</em>, </td>
 969         </tr>
 970         <tr>
 971           <td class="paramkey"></td>
 972           <td></td>
 973           <td class="paramtype"><a class="el" href="structrt__task__mcb.html">RT_TASK_MCB</a> *&nbsp;</td>
 974           <td class="paramname"> <em>mcb_r</em>, </td>
 975         </tr>
 976         <tr>
 977           <td class="paramkey"></td>
 978           <td></td>
 979           <td class="paramtype">RTIME&nbsp;</td>
 980           <td class="paramname"> <em>timeout</em></td><td>&nbsp;</td>
 981         </tr>
 982         <tr>
 983           <td></td>
 984           <td>)</td>
 985           <td></td><td></td><td></td>
 986         </tr>
 987       </table>
 988 </div>
 989 <div class="memdoc">
 990
 991 <p>Send a message to a task. </p>
 992 <p>This service is part of the synchronous message passing support available to Xenomai tasks. It allows the caller to send a variable-sized message to another task, waiting for the remote to receive the initial message by a call to <a class="el" href="group__task.html#gaa152f8f41876fc3a828a8eba74d493fe" title="Receive a message from a task.">rt_task_receive()</a>, then reply to it using <a class="el" href="group__task.html#gacd8a4fb2d11f0548bd053dfbf92f9e9d" title="Reply to a task.">rt_task_reply()</a>.</p>
 993 <p>A basic message control block is used to store the location and size of the data area to send or retrieve upon reply, in addition to a user-defined operation code.</p>
 994 <dl><dt><b>Parameters:</b></dt><dd>
 995   <table border="0" cellspacing="2" cellpadding="0">
 996     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the recipient task.</td></tr>
 997     <tr><td valign="top"></td><td valign="top"><em>mcb_s</em>&nbsp;</td><td>The address of the message control block referring to the message to be sent. The fields from this control block should be set as follows:</td></tr>
 998   </table>
 999   </dd>
1000 </dl>
1001 <ul>
1002 <li>mcb_s-&gt;data should contain the address of the payload data to send to the remote task.</li>
1003 </ul>
1004 <ul>
1005 <li>mcb_s-&gt;size should contain the size in bytes of the payload data pointed at by mcb_s-&gt;data. 0 is a legitimate value, and indicates that no payload data will be transferred. In the latter case, mcb_s-&gt;data will be ignored. See note.</li>
1006 </ul>
1007 <ul>
1008 <li>mcb_s-&gt;opcode is an opaque operation code carried during the message transfer the caller can fill with any appropriate value. It will be made available "as is" to the remote task into the operation code field by the <a class="el" href="group__task.html#gaa152f8f41876fc3a828a8eba74d493fe" title="Receive a message from a task.">rt_task_receive()</a> service.</li>
1009 </ul>
1010 <dl><dt><b>Parameters:</b></dt><dd>
1011   <table border="0" cellspacing="2" cellpadding="0">
1012     <tr><td valign="top"></td><td valign="top"><em>mcb_r</em>&nbsp;</td><td>The address of an optional message control block referring to the reply message area. If <em>mcb_r</em> is NULL and a reply is sent back by the remote task, the reply message will be discarded, and -ENOBUFS will be returned to the caller. When <em>mcb_r</em> is valid, the fields from this control block should be set as follows:</td></tr>
1013   </table>
1014   </dd>
1015 </dl>
1016 <ul>
1017 <li>mcb_r-&gt;data should contain the address of a buffer large enough to collect the reply data from the remote task.</li>
1018 </ul>
1019 <ul>
1020 <li>mcb_r-&gt;size should contain the size in bytes of the buffer space pointed at by mcb_r-&gt;data. If mcb_r-&gt;size is lower than the actual size of the reply message, no data copy takes place and -ENOBUFS is returned to the caller. See note.</li>
1021 </ul>
1022 <p>Upon return, mcb_r-&gt;opcode will contain the status code sent back from the remote task using <a class="el" href="group__task.html#gacd8a4fb2d11f0548bd053dfbf92f9e9d" title="Reply to a task.">rt_task_reply()</a>, or 0 if unspecified.</p>
1023 <dl><dt><b>Parameters:</b></dt><dd>
1024   <table border="0" cellspacing="2" cellpadding="0">
1025     <tr><td valign="top"></td><td valign="top"><em>timeout</em>&nbsp;</td><td>The number of clock ticks to wait for the remote task to reply to the initial message (see note). Passing TM_INFINITE causes the caller to block indefinitely until the remote task eventually replies. Passing TM_NONBLOCK causes the service to return immediately without waiting if the remote task is not waiting for messages (i.e. if <em>task</em> is not currently blocked on the <a class="el" href="group__task.html#gaa152f8f41876fc3a828a8eba74d493fe" title="Receive a message from a task.">rt_task_receive()</a> service); however, the caller will wait indefinitely for a reply from that remote task if present.</td></tr>
1026   </table>
1027   </dd>
1028 </dl>
1029 <dl class="return"><dt><b>Returns:</b></dt><dd>A positive value is returned upon success, representing the length (in bytes) of the reply message returned by the remote task. 0 is a success status, meaning either that <em>mcb_r</em> was NULL on entry, or that no actual message was passed to the remote call to <a class="el" href="group__task.html#gacd8a4fb2d11f0548bd053dfbf92f9e9d" title="Reply to a task.">rt_task_reply()</a>. Otherwise:</dd></dl>
1030 <ul>
1031 <li>-ENOBUFS is returned if <em>mcb_r</em> does not point at a message area large enough to collect the remote task's reply. This includes the case where <em>mcb_r</em> is NULL on entry albeit the remote task attempts to send a reply message.</li>
1032 </ul>
1033 <ul>
1034 <li>-EWOULDBLOCK is returned if <em>timeout</em> is equal to TM_NONBLOCK and <em>task</em> is not currently blocked on the <a class="el" href="group__task.html#gaa152f8f41876fc3a828a8eba74d493fe" title="Receive a message from a task.">rt_task_receive()</a> service.</li>
1035 </ul>
1036 <ul>
1037 <li>-EIDRM is returned if <em>task</em> has been deleted while waiting for a reply.</li>
1038 </ul>
1039 <ul>
1040 <li>-EINTR is returned if <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> has been called for the caller before any reply was available.</li>
1041 </ul>
1042 <ul>
1043 <li>-EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime context).</li>
1044 </ul>
1045 <ul>
1046 <li>-ESRCH is returned if <em>task</em> cannot be found (when called from user-space only).</li>
1047 </ul>
1048 <p>Environments:</p>
1049 <p>This service can be called from:</p>
1050 <ul>
1051 <li>Kernel-based task</li>
1052 <li>User-space task (switches to primary mode)</li>
1053 </ul>
1054 <p>Rescheduling: Always.</p>
1055 <dl class="note"><dt><b>Note:</b></dt><dd>The <em>timeout</em> value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.</dd>
1056 <dd>
1057 When called from a user-space task, this service may need to allocate some temporary buffer space from the system heap to hold both the sent and the reply data if this cumulated size exceeds a certain amount; the threshold before allocation is currently set to 64 bytes. </dd></dl>
1058
1059 <p>References <a class="el" href="structrt__task__mcb.html#a99ea768acdf624f0e902e7a5bf8f6c34">rt_task_mcb::data</a>, <a class="el" href="structrt__task__mcb.html#ac3568d32f8391fbc6969ab9338bbb707">rt_task_mcb::flowid</a>, <a class="el" href="structrt__task__mcb.html#a031bcf333a820d4854fdbf19d0dd8ac3">rt_task_mcb::opcode</a>, <a class="el" href="group__posix__cancel.html#ga636480bad96654729ecf18017c2820cd">pthread_setcanceltype()</a>, <a class="el" href="structrt__task__mcb.html#adb07bafe0574adca45ef82f7c8d5a4d9">rt_task_mcb::size</a>, <a class="el" href="group__nucleus__info__flags.html#ga6aa575e1a99b9c931d3b1feb8bc7a36f">XNBREAK</a>, <a class="el" href="group__nucleus__info__flags.html#gab07d9dea73645dbba353dc2452c15b40">XNRMID</a>, <a class="el" href="group__synch.html#ga6d4ad886901c751a4f3c51b90fc8f91f">xnsynch_acquire()</a>, <a class="el" href="group__synch.html#ga82beb68147bc5f0306ab02a61a9dc76b">xnsynch_flush()</a>, and <a class="el" href="group__nucleus__info__flags.html#gaa11d7fc754db50d3a1f1e41611d324e9">XNTIMEO</a>.</p>
1060
1061 </div>
1062 </div>
1063 <a class="anchor" id="ga915e7edfb0aaddb643794d7abc7093bf"></a><!-- doxytag: member="task.c::rt_task_set_mode" ref="ga915e7edfb0aaddb643794d7abc7093bf" args="(int clrmask, int setmask, int *mode_r)" -->
1064 <div class="memitem">
1065 <div class="memproto">
1066       <table class="memname">
1067         <tr>
1068           <td class="memname">int rt_task_set_mode </td>
1069           <td>(</td>
1070           <td class="paramtype">int&nbsp;</td>
1071           <td class="paramname"> <em>clrmask</em>, </td>
1072         </tr>
1073         <tr>
1074           <td class="paramkey"></td>
1075           <td></td>
1076           <td class="paramtype">int&nbsp;</td>
1077           <td class="paramname"> <em>setmask</em>, </td>
1078         </tr>
1079         <tr>
1080           <td class="paramkey"></td>
1081           <td></td>
1082           <td class="paramtype">int *&nbsp;</td>
1083           <td class="paramname"> <em>mode_r</em></td><td>&nbsp;</td>
1084         </tr>
1085         <tr>
1086           <td></td>
1087           <td>)</td>
1088           <td></td><td></td><td></td>
1089         </tr>
1090       </table>
1091 </div>
1092 <div class="memdoc">
1093
1094 <p>Change task mode bits. </p>
1095 <p>Each Xenomai task has a set of internal bits determining various operating conditions; the <a class="el" href="group__task.html#ga915e7edfb0aaddb643794d7abc7093bf" title="Change task mode bits.">rt_task_set_mode()</a> service allows to alter three of them, respectively controlling:</p>
1096 <ul>
1097 <li>whether the task locks the rescheduling procedure,</li>
1098 <li>whether the task undergoes a round-robin scheduling,</li>
1099 <li>whether the task blocks the delivery of signals.</li>
1100 </ul>
1101 <p>To this end, <a class="el" href="group__task.html#ga915e7edfb0aaddb643794d7abc7093bf" title="Change task mode bits.">rt_task_set_mode()</a> takes a bitmask of mode bits to clear for disabling the corresponding modes, and another one to set for enabling them. The mode bits which were previously in effect can be returned upon request.</p>
1102 <p>The following bits can be part of the bitmask:</p>
1103 <ul>
1104 <li>T_LOCK causes the current task to lock the scheduler. Clearing this bit unlocks the scheduler.</li>
1105 </ul>
1106 <ul>
1107 <li>T_NOSIG disables the asynchronous signal delivery for the current task.</li>
1108 </ul>
1109 <ul>
1110 <li>When set, T_WARNSW causes the SIGXCPU signal to be sent to the current user-space task whenever it switches to the secondary mode. This feature is useful to detect unwanted migrations to the Linux domain.</li>
1111 </ul>
1112 <ul>
1113 <li>T_RPIOFF disables thread priority coupling between Xenomai and Linux schedulers. This bit prevents the root Linux thread from inheriting the priority of the running shadow Xenomai thread. Use CONFIG_XENO_OPT_RPIOFF to globally disable priority coupling.</li>
1114 </ul>
1115 <ul>
1116 <li>T_CONFORMING can be passed in <em>setmask</em> to switch the current user-space task to its preferred runtime mode. The only meaningful use of this switch is to force a real-time shadow back to primary mode. Any other use either cause to a nop, or an error.</li>
1117 </ul>
1118 <p>Normally, this service can only be called on behalf of a regular real-time task, either running in kernel or user-space. However, as a special exception, requests for setting/clearing the T_LOCK bit from asynchronous contexts are silently dropped, and the call returns successfully if no other mode bits have been specified. This is consistent with the fact that Xenomai enforces a scheduler lock until the outer interrupt handler has returned.</p>
1119 <dl><dt><b>Parameters:</b></dt><dd>
1120   <table border="0" cellspacing="2" cellpadding="0">
1121     <tr><td valign="top"></td><td valign="top"><em>clrmask</em>&nbsp;</td><td>A bitmask of mode bits to clear for the current task, before <em>setmask</em> is applied. 0 is an acceptable value which leads to a no-op.</td></tr>
1122     <tr><td valign="top"></td><td valign="top"><em>setmask</em>&nbsp;</td><td>A bitmask of mode bits to set for the current task. 0 is an acceptable value which leads to a no-op.</td></tr>
1123     <tr><td valign="top"></td><td valign="top"><em>mode_r</em>&nbsp;</td><td>If non-NULL, <em>mode_r</em> must be a pointer to a memory location which will be written upon success with the previous set of active mode bits. If NULL, the previous set of active mode bits will not be returned.</td></tr>
1124   </table>
1125   </dd>
1126 </dl>
1127 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success, or:</dd></dl>
1128 <ul>
1129 <li>-EINVAL if either <em>setmask</em> or <em>clrmask</em> specifies invalid bits. T_CONFORMING is always invalid in <em>clrmask</em>, or when applied in <em>setmask</em> to kernel-based tasks.</li>
1130 </ul>
1131 <ul>
1132 <li>-EPERM is returned if this service was not called from a real-time task context.</li>
1133 </ul>
1134 <p>Environments:</p>
1135 <p>This service can be called from:</p>
1136 <ul>
1137 <li>Kernel-based task</li>
1138 <li>User-space task</li>
1139 </ul>
1140 <p>Rescheduling: possible, if T_LOCK has been passed into <em>clrmask</em> and the calling context is a task. </p>
1141
1142 <p>References <a class="el" href="group__native__task__status.html#ga2ac6cf9677bae1012ecbcb6037d14fcb">T_LOCK</a>, <a class="el" href="group__native__task__status.html#ga7eece760fbef63995ee0db3a8d442448">T_NOSIG</a>, <a class="el" href="group__native__task__status.html#gab816682b06a99061431f597b7f9ae1e9">T_RPIOFF</a>, <a class="el" href="group__native__task__status.html#ga725324cb26d8b5835c0818acb738bfe6">T_WARNSW</a>, <a class="el" href="group__pod.html#gacf5b53f0405351327b89b0cc4976b962">xnpod_schedule()</a>, and <a class="el" href="group__pod.html#ga629c06b152dabfdb679b6e49bd9f7734">xnpod_set_thread_mode()</a>.</p>
1143
1144 </div>
1145 </div>
1146 <a class="anchor" id="gababee94264156693cd4f5b9b70d3c5a1"></a><!-- doxytag: member="task.c::rt_task_set_periodic" ref="gababee94264156693cd4f5b9b70d3c5a1" args="(RT_TASK *task, RTIME idate, RTIME period)" -->
1147 <div class="memitem">
1148 <div class="memproto">
1149       <table class="memname">
1150         <tr>
1151           <td class="memname">int rt_task_set_periodic </td>
1152           <td>(</td>
1153           <td class="paramtype">RT_TASK *&nbsp;</td>
1154           <td class="paramname"> <em>task</em>, </td>
1155         </tr>
1156         <tr>
1157           <td class="paramkey"></td>
1158           <td></td>
1159           <td class="paramtype">RTIME&nbsp;</td>
1160           <td class="paramname"> <em>idate</em>, </td>
1161         </tr>
1162         <tr>
1163           <td class="paramkey"></td>
1164           <td></td>
1165           <td class="paramtype">RTIME&nbsp;</td>
1166           <td class="paramname"> <em>period</em></td><td>&nbsp;</td>
1167         </tr>
1168         <tr>
1169           <td></td>
1170           <td>)</td>
1171           <td></td><td></td><td></td>
1172         </tr>
1173       </table>
1174 </div>
1175 <div class="memdoc">
1176
1177 <p>Make a real-time task periodic. </p>
1178 <p>Make a task periodic by programing its first release point and its period in the processor time line. Subsequent calls to <a class="el" href="group__task.html#ga1645d3a072ef3cefeed3bcbb27dcf108" title="Wait for the next periodic release point.">rt_task_wait_period()</a> will delay the task until the next periodic release point in the processor timeline is reached.</p>
1179 <dl><dt><b>Parameters:</b></dt><dd>
1180   <table border="0" cellspacing="2" cellpadding="0">
1181     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task. This task is immediately delayed until the first periodic release point is reached. If <em>task</em> is NULL, the current task is set periodic.</td></tr>
1182     <tr><td valign="top"></td><td valign="top"><em>idate</em>&nbsp;</td><td>The initial (absolute) date of the first release point, expressed in clock ticks (see note). The affected task will be delayed until this point is reached. If <em>idate</em> is equal to TM_NOW, the current system date is used, and no initial delay takes place.</td></tr>
1183     <tr><td valign="top"></td><td valign="top"><em>period</em>&nbsp;</td><td>The period of the task, expressed in clock ticks (see note). Passing TM_INFINITE attempts to stop the task's periodic timer; in the latter case, the routine always exits succesfully, regardless of the previous state of this timer.</td></tr>
1184   </table>
1185   </dd>
1186 </dl>
1187 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1188 <ul>
1189 <li>-EINVAL is returned if <em>task</em> is not a task descriptor, or <em>period</em> is different from TM_INFINITE but shorter than the scheduling latency value for the target system, as available from /proc/xenomai/latency.</li>
1190 </ul>
1191 <ul>
1192 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
1193 </ul>
1194 <ul>
1195 <li>-ETIMEDOUT is returned if <em>idate</em> is different from TM_INFINITE and represents a date in the past.</li>
1196 </ul>
1197 <ul>
1198 <li>-EWOULDBLOCK is returned if the system timer is not active.</li>
1199 </ul>
1200 <ul>
1201 <li>-EPERM is returned if <em>task</em> is NULL but not called from a task context.</li>
1202 </ul>
1203 <p>Environments:</p>
1204 <p>This service can be called from:</p>
1205 <ul>
1206 <li>Kernel module initialization/cleanup code or interrupt only if <em>task</em> is non-NULL.</li>
1207 </ul>
1208 <ul>
1209 <li>Kernel-based task</li>
1210 <li>User-space task (switches to primary mode)</li>
1211 </ul>
1212 <p>Rescheduling: always if the operation affects the current task and <em>idate</em> has not elapsed yet.</p>
1213 <dl class="note"><dt><b>Note:</b></dt><dd>The <em>idate</em> and <em>period</em> values will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise. </dd></dl>
1214
1215 <p>References <a class="el" href="group__pod.html#gaed5776a428e7c59b52b1da76f0d765fa">xnpod_set_thread_periodic()</a>.</p>
1216
1217 </div>
1218 </div>
1219 <a class="anchor" id="ga3bed8d001e212a3328a4e7e73f1765e8"></a><!-- doxytag: member="task.c::rt_task_set_priority" ref="ga3bed8d001e212a3328a4e7e73f1765e8" args="(RT_TASK *task, int prio)" -->
1220 <div class="memitem">
1221 <div class="memproto">
1222       <table class="memname">
1223         <tr>
1224           <td class="memname">int rt_task_set_priority </td>
1225           <td>(</td>
1226           <td class="paramtype">RT_TASK *&nbsp;</td>
1227           <td class="paramname"> <em>task</em>, </td>
1228         </tr>
1229         <tr>
1230           <td class="paramkey"></td>
1231           <td></td>
1232           <td class="paramtype">int&nbsp;</td>
1233           <td class="paramname"> <em>prio</em></td><td>&nbsp;</td>
1234         </tr>
1235         <tr>
1236           <td></td>
1237           <td>)</td>
1238           <td></td><td></td><td></td>
1239         </tr>
1240       </table>
1241 </div>
1242 <div class="memdoc">
1243
1244 <p>Change the base priority of a real-time task. </p>
1245 <p>Changing the base priority of a task does not affect the priority boost the target task might have obtained as a consequence of a previous priority inheritance.</p>
1246 <dl><dt><b>Parameters:</b></dt><dd>
1247   <table border="0" cellspacing="2" cellpadding="0">
1248     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task.</td></tr>
1249     <tr><td valign="top"></td><td valign="top"><em>prio</em>&nbsp;</td><td>The new task priority. This value must range from [0 .. 99] (inclusive) where 0 is the lowest effective priority.</td></tr>
1250   </table>
1251   </dd>
1252 </dl>
1253 <dl class="return"><dt><b>Returns:</b></dt><dd>Upon success, the previously set priority is returned. Otherwise:</dd></dl>
1254 <ul>
1255 <li>-EINVAL is returned if <em>task</em> is not a task descriptor, or if <em>prio</em> is invalid.</li>
1256 </ul>
1257 <ul>
1258 <li>-EPERM is returned if <em>task</em> is NULL but not called from a task context.</li>
1259 </ul>
1260 <ul>
1261 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
1262 </ul>
1263 <p>Side-effects:</p>
1264 <ul>
1265 <li>This service calls the rescheduling procedure.</li>
1266 </ul>
1267 <ul>
1268 <li>Assigning the same priority to a running or ready task moves it to the end of its priority group, thus causing a manual round-robin.</li>
1269 </ul>
1270 <p>Environments:</p>
1271 <p>This service can be called from:</p>
1272 <ul>
1273 <li>Kernel module initialization/cleanup code</li>
1274 <li>Interrupt service routine only if <em>task</em> is non-NULL.</li>
1275 </ul>
1276 <ul>
1277 <li>Kernel-based task</li>
1278 <li>User-space task</li>
1279 </ul>
1280 <p>Rescheduling: possible if <em>task</em> is the current one. </p>
1281
1282 <p>References <a class="el" href="group__pod.html#gacf5b53f0405351327b89b0cc4976b962">xnpod_schedule()</a>, and <a class="el" href="group__pod.html#ga6d535ef9821e98fd7f257b50a3c8d595">xnpod_set_thread_schedparam()</a>.</p>
1283
1284 </div>
1285 </div>
1286 <a class="anchor" id="ga72e0a9355d06c346a95bf88b857a9749"></a><!-- doxytag: member="task.h::rt_task_shadow" ref="ga72e0a9355d06c346a95bf88b857a9749" args="(RT_TASK *task, const char *name, int prio, int mode)" -->
1287 <div class="memitem">
1288 <div class="memproto">
1289       <table class="memname">
1290         <tr>
1291           <td class="memname">int rt_task_shadow </td>
1292           <td>(</td>
1293           <td class="paramtype">RT_TASK *&nbsp;</td>
1294           <td class="paramname"> <em>task</em>, </td>
1295         </tr>
1296         <tr>
1297           <td class="paramkey"></td>
1298           <td></td>
1299           <td class="paramtype">const char *&nbsp;</td>
1300           <td class="paramname"> <em>name</em>, </td>
1301         </tr>
1302         <tr>
1303           <td class="paramkey"></td>
1304           <td></td>
1305           <td class="paramtype">int&nbsp;</td>
1306           <td class="paramname"> <em>prio</em>, </td>
1307         </tr>
1308         <tr>
1309           <td class="paramkey"></td>
1310           <td></td>
1311           <td class="paramtype">int&nbsp;</td>
1312           <td class="paramname"> <em>mode</em></td><td>&nbsp;</td>
1313         </tr>
1314         <tr>
1315           <td></td>
1316           <td>)</td>
1317           <td></td><td></td><td></td>
1318         </tr>
1319       </table>
1320 </div>
1321 <div class="memdoc">
1322
1323 <p>Turns the current Linux task into a native Xenomai task. </p>
1324 <p>Creates a real-time task running in the context of the calling regular Linux task in user-space.</p>
1325 <dl><dt><b>Parameters:</b></dt><dd>
1326   <table border="0" cellspacing="2" cellpadding="0">
1327     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>In non-NULL, the address of a task descriptor Xenomai will use to store the task-related data; this descriptor must always be valid while the task is active therefore it must be allocated in permanent memory. If NULL is passed, then the descriptor will not be returned; main() threads which do not need to be referred to by other threads may use this syntax to promote themselves to the real-time domain for instance.</td></tr>
1328   </table>
1329   </dd>
1330 </dl>
1331 <dl class="note"><dt><b>Note:</b></dt><dd>Allowing for a NULL descriptor pointer to be passed is a recent feature which is not available with any earlier Xenomai release.</dd></dl>
1332 <p>The current context is switched to primary execution mode and returns immediately, unless T_SUSP has been passed in the <em>mode</em> parameter.</p>
1333 <dl><dt><b>Parameters:</b></dt><dd>
1334   <table border="0" cellspacing="2" cellpadding="0">
1335     <tr><td valign="top"></td><td valign="top"><em>name</em>&nbsp;</td><td>An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created task.</td></tr>
1336     <tr><td valign="top"></td><td valign="top"><em>prio</em>&nbsp;</td><td>The base priority which will be set for the current task. This value must range from [0 .. 99] (inclusive) where 0 is the lowest effective priority.</td></tr>
1337     <tr><td valign="top"></td><td valign="top"><em>mode</em>&nbsp;</td><td>The task creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new task:</td></tr>
1338   </table>
1339   </dd>
1340 </dl>
1341 <ul>
1342 <li>T_FPU allows the task to use the FPU whenever available on the platform. This flag is forced for this call, therefore it can be omitted.</li>
1343 </ul>
1344 <ul>
1345 <li>T_SUSP causes the task to enter the suspended mode after it has been put under Xenomai's control. In such a case, a call to <a class="el" href="group__task.html#ga1fab1aa24ef6f199546fd9669ae711be" title="Resume a real-time task.">rt_task_resume()</a> will be needed to wake up the current task.</li>
1346 </ul>
1347 <ul>
1348 <li>T_CPU(cpuid) makes the current task affine to CPU # <b>cpuid</b>. CPU identifiers range from 0 to RTHAL_NR_CPUS - 1 (inclusive). The calling task will migrate to another processor before this service returns if the current one is not part of the CPU affinity mask.</li>
1349 </ul>
1350 <p>Passing T_CPU(0)|T_CPU(1) in the <em>mode</em> parameter thus defines a task affine to CPUs #0 and #1.</p>
1351 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1352 <ul>
1353 <li>-EBUSY is returned if the current Linux task is already mapped to a Xenomai context.</li>
1354 </ul>
1355 <ul>
1356 <li>-ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to create or register the task.</li>
1357 </ul>
1358 <ul>
1359 <li>-EEXIST is returned if the <em>name</em> is already in use by some registered object.</li>
1360 </ul>
1361 <ul>
1362 <li>-EPERM is returned if this service was called from an asynchronous context.</li>
1363 </ul>
1364 <p>Environments:</p>
1365 <p>This service can be called from:</p>
1366 <ul>
1367 <li>User-space task (enters primary mode)</li>
1368 </ul>
1369 <p>Rescheduling: possible.</p>
1370 <dl class="note"><dt><b>Note:</b></dt><dd></dd></dl>
1371 <p>When creating or shadowing a Xenomai thread for the first time in user-space, Xenomai installs a handler for the SIGWINCH signal. If you had installed a handler before that, it will be automatically called by Xenomai for SIGWINCH signals that it has not sent.</p>
1372 <p>If, however, you install a signal handler for SIGWINCH after creating or shadowing the first Xenomai thread, you have to explicitly call the function xeno_sigwinch_handler at the beginning of your signal handler, using its return to know if the signal was in fact an internal signal of Xenomai (in which case it returns 1), or if you should handle the signal (in which case it returns 0). xeno_sigwinch_handler prototype is:</p>
1373 <p><b>int xeno_sigwinch_handler(int sig, siginfo_t *si, void *ctxt);</b></p>
1374 <p>Which means that you should register your handler with sigaction, using the SA_SIGINFO flag, and pass all the arguments you received to xeno_sigwinch_handler. </p>
1375 <dl><dt><b>Examples: </b></dt><dd><a class="el" href="rtcanrecv_8c-example.html#a23">rtcanrecv.c</a>, and <a class="el" href="rtcansend_8c-example.html#a19">rtcansend.c</a>.</dd>
1376 </dl>
1377 <p>References <a class="el" href="group__posix__tsd.html#ga31469375891078185bda93f0e4411a2c">pthread_getspecific()</a>, <a class="el" href="group__posix__thread.html#ga4c4f5f3b4f8f45d9d897847d53b11aaa">pthread_self()</a>, <a class="el" href="group__posix__cancel.html#ga636480bad96654729ecf18017c2820cd">pthread_setcanceltype()</a>, and <a class="el" href="group__posix__tsd.html#ga2187333dd46ce08d9d2e044f79fad705">pthread_setspecific()</a>.</p>
1378
1379 </div>
1380 </div>
1381 <a class="anchor" id="gad5225e5fb8d583fbdfa5299f322b8366"></a><!-- doxytag: member="task.c::rt_task_sleep" ref="gad5225e5fb8d583fbdfa5299f322b8366" args="(RTIME delay)" -->
1382 <div class="memitem">
1383 <div class="memproto">
1384       <table class="memname">
1385         <tr>
1386           <td class="memname">int rt_task_sleep </td>
1387           <td>(</td>
1388           <td class="paramtype">RTIME&nbsp;</td>
1389           <td class="paramname"> <em>delay</em></td>
1390           <td>&nbsp;)&nbsp;</td>
1391           <td></td>
1392         </tr>
1393       </table>
1394 </div>
1395 <div class="memdoc">
1396
1397 <p>Delay the calling task (relative). </p>
1398 <p>Delay the execution of the calling task for a number of internal clock ticks.</p>
1399 <dl><dt><b>Parameters:</b></dt><dd>
1400   <table border="0" cellspacing="2" cellpadding="0">
1401     <tr><td valign="top"></td><td valign="top"><em>delay</em>&nbsp;</td><td>The number of clock ticks to wait before resuming the task (see note). Passing zero causes the task to return immediately with no delay.</td></tr>
1402   </table>
1403   </dd>
1404 </dl>
1405 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success, otherwise:</dd></dl>
1406 <ul>
1407 <li>-EINTR is returned if <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> has been called for the sleeping task before the sleep time has elapsed.</li>
1408 </ul>
1409 <ul>
1410 <li>-EWOULDBLOCK is returned if the system timer is inactive.</li>
1411 </ul>
1412 <ul>
1413 <li>-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).</li>
1414 </ul>
1415 <p>Environments:</p>
1416 <p>This service can be called from:</p>
1417 <ul>
1418 <li>Kernel-based task</li>
1419 <li>User-space task (switches to primary mode)</li>
1420 </ul>
1421 <p>Rescheduling: always unless a null delay is given.</p>
1422 <dl class="note"><dt><b>Note:</b></dt><dd>The <em>delay</em> value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise. </dd></dl>
1423
1424 <p>References <a class="el" href="group__posix__cancel.html#ga636480bad96654729ecf18017c2820cd">pthread_setcanceltype()</a>, <a class="el" href="group__nucleus__info__flags.html#ga6aa575e1a99b9c931d3b1feb8bc7a36f">XNBREAK</a>, <a class="el" href="group__nucleus__state__flags.html#gaa31d298d298eb696ccf840473b94912c">XNDELAY</a>, and <a class="el" href="group__pod.html#ga767221cf87c198c5dc071e9f597dcb3a">xnpod_suspend_thread()</a>.</p>
1425
1426 </div>
1427 </div>
1428 <a class="anchor" id="ga0dc2deebe7500c9d21ff05d51d5efaa8"></a><!-- doxytag: member="task.c::rt_task_sleep_until" ref="ga0dc2deebe7500c9d21ff05d51d5efaa8" args="(RTIME date)" -->
1429 <div class="memitem">
1430 <div class="memproto">
1431       <table class="memname">
1432         <tr>
1433           <td class="memname">int rt_task_sleep_until </td>
1434           <td>(</td>
1435           <td class="paramtype">RTIME&nbsp;</td>
1436           <td class="paramname"> <em>date</em></td>
1437           <td>&nbsp;)&nbsp;</td>
1438           <td></td>
1439         </tr>
1440       </table>
1441 </div>
1442 <div class="memdoc">
1443
1444 <p>Delay the calling task (absolute). </p>
1445 <p>Delay the execution of the calling task until a given date is reached.</p>
1446 <dl><dt><b>Parameters:</b></dt><dd>
1447   <table border="0" cellspacing="2" cellpadding="0">
1448     <tr><td valign="top"></td><td valign="top"><em>date</em>&nbsp;</td><td>The absolute date in clock ticks to wait before resuming the task (see note). As a special case, TM_INFINITE is an acceptable value that makes the caller block indefinitely, until <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> is called against it. Otherwise, any wake up date in the past causes the task to return immediately with no delay.</td></tr>
1449   </table>
1450   </dd>
1451 </dl>
1452 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1453 <ul>
1454 <li>-EINTR is returned if <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> has been called for the sleeping task before the sleep time has elapsed.</li>
1455 </ul>
1456 <ul>
1457 <li>-ETIMEDOUT is returned if <em>date</em> has already elapsed.</li>
1458 </ul>
1459 <ul>
1460 <li>-EWOULDBLOCK is returned if the system timer is inactive, and <dl class="date"><dt><b>Date:</b></dt><dd>is valid but different from TM_INFINITE.</dd></dl>
1461 </li>
1462 <li>-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).</li>
1463 </ul>
1464 <p>Environments:</p>
1465 <p>This service can be called from:</p>
1466 <ul>
1467 <li>Kernel-based task</li>
1468 <li>User-space task (switches to primary mode)</li>
1469 </ul>
1470 <p>Rescheduling: always unless a date in the past is given.</p>
1471 <dl class="note"><dt><b>Note:</b></dt><dd>The <em>date</em> value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise. </dd></dl>
1472
1473 <p>References <a class="el" href="group__posix__cancel.html#ga636480bad96654729ecf18017c2820cd">pthread_setcanceltype()</a>, <a class="el" href="group__nucleus__info__flags.html#ga6aa575e1a99b9c931d3b1feb8bc7a36f">XNBREAK</a>, <a class="el" href="group__nucleus__state__flags.html#gaa31d298d298eb696ccf840473b94912c">XNDELAY</a>, <a class="el" href="group__pod.html#ga767221cf87c198c5dc071e9f597dcb3a">xnpod_suspend_thread()</a>, and <a class="el" href="group__timebase.html#ga5246b53b5b2d1b11d4fab4312fd16fda">xntbase_get_time()</a>.</p>
1474
1475 </div>
1476 </div>
1477 <a class="anchor" id="ga9250436d7bd9e49a0320161d2e9373ae"></a><!-- doxytag: member="task.c::rt_task_slice" ref="ga9250436d7bd9e49a0320161d2e9373ae" args="(RT_TASK *task, RTIME quantum)" -->
1478 <div class="memitem">
1479 <div class="memproto">
1480       <table class="memname">
1481         <tr>
1482           <td class="memname">int rt_task_slice </td>
1483           <td>(</td>
1484           <td class="paramtype">RT_TASK *&nbsp;</td>
1485           <td class="paramname"> <em>task</em>, </td>
1486         </tr>
1487         <tr>
1488           <td class="paramkey"></td>
1489           <td></td>
1490           <td class="paramtype">RTIME&nbsp;</td>
1491           <td class="paramname"> <em>quantum</em></td><td>&nbsp;</td>
1492         </tr>
1493         <tr>
1494           <td></td>
1495           <td>)</td>
1496           <td></td><td></td><td></td>
1497         </tr>
1498       </table>
1499 </div>
1500 <div class="memdoc">
1501
1502 <p>Set a task's round-robin quantum. </p>
1503 <p>Set the time credit allotted to a task undergoing the round-robin scheduling. If <em>quantum</em> is non-zero, <a class="el" href="group__task.html#ga9250436d7bd9e49a0320161d2e9373ae" title="Set a task&#39;s round-robin quantum.">rt_task_slice()</a> also refills the current quantum for the target task, otherwise, time-slicing is stopped for that task.</p>
1504 <dl><dt><b>Parameters:</b></dt><dd>
1505   <table border="0" cellspacing="2" cellpadding="0">
1506     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task. If <em>task</em> is NULL, the current task is considered.</td></tr>
1507     <tr><td valign="top"></td><td valign="top"><em>quantum</em>&nbsp;</td><td>The round-robin quantum for the task expressed in ticks (see note).</td></tr>
1508   </table>
1509   </dd>
1510 </dl>
1511 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1512 <ul>
1513 <li>-EINVAL is returned if <em>task</em> is not a task descriptor.</li>
1514 </ul>
1515 <ul>
1516 <li>-EPERM is returned if <em>task</em> is NULL but not called from a task context.</li>
1517 </ul>
1518 <p>Environments:</p>
1519 <p>This service can be called from:</p>
1520 <ul>
1521 <li>Kernel module initialization/cleanup code</li>
1522 <li>Interrupt service routine only if <em>task</em> is non-NULL.</li>
1523 </ul>
1524 <ul>
1525 <li>Kernel-based task</li>
1526 <li>User-space task</li>
1527 </ul>
1528 <p>Rescheduling: never.</p>
1529 <dl class="note"><dt><b>Note:</b></dt><dd>The <em>quantum</em> value is always interpreted as a count of ticks. If the task undergoes aperiodic timing, the tick duration is defined by CONFIG_XENO_OPT_TIMING_VIRTICK. </dd></dl>
1530
1531 <p>References <a class="el" href="group__pod.html#ga4b8647e7a6969962c788669ff8d46d3b">xnpod_set_thread_tslice()</a>.</p>
1532
1533 </div>
1534 </div>
1535 <a class="anchor" id="ga520e6fad1decc5beff58b394ff443265"></a><!-- doxytag: member="task.h::rt_task_spawn" ref="ga520e6fad1decc5beff58b394ff443265" args="(RT_TASK *task, const char *name, int stksize, int prio, int mode, void(*entry)(void *cookie), void *cookie)" -->
1536 <div class="memitem">
1537 <div class="memproto">
1538       <table class="memname">
1539         <tr>
1540           <td class="memname">int rt_task_spawn </td>
1541           <td>(</td>
1542           <td class="paramtype">RT_TASK *&nbsp;</td>
1543           <td class="paramname"> <em>task</em>, </td>
1544         </tr>
1545         <tr>
1546           <td class="paramkey"></td>
1547           <td></td>
1548           <td class="paramtype">const char *&nbsp;</td>
1549           <td class="paramname"> <em>name</em>, </td>
1550         </tr>
1551         <tr>
1552           <td class="paramkey"></td>
1553           <td></td>
1554           <td class="paramtype">int&nbsp;</td>
1555           <td class="paramname"> <em>stksize</em>, </td>
1556         </tr>
1557         <tr>
1558           <td class="paramkey"></td>
1559           <td></td>
1560           <td class="paramtype">int&nbsp;</td>
1561           <td class="paramname"> <em>prio</em>, </td>
1562         </tr>
1563         <tr>
1564           <td class="paramkey"></td>
1565           <td></td>
1566           <td class="paramtype">int&nbsp;</td>
1567           <td class="paramname"> <em>mode</em>, </td>
1568         </tr>
1569         <tr>
1570           <td class="paramkey"></td>
1571           <td></td>
1572           <td class="paramtype">void(*)(void *cookie)&nbsp;</td>
1573           <td class="paramname"> <em>entry</em>, </td>
1574         </tr>
1575         <tr>
1576           <td class="paramkey"></td>
1577           <td></td>
1578           <td class="paramtype">void *&nbsp;</td>
1579           <td class="paramname"> <em>cookie</em></td><td>&nbsp;</td>
1580         </tr>
1581         <tr>
1582           <td></td>
1583           <td>)</td>
1584           <td></td><td></td><td><code> [inline, static]</code></td>
1585         </tr>
1586       </table>
1587 </div>
1588 <div class="memdoc">
1589
1590 <p>Spawn a new real-time task. </p>
1591 <p>Creates and immediately starts a real-time task, either running in a kernel module or in user-space depending on the caller's context. This service is a simple shorthand for <a class="el" href="group__task.html#ga03387550693c21d0223f739570ccd992" title="Create a new real-time task.">rt_task_create()</a> followed by a call to <a class="el" href="group__task.html#gac9638918b8310a430088f5c9a04d2bb7" title="Start a real-time task.">rt_task_start()</a>.</p>
1592 <dl><dt><b>Parameters:</b></dt><dd>
1593   <table border="0" cellspacing="2" cellpadding="0">
1594     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The address of a task descriptor Xenomai will use to store the task-related data. This descriptor must always be valid while the task is active therefore it must be allocated in permanent memory.</td></tr>
1595     <tr><td valign="top"></td><td valign="top"><em>name</em>&nbsp;</td><td>An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created task.</td></tr>
1596     <tr><td valign="top"></td><td valign="top"><em>stksize</em>&nbsp;</td><td>The size of the stack (in bytes) for the new task. If zero is passed, a reasonable pre-defined size will be substituted.</td></tr>
1597     <tr><td valign="top"></td><td valign="top"><em>prio</em>&nbsp;</td><td>The base priority of the new task. This value must range from [0 .. 99] (inclusive) where 0 is the lowest effective priority.</td></tr>
1598     <tr><td valign="top"></td><td valign="top"><em>mode</em>&nbsp;</td><td>The task creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new task:</td></tr>
1599   </table>
1600   </dd>
1601 </dl>
1602 <ul>
1603 <li>T_FPU allows the task to use the FPU whenever available on the platform. This flag is forced for user-space tasks.</li>
1604 </ul>
1605 <ul>
1606 <li>T_SUSP causes the task to start in suspended mode. In such a case, the thread will have to be explicitly resumed using the <a class="el" href="group__task.html#ga1fab1aa24ef6f199546fd9669ae711be" title="Resume a real-time task.">rt_task_resume()</a> service for its execution to actually begin.</li>
1607 </ul>
1608 <ul>
1609 <li>T_CPU(cpuid) makes the new task affine to CPU # <b>cpuid</b>. CPU identifiers range from 0 to RTHAL_NR_CPUS - 1 (inclusive).</li>
1610 </ul>
1611 <ul>
1612 <li>T_JOINABLE (user-space only) allows another task to wait on the termination of the new task. This implies that <a class="el" href="group__task.html#ga8c77d57638578a126812e29429f61fe7" title="Wait on the termination of a real-time task.">rt_task_join()</a> is actually called for this task to clean up any user-space located resources after its termination.</li>
1613 </ul>
1614 <p>Passing T_FPU|T_CPU(1) in the <em>mode</em> parameter thus creates a task with FPU support enabled and which will be affine to CPU #1.</p>
1615 <dl><dt><b>Parameters:</b></dt><dd>
1616   <table border="0" cellspacing="2" cellpadding="0">
1617     <tr><td valign="top"></td><td valign="top"><em>entry</em>&nbsp;</td><td>The address of the task's body routine. In other words, it is the task entry point.</td></tr>
1618     <tr><td valign="top"></td><td valign="top"><em>cookie</em>&nbsp;</td><td>A user-defined opaque cookie the real-time kernel will pass to the emerging task as the sole argument of its entry point.</td></tr>
1619   </table>
1620   </dd>
1621 </dl>
1622 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1623 <ul>
1624 <li>-ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to create the new task's stack space or register the task.</li>
1625 </ul>
1626 <ul>
1627 <li>-EEXIST is returned if the <em>name</em> is already in use by some registered object.</li>
1628 </ul>
1629 <ul>
1630 <li>-EPERM is returned if this service was called from an asynchronous context.</li>
1631 </ul>
1632 <p>Environments:</p>
1633 <p>This service can be called from:</p>
1634 <ul>
1635 <li>Kernel module initialization/cleanup code</li>
1636 <li>Kernel-based task</li>
1637 <li>User-space task</li>
1638 </ul>
1639 <p>Rescheduling: possible.</p>
1640 <dl class="note"><dt><b>Note:</b></dt><dd></dd></dl>
1641 <p>When creating or shadowing a Xenomai thread for the first time in user-space, Xenomai installs a handler for the SIGWINCH signal. If you had installed a handler before that, it will be automatically called by Xenomai for SIGWINCH signals that it has not sent.</p>
1642 <p>If, however, you install a signal handler for SIGWINCH after creating or shadowing the first Xenomai thread, you have to explicitly call the function xeno_sigwinch_handler at the beginning of your signal handler, using its return to know if the signal was in fact an internal signal of Xenomai (in which case it returns 1), or if you should handle the signal (in which case it returns 0). xeno_sigwinch_handler prototype is:</p>
1643 <p><b>int xeno_sigwinch_handler(int sig, siginfo_t *si, void *ctxt);</b></p>
1644 <p>Which means that you should register your handler with sigaction, using the SA_SIGINFO flag, and pass all the arguments you received to xeno_sigwinch_handler. </p>
1645
1646 <p>References <a class="el" href="group__task.html#ga03387550693c21d0223f739570ccd992">rt_task_create()</a>, and <a class="el" href="group__task.html#gac9638918b8310a430088f5c9a04d2bb7">rt_task_start()</a>.</p>
1647
1648 </div>
1649 </div>
1650 <a class="anchor" id="gac9638918b8310a430088f5c9a04d2bb7"></a><!-- doxytag: member="task.c::rt_task_start" ref="gac9638918b8310a430088f5c9a04d2bb7" args="(RT_TASK *task, void(*entry)(void *cookie), void *cookie)" -->
1651 <div class="memitem">
1652 <div class="memproto">
1653       <table class="memname">
1654         <tr>
1655           <td class="memname">int rt_task_start </td>
1656           <td>(</td>
1657           <td class="paramtype">RT_TASK *&nbsp;</td>
1658           <td class="paramname"> <em>task</em>, </td>
1659         </tr>
1660         <tr>
1661           <td class="paramkey"></td>
1662           <td></td>
1663           <td class="paramtype">void(*)(void *cookie)&nbsp;</td>
1664           <td class="paramname"> <em>entry</em>, </td>
1665         </tr>
1666         <tr>
1667           <td class="paramkey"></td>
1668           <td></td>
1669           <td class="paramtype">void *&nbsp;</td>
1670           <td class="paramname"> <em>cookie</em></td><td>&nbsp;</td>
1671         </tr>
1672         <tr>
1673           <td></td>
1674           <td>)</td>
1675           <td></td><td></td><td></td>
1676         </tr>
1677       </table>
1678 </div>
1679 <div class="memdoc">
1680
1681 <p>Start a real-time task. </p>
1682 <p>Start a (newly) created task, scheduling it for the first time. This call releases the target task from the dormant state.</p>
1683 <p>The TSTART hooks are called on behalf of the calling context (if any, see <a class="el" href="group__task.html#ga7452f367f9e17bf2fc0b70f717b96dd8" title="Install a task hook.">rt_task_add_hook()</a>).</p>
1684 <dl><dt><b>Parameters:</b></dt><dd>
1685   <table border="0" cellspacing="2" cellpadding="0">
1686     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task which must have been previously created by the <a class="el" href="group__task.html#ga03387550693c21d0223f739570ccd992" title="Create a new real-time task.">rt_task_create()</a> service.</td></tr>
1687     <tr><td valign="top"></td><td valign="top"><em>entry</em>&nbsp;</td><td>The address of the task's body routine. In other words, it is the task entry point.</td></tr>
1688     <tr><td valign="top"></td><td valign="top"><em>cookie</em>&nbsp;</td><td>A user-defined opaque cookie the real-time kernel will pass to the emerging task as the sole argument of its entry point.</td></tr>
1689   </table>
1690   </dd>
1691 </dl>
1692 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1693 <ul>
1694 <li>-EINVAL is returned if <em>task</em> is not a task descriptor.</li>
1695 </ul>
1696 <ul>
1697 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
1698 </ul>
1699 <ul>
1700 <li>-EBUSY is returned if <em>task</em> is already started.</li>
1701 </ul>
1702 <ul>
1703 <li>-EPERM is returned if this service was called from an asynchronous context.</li>
1704 </ul>
1705 <p>Environments:</p>
1706 <p>This service can be called from:</p>
1707 <ul>
1708 <li>Kernel module initialization/cleanup code</li>
1709 <li>Kernel-based task</li>
1710 <li>User-space task</li>
1711 </ul>
1712 <p>Rescheduling: possible. </p>
1713
1714 <p>References <a class="el" href="group__nucleus__state__flags.html#ga5fa9672a03ebd4beaf7ab3caa5699fa6">XNDORMANT</a>, and <a class="el" href="group__pod.html#gad322f6afd62430705486a9036d0b7d66">xnpod_start_thread()</a>.</p>
1715
1716 <p>Referenced by <a class="el" href="group__task.html#ga520e6fad1decc5beff58b394ff443265">rt_task_spawn()</a>.</p>
1717
1718 </div>
1719 </div>
1720 <a class="anchor" id="ga926a4b10e3631f76c5f38910e6eea24c"></a><!-- doxytag: member="task.c::rt_task_suspend" ref="ga926a4b10e3631f76c5f38910e6eea24c" args="(RT_TASK *task)" -->
1721 <div class="memitem">
1722 <div class="memproto">
1723       <table class="memname">
1724         <tr>
1725           <td class="memname">int rt_task_suspend </td>
1726           <td>(</td>
1727           <td class="paramtype">RT_TASK *&nbsp;</td>
1728           <td class="paramname"> <em>task</em></td>
1729           <td>&nbsp;)&nbsp;</td>
1730           <td></td>
1731         </tr>
1732       </table>
1733 </div>
1734 <div class="memdoc">
1735
1736 <p>Suspend a real-time task. </p>
1737 <p>Forcibly suspend the execution of a task. This task will not be eligible for scheduling until it is explicitly resumed by a call to <a class="el" href="group__task.html#ga1fab1aa24ef6f199546fd9669ae711be" title="Resume a real-time task.">rt_task_resume()</a>. In other words, the suspended state caused by a call to <a class="el" href="group__task.html#ga926a4b10e3631f76c5f38910e6eea24c" title="Suspend a real-time task.">rt_task_suspend()</a> is cumulative with respect to the delayed and blocked states caused by other services, and is managed separately from them.</p>
1738 <p>A nesting count is maintained so that <a class="el" href="group__task.html#ga926a4b10e3631f76c5f38910e6eea24c" title="Suspend a real-time task.">rt_task_suspend()</a> and <a class="el" href="group__task.html#ga1fab1aa24ef6f199546fd9669ae711be" title="Resume a real-time task.">rt_task_resume()</a> must be used in pairs.</p>
1739 <p>Receiving a Linux signal causes the suspended task to resume immediately.</p>
1740 <dl><dt><b>Parameters:</b></dt><dd>
1741   <table border="0" cellspacing="2" cellpadding="0">
1742     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task. If <em>task</em> is NULL, the current task is suspended.</td></tr>
1743   </table>
1744   </dd>
1745 </dl>
1746 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1747 <ul>
1748 <li>-EINTR is returned if a Linux signal has been received by the suspended task.</li>
1749 </ul>
1750 <ul>
1751 <li>-EINVAL is returned if <em>task</em> is not a task descriptor.</li>
1752 </ul>
1753 <ul>
1754 <li>-EPERM is returned if this service was called from an invalid context (e.g. interrupt, non-realtime context).</li>
1755 </ul>
1756 <ul>
1757 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
1758 </ul>
1759 <p>Environments:</p>
1760 <p>This service can be called from:</p>
1761 <ul>
1762 <li>Kernel module initialization/cleanup code</li>
1763 <li>Interrupt service routine only if <em>task</em> is non-NULL.</li>
1764 </ul>
1765 <ul>
1766 <li>Kernel-based task</li>
1767 <li>User-space task (switches to primary mode)</li>
1768 </ul>
1769 <p>Rescheduling: always if <em>task</em> is NULL. </p>
1770
1771 <p>References <a class="el" href="group__nucleus__info__flags.html#ga6aa575e1a99b9c931d3b1feb8bc7a36f">XNBREAK</a>, <a class="el" href="group__pod.html#ga767221cf87c198c5dc071e9f597dcb3a">xnpod_suspend_thread()</a>, and <a class="el" href="group__nucleus__state__flags.html#ga6b605ad2bb16ae2386821be8ce8d341b">XNSUSP</a>.</p>
1772
1773 </div>
1774 </div>
1775 <a class="anchor" id="ga2038cbe2350a8e2558330a3f45953865"></a><!-- doxytag: member="task.h::rt_task_unbind" ref="ga2038cbe2350a8e2558330a3f45953865" args="(RT_TASK *task)" -->
1776 <div class="memitem">
1777 <div class="memproto">
1778       <table class="memname">
1779         <tr>
1780           <td class="memname">int rt_task_unbind </td>
1781           <td>(</td>
1782           <td class="paramtype">RT_TASK *&nbsp;</td>
1783           <td class="paramname"> <em>task</em></td>
1784           <td>&nbsp;)&nbsp;</td>
1785           <td><code> [inline, static]</code></td>
1786         </tr>
1787       </table>
1788 </div>
1789 <div class="memdoc">
1790
1791 <p>Unbind from a real-time task. </p>
1792 <p>This user-space only service unbinds the calling task from the task object previously retrieved by a call to <a class="el" href="group__task.html#gab6bd973c22a6f66e28653922c53e0385" title="Bind to a real-time task.">rt_task_bind()</a>.</p>
1793 <dl><dt><b>Parameters:</b></dt><dd>
1794   <table border="0" cellspacing="2" cellpadding="0">
1795     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The address of a task descriptor to unbind from.</td></tr>
1796   </table>
1797   </dd>
1798 </dl>
1799 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is always returned.</dd></dl>
1800 <p>This service can be called from:</p>
1801 <ul>
1802 <li>User-space task.</li>
1803 </ul>
1804 <p>Rescheduling: never. </p>
1805
1806 </div>
1807 </div>
1808 <a class="anchor" id="ga770281eeca009c0a08a7c4a9fd849ac1"></a><!-- doxytag: member="task.c::rt_task_unblock" ref="ga770281eeca009c0a08a7c4a9fd849ac1" args="(RT_TASK *task)" -->
1809 <div class="memitem">
1810 <div class="memproto">
1811       <table class="memname">
1812         <tr>
1813           <td class="memname">int rt_task_unblock </td>
1814           <td>(</td>
1815           <td class="paramtype">RT_TASK *&nbsp;</td>
1816           <td class="paramname"> <em>task</em></td>
1817           <td>&nbsp;)&nbsp;</td>
1818           <td></td>
1819         </tr>
1820       </table>
1821 </div>
1822 <div class="memdoc">
1823
1824 <p>Unblock a real-time task. </p>
1825 <p>Break the task out of any wait it is currently in. This call clears all delay and/or resource wait condition for the target task. However, <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> does not resume a task which has been forcibly suspended by a previous call to <a class="el" href="group__task.html#ga926a4b10e3631f76c5f38910e6eea24c" title="Suspend a real-time task.">rt_task_suspend()</a>. If all suspensive conditions are gone, the task becomes eligible anew for scheduling.</p>
1826 <dl><dt><b>Parameters:</b></dt><dd>
1827   <table border="0" cellspacing="2" cellpadding="0">
1828     <tr><td valign="top"></td><td valign="top"><em>task</em>&nbsp;</td><td>The descriptor address of the affected task.</td></tr>
1829   </table>
1830   </dd>
1831 </dl>
1832 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1833 <ul>
1834 <li>-EINVAL is returned if <em>task</em> is not a task descriptor.</li>
1835 </ul>
1836 <ul>
1837 <li>-EIDRM is returned if <em>task</em> is a deleted task descriptor.</li>
1838 </ul>
1839 <p>Environments:</p>
1840 <p>This service can be called from:</p>
1841 <ul>
1842 <li>Kernel module initialization/cleanup code</li>
1843 <li>Interrupt service routine</li>
1844 <li>Kernel-based task</li>
1845 <li>User-space task</li>
1846 </ul>
1847 <p>Rescheduling: possible. </p>
1848
1849 <p>References <a class="el" href="group__pod.html#gacf5b53f0405351327b89b0cc4976b962">xnpod_schedule()</a>, and <a class="el" href="group__pod.html#gae5f0d19e7a499b9b262f68a43ab545dd">xnpod_unblock_thread()</a>.</p>
1850
1851 </div>
1852 </div>
1853 <a class="anchor" id="ga1645d3a072ef3cefeed3bcbb27dcf108"></a><!-- doxytag: member="task.c::rt_task_wait_period" ref="ga1645d3a072ef3cefeed3bcbb27dcf108" args="(unsigned long *overruns_r)" -->
1854 <div class="memitem">
1855 <div class="memproto">
1856       <table class="memname">
1857         <tr>
1858           <td class="memname">int rt_task_wait_period </td>
1859           <td>(</td>
1860           <td class="paramtype">unsigned long *&nbsp;</td>
1861           <td class="paramname"> <em>overruns_r</em></td>
1862           <td>&nbsp;)&nbsp;</td>
1863           <td></td>
1864         </tr>
1865       </table>
1866 </div>
1867 <div class="memdoc">
1868
1869 <p>Wait for the next periodic release point. </p>
1870 <p>Make the current task wait for the next periodic release point in the processor time line.</p>
1871 <dl><dt><b>Parameters:</b></dt><dd>
1872   <table border="0" cellspacing="2" cellpadding="0">
1873     <tr><td valign="top"></td><td valign="top"><em>overruns_r</em>&nbsp;</td><td>If non-NULL, <em>overruns_r</em> must be a pointer to a memory location which will be written with the count of pending overruns. This value is copied only when <a class="el" href="group__task.html#ga1645d3a072ef3cefeed3bcbb27dcf108" title="Wait for the next periodic release point.">rt_task_wait_period()</a> returns -ETIMEDOUT or success; the memory location remains unmodified otherwise. If NULL, this count will never be copied back.</td></tr>
1874   </table>
1875   </dd>
1876 </dl>
1877 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success; if <em>overruns_r</em> is valid, zero is copied to the pointed memory location. Otherwise:</dd></dl>
1878 <ul>
1879 <li>-EWOULDBLOCK is returned if <a class="el" href="group__task.html#gababee94264156693cd4f5b9b70d3c5a1" title="Make a real-time task periodic.">rt_task_set_periodic()</a> has not previously been called for the calling task.</li>
1880 </ul>
1881 <ul>
1882 <li>-EINTR is returned if <a class="el" href="group__task.html#ga770281eeca009c0a08a7c4a9fd849ac1" title="Unblock a real-time task.">rt_task_unblock()</a> has been called for the waiting task before the next periodic release point has been reached. In this case, the overrun counter is reset too.</li>
1883 </ul>
1884 <ul>
1885 <li>-ETIMEDOUT is returned if a timer overrun occurred, which indicates that a previous release point has been missed by the calling task. If <em>overruns_r</em> is valid, the count of pending overruns is copied to the pointed memory location.</li>
1886 </ul>
1887 <ul>
1888 <li>-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).</li>
1889 </ul>
1890 <p>Environments:</p>
1891 <p>This service can be called from:</p>
1892 <ul>
1893 <li>Kernel-based task</li>
1894 <li>User-space task (switches to primary mode)</li>
1895 </ul>
1896 <p>Rescheduling: always, unless the current release point has already been reached. In the latter case, the current task immediately returns from this service without being delayed. </p>
1897
1898 <p>References <a class="el" href="group__posix__cancel.html#ga636480bad96654729ecf18017c2820cd">pthread_setcanceltype()</a>, and <a class="el" href="group__pod.html#gaf836996e4a3378928f2a9f93a4915cfa">xnpod_wait_thread_period()</a>.</p>
1899
1900 </div>
1901 </div>
1902 <a class="anchor" id="ga31e44b069b2486c2d2bdfb8a0a3557c8"></a><!-- doxytag: member="task.c::rt_task_yield" ref="ga31e44b069b2486c2d2bdfb8a0a3557c8" args="(void)" -->
1903 <div class="memitem">
1904 <div class="memproto">
1905       <table class="memname">
1906         <tr>
1907           <td class="memname">int rt_task_yield </td>
1908           <td>(</td>
1909           <td class="paramtype">void&nbsp;</td>
1910           <td class="paramname"></td>
1911           <td>&nbsp;)&nbsp;</td>
1912           <td></td>
1913         </tr>
1914       </table>
1915 </div>
1916 <div class="memdoc">
1917
1918 <p>Manual round-robin. </p>
1919 <p>Move the current task to the end of its priority group, so that the next equal-priority task in ready state is switched in.</p>
1920 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned upon success. Otherwise:</dd></dl>
1921 <ul>
1922 <li>-EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).</li>
1923 </ul>
1924 <p>Environments:</p>
1925 <p>This service can be called from:</p>
1926 <ul>
1927 <li>Kernel-based task</li>
1928 <li>User-space task</li>
1929 </ul>
1930 <p>Rescheduling: always if a next equal-priority task is ready to run, otherwise, this service leads to a no-op. </p>
1931
1932 </div>
1933 </div>
1934 </div>
1935 <hr class="footer"/><address class="footer"><small>Generated on Wed Nov 2 2011 18:01:10 for Xenomai API by&nbsp;
1936 <a href="http://www.doxygen.org/index.html">
1937 <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
1938 </body>
1939 </html>