1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<!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: Preparations</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__p_r_e_p.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">Preparations </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The following figure shows the directory structure of the extracted source package. It is recommended to keep the folder structure as is. This will simplify version updates in future.</p>
<table style="border:0px">
<tr>
<td><div class="image">
<img src="release_package_directory.png" alt="release_package_directory.png"/>
</div>
</td></tr>
</table>
<p><br/>
</p>
<table class="doxtable">
<tr>
<th>Folder </th><th>Description</th></tr>
<tr>
<td><code>cfg</code> </td><td>Contains configuration files that can be customized by the user. </td></tr>
<tr>
<td><code>doc</code> </td><td>Contains the online documentation. </td></tr>
<tr>
<td><code>inc</code> </td><td>Contains the C header files. </td></tr>
<tr>
<td><code>src</code> </td><td>Contains the C source files. </td></tr>
</table>
<h1>Data Types</h1>
<p>Data types must be defined within the header file <code>cfg/ucs_types_cfg.h</code>. The easiest way to make the data types available is to include the standard library <code><stdint.h></code>. If the compiler does not provide this library the following data types must be defined by the application.</p>
<table class="doxtable">
<tr>
<th>Data Type </th><th>Definition</th></tr>
<tr>
<td><code>int8_t</code> </td><td>Signed integer, 8 bit </td></tr>
<tr>
<td><code>int16_t</code> </td><td>Signed integer, 16 bit </td></tr>
<tr>
<td><code>int32_t</code> </td><td>Signed integer, 32 bit </td></tr>
<tr>
<td><code>uint8_t</code> </td><td>Unsigned integer, 8 bit </td></tr>
<tr>
<td><code>uint16_t</code> </td><td>Unsigned integer, 16 bit </td></tr>
<tr>
<td><code>uint32_t</code> </td><td>Unsigned integer, 32 bit </td></tr>
</table>
<p>The data type <code>size_t</code> is required for results of <code>sizeof()</code> operations. Typically <code>size_t</code> is define in <stddef.h>.</p>
<table class="doxtable">
<tr>
<th>Data Type </th><th>Definition</th></tr>
<tr>
<td><code>size_t</code> </td><td>Result of <code>sizeof()</code> operator </td></tr>
</table>
<p>For boolean types the definition of <code>bool</code> has to be taken from <code><stdbool.h></code>. If this library is not available, the application has to define its own boolean data type based on an unsigned, 8-bit integer.</p>
<table class="doxtable">
<tr>
<th>Data Type </th><th>Definition</th></tr>
<tr>
<td><code>bool</code> </td><td>Unsigned integer, 8 bit </td></tr>
</table>
<p>In conjunction with boolean variables and constants the constants <code>true</code> and <code>false</code> must be used exclusively. These constants are also defined in <code><stdbool.h></code>. If the library is not available, the following macros must be defined by the application.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define true ((bool)1)</span></div>
<div class="line"><span class="preprocessor">#define false ((bool)0)</span></div>
</div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>If the library is compiled under C++ the definition of <code>bool</code>, <code>true</code> and <code>false</code> must be adapted to the boolean data type used by that compiler.</dd></dl>
<h1>Thread Safety</h1>
<p>The library is not thread-safe. I.e., the configuration does not support the definition of mutexes and cannot handle calls from different thread contexts. Hence, the application has to ensure that the library is invoked correctly. This can be reached by the following approaches:</p>
<ul>
<li>The application must call the UNICENS API always from the same thread (recommended).</li>
<li>The application must protect every UNICENS API call by mutexes or semaphores to avoid that concurrent threads access the API at the same time. Please note: API callback functions are invoked by ongoing API call. It is recommended to use context sensitive mutexes or to avoid further API calls from within an API callback function.</li>
</ul>
<h1>Static Configurations</h1>
<p>The library provides some static configuration settings that must be specified at compile time. These settings are part of the file <code>cfg/ucs_cfg.h</code> and are pre-defined to default values. Hence, adjustment may be done when needed. The following settings are examples for the static configuration.</p>
<ul>
<li>Define the maximum number of API instances that are available within one process.</li>
<li>Define the maximum number of remote nodes to be configured.</li>
<li>Define the number of Tx and Rx application messages that can be processed at a moment and the according payload size per message.</li>
<li>Enable/disable the library trace output.</li>
</ul>
<h1>Include Header File</h1>
<p>To access the UNICENS API, the application must solely include the header file <code>ucs_api.h</code>.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "ucs_api.h"</span> <span class="comment">/* include the UNICENS header file */</span></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">/* ... */</span></div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --><h1>64-bit Support</h1>
<p>The UNICENS library is designed portable and thus supports also 64-bit systems. Platform dependent settings can be modified in the configuration files. Please check the following settings to ensure that the configuration files are well adopted for a 64-bit system:</p>
<ul>
<li>Check if data type definitions in <code>cfg/ucs_types_cfg.h</code> are correct.</li>
<li>Check if <code>size_t</code> is defined correctly.</li>
<li>If available, please include <code><stdint.h></code> and <code><stddef.h></code> for the target system.</li>
</ul>
</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>
|
