doc/html/ref/synth-syscalls.html

   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.               -->
   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 >