diff options
Diffstat (limited to 'ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__i_n_i_t.html')
| -rw-r--r-- | ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__i_n_i_t.html | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__i_n_i_t.html b/ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__i_n_i_t.html new file mode 100644 index 0000000..838cb1e --- /dev/null +++ b/ucs2-lib/doc/html/_p__u_m__s_t_a_r_t_e_d__i_n_i_t.html @@ -0,0 +1,195 @@ +<!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: Initialization</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__i_n_i_t.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">Initialization </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><h1>Retrieving an API Instance</h1> +<p>UNICENS supports to access multiple instances within one process space. One UNICENS API instance is dedicated to one INIC the associated network. Hence, it is possible to deal with multiple networks within one process space. The maximum number of UNICENS API instances must be configured in <code>ucs_cfg.h</code>.</p> +<p>The following definition configures UNICENS to be used with 2 INICs. </p> +<div class="fragment"><div class="line"><span class="comment">/* Number of API instances which can be created by function Ucs_CreateInstance().</span></div> +<div class="line"><span class="comment"> Valid range: 1..10. Default value: 1.</span></div> +<div class="line"><span class="comment"> */</span></div> +<div class="line"><span class="preprocessor">#define UCS_NUM_INSTANCES 2</span></div> +</div><!-- fragment --><p>Accordingly UNICENS can provide 2 API instances that can be retrieved by calling <a class="el" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_ga85a99b5d236b29e2d598bef51edad638.html#ga85a99b5d236b29e2d598bef51edad638" title="Retrieves a UNICENS API instance.">Ucs_CreateInstance()</a>. The retrieved instance remains valid until the process ends. There is no need to return or re-create an already retrieved instance. The following code shows how to retrieve one API instance.</p> +<div class="fragment"><div class="line"><span class="comment">/* create UNICENS API instance */</span></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_ga074c04d40d00986e0c869adaec8fadda.html#ga074c04d40d00986e0c869adaec8fadda" title="UNICENS instance.">Ucs_Inst_t</a>* inst_ptr = NULL;</div> +<div class="line">inst_ptr = <a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_ga85a99b5d236b29e2d598bef51edad638.html#ga85a99b5d236b29e2d598bef51edad638" title="Retrieves a UNICENS API instance.">Ucs_CreateInstance</a>();</div> +<div class="line"></div> +<div class="line"><span class="keywordflow">if</span> (inst_ptr == NULL)</div> +<div class="line">{</div> +<div class="line"> <span class="comment">/* UNICENS cannot any further API instance.</span></div> +<div class="line"><span class="comment"> Check configuration MACRO UCS_NUM_INSTANCES.</span></div> +<div class="line"><span class="comment"> */</span></div> +<div class="line"> <span class="keywordflow">return</span>; </div> +<div class="line">}</div> +</div><!-- fragment --><h1>Configuration Structure</h1> +<p>The application has to prepare a configuration structure in order to initialize UNICENS. Therefore, it has to provide a <a class="el" href="struct_ucs___init_data__t.html">Ucs_InitData_t</a> variable. It is recommended to set the variable to default values by calling <a class="el" 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>. After that the application shall set specific attributes of the variable. The function <a class="el" 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> can be called at any time and is not bound up with a certain API instance.</p> +<div class="fragment"><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><!-- fragment --><p>After the function returns, the application has to setup the configuration settings. The following section shows an example configuration.</p> +<div class="fragment"><div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_a41f828ebbe67a574ee39abd6c054bb6c.html#a41f828ebbe67a574ee39abd6c054bb6c" title="Optional reference to a user context which is provided within API callback functions.">user_ptr</a> = &my_class;</div> +<div class="line"></div> +<div class="line"><span class="comment">/* General Section */</span></div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_a43e7559dfe1bc2860cb0d2749fa66071.html#a43e7559dfe1bc2860cb0d2749fa66071" title="General initialization data.">general</a>.<a class="code" href="struct_ucs___general___init_data__t_aa197d5a04c7eee7b95eb9e1de232d161.html#aa197d5a04c7eee7b95eb9e1de232d161" title="Mandatory callback function notifying an error that terminates the API.">error_fptr</a> = &App_OnGeneralError;</div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_a43e7559dfe1bc2860cb0d2749fa66071.html#a43e7559dfe1bc2860cb0d2749fa66071" title="General initialization data.">general</a>.<a class="code" href="struct_ucs___general___init_data__t_a4e1140be3951f0e14d4071840f4ebc8e.html#a4e1140be3951f0e14d4071840f4ebc8e" title="Mandatory callback function querying the actual system tick count.">get_tick_count_fptr</a> = &App_OnGetTickCount;</div> +<div class="line"></div> +<div class="line"><span class="comment">/* LLD Section */</span> </div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_ac0b0a4478bafe6e81ed3c3e2c72f4fc9.html#ac0b0a4478bafe6e81ed3c3e2c72f4fc9" title="Comprises assignment to low-level driver communication interfaces.">lld</a>.<a class="code" href="struct_ucs___lld___callbacks__t_a44afa0156353f9fba156ff0c91873968.html#a44afa0156353f9fba156ff0c91873968" title="Optional pointer that is passed when invoking a callback function which is assigned in Ucs_Lld_Callba...">lld_user_ptr</a> = &my_lld_class;</div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_ac0b0a4478bafe6e81ed3c3e2c72f4fc9.html#ac0b0a4478bafe6e81ed3c3e2c72f4fc9" title="Comprises assignment to low-level driver communication interfaces.">lld</a>.<a class="code" href="struct_ucs___lld___callbacks__t_a96bad24b6b49ffacfd9136230447cb22.html#a96bad24b6b49ffacfd9136230447cb22" title="Callback function to initialize the low-level driver and start the transmission and reception of mess...">start_fptr</a> = &Lld_Start;</div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_ac0b0a4478bafe6e81ed3c3e2c72f4fc9.html#ac0b0a4478bafe6e81ed3c3e2c72f4fc9" title="Comprises assignment to low-level driver communication interfaces.">lld</a>.<a class="code" href="struct_ucs___lld___callbacks__t_ab0f955ca90942fda14ac12500422a437.html#ab0f955ca90942fda14ac12500422a437" title="Callback function to stop/abort the transmission and reception of messages.">stop_fptr</a> = &Lld_Stop;</div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_ac0b0a4478bafe6e81ed3c3e2c72f4fc9.html#ac0b0a4478bafe6e81ed3c3e2c72f4fc9" title="Comprises assignment to low-level driver communication interfaces.">lld</a>.<a class="code" href="struct_ucs___lld___callbacks__t_ad8f7d021075e06672a999eb02da1d2e4.html#ad8f7d021075e06672a999eb02da1d2e4" title="Callback function to transmit one or multiple messages to the INIC.">tx_transmit_fptr</a> = &Lld_TxTransmit;</div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_ac0b0a4478bafe6e81ed3c3e2c72f4fc9.html#ac0b0a4478bafe6e81ed3c3e2c72f4fc9" title="Comprises assignment to low-level driver communication interfaces.">lld</a>.<a class="code" href="struct_ucs___lld___callbacks__t_a90fa6db664734c2446327b71c51f5b52.html#a90fa6db664734c2446327b71c51f5b52" title="Callback function which is invoked as soon as Rx message objects are available again.">rx_available_fptr</a> = &Lld_RxMsgAvailable;</div> +<div class="line"></div> +<div class="line"><span class="comment">/* Node Discovery Section */</span> </div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_a97b13c03602cc54884ae1765c518bd7b.html#a97b13c03602cc54884ae1765c518bd7b" title="The initialization data of the Node Discovery.">nd</a>.<a class="code" href="struct_ucs___nd___init_data__t_a98b9ccad2c6c5fa2edaf472151ee853c.html#a98b9ccad2c6c5fa2edaf472151ee853c" title="Callback function reporting the results of the Node Discovery service.">report_fptr</a> = &App_OnNodeDiscoveryResult;</div> +<div class="line">init_data.<a class="code" href="struct_ucs___init_data__t_a97b13c03602cc54884ae1765c518bd7b.html#a97b13c03602cc54884ae1765c518bd7b" title="The initialization data of the Node Discovery.">nd</a>.<a class="code" href="struct_ucs___nd___init_data__t_ab9bc02a84c7daeff234344541d41be62.html#ab9bc02a84c7daeff234344541d41be62" title="Callback function asking for evaluation of the found signature.">eval_fptr</a> = &App_OnNodeDiscoveryEval;</div> +</div><!-- fragment --><h2>User References</h2> +<p>By assigning <a class="el" href="struct_ucs___init_data__t.html">init_data.user_ptr</a> and <a class="el" href="struct_ucs___lld___callbacks__t.html">init_data.lld.lld_user_ptr</a> the application is able assign references of own objects to a certain UNICENS API instance. E.g., when driving 2 API instances the application can assign 2 different LLD objects. When UNICENS invokes LLD callback functions then one argument will provide the assigned lld_user_ptr. The application can simply forward the call to the actual LLD object.</p> +<div class="fragment"><div class="line"><span class="keywordtype">void</span> Lld_TxTransmit(<a class="code" href="struct_ucs___lld___tx_msg__t.html" title="Tx message object providing the raw port message byte stream.">Ucs_Lld_TxMsg_t</a> *msg_ptr, <span class="keywordtype">void</span> *lld_user_ptr)</div> +<div class="line">{</div> +<div class="line"> CMyLldClass *my_lld = (CMyLldClass*)lld_user_ptr;</div> +<div class="line"> my_lld->Transmit(msg_ptr);</div> +<div class="line">}</div> +</div><!-- fragment --><h2>General Configuration</h2> +<p>The callback <code>general.error_fptr()</code> is called if a general error occurs. The callback must adhere to function signature <a class="el" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_ga64926a6a194cfb06703835e3d06475c6.html#ga64926a6a194cfb06703835e3d06475c6">Ucs_ErrorCb_t</a>. If a general error occurs the application must trigger a re-initialization of UNICENS. A simple example implementation is shown below.</p> +<dl class="section note"><dt>Note</dt><dd><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> must not be called within <code>general.error_fptr()</code>!</dd></dl> +<div class="fragment"><div class="line"><span class="keywordtype">void</span> App_OnGeneralError(<a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v___t_y_p_e_s_ga9551cd80ce8a13fa6cce717cbc13e499.html#ga9551cd80ce8a13fa6cce717cbc13e499" title="UNICENS general error codes.">Ucs_Error_t</a> error_code, <span class="keywordtype">void</span> *user_ptr)</div> +<div class="line">{</div> +<div class="line"> printf(<span class="stringliteral">"General Error Occurred (Code: %u).\n\r"</span>, error_code);</div> +<div class="line"> App_TriggerReInit(); <span class="comment">/* cleanup and re-initialize when leaving Ucs_Service() */</span></div> +<div class="line">}</div> +</div><!-- fragment --><h2>Timer Configuration</h2> +<p>The UNICENS timer management requires a timer tick in <b>milliseconds</b> that is gathered via the callback <code>general.get_tick_count_fptr()</code>. The callback must adhere to function signature <a class="el" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v_ga981854177aa9ebd554ab522199193bd3.html#ga981854177aa9ebd554ab522199193bd3">Ucs_GetTickCountCb_t</a>. An example implementation for a <em>Windows</em> platform is shown below.</p> +<div class="fragment"><div class="line">uint16_t App_OnGetTickCount(<span class="keywordtype">void</span> *user_ptr)</div> +<div class="line">{</div> +<div class="line"> DWORD tc = GetTickCount(); <span class="comment">/* Get current tick count in milliseconds */</span></div> +<div class="line"> <span class="keywordflow">return</span> (uint16_t)tc;</div> +<div class="line">}</div> +</div><!-- fragment --><h1>Initialization</h1> +<p>The function <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> must be called by the application to initialize one UNICENS API instance. library. The first argument is the reference to the API instance. The second argument is the reference to the initialization structure. The third argument is optional and can provide the reference to a result callback function. It is highly recommended to use the result callback to be able to handle possible errors during the initialization.</p> +<div class="fragment"><div class="line"><span class="keywordtype">void</span> App_Init(<span class="keywordtype">void</span>)</div> +<div class="line">{</div> +<div class="line"> ...</div> +<div class="line"> </div> +<div class="line"> <span class="keywordflow">if</span>(<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>(inst_ptr, init_data, &App_OnInitResult) != <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"> <span class="comment">/* Handle synchronous initialization errors here... */</span></div> +<div class="line"> }</div> +<div class="line"> ...</div> +<div class="line">}</div> +<div class="line"></div> +<div class="line"><span class="keywordtype">void</span> App_OnInitResult(<a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v___t_y_p_e_s_ga0a933f34b9acbf21dc68f426c324e78c.html#ga0a933f34b9acbf21dc68f426c324e78c" title="Result values of initialization result callback function.">Ucs_InitResult_t</a> result, <span class="keywordtype">void</span> *user_ptr)</div> +<div class="line">{</div> +<div class="line"> <span class="keywordflow">if</span>(result != <a class="code" href="group___g___u_c_s___i_n_i_t___a_n_d___s_r_v___t_y_p_e_s_ga0a933f34b9acbf21dc68f426c324e78c.html#gga0a933f34b9acbf21dc68f426c324e78cac4d2785b5c79a9b38389e08d30494714" title="Initialization succeeded.">UCS_INIT_RES_SUCCESS</a>)</div> +<div class="line"> {</div> +<div class="line"> <span class="comment">/* Handle asynchronous initialization errors here... */</span></div> +<div class="line"> }</div> +<div class="line">}</div> +</div><!-- fragment --> </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> |