1 <!-- 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. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="eCos Synthetic Target"
23 HREF="hal-synth-arch.html"><LINK
25 TITLE="The Console Device"
26 HREF="synth-console.html"><LINK
28 TITLE="Writing New Devices - target"
29 HREF="synth-new-target.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="synth-console.html"
71 HREF="synth-new-target.html"
82 NAME="SYNTH-SYSCALLS">System Calls</H1
90 >cyg_hal_sys_xyz -- Access Linux system facilities</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/hal/hal_io.h>
118 >int cyg_hal_sys_xyzzy</CODE
128 NAME="SYNTH-SYSCALLS-DESCRIPTION"
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
142 >cyg_hal_sys_write</TT
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.
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
155 >cyg/hal/hal_io.h</TT
157 convention: given a Linux system call such as
161 >, the synthetic target will prefix
165 > and provide a function with that name.
166 The second argument to the <TT
170 a set of flags such as <TT
174 file will define a matching constant
177 >CYG_HAL_SYS_O_RDONLY</TT
178 >. There are also data
179 structures such as <SPAN
181 >cyg_hal_sys_sigset_t</SPAN
183 matching the Linux data structure <SPAN
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
196 > to indicate an error, with the
197 actual error code held in <TT
201 underlying system call and hence the
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.
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
218 > system call has been superseded by
222 >, and that is what the
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
232 >cyg_hal_sys__newselect</TT
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.
239 >eCos packages and applications should never
243 > Linux header files directly. For example,
246 >#include </usr/include/fcntl.h></TT
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
255 >cyg/hal/hal_io.h</TT
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.
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
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.
281 SUMMARY="Footer navigation table"
292 HREF="synth-console.html"
310 HREF="synth-new-target.html"
320 >The Console Device</TD
326 HREF="hal-synth-arch.html"
334 >Writing New Devices - target</TD