forked from RedhawkSDR/Documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmainch6.html
404 lines (389 loc) · 20.2 KB
/
mainch6.html
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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html >
<head><title>6 Devices</title>
<meta http-equiv="Content-Type" content="text/html; charset="utf-8"">
<meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)">
<meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)">
<!-- html,2,next,javascript,charset="utf-8" -->
<meta name="src" content="main.tex">
<meta name="date" content="2013-03-12 19:46:00">
<link rel="stylesheet" type="text/css" href="main.css">
<script type="text/javascript" src="scripts/shCore.js"></script>
<script type="text/javascript" src="scripts/shBrushCpp.js"></script>
<script type="text/javascript" src="scripts/shBrushJava.js"></script>
<script type="text/javascript" src="scripts/shBrushPython.js"></script>
<script type="text/javascript" src="scripts/shBrushBash.js"></script>
<script type="text/javascript" src="scripts/shBrushXml.js"></script>
<link href="styles/shCore.css" rel="stylesheet" type="text/css" />
<link href="styles/shThemeDefault.css" rel="stylesheet" type="text/css" />
<script type="text/javascript">
SyntaxHighlighter.all()
</script>
</head><body
>
<script>
function f() {
document.getElementById('main_content_wrap').focus();
}
if (window.addEventListener) {
window.addEventListener("load", f, false);
} else if (window.attachEvent) {
window.attachEvent("onload", f);
}
</script>
<div class="header">
<ul class="navbar">
<li><a class="logo-small" href="index.html"><img src="images/RedHawk_Logo_ALT_B_121px.png"/></a></li> <li><a href="index.html">Home</a></li>
<li><a href="gettingstarted/main.html">Getting Started</a></li>
<li><a class="active" href="main.html">Documentation</a></li>
<li><a href="download.html">Download</a></li>
<li><a href="support.html">Support</a></li>
</ul>
<div class="pattern right"></div>
<a id="forkme_banner" href="https://github.com/redhawksdr">View on GitHub</a>
</div>
<!-- Custom MAIN CONTENT -->
<div id="main_content_wrap" tabindex="0" class="outer">
<section id="main_content" class="inner">
<!--l. 1--><div class="crosslinks"><p class="noindent">[<a
href="mainch7.html" >next</a>] [<a
href="mainch5.html" >prev</a>] [<a
href="mainch5.html#tailmainch5.html" >prev-tail</a>] [<a
href="#tailmainch6.html">tail</a>] [<a
href="main.html#mainch6.html" >up</a>] </p></div>
<h2 class="chapterHead"><span class="titlemark">Chapter 6</span><br /><a
id="x8-870006"></a>Devices</h2>
<h3 class="sectionHead"><span class="titlemark">6.1 </span> <a
id="x8-880006.1"></a>Introduction</h3>
<!--l. 6--><p class="noindent" ><a
href="mainli2.html#glo:device">Devices</a> are proxies that run on a host but interact with installed hardware.
<!--l. 8--><p class="noindent" >The <a
href="mainap3.html#sca">SCA</a> defines three <span
class="cmtt-12">Device </span>class types:
<!--l. 10--><p class="noindent" >
<ol class="enumerate1" >
<li
class="enumerate" id="x8-88002x1"><a
href="mainli2.html#glo:device">Device</a>
</li>
<li
class="enumerate" id="x8-88004x2">Loadable <a
href="mainli2.html#glo:device">Device</a>, which inherits from <a
href="mainli2.html#glo:device">Device</a>
</li>
<li
class="enumerate" id="x8-88006x3">Executable <a
href="mainli2.html#glo:device">Device</a>, which inherits from Loadable <a
href="mainli2.html#glo:device">Device</a></li></ol>
<!--l. 15--><p class="noindent" >All of these classes inherit from the <span
class="cmtt-12">Resource </span>class, making them similar to <a
href="mainli2.html#glo:component">Components</a> in
their basic lifecycle. This chapter discuss the methods that each of the above classes
defines.
<!--l. 18--><p class="noindent" >It is expected that developers will define their own <a
href="mainli2.html#glo:device">Devices</a> that will implement a customized
version of each of these methods. REDHAWK provides a General Purpose Processor (<a
href="mainap3.html#gpp">GPP</a>), which
is an Executable <a
href="mainli2.html#glo:device">Device</a> that serves as a useful implementation example. Note that the <a
href="mainap3.html#gpp">GPP</a> is
written in Python. It is often the case that <a
href="mainli2.html#glo:device">Devices</a> (being hardware proxies rather than actual
hardware) do not execute performance-critical tasks, since the primary goal of the <a
href="mainap3.html#gpp">GPP</a> <a
href="mainli2.html#glo:device">Device</a> is
to spawn off <a
href="mainli2.html#glo:component">Component</a> processes. Because of this, a higher-level language provides sufficient
performance.
<!--l. 24--><p class="noindent" >Section 3.1.3.3 (<a
href="mainli2.html#glo:device">Device</a> Interfaces) of the <a
href="mainap3.html#sca">SCA</a> 2.2.2 specification may also prove useful in
understanding the expected roles and behaviors of the various <a
href="mainli2.html#glo:device">Device</a> types.
<!--l. 26--><p class="noindent" >
<h3 class="sectionHead"><span class="titlemark">6.2 </span> <a
id="x8-890006.2"></a>Device</h3>
<!--l. 27--><p class="noindent" >The Basic <a
href="mainli2.html#glo:device">Device</a> methods are <span
class="cmtt-12">allocateCapacity() </span>and <span
class="cmtt-12">deallocateCapacity()</span>. These methods
facilitate <a
href="mainli2.html#glo:device">Device</a> management of available capacities so that the <a
href="mainli2.html#glo:applicationfactory">Application Factory</a> can determine
the suitability for deployment of a <a
href="mainli2.html#glo:component">Component</a> on a particular <a
href="mainli2.html#glo:device">Device</a>. A <a
href="mainli2.html#glo:component">Component</a> can specify
the need for a particular quantity of a specific resource, such as memory available, in order for it
to be deployed on particular <a
href="mainli2.html#glo:device">Device</a>. This allows hardware resources to be monitored
as they are allocated to different <a
href="mainli2.html#glo:component">Components</a> and <a
href="mainli2.html#glo:application">Applications</a> to prevent allocation
failure and to ensure that <a
href="mainli2.html#glo:component">Components</a> will have the capacity they need to operate
properly.
<!--l. 32--><p class="noindent" ><a
href="mainli2.html#glo:device">Devices</a> also need to maintain the current state of the hardware through <span
class="cmtt-12">usageState </span>(<span
class="cmtt-12">IDLE</span>,
<span
class="cmtt-12">ACTIVE </span>or <span
class="cmtt-12">BUSY</span>), <span
class="cmtt-12">adminState </span>(<span
class="cmtt-12">LOCKED</span>, <span
class="cmtt-12">UNLOCKED </span>or <span
class="cmtt-12">SHUTTING</span><span
class="cmtt-12">_DOWN</span>), and <span
class="cmtt-12">operationalState</span>
(<span
class="cmtt-12">ENABLED </span>or <span
class="cmtt-12">DISABLED</span>).
<!--l. 34--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">6.2.1 </span> <a
id="x8-900006.2.1"></a><span
class="cmtt-12">allocateCapacity()</span></h4>
<!--l. 35--><p class="noindent" >In REDHAWK 1.8, the implementation of capacity allocation for C++ and Java <a
href="mainli2.html#glo:device">Devices</a> vary in
comparison to that of Python <a
href="mainli2.html#glo:device">Devices</a>. Python <a
href="mainli2.html#glo:device">Devices</a> provide an additional level of support that
is not provided in C++ and Java <a
href="mainli2.html#glo:device">Devices</a>.
<!--l. 38--><p class="noindent" >An allocatable capacity is defined as a <a
href="mainli2.html#glo:property">Property</a> in the <a
href="mainli2.html#glo:device">Device</a>’s <a
href="mainap3.html#prf">PRF</a> file.
<!--l. 40--><p class="noindent" >Below is an example of an allocation <a
href="mainli2.html#glo:property">Property</a> in the <a
href="mainap3.html#gpp">GPP</a>’s <a
href="mainap3.html#prf">PRF</a> <a
href="mainap3.html#xml">XML</a> file:
<script type="syntaxhighlighter" class="brush: xml"><![CDATA[
<simple id="DCE:8dcef419-b440-4bcf-b893-cab79b6024fb"
mode="readwrite" name="memCapacity" type="long">
<description>Amount of RAM in the GPP not allocated to
an application</description>
<units>MiB</units>
<kind kindtype="allocation"/>
<kind kindtype="event"/>
<action type="external"/>
</simple>
]]></script>
<!--l. 54--><p class="noindent" >
<h5 class="subsubsectionHead"><a
id="x8-910006.2.1"></a>C++ and Java Device Capacity Allocation</h5>
<!--l. 55--><p class="noindent" >When the <a
href="mainli2.html#glo:applicationfactory">Application Factory</a> calls the <span
class="cmtt-12">allocateCapacity() </span>method on a <a
href="mainli2.html#glo:device">Device</a>, it provides the
type and the amount of a resource that is requested. For example, the <a
href="mainli2.html#glo:applicationfactory">Application Factory</a> may
call <span
class="cmtt-12">allocateCapacity() </span>to allocate 1 MB of memory on a <a
href="mainli2.html#glo:device">Device</a>. The <span
class="cmtt-12">allocateCapacity()</span>
method simply checks to see if the requested amount of memory is less than the available
memory. If so, the amount of memory is decremented by the amount requested and the
<span
class="cmtt-12">allocateCapacity() </span>method returns true. The <span
class="cmtt-12">allocateCapacity() </span>will return false if it does
not have the capacity for the request.
<!--l. 61--><p class="noindent" >If a developer wishes to implement different behavior in C++ or Java <a
href="mainli2.html#glo:device">Devices</a>, the
<span
class="cmtt-12">allocateCapacity() </span>method may be overridden in their <a
href="mainli2.html#glo:device">Device</a> implementation.
<!--l. 63--><p class="noindent" >
<h5 class="subsubsectionHead"><a
id="x8-920006.2.1"></a>Python Device Capacity Allocation</h5>
<!--l. 64--><p class="noindent" >The <span
class="cmtt-12">Device </span>base class in device.py (distributed as a part of the REDHAWK Core Framework)
provides a means for defining custom allocate methods for particular allocation <a
href="mainli2.html#glo:property">Properties</a>. To do
so, a method is added to the <a
href="mainli2.html#glo:device">Device</a> implementation named <span
class="cmtt-12">allocate</span><span
class="cmtt-12">_ </span>followed by the name of the
allocation <a
href="mainli2.html#glo:property">Property</a>. The example code below demonstrates the <span
class="cmtt-12">allocation() </span>method for the
<span
class="cmtt-12">memCapacity </span>allocation <a
href="mainli2.html#glo:property">Property</a> of the <a
href="mainap3.html#gpp">GPP</a>.
<script type="syntaxhighlighter" class="brush: python"><![CDATA[
# overrides allocateCapacity for memCapacity
def allocate_memCapacity(self, value):
# see if calculated capacity and measured capacity
# is available
if value > self.memCapacity or value > self.memFree:
return False
self.memCapacity = self.memCapacity - value
self._log.debug("Remaining capacity %s", self.memCapacity)
return True
]]></script>
<!--l. 82--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">6.2.2 </span> <a
id="x8-930006.2.2"></a><span
class="cmtt-12">deallocateCapacity()</span></h4>
<!--l. 83--><p class="noindent" >
<h5 class="subsubsectionHead"><a
id="x8-940006.2.2"></a>C++ and Java Capacity Deallocation</h5>
<!--l. 84--><p class="noindent" >The <span
class="cmtt-12">deallocateCapacity() </span>method essentially reverses the process implemented in
the <span
class="cmtt-12">allocateCapacity() </span>method (i.e., the available capacity for the given resource is
incremented).
<!--l. 86--><p class="noindent" >
<h5 class="subsubsectionHead"><a
id="x8-950006.2.2"></a>Python deallocate_ Methods</h5>
<!--l. 87--><p class="noindent" >Similar to the Python <a
href="mainli2.html#glo:device">Device</a>’s support for custom allocation methods, custom deallocation
methods may be created by adding a method named <span
class="cmtt-12">deallocate</span><span
class="cmtt-12">_ </span>followed by the allocation
<a
href="mainli2.html#glo:property">Property</a> name. The example code below demonstrates the <span
class="cmtt-12">deallocation() </span>method for the
<span
class="cmtt-12">memCapacity </span>allocation <a
href="mainli2.html#glo:property">Property</a> of the <a
href="mainap3.html#gpp">GPP</a>.
<script type="syntaxhighlighter" class="brush: python"><![CDATA[
# overrides deallocateCapacity for memCapacity
def deallocate_memCapacity(self, value):
self._log.debug("deallocate_memCapacity(%s)", value)
# make sure this is not over the actual capacity
# (due to an update of the memThreshold)
if self.memCapacity + value > self.memThresholdValue:
self.memCapacity = self.memThresholdValue
else:
self.memCapacity = self.memCapacity + value
self._log.debug("Remaining capacity %s", self.memCapacity)
]]></script>
<!--l. 103--><p class="noindent" >
<h3 class="sectionHead"><span class="titlemark">6.3 </span> <a
id="x8-960006.3"></a>Loadable Device</h3>
<!--l. 104--><p class="noindent" >The Loadable <a
href="mainli2.html#glo:device">Device</a> methods, <span
class="cmtt-12">load() </span>and <span
class="cmtt-12">unload()</span>, facilitate file copying from the File System
to the physical hardware represented by the <a
href="mainli2.html#glo:device">Device</a> proxy. This ability is commonly used to
manage <a
href="mainli2.html#glo:component">Components</a> binaries. During the runtime, a cache for each <a
href="mainli2.html#glo:device">Device</a> is created at its File
System’s mount point.
<!--l. 108--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">6.3.1 </span> <a
id="x8-970006.3.1"></a><span
class="cmtt-12">load()</span></h4>
<!--l. 109--><p class="noindent" >When the <span
class="cmtt-12">load() </span>method is called on a Loadable <a
href="mainli2.html#glo:device">Device</a>, the Loadable <a
href="mainli2.html#glo:device">Device</a> copies the file
indicated by the provided filename onto the hardware that the proxy represents. If the Loadable
<a
href="mainli2.html#glo:device">Device</a> is also an Executable <a
href="mainli2.html#glo:device">Device</a>, this method may be a prerequisite to calling the <span
class="cmtt-12">execute()</span>
method.
<!--l. 112--><p class="noindent" >For example, a Loadable <a
href="mainli2.html#glo:device">Device</a> <span
class="cmtt-12">Foo </span>is a proxy for a receiver <span
class="cmtt-12">Bar</span>, <span
class="cmtt-12">Foo</span>’s <span
class="cmtt-12">load() </span>method must
support copying the local code (perhaps on a desktop computer) to be run on the receiver to the
<span
class="cmtt-12">Bar</span>’s file system.
<!--l. 114--><p class="noindent" >In the case of the <a
href="mainap3.html#gpp">GPP</a>, the executable files associated with a <a
href="mainli2.html#glo:component">Component</a>
are copied to the directory associated with the running <a
href="mainap3.html#gpp">GPP</a> <a
href="mainli2.html#glo:device">Device</a> (e.g.,
<span
class="cmtt-12">$SDRROOT/dev/.DeviceManager</span><span
class="cmtt-12">_/GPP</span><span
class="cmtt-12">_1/component/myComponent/myComponent.py</span>).
<!--l. 116--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">6.3.2 </span> <a
id="x8-980006.3.2"></a><span
class="cmtt-12">unload()</span></h4>
<!--l. 117--><p class="noindent" >The <span
class="cmtt-12">unload() </span>method removes loaded files from the physical device that the Loadable <a
href="mainli2.html#glo:device">Device</a>
proxy represents.
<!--l. 119--><p class="noindent" >
<h3 class="sectionHead"><span class="titlemark">6.4 </span> <a
id="x8-990006.4"></a>Executable Device</h3>
<!--l. 120--><p class="noindent" >The Executable <a
href="mainli2.html#glo:device">Device</a> methods, <span
class="cmtt-12">execute() </span>and <span
class="cmtt-12">terminate()</span>, take care of the life cycle of an
executable program that is run on the <a
href="mainli2.html#glo:device">Device</a> hardware. They provide a mechanism for starting up
and executing a software process or thread on a <a
href="mainli2.html#glo:device">Device</a>.
<!--l. 123--><p class="noindent" >If the <a
href="mainli2.html#glo:device">Device</a> is running the Linux <a
href="mainap3.html#os">OS</a>, the <span
class="cmtt-12">execute() </span>method will call a <span
class="cmtt-12">fork() </span>function to start a
<a
href="mainli2.html#glo:component">Component</a> process. For Executable <a
href="mainli2.html#glo:device">Devices</a> that do not execute code using a <span
class="cmtt-12">fork() </span>statement,
the developer would be required to implement the necessary code for executing a <a
href="mainli2.html#glo:component">Component</a>
process for the particular <a
href="mainli2.html#glo:device">Device</a>’s hardware implementation.
<!--l. 126--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">6.4.1 </span> <a
id="x8-1000006.4.1"></a><span
class="cmtt-12">execute()</span></h4>
<!--l. 127--><p class="noindent" >The <span
class="cmtt-12">execute() </span>method is called by the <a
href="mainli2.html#glo:applicationfactory">Application Factory</a> when a <a
href="mainli2.html#glo:component">Component</a> process needs to
be started. In the case of the <a
href="mainap3.html#gpp">GPP</a> <a
href="mainli2.html#glo:device">Device</a>, the <span
class="cmtt-12">execute() </span>method uses the provides arguments
(indicating the <a
href="mainli2.html#glo:component">Component</a> name and <a
href="mainli2.html#glo:property">Property</a> overrides from the <a
href="mainap3.html#sad">SAD</a> file) to formulate a Linux
command-line execution statement. After starting the <a
href="mainli2.html#glo:component">Component</a> process, the <a
href="mainli2.html#glo:device">Device</a> returns to
wait for commands.
<!--l. 131--><p class="noindent" >
<h4 class="subsectionHead"><span class="titlemark">6.4.2 </span> <a
id="x8-1010006.4.2"></a><span
class="cmtt-12">terminate()</span></h4>
<!--l. 132--><p class="noindent" >The <span
class="cmtt-12">terminate() </span>method exists to kill processes that have been started by the <a
href="mainli2.html#glo:device">Device</a>. In the
example of the <a
href="mainap3.html#gpp">GPP</a> <a
href="mainli2.html#glo:device">Device</a>, the <span
class="cmtt-12">terminate() </span>method simply sends a kill command to the given
Process Identifier (<a
href="mainap3.html#pid">PID</a>) and waits for it to die.
<!--l. 1--><div class="crosslinks"><p class="noindent">[<a
href="mainch7.html" >next</a>] [<a
href="mainch5.html" >prev</a>] [<a
href="mainch5.html#tailmainch5.html" >prev-tail</a>] [<a
href="mainch6.html" >front</a>] [<a
href="main.html#mainch6.html" >up</a>] </p></div>
<!--l. 1--><p class="noindent" ><a
id="tailmainch6.html"></a>
<div class=license>
<hr>
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/deed.en_US"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/80x15.png" /></a><br /><span xmlns:dct="http:// purl.org/dc/terms/" property="dct:title">REDHAWK Documentation</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/deed.en_US">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
</div>
</body></html>