OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [synth-syscalls.html] - Blame information for rev 588

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback
<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
2
<!-- This material may be distributed only subject to the terms      -->
3
<!-- and conditions set forth in the Open Publication License, v1.0  -->
4
<!-- or later (the latest version is presently available at          -->
5
<!-- http://www.opencontent.org/openpub/).                           -->
6
<!-- Distribution of the work or derivative of the work in any       -->
7
<!-- standard (paper) book form is prohibited unless prior           -->
8
<!-- permission is obtained from the copyright holder.               -->
9
<HTML
10
><HEAD
11
><TITLE
12
>System Calls</TITLE
13
><meta name="MSSmartTagsPreventParsing" content="TRUE">
14
<META
15
NAME="GENERATOR"
16
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
17
"><LINK
18
REL="HOME"
19
TITLE="eCos Reference Manual"
20
HREF="ecos-ref.html"><LINK
21
REL="UP"
22
TITLE="eCos Synthetic Target"
23
HREF="hal-synth-arch.html"><LINK
24
REL="PREVIOUS"
25
TITLE="The Console Device"
26
HREF="synth-console.html"><LINK
27
REL="NEXT"
28
TITLE="Writing New Devices - target"
29
HREF="synth-new-target.html"></HEAD
30
><BODY
31
CLASS="REFENTRY"
32
BGCOLOR="#FFFFFF"
33
TEXT="#000000"
34
LINK="#0000FF"
35
VLINK="#840084"
36
ALINK="#0000FF"
37
><DIV
38
CLASS="NAVHEADER"
39
><TABLE
40
SUMMARY="Header navigation table"
41
WIDTH="100%"
42
BORDER="0"
43
CELLPADDING="0"
44
CELLSPACING="0"
45
><TR
46
><TH
47
COLSPAN="3"
48
ALIGN="center"
49
>eCos Reference Manual</TH
50
></TR
51
><TR
52
><TD
53
WIDTH="10%"
54
ALIGN="left"
55
VALIGN="bottom"
56
><A
57
HREF="synth-console.html"
58
ACCESSKEY="P"
59
>Prev</A
60
></TD
61
><TD
62
WIDTH="80%"
63
ALIGN="center"
64
VALIGN="bottom"
65
></TD
66
><TD
67
WIDTH="10%"
68
ALIGN="right"
69
VALIGN="bottom"
70
><A
71
HREF="synth-new-target.html"
72
ACCESSKEY="N"
73
>Next</A
74
></TD
75
></TR
76
></TABLE
77
><HR
78
ALIGN="LEFT"
79
WIDTH="100%"></DIV
80
><H1
81
><A
82
NAME="SYNTH-SYSCALLS">System Calls</H1
83
><DIV
84
CLASS="REFNAMEDIV"
85
><A
86
NAME="AEN18139"
87
></A
88
><H2
89
>Name</H2
90
>cyg_hal_sys_xyz&nbsp;--&nbsp;Access Linux system facilities</DIV
91
><DIV
92
CLASS="REFSYNOPSISDIV"
93
><A
94
NAME="AEN18142"><H2
95
>Synopsis</H2
96
><DIV
97
CLASS="FUNCSYNOPSIS"
98
><A
99
NAME="AEN18143"><P
100
></P
101
><TABLE
102
BORDER="5"
103
BGCOLOR="#E0E0F0"
104
WIDTH="70%"
105
><TR
106
><TD
107
><PRE
108
CLASS="FUNCSYNOPSISINFO"
109
>#include &lt;cyg/hal/hal_io.h&gt;
110
      </PRE
111
></TD
112
></TR
113
></TABLE
114
><P
115
><CODE
116
><CODE
117
CLASS="FUNCDEF"
118
>int cyg_hal_sys_xyzzy</CODE
119
>(...);</CODE
120
></P
121
><P
122
></P
123
></DIV
124
></DIV
125
><DIV
126
CLASS="REFSECT1"
127
><A
128
NAME="SYNTH-SYSCALLS-DESCRIPTION"
129
></A
130
><H2
131
>Description</H2
132
><P
133
>On a real embedded target eCos interacts with the hardware by peeking
134
and poking various registers, manipulating special regions of memory,
135
and so on. The synthetic target does not access hardware directly.
136
Instead I/O and other operations are emulated by making appropriate
137
Linux system calls. The HAL package exports a number of functions
138
which allow other packages, or even application code, to make these
139
same system calls. However this facility must be used with care: any
140
code which calls, for example, <TT
141
CLASS="FUNCTION"
142
>cyg_hal_sys_write</TT
143
>
144
will only ever run on the synthetic target; that functionality is
145
obviously not provided on any real hardware because there is no
146
underlying Linux kernel to implement it.
147
    </P
148
><P
149
>The synthetic target only provides a subset of the available system
150
calls, specifically those calls which have proved useful to implement
151
I/O emulation. This subset can be extended fairly easily if necessary.
152
All of the available calls, plus associated data structures and
153
macros, are defined in the header file <TT
154
CLASS="FILENAME"
155
>cyg/hal/hal_io.h</TT
156
>. There is a simple
157
convention: given a Linux system call such as
158
<TT
159
CLASS="FUNCTION"
160
>open</TT
161
>, the synthetic target will prefix
162
<TT
163
CLASS="LITERAL"
164
>cyg_hal_sys</TT
165
> and provide a function with that name.
166
The second argument to the <TT
167
CLASS="FUNCTION"
168
>open</TT
169
> system call is
170
a set of flags such as <TT
171
CLASS="CONSTANT"
172
>O_RDONLY</TT
173
>, and the header
174
file will define a matching constant
175
<TT
176
CLASS="CONSTANT"
177
>CYG_HAL_SYS_O_RDONLY</TT
178
>. There are also data
179
structures such as <SPAN
180
CLASS="STRUCTNAME"
181
>cyg_hal_sys_sigset_t</SPAN
182
>,
183
matching the Linux data structure <SPAN
184
CLASS="STRUCTNAME"
185
>sigset_t</SPAN
186
>.
187
    </P
188
><P
189
>In most cases the functions provided by the synthetic target behave as
190
per the documentation for the Linux system calls, and section 2 of the
191
Linux man pages can be consulted for more information. There is one
192
important difference: typically the documentation will say that a
193
function returns <TT
194
CLASS="LITERAL"
195
>-1</TT
196
> to indicate an error, with the
197
actual error code held in <TT
198
CLASS="VARNAME"
199
>errno</TT
200
>; the actual
201
underlying system call and hence the
202
<TT
203
CLASS="FUNCTION"
204
>cyg_hal_sys_xyz</TT
205
> provided by eCos instead returns
206
a negative number to indicate an error, with the absolute value of
207
that number corresponding to the error code; usually it is the C
208
library which handles this and manipulates errno, but of course
209
synthetic target applications are not linked with that Linux library.
210
    </P
211
><P
212
>However, there are some exceptions. The Linux kernel has evolved over
213
the years, and some of the original system call interfaces are no
214
longer appropriate. For example the original
215
<TT
216
CLASS="FUNCTION"
217
>select</TT
218
> system call has been superseded by
219
<TT
220
CLASS="FUNCTION"
221
>_newselect</TT
222
>, and that is what the
223
<TT
224
CLASS="FUNCTION"
225
>select</TT
226
> function in the C library actually uses.
227
The old call is still available to preserve binary compatibility but,
228
like the C library, eCos makes use of the new one because it provides
229
the appropriate functionality. In an attempt to reduce confusion the
230
eCos function is called <TT
231
CLASS="FUNCTION"
232
>cyg_hal_sys__newselect</TT
233
>,
234
in other words it matches the official system call naming scheme. The
235
authoritive source of information on such matters is the Linux kernel
236
sources themselves, and especially its header files.
237
    </P
238
><P
239
>eCos packages and applications should never
240
<TT
241
CLASS="LITERAL"
242
>#include</TT
243
> Linux header files directly. For example,
244
doing a <TT
245
CLASS="LITERAL"
246
>#include&nbsp;&lt;/usr/include/fcntl.h&gt;</TT
247
>
248
to access additional macros or structure definitions, or alternatively
249
manipulating the header file search path, will lead to problems
250
because the Linux header files are likely to duplicate and clash with
251
definitions in the eCos headers. Instead the appropriate functionality
252
should be extracted from the Linux headers and moved into either
253
<TT
254
CLASS="FILENAME"
255
>cyg/hal/hal_io.h</TT
256
> or into
257
application code, with suitable renaming to avoid clashes with eCos
258
names. Users should be aware that large-scale copying may involve
259
licensing complications.
260
    </P
261
><P
262
>Adding more system calls is usually straightforward and involves
263
adding one or more lines to the platform-specific file in the
264
appropriate platform HAL, for example
265
<TT
266
CLASS="FILENAME"
267
>syscall-i386-linux-1.0.S</TT
268
>. However it is necessary
269
to do some research first about the exact interface implemented by the
270
system call, because of issues such as old system calls that have been
271
superseded. The required information can usually be found fairly
272
easily by searching through the Linux kernel sources and possibly the
273
GNU C library sources.
274
    </P
275
></DIV
276
><DIV
277
CLASS="NAVFOOTER"
278
><HR
279
ALIGN="LEFT"
280
WIDTH="100%"><TABLE
281
SUMMARY="Footer navigation table"
282
WIDTH="100%"
283
BORDER="0"
284
CELLPADDING="0"
285
CELLSPACING="0"
286
><TR
287
><TD
288
WIDTH="33%"
289
ALIGN="left"
290
VALIGN="top"
291
><A
292
HREF="synth-console.html"
293
ACCESSKEY="P"
294
>Prev</A
295
></TD
296
><TD
297
WIDTH="34%"
298
ALIGN="center"
299
VALIGN="top"
300
><A
301
HREF="ecos-ref.html"
302
ACCESSKEY="H"
303
>Home</A
304
></TD
305
><TD
306
WIDTH="33%"
307
ALIGN="right"
308
VALIGN="top"
309
><A
310
HREF="synth-new-target.html"
311
ACCESSKEY="N"
312
>Next</A
313
></TD
314
></TR
315
><TR
316
><TD
317
WIDTH="33%"
318
ALIGN="left"
319
VALIGN="top"
320
>The Console Device</TD
321
><TD
322
WIDTH="34%"
323
ALIGN="center"
324
VALIGN="top"
325
><A
326
HREF="hal-synth-arch.html"
327
ACCESSKEY="U"
328
>Up</A
329
></TD
330
><TD
331
WIDTH="33%"
332
ALIGN="right"
333
VALIGN="top"
334
>Writing New Devices - target</TD
335
></TR
336
></TABLE
337
></DIV
338
></BODY
339
></HTML
340
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.