packages/hal/synth/arch/v2_0/doc/synth-syscalls.html

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