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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2K.1beta (1.48)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Necessary Functions</TITLE>
<META NAME="description" CONTENT="Necessary Functions">
<META NAME="keywords" CONTENT="rtic">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="LaTeX2HTML v2K.1beta">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="rtic.css">
<LINK REL="next" HREF="node44.html">
<LINK REL="previous" HREF="node42.html">
<LINK REL="up" HREF="node42.html">
<LINK REL="next" HREF="node44.html">
</HEAD>
<BODY bgcolor="white">
<!--Navigation Panel-->
<A NAME="tex2html592"
HREF="node44.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="/usr/share/latex2html/icons/next.png"></A>
<A NAME="tex2html590"
HREF="node42.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="/usr/share/latex2html/icons/up.png"></A>
<A NAME="tex2html584"
HREF="node42.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
SRC="/usr/share/latex2html/icons/prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html593"
HREF="node44.html">The user_controller.c API</A>
<B> Up:</B> <A NAME="tex2html591"
HREF="node42.html">Generating a user_controller.c File</A>
<B> Previous:</B> <A NAME="tex2html585"
HREF="node42.html">Generating a user_controller.c File</A>
<BR>
<BR>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION00410000000000000000">
Necessary Functions</A>
</H1>
<P>
The user must create a file, <TT>user_controller.c</TT> which must
reside inside of the <TT>rtic-*.*.*/user</TT> directory. The user is
limited to only including the following header files:
<P>
<UL>
<LI><TT>#include ``main.h''</TT>: this header file contains all of the
RTiC-Lab macros and definitions, as described in the next section. It
must be present in ALL <TT>user_controller.c</TT> files.
<P>
</LI>
<LI><TT>#include <IMG
WIDTH="21" HEIGHT="36" ALIGN="MIDDLE" BORDER="0"
SRC="img52.png"
ALT="$<$">math.h<IMG
WIDTH="21" HEIGHT="36" ALIGN="MIDDLE" BORDER="0"
SRC="img53.png"
ALT="$>$"></TT>: this header file is the standard
math library. This include file is optional, and depends on the user's
controller.
</LI>
</UL>
<P>
If you find that you need to include any other include files, then you
are probably doing something wrong. The code that you write here is
going to be inserted into the kernel space of Linux. As a consequence,
there are very limited things that it can do. Thus, you cannot use
any screen I/O commands such as <TT>printf</TT>, nor any dynamic memory
allocation schemes such as <TT>malloc</TT> and <TT>calloc</TT>. In short,
your <TT>user_controller.c</TT> file must contain only mathematical
functions, mathematical manipulation (e.g. <IMG
WIDTH="21" HEIGHT="36" ALIGN="MIDDLE" BORDER="0"
SRC="img54.png"
ALT="$+$">, <IMG
WIDTH="22" HEIGHT="36" ALIGN="MIDDLE" BORDER="0"
SRC="img55.png"
ALT="$-$">, <IMG
WIDTH="16" HEIGHT="40" ALIGN="MIDDLE" BORDER="0"
SRC="img56.png"
ALT="$/$">, <IMG
WIDTH="22" HEIGHT="40" ALIGN="MIDDLE" BORDER="0"
SRC="img57.png"
ALT="$\%$">, etc.),
and the macros supplied by RTiC-Lab.
<P>
The user must then create three functions within this file, none of
which need to be declared:
<P>
<OL>
<LI><TT>int control_init(void)</TT>: This function initializes the
user's controller. More specifically, all of the controller states
need to be initialized in this function. This function is called
immediately after the ``RUN'' button is pressed. The return value of
this function must be either success (0) or failure (-1). If a failure
is detected, then the controller will not run and <TT>xrtic</TT> will a
status error. This function should not take any arguments.
<P>
</LI>
<LI><TT>void control_run(void)</TT>: This function is called once per
period ad infinitum. Therefore, it must contain the actual controller
code necessary to execute the user's controller. This function both
takes in no arguments, and returns nothing.
<P>
</LI>
<LI><TT>int control_stop(void)</TT>: This function is called
immediately after the ``STOP'' button is pressed in case the user
needs to perform any activities after the controller is shutdown. This
function takes no arguments and returns either (0) for success, or (-1)
for failure.
</LI>
</OL>
<P>
Because of the fact that this controller is to be implemented into
kernel space, then the controller designer must keep certain points in mind:
<P>
<OL>
<LI>there is no memory protection. This means that if your code
causes a segmentation fault, then the entire computer will be rendered
unstable, thus requiring that you restart the computer. A test suite,
<TT>test_user_controller</TT> is currently being developed that will
test the user's controller prior to inserting it into kernel
space. However, at this point, this code does not quite perform too
many sanity checks. Consequently, as of the time of this writing, you
are responsible for testing the sanity of your code.
<P>
</LI>
<LI>there is no access to functions such as ``printf''. Therefore,
you must use the <TT>RETURN_VAL</TT> macro (described in the next
section) in order to debug the logic of your code.
</LI>
</OL>
<P>
In order to simplify the code implementation, a simple to use API
(Advanced Programming Interface) has been developed to aid in the
controller implementation. This API is described in detail in what
follows.
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html592"
HREF="node44.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="/usr/share/latex2html/icons/next.png"></A>
<A NAME="tex2html590"
HREF="node42.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="/usr/share/latex2html/icons/up.png"></A>
<A NAME="tex2html584"
HREF="node42.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
SRC="/usr/share/latex2html/icons/prev.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html593"
HREF="node44.html">The user_controller.c API</A>
<B> Up:</B> <A NAME="tex2html591"
HREF="node42.html">Generating a user_controller.c File</A>
<B> Previous:</B> <A NAME="tex2html585"
HREF="node42.html">Generating a user_controller.c File</A>
<!--End of Navigation Panel-->
<ADDRESS>
Michael Barabanov
2001-06-19
</ADDRESS>
</BODY>
</HTML>
|
