diff options
Diffstat (limited to 'ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__a_m_s.html')
| -rw-r--r-- | ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__a_m_s.html | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__a_m_s.html b/ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__a_m_s.html new file mode 100644 index 0000000..f85d46c --- /dev/null +++ b/ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__a_m_s.html @@ -0,0 +1,316 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<title>UNICENS: Application Message Service</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<link href="navtree.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="resize.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<script type="text/javascript"> + $(document).ready(initResizable); +</script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> + $(document).ready(function() { searchBox.OnSelectItem(0); }); +</script> +<link href="style_html.css" rel="stylesheet" type="text/css" /> +<link href="inic.css" rel="stylesheet" type="text/css"/> +</head> +<body> +<div class="GlobalWrapper"> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr> + <td><a href="index.html"><img alt="Logo" src="logo.png"/></a></td> + <td> + <div id="projectname">UNICENS <span id="projectnumber">V2.1.0-3491</span></div> + <div id="projectbrief">User Manual and API Reference</div> + <div id="searchbox"> <div id="MSearchBox" class="MSearchBoxInactive"> + <span class="left"> + <img id="MSearchSelect" src="search/mag_sel.png" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + alt=""/> + <input type="text" id="MSearchField" value="Search" accesskey="S" + onfocus="searchBox.OnSearchFieldFocus(true)" + onblur="searchBox.OnSearchFieldFocus(false)" + onkeyup="searchBox.OnSearchFieldChange(event)"/> + </span><span class="right"> + <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a> + </span> + </div> +</div> + </td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.8.2 --> +<script type="text/javascript"> +var searchBox = new SearchBox("searchBox", "search",false,'Search'); +</script> +</div><!-- top --> +<div id="side-nav" class="ui-resizable side-nav-resizable"> + <div id="nav-tree"> + <div id="nav-tree-contents"> + <div id="nav-sync" class="sync"></div> + </div> + </div> + <div id="splitbar" style="-moz-user-select:none;" + class="ui-resizable-handle"> + </div> +</div> +<script type="text/javascript"> +$(document).ready(function(){initNavTree('_p__u_m__s_t_a_r_t_e_d__a_m_s.html','');}); +</script> +<div id="doc-content"> +<!-- window showing the filter options --> +<div id="MSearchSelectWindow" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + onkeydown="return searchBox.OnSearchSelectKey(event)"> +<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Pages</a></div> + +<!-- iframe showing the search results (closed by default) --> +<div id="MSearchResultsWindow"> +<iframe src="javascript:void(0)" frameborder="0" + name="MSearchResults" id="MSearchResults"> +</iframe> +</div> + +<div class="header"> + <div class="headertitle"> +<div class="title">Application Message Service </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><h1>Introduction</h1> +<p>The Application Message Service (AMS) provides a central interface to transmit and receive application messages via the Control Channel of the MOST network. The so called application messages can have a payload size of up to 65535 bytes. Since the payload size of a single MOST control message is limited to 45 bytes (MOST150), an application messages with larger payload is transmitted via segmented transfer. The Application Message Service provides a common interface for single and segmented transfer and automatically performs segmentation.</p> +<table class="mns_ic_table"> +<tr> +<td id="mns_ic_api"> </td><td>See also <em>API Reference</em>, section <a class="el" href="group___g___u_c_s___a_m_s.html">Application Message Service</a>. </td></tr> +</table> +<h1>Configuration</h1> +<p>Any message which is received or transmitted via the Application Message Service requires a certain amount of memory. The UNICENS Library reserves an amount of memory which can be adjusted by defining the number und payload of AMS Tx and Rx messages. The configuration file ucs_cfg.h can be modified to your specific needs. A possible configuration might be:</p> +<ul> +<li>20 Rx Message Objects, each object has a reserved payload size of 400 bytes</li> +<li>20 Tx Message Objects, each object has a reserved payload size of 100 bytes</li> +</ul> +<p>The corresponding configuration will look like this: </p> +<div class="fragment"><div class="line"><span class="comment">/* File: ucs_cfg.h */</span></div> +<div class="line"><span class="preprocessor">#define UCS_AMS_NUM_RX_MSGS 20U</span></div> +<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define UCS_AMS_SIZE_RX_MSG 400U</span></div> +<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define UCS_AMS_NUM_TX_MSGS 20U</span></div> +<div class="line"><span class="preprocessor">#define UCS_AMS_SIZE_TX_MSG 100U</span></div> +</div><!-- fragment --><h1>Initialization</h1> +<p>Prior to the call of <a class="el" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_gaea8d7735d41853167a2befdc06febe43.html#gaea8d7735d41853167a2befdc06febe43" title="UNICENS initialization function.">Ucs_Init()</a>, the application is able to configure the AMS-related <a class="el" href="struct_ucs___ams___init_data__t.html">part</a> of the initialization structure. The following table provides a brief overview of all parameters. </p> +<table class="doxtable"> +<tr> +<th>Parameter </th><th align="center">Default </th><th align="center">Mandatory </th><th>Description</th></tr> +<tr> +<td>rx.message_received_fptr </td><td align="center">NULL </td><td align="center">No </td><td>Callback function that is invoked on message reception </td></tr> +<tr> +<td>tx.message_freed_fptr </td><td align="center">NULL </td><td align="center">No </td><td>Callback function that is invoked if memory dedicated to a Tx message is freed after a prior allocation has failed </td></tr> +<tr> +<td>tx.default_llrbc </td><td align="center">10 </td><td align="center">No </td><td>Default low-level retry block count for Tx messages </td></tr> +</table> +<p>The code below shows a possible initialization sequence of the Application Message Service.</p> +<div class="fragment"><div class="line"><span class="keywordtype">void</span> App_Initialize(<span class="keywordtype">void</span>)</div> +<div class="line">{</div> +<div class="line"> <a class="code" href="struct_ucs___init_data__t.html" title="UNICENS initialization structure used by function Ucs_Init().">Ucs_InitData_t</a> init_data;</div> +<div class="line"> <a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_ga64b50780725a0dc8693b5b73f8345ad6.html#ga64b50780725a0dc8693b5b73f8345ad6" title="Assigns default values to a provided UNICENS init structure.">Ucs_SetDefaultConfig</a>(&init_data);</div> +<div class="line"></div> +<div class="line"> init_data.<a class="code" href="struct_ucs___init_data__t_afc4097eb34fb5c24bb13e02b6f506b3c.html#afc4097eb34fb5c24bb13e02b6f506b3c" title="The initialization data of the Application Message Service.">ams</a>.<a class="code" href="struct_ucs___ams___init_data__t_a8e01298906b1fbe44765c6e9e4bbc888.html#a8e01298906b1fbe44765c6e9e4bbc888" title="Tx related initialization parameters.">tx</a>.<a class="code" href="struct_ucs___ams_tx___init_data__t_a804bd7e626fd73b27d18af9a036d7ad4.html#a804bd7e626fd73b27d18af9a036d7ad4" title="Specifies the low-level retry block count which is pre-selected in an allocated Tx message object...">default_llrbc</a> = 4U;</div> +<div class="line"> init_data.<a class="code" href="struct_ucs___init_data__t_afc4097eb34fb5c24bb13e02b6f506b3c.html#afc4097eb34fb5c24bb13e02b6f506b3c" title="The initialization data of the Application Message Service.">ams</a>.<a class="code" href="struct_ucs___ams___init_data__t_a8e01298906b1fbe44765c6e9e4bbc888.html#a8e01298906b1fbe44765c6e9e4bbc888" title="Tx related initialization parameters.">tx</a>.<a class="code" href="struct_ucs___ams_tx___init_data__t_a9217a093b6d7e68b7cd9d759c5cef192.html#a9217a093b6d7e68b7cd9d759c5cef192" title="Callback function which is invoked by the UNICENS library to notify that memory of a Tx message objec...">message_freed_fptr</a> = &App_OnAmsTxMessageFreed;</div> +<div class="line"> init_data.<a class="code" href="struct_ucs___init_data__t_afc4097eb34fb5c24bb13e02b6f506b3c.html#afc4097eb34fb5c24bb13e02b6f506b3c" title="The initialization data of the Application Message Service.">ams</a>.<a class="code" href="struct_ucs___ams___init_data__t_a976344e02b80d33e167c34d3c6ae9cab.html#a976344e02b80d33e167c34d3c6ae9cab" title="Rx related initialization parameters.">rx</a>.<a class="code" href="struct_ucs___ams_rx___init_data__t_a94cec5846cb407141e9c1e1a2ea205d3.html#a94cec5846cb407141e9c1e1a2ea205d3" title="Callback function that is invoked if the UNICENS library has received a message completely and append...">message_received_fptr</a> = &App_OnAmsRxComplete;</div> +<div class="line"></div> +<div class="line"> <span class="comment">/* ... further initialization ... */</span></div> +<div class="line"></div> +<div class="line"> <a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_gaea8d7735d41853167a2befdc06febe43.html#gaea8d7735d41853167a2befdc06febe43" title="UNICENS initialization function.">Ucs_Init</a>(&init_data, &App_OnInitResult);</div> +<div class="line">}</div> +</div><!-- fragment --><table class="mns_ic_table"> +<tr> +<td id="mns_ic_started"> </td><td>See also <em>Getting Started</em>, section <a class="el" href="_p__u_m__s_t_a_r_t_e_d__i_n_i_t.html">Initialization</a>. </td></tr> +</table> +<h1>Transmission of Messages</h1> +<p>In order to transmit an application message you haves to process the following steps.</p> +<ol type="1"> +<li>Retrieve a message object by calling <a class="el" href="group___g___u_c_s___a_m_s_gafbcfeaaa6ff3d255609e404b16dbdf0f.html#gafbcfeaaa6ff3d255609e404b16dbdf0f" title="Allocates an application message object for transmission.">Ucs_AmsTx_AllocMsg()</a> and specifying the needed amount of payload.</li> +<li>Modify the attributes of the given message object.</li> +<li>Take care not to modify <code>data_ptr</code>[] beyond the specified amount of payload.</li> +<li>Transmit the message object by calling <a class="el" href="group___g___u_c_s___a_m_s_ga6486fc060d0aa8b1bb34851d2e63b755.html#ga6486fc060d0aa8b1bb34851d2e63b755" title="Transmits an application message.">Ucs_AmsTx_SendMsg()</a>.</li> +<li>Optionally check the transmission result after the transmission has finished.</li> +</ol> +<p>The following example explains how to retrieve a message object with a payload size of 3 bytes. Be aware of the function <a class="el" href="group___g___u_c_s___a_m_s_gafbcfeaaa6ff3d255609e404b16dbdf0f.html#gafbcfeaaa6ff3d255609e404b16dbdf0f" title="Allocates an application message object for transmission.">Ucs_AmsTx_AllocMsg()</a> might return <code>NULL</code> if it is not possible to allocate the required amount of memory for the message.</p> +<div class="fragment"><div class="line"><span class="keywordtype">void</span> App_SendMessage(<span class="keywordtype">void</span>)</div> +<div class="line">{</div> +<div class="line"> <a class="code" href="struct_ucs___ams_tx___msg__t.html" title="Application message Tx type.">Ucs_AmsTx_Msg_t</a> *tx_ptr = <a class="code" href="group___g___u_c_s___a_m_s_gafbcfeaaa6ff3d255609e404b16dbdf0f.html#gafbcfeaaa6ff3d255609e404b16dbdf0f" title="Allocates an application message object for transmission.">Ucs_AmsTx_AllocMsg</a>(20U);</div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">if</span> (tx_ptr != NULL)</div> +<div class="line"> {</div> +<div class="line"> <a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v___t_y_p_e_s_ga886138f5d13e84ffaa3df5769830e1cd.html#ga886138f5d13e84ffaa3df5769830e1cd" title="Standard return codes used for synchronous response.">Ucs_Return_t</a> ret;</div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a9a199f6a8a711b94ff827e6807980cb3.html#a9a199f6a8a711b94ff827e6807980cb3" title="Destination address. Find some predefined addresses here.">destination_address</a> = 0x202U;</div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a689014fc11d4f26d264ddae2eaebc9d8.html#a689014fc11d4f26d264ddae2eaebc9d8" title="16bit message descriptor">msg_id</a> = 0x1234U;</div> +<div class="line"> <span class="comment">/* it is possible to set a smaller data_size than */</span></div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_aae6bdbdf6ea1ad3da5af37f0a91d3ea0.html#aae6bdbdf6ea1ad3da5af37f0a91d3ea0" title="The size of payload data in bytes.">data_size</a> = 3U; <span class="comment">/* earlier defined when calling Ucs_AmsTx_AllocMsg() */</span></div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a6166cef59cbe432be35512925debeae6.html#a6166cef59cbe432be35512925debeae6" title="Payload data.">data_ptr</a>[0] = 0xAAU;</div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a6166cef59cbe432be35512925debeae6.html#a6166cef59cbe432be35512925debeae6" title="Payload data.">data_ptr</a>[1] = 0xBBU;</div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a6166cef59cbe432be35512925debeae6.html#a6166cef59cbe432be35512925debeae6" title="Payload data.">data_ptr</a>[2] = 0xCCU;</div> +<div class="line"></div> +<div class="line"> ret = <a class="code" href="group___g___u_c_s___a_m_s_ga6486fc060d0aa8b1bb34851d2e63b755.html#ga6486fc060d0aa8b1bb34851d2e63b755" title="Transmits an application message.">Ucs_AmsTx_SendMsg</a>(tx_ptr, &App_OnTxMessageComplete);</div> +<div class="line"> (void)printf(<span class="stringliteral">"App_SendMessage(): called, tx_ptr=0x%04p, ret=%02X\n"</span>, tx_ptr, ret);</div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">if</span> (ret != <a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v___t_y_p_e_s_ga886138f5d13e84ffaa3df5769830e1cd.html#gga886138f5d13e84ffaa3df5769830e1cda3fb51656e17ee4802f23706f35e349bc" title="Operation successfully completed.">UCS_RET_SUCCESS</a>)</div> +<div class="line"> {</div> +<div class="line"> <a class="code" href="group___g___u_c_s___a_m_s_ga9e03946330dcc4ed4111b1d43714308d.html#ga9e03946330dcc4ed4111b1d43714308d" title="Frees an unused Tx message object.">Ucs_AmsTx_FreeUnusedMsg</a>(running_inst_ptr, tx_ptr);</div> +<div class="line"> }</div> +<div class="line"> }</div> +<div class="line"> <span class="keywordflow">else</span></div> +<div class="line"> {</div> +<div class="line"> <span class="comment">/* not able to allocate enough memory for the message - wait until App_OnAmsTxMessageFreed() */</span></div> +<div class="line"> }</div> +<div class="line">}</div> +</div><!-- fragment --><p>As soon as the transmission has been completed, the Application Message Service will invoke the callback function that was passed to <a class="el" href="group___g___u_c_s___a_m_s_ga6486fc060d0aa8b1bb34851d2e63b755.html#ga6486fc060d0aa8b1bb34851d2e63b755" title="Transmits an application message.">Ucs_AmsTx_SendMsg()</a>. The application's callback function must have the function signature of <a class="el" href="group___g___u_c_s___a_m_s___t_y_p_e_s_ga60acfdd5b93a99906d751ac2f14623a9.html#ga60acfdd5b93a99906d751ac2f14623a9">Ucs_AmsTx_CompleteCb_t</a>. Within the callback function, the application is allowed to access the message object (read only). After the callback function has returned, the application is no longer allowed to access the message object.</p> +<p>An example implementation of such a callback function is shown below.</p> +<div class="fragment"><div class="line"><span class="keywordtype">void</span> App_OnTxMessageComplete(<a class="code" href="struct_ucs___ams_tx___msg__t.html" title="Application message Tx type.">Ucs_AmsTx_Msg_t</a>* msg_ptr, <a class="code" href="group___g___u_c_s___a_m_s___t_y_p_e_s_ga36b630c866dc0c03134f60e98be39f0b.html#ga36b630c866dc0c03134f60e98be39f0b" title="Transmission result of an application message.">Ucs_AmsTx_Result_t</a> result, <a class="code" href="group___g___u_c_s___a_m_s___t_y_p_e_s_ga667b741121fdfbda2fe19fa23ffc7479.html#ga667b741121fdfbda2fe19fa23ffc7479" title="Detailed INIC transmission information which might be useful for debugging purposes.">Ucs_AmsTx_Info_t</a> info)</div> +<div class="line">{</div> +<div class="line"> <span class="keywordflow">if</span> (result == <a class="code" href="group___g___u_c_s___a_m_s___t_y_p_e_s_ga36b630c866dc0c03134f60e98be39f0b.html#gga36b630c866dc0c03134f60e98be39f0ba3213fda6aaa6f3b8caafcf08b75e4e65" title="The transmission succeeded.">UCS_AMSTX_RES_SUCCESS</a>)</div> +<div class="line"> {</div> +<div class="line"> <span class="comment">/* the transmission was finished successfully */</span></div> +<div class="line"> }</div> +<div class="line"> <span class="keywordflow">else</span></div> +<div class="line"> {</div> +<div class="line"> <span class="comment">/* the application has to retry later ... */</span></div> +<div class="line"> }</div> +<div class="line"></div> +<div class="line"> <span class="comment">/* the application is not allowed to reuse this message object */</span></div> +<div class="line">}</div> +</div><!-- fragment --><h1>Transmission of External Payload</h1> +<p>An application may also transmit an application message with "external" payload. This might be useful to avoid copy operations if the message payload is already available in a continuous memory chunk. Process the following steps in order to transmit an application message with external payload.</p> +<ol type="1"> +<li>Prepare the external payload and take care that it is not modified during the transmission.</li> +<li>Retrieve a message object by calling <a class="el" href="group___g___u_c_s___a_m_s_gafbcfeaaa6ff3d255609e404b16dbdf0f.html#gafbcfeaaa6ff3d255609e404b16dbdf0f" title="Allocates an application message object for transmission.">Ucs_AmsTx_AllocMsg()</a>. It is sufficient to pass "0" as <code>data_size</code>. So the Application Message Service will not allocate a separate memory chunk for the payload.</li> +<li>Modify the attributes of the given message object.</li> +<li>Set <code>data_ptr</code> to the external payload reference. Set <code>data_size</code> to define the desired amount of payload to transmit.</li> +<li>Transmit the message object by calling <a class="el" href="group___g___u_c_s___a_m_s_ga6486fc060d0aa8b1bb34851d2e63b755.html#ga6486fc060d0aa8b1bb34851d2e63b755" title="Transmits an application message.">Ucs_AmsTx_SendMsg()</a>.</li> +<li>Check the transmission result after the transmission has finished. The external payload is no longer used by the Application Message Service. I.e., the external payload may now be freed or reused for further transmission.</li> +</ol> +<p>The following example explains how to retrieve a message object and assign a predefined string as external payload. It is important to pass a callback function to <a class="el" href="group___g___u_c_s___a_m_s_ga6486fc060d0aa8b1bb34851d2e63b755.html#ga6486fc060d0aa8b1bb34851d2e63b755" title="Transmits an application message.">Ucs_AmsTx_SendMsg()</a>. The Application Message Service calls this function after the transmission is finished.</p> +<div class="fragment"><div class="line"> <span class="comment">/* provide fixed string "Hello" */</span></div> +<div class="line"><span class="keyword">static</span> uint8_t my_string[14] = {0x01,<span class="charliteral">'H'</span>,<span class="charliteral">'e'</span>,<span class="charliteral">'l'</span>,<span class="charliteral">'l'</span>,<span class="charliteral">'o'</span>,<span class="charliteral">' '</span>,<span class="charliteral">'W'</span>,<span class="charliteral">'o'</span>,<span class="charliteral">'r'</span>,<span class="charliteral">'l'</span>,<span class="charliteral">'d'</span>,<span class="charliteral">'!'</span>,0x00};</div> +<div class="line"><span class="keyword">static</span> <span class="keywordtype">bool</span> string_in_use = <span class="keyword">false</span>; <span class="comment">/* avoid concurrent access */</span></div> +<div class="line"></div> +<div class="line"><span class="keywordtype">void</span> App_SendMessageExt(<span class="keywordtype">void</span>)</div> +<div class="line">{</div> +<div class="line"> <span class="keywordflow">if</span> (!string_in_use)</div> +<div class="line"> {</div> +<div class="line"> <a class="code" href="struct_ucs___ams_tx___msg__t.html" title="Application message Tx type.">Ucs_AmsTx_Msg_t</a> *tx_ptr = <a class="code" href="group___g___u_c_s___a_m_s_gafbcfeaaa6ff3d255609e404b16dbdf0f.html#gafbcfeaaa6ff3d255609e404b16dbdf0f" title="Allocates an application message object for transmission.">Ucs_AmsTx_AllocMsg</a>(0U); <span class="comment">/* define data_size "0" */</span></div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">if</span> (tx_ptr != NULL)</div> +<div class="line"> {</div> +<div class="line"> string_in_use = <span class="keyword">true</span>; <span class="comment">/* lock string against concurrent access */</span></div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a9a199f6a8a711b94ff827e6807980cb3.html#a9a199f6a8a711b94ff827e6807980cb3" title="Destination address. Find some predefined addresses here.">destination_address</a> = 0x202U;</div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a689014fc11d4f26d264ddae2eaebc9d8.html#a689014fc11d4f26d264ddae2eaebc9d8" title="16bit message descriptor">msg_id</a> = 0x1234U;</div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a6166cef59cbe432be35512925debeae6.html#a6166cef59cbe432be35512925debeae6" title="Payload data.">data_ptr</a> = my_string; <span class="comment">/* now set external data and size */</span></div> +<div class="line"> tx_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_aae6bdbdf6ea1ad3da5af37f0a91d3ea0.html#aae6bdbdf6ea1ad3da5af37f0a91d3ea0" title="The size of payload data in bytes.">data_size</a> = 14U;</div> +<div class="line"></div> +<div class="line"> ret = <a class="code" href="group___g___u_c_s___a_m_s_ga6486fc060d0aa8b1bb34851d2e63b755.html#ga6486fc060d0aa8b1bb34851d2e63b755" title="Transmits an application message.">Ucs_AmsTx_SendMsg</a>(tx_ptr, &App_OnTxStringComplete);</div> +<div class="line"> (void)printf(<span class="stringliteral">"App_SendMessage(): called, tx_ptr=0x%04p, ret=%02X\n"</span>, tx_ptr, ret);</div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">if</span> (ret != <a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v___t_y_p_e_s_ga886138f5d13e84ffaa3df5769830e1cd.html#gga886138f5d13e84ffaa3df5769830e1cda3fb51656e17ee4802f23706f35e349bc" title="Operation successfully completed.">UCS_RET_SUCCESS</a>)</div> +<div class="line"> { <span class="comment">/* free memory if transmission is not possible */</span></div> +<div class="line"> <a class="code" href="group___g___u_c_s___a_m_s_ga9e03946330dcc4ed4111b1d43714308d.html#ga9e03946330dcc4ed4111b1d43714308d" title="Frees an unused Tx message object.">Ucs_AmsTx_FreeUnusedMsg</a>(running_inst_ptr, tx_ptr);</div> +<div class="line"> string_in_use = <span class="keyword">false</span>;</div> +<div class="line"> }</div> +<div class="line"> }</div> +<div class="line"> <span class="keywordflow">else</span></div> +<div class="line"> {</div> +<div class="line"> <span class="comment">/* not able to allocate enough memory for the message - wait until App_OnAmsTxMessageFreed() */</span></div> +<div class="line"> }</div> +<div class="line"> }</div> +<div class="line">}</div> +</div><!-- fragment --><p>After completed transmission, the Application Message Service will invoke the callback function that was passed to <a class="el" href="group___g___u_c_s___a_m_s_ga6486fc060d0aa8b1bb34851d2e63b755.html#ga6486fc060d0aa8b1bb34851d2e63b755" title="Transmits an application message.">Ucs_AmsTx_SendMsg()</a>. The application is responsible to free or reuse the external payload. The Application Message Service will no longer access it.</p> +<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> App_OnTxStringComplete(<a class="code" href="struct_ucs___ams_tx___msg__t.html" title="Application message Tx type.">Ucs_AmsTx_Msg_t</a>* msg_ptr, <a class="code" href="group___g___u_c_s___a_m_s___t_y_p_e_s_ga36b630c866dc0c03134f60e98be39f0b.html#ga36b630c866dc0c03134f60e98be39f0b" title="Transmission result of an application message.">Ucs_AmsTx_Result_t</a> result, <a class="code" href="group___g___u_c_s___a_m_s___t_y_p_e_s_ga667b741121fdfbda2fe19fa23ffc7479.html#ga667b741121fdfbda2fe19fa23ffc7479" title="Detailed INIC transmission information which might be useful for debugging purposes.">Ucs_AmsTx_Info_t</a> info)</div> +<div class="line">{</div> +<div class="line"> uint8_t* payload_ptr;</div> +<div class="line"> </div> +<div class="line"> <span class="comment">/* ... handle transmission result ... */</span></div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">if</span> (msg_ptr-><a class="code" href="struct_ucs___ams_tx___msg__t_a6166cef59cbe432be35512925debeae6.html#a6166cef59cbe432be35512925debeae6" title="Payload data.">data_ptr</a> == my_string) <span class="comment">/* message object has shared string resource ? */</span></div> +<div class="line"> {</div> +<div class="line"> string_in_use = <span class="keyword">false</span>; <span class="comment">/* unlock string usage */</span></div> +<div class="line"> }</div> +<div class="line">}</div> +</div><!-- fragment --><h1>Reception of Messages</h1> +<p>By calling <a class="el" href="struct_ucs___ams_rx___init_data__t_a94cec5846cb407141e9c1e1a2ea205d3.html#a94cec5846cb407141e9c1e1a2ea205d3">ams.rx.message_received_fptr()</a> the AMS notifies that a new Rx message was received and has been added to the Rx queue. It is recommended that the application processes the Rx queue asynchronously, i.e., not within the <a class="el" href="struct_ucs___ams_rx___init_data__t_a94cec5846cb407141e9c1e1a2ea205d3.html#a94cec5846cb407141e9c1e1a2ea205d3">ams.rx.message_received_fptr()</a>. Therefore, the AMS provides the functions <a class="el" href="group___g___u_c_s___a_m_s_gab096e481474195cc57d4d801f1d295f2.html#gab096e481474195cc57d4d801f1d295f2" title="Retrieves a reference to the front-most message in the Rx queue.">Ucs_AmsRx_PeekMsg()</a>, <a class="el" href="group___g___u_c_s___a_m_s_ga6f571e2e15fac1e4be068cdf0ccac44d.html#ga6f571e2e15fac1e4be068cdf0ccac44d" title="Removes and frees the front-most message from the Rx queue.">Ucs_AmsRx_ReleaseMsg()</a> and <a class="el" href="group___g___u_c_s___a_m_s_ga9fe2ca761b3856b5e7c3446cc49e90ad.html#ga9fe2ca761b3856b5e7c3446cc49e90ad" title="Retrieves the number of messages that are located in the Rx queue.">Ucs_AmsRx_GetMsgCnt()</a>. The example shows that the callback function is implemented to set the variable <code>_process_rx</code> to <code>true</code>. The following main loop will process Rx messages if the variable is set. Instead of implementing the callback function it is also possible to use <a class="el" href="group___g___u_c_s___a_m_s_ga9fe2ca761b3856b5e7c3446cc49e90ad.html#ga9fe2ca761b3856b5e7c3446cc49e90ad" title="Retrieves the number of messages that are located in the Rx queue.">Ucs_AmsRx_GetMsgCnt()</a> to retrieve the number of available messages in the Rx queue.</p> +<div class="fragment"><div class="line"><span class="keywordtype">void</span> App_OnAmsRxComplete(<span class="keywordtype">void</span>)</div> +<div class="line">{</div> +<div class="line"> <span class="comment">/* A new application message was received. */</span></div> +<div class="line"> <span class="comment">/* Trigger an event to process the Rx queue asynchronously. */</span></div> +<div class="line">} </div> +<div class="line"></div> +<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)</div> +<div class="line">{</div> +<div class="line"> <span class="comment">/* initialization */</span></div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">while</span> (_running)</div> +<div class="line"> {</div> +<div class="line"> <span class="comment">/* ... */</span> <span class="comment">/* driving UNICENS and low-level driver */</span></div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">if</span> (<a class="code" href="group___g___u_c_s___a_m_s_ga9fe2ca761b3856b5e7c3446cc49e90ad.html#ga9fe2ca761b3856b5e7c3446cc49e90ad" title="Retrieves the number of messages that are located in the Rx queue.">Ucs_AmsRx_GetMsgCnt</a>() > 0U) <span class="comment">/* process all Rx messages in AMS queue */</span></div> +<div class="line"> {</div> +<div class="line"> <a class="code" href="struct_ucs___ams_rx___msg__t.html" title="Application message Rx type.">Ucs_AmsRx_Msg_t</a> *msg_ptr;</div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">for</span> (msg_ptr = <a class="code" href="group___g___u_c_s___a_m_s_gab096e481474195cc57d4d801f1d295f2.html#gab096e481474195cc57d4d801f1d295f2" title="Retrieves a reference to the front-most message in the Rx queue.">Ucs_AmsRx_PeekMsg</a>(); msg_ptr != NULL; msg_ptr = <a class="code" href="group___g___u_c_s___a_m_s_gab096e481474195cc57d4d801f1d295f2.html#gab096e481474195cc57d4d801f1d295f2" title="Retrieves a reference to the front-most message in the Rx queue.">Ucs_AmsRx_PeekMsg</a>())</div> +<div class="line"> {</div> +<div class="line"> uint16_t cnt;</div> +<div class="line"></div> +<div class="line"> (void)printf(<span class="stringliteral">"AMS RX: from %04X -> ID-%04X [ "</span>, msg_ptr-><a class="code" href="struct_ucs___ams_rx___msg__t_abb27f24f389ff3575a5ee33e74e66eb6.html#abb27f24f389ff3575a5ee33e74e66eb6" title="Source address.">source_address</a>, msg_ptr-><a class="code" href="struct_ucs___ams_rx___msg__t_a689014fc11d4f26d264ddae2eaebc9d8.html#a689014fc11d4f26d264ddae2eaebc9d8" title="16bit message descriptor">msg_id</a>);</div> +<div class="line"> <span class="keywordflow">for</span> (cnt = 0U; cnt < msg_ptr-><a class="code" href="struct_ucs___ams_rx___msg__t_aae6bdbdf6ea1ad3da5af37f0a91d3ea0.html#aae6bdbdf6ea1ad3da5af37f0a91d3ea0" title="Payload size in bytes.">data_size</a>; cnt++)</div> +<div class="line"> {</div> +<div class="line"> (void)printf(<span class="stringliteral">"%02X "</span>, msg_ptr-><a class="code" href="struct_ucs___ams_rx___msg__t_a6166cef59cbe432be35512925debeae6.html#a6166cef59cbe432be35512925debeae6" title="Reference to payload.">data_ptr</a>[cnt]);</div> +<div class="line"> }</div> +<div class="line"> (void)printf(<span class="stringliteral">"]\n"</span>);</div> +<div class="line"></div> +<div class="line"> <span class="comment">/* ... */</span> <span class="comment">/* process message now */</span></div> +<div class="line"></div> +<div class="line"> <a class="code" href="group___g___u_c_s___a_m_s_ga6f571e2e15fac1e4be068cdf0ccac44d.html#ga6f571e2e15fac1e4be068cdf0ccac44d" title="Removes and frees the front-most message from the Rx queue.">Ucs_AmsRx_ReleaseMsg</a>(); <span class="comment">/* free message and remove it from the queue */</span> </div> +<div class="line"> }</div> +<div class="line"> }</div> +<div class="line"> }</div> +<div class="line"></div> +<div class="line"> <span class="keywordflow">return</span> 0;</div> +<div class="line">}</div> +</div><!-- fragment --><p>The asynchronous processing of the AMS Rx queue provides a comfortable way to process messages at the best moment for the application. During high message load it is possible that the application is not able to respond to a message immediately. In that case the application shall not call <a class="el" href="group___g___u_c_s___a_m_s_ga6f571e2e15fac1e4be068cdf0ccac44d.html#ga6f571e2e15fac1e4be068cdf0ccac44d" title="Removes and frees the front-most message from the Rx queue.">Ucs_AmsRx_ReleaseMsg()</a>. Later, when it is able to process the message it can retrieve the same Rx message object by calling <a class="el" href="group___g___u_c_s___a_m_s_gab096e481474195cc57d4d801f1d295f2.html#gab096e481474195cc57d4d801f1d295f2" title="Retrieves a reference to the front-most message in the Rx queue.">Ucs_AmsRx_PeekMsg()</a>.</p> +<dl class="section note"><dt>Note</dt><dd>It is possible that <a class="el" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_ga649fb9128df6f634fc86aa03b374d822.html#ga649fb9128df6f634fc86aa03b374d822" title="The application must call this function cyclically to drive UNICENS.">Ucs_Service()</a> flushes the AMS Rx queue. Hence, a reference returned by <a class="el" href="group___g___u_c_s___a_m_s_gab096e481474195cc57d4d801f1d295f2.html#gab096e481474195cc57d4d801f1d295f2" title="Retrieves a reference to the front-most message in the Rx queue.">Ucs_AmsRx_PeekMsg()</a> may become invalid during the call of <a class="el" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_ga649fb9128df6f634fc86aa03b374d822.html#ga649fb9128df6f634fc86aa03b374d822" title="The application must call this function cyclically to drive UNICENS.">Ucs_Service()</a>. It is recommended to call <a class="el" href="group___g___u_c_s___a_m_s_gab096e481474195cc57d4d801f1d295f2.html#gab096e481474195cc57d4d801f1d295f2" title="Retrieves a reference to the front-most message in the Rx queue.">Ucs_AmsRx_PeekMsg()</a>, do the Rx message processing and call <a class="el" href="group___g___u_c_s___a_m_s_ga6f571e2e15fac1e4be068cdf0ccac44d.html#ga6f571e2e15fac1e4be068cdf0ccac44d" title="Removes and frees the front-most message from the Rx queue.">Ucs_AmsRx_ReleaseMsg()</a> in one go. If the application does not call <a class="el" href="group___g___u_c_s___a_m_s_ga6f571e2e15fac1e4be068cdf0ccac44d.html#ga6f571e2e15fac1e4be068cdf0ccac44d" title="Removes and frees the front-most message from the Rx queue.">Ucs_AmsRx_ReleaseMsg()</a> because it cannot finish the message processing, it is recommended to retry <a class="el" href="group___g___u_c_s___a_m_s_gab096e481474195cc57d4d801f1d295f2.html#gab096e481474195cc57d4d801f1d295f2" title="Retrieves a reference to the front-most message in the Rx queue.">Ucs_AmsRx_PeekMsg()</a> when message processing is possible again.</dd></dl> +<table class="mns_ic_table"> +<tr> +<td id="mns_ic_api"> </td><td>See also <em>API Reference</em>, section <a class="el" href="group___g___u_c_s___a_m_s.html">Application Message Service</a>. </td></tr> +</table> +</div></div><!-- contents --> +</div><!-- doc-content --> +<!-- start footer part --> +<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> + <ul> + <li class="footer">© 2017 Microchip Technology Inc. All rights reserved. <a href="http://www.microchip.com" target="_blank">www.microchip.com</a></li> + </ul> +</div> +</body> +<!-- +Generated on Mon Apr 3 2017 13:52:59 for UNICENS by +Doxygen 1.8.2 +--> +<script language="javascript"> +<!-- +$('#MSearchResults').wrap('<div style="position: absolute; margin-left: 444px;"></div>'); +--> +</script> +</html> |