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
|
<!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>The API</TITLE>
<META NAME="description" CONTENT="The API">
<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="node49.html">
<LINK REL="previous" HREF="node47.html">
<LINK REL="up" HREF="node47.html">
<LINK REL="next" HREF="node49.html">
</HEAD>
<BODY bgcolor="white">
<!--Navigation Panel-->
<A NAME="tex2html656"
HREF="node49.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="/usr/share/latex2html/icons/next.png"></A>
<A NAME="tex2html654"
HREF="node47.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="/usr/share/latex2html/icons/up.png"></A>
<A NAME="tex2html648"
HREF="node47.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="tex2html657"
HREF="node49.html">Example Calls</A>
<B> Up:</B> <A NAME="tex2html655"
HREF="node47.html">Adding Modules</A>
<B> Previous:</B> <A NAME="tex2html649"
HREF="node47.html">Adding Modules</A>
<BR>
<BR>
<!--End of Navigation Panel-->
<H3><A NAME="SECTION00511100000000000000">
The API</A>
</H3>
Now that we know what is necessary within our communications programs,
let's take a look at the actual API. Note that unless otherwise
specified, all of the following functions return <TT>RTIC_SUCCESS</TT> on
success, otherwise they return <TT>RTIC_ERROR</TT>:
<P>
<UL>
<LI><TT>int rtic_check_ID(const char *,int, const FLAG)</TT>:
this function checks the value of the ID to ensure that it is
indeed a valid value for <TT>ID</TT>. Its arguments denote a text
identifier (used when printing out error messages), the parameter's
<TT>ID</TT> to be checked, and either <TT>TRUE</TT> or <TT>FALSE</TT>
depending on whether the parameter is a matrix or not,
respectively. The arguments are a descriptive string, an
identifier, and true or false, depending on whether the parameter
is a scalar or a matrix. If the ID is valid, this function returns
``RTIC_SUCCESS'', otherwise it returns ``RTIC_ERROR'' and prints
out a useful message.
<P>
</LI>
<LI><TT>void rtic_get_data(struct data_struct *data)</TT>:
this function returns the next data point that appears in <TT> xrtic</TT>. It loads the data into the structure ``<TT>data</TT>'', for
which the user should have already allocated memory. If there is no
data to be read, this function blocks until a new data point
arrives. The data structure takes on the following form (defined
in <TT>main.h</TT>):
<P><PRE>
struct data_struct
{
long long time; /* nano-seconds of
actual run-time */
int factor; /* downsample ratio */
float val[RTIC_MAX_DATA_BUF]; /* user specified return
values */
};
</PRE>
<P>
</LI>
<LI><TT>int rtic_connect_init(int *,char ***,const FLAG)</TT>:
This function initializes the connection to rtic-lab.
<P>
</LI>
<LI><TT>int rtic_connect_quit(void)</TT>:
This function disconnects from rtic-lab.
<P>
</LI>
<LI><TT>int rtic_set_scalar(int ID,float val)</TT>: sets the value of ``val'' to the scalar identified by ``ID''
<P>
</LI>
<LI>int rtic_get_scalar(int ID,float *val): gets the value of the parameter identified by the identifier ``ID'' and sets the value onto the memory pointed to by ``*val''.
<P>
</LI>
<LI><TT>int rtic_set_frequency(float freq)</TT>: Sets the run-time frequency to the value given by ``freq''
<P>
</LI>
<LI><TT>int rtic_get_nrt_frequency(float *freq)</TT>: gets the run-time frequency as seen by xrtic and puts it in the memory location pointed to by ``*freq''
<P>
</LI>
<LI><TT>int rtic_set_tx_rate(int ratio)</TT>: Sets the initial downsample ratio to ``ratio''
<P>
</LI>
<LI><TT>int rtic_get_tx_rate(int *ratio)</TT>: Gets the initial downsample ratio as seen by xrtic
<P>
</LI>
<LI><TT>int rtic_get_rtime(float *time)</TT>: get the running time of the embedded tasks, in seconds.
<P>
</LI>
<LI><TT>int rtic_get_AD_reg(int *reg)</TT>: gets the AD status register value and sets it in ``reg''.
<P>
</LI>
<LI><TT>int rtic_get_DA_reg(int *reg)</TT>: gets the DA status register value and sets it in ``reg''.
<P>
</LI>
<LI><TT>int rtic_get_WD_reg(int *reg)</TT>: gets the Watchdog status register value and sets it in ``reg''
<P>
</LI>
<LI><TT>char *rtic_get_message(void)</TT>: this function gets the status message
</LI>
<LI><TT>int rtic_get_flag_quit(FLAG *quit_flag)</TT>: gets the value of the ``Quit'' flag from the embedded tasks. The value is placed in the memory location pointed to by ``*quit_flag''.
<P>
</LI>
<LI><TT>int rtic_get_flag_run(FLAG *run_flag)</TT>: gets the value of the ``run'' flag from the embedded tasks. That is, are the embedded tasks running? The value is placed in the memory location pointed to by ``*run_flag''.
<P>
</LI>
<LI><TT>int rtic_get_flag_connect(FLAG *connect_flag)</TT>: checks whether xrtic has already connected successfully to the embedded tasks. The value is placed in the memory location pointed to by ``*quit_flag''.
<P>
</LI>
<LI><TT>int rtic_get_flag_verbose(FLAG *verbose_flag)</TT>:
gets the value of the verbose flag, that is ``are status reports being
generated every time that the watchdog runs?''. The value is placed in
the memory location pointed to by ``*verbose_flag''.
<P>
</LI>
<LI><TT>int rtic_get_flag_data_TX(FLAG *data_TX_flag)</TT>: gets the value of the <TT>data_TX</TT> flag. That is, ``is data being transmitted from the embedded tasks onto xrtic?''. The value is placed in the memory location pointed to by ``*data_TX_flag''.
<P>
</LI>
<LI><TT>int rtic_get_flag_bench(FLAG *bench_flag)</TT>: gets the value of the bench flag. That is, ``is the time that is being reported by the time column in the data the loop time or the run-time?''. True denotes that the time field in the data vector denotes the ``loop time'' of the controller. The value of this flag is placed in the memory location pointed to by ``*bench_flag''.
<P>
</LI>
</UL>
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html656"
HREF="node49.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next"
SRC="/usr/share/latex2html/icons/next.png"></A>
<A NAME="tex2html654"
HREF="node47.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="/usr/share/latex2html/icons/up.png"></A>
<A NAME="tex2html648"
HREF="node47.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="tex2html657"
HREF="node49.html">Example Calls</A>
<B> Up:</B> <A NAME="tex2html655"
HREF="node47.html">Adding Modules</A>
<B> Previous:</B> <A NAME="tex2html649"
HREF="node47.html">Adding Modules</A>
<!--End of Navigation Panel-->
<ADDRESS>
Michael Barabanov
2001-06-19
</ADDRESS>
</BODY>
</HTML>
|
