Mercurial > flash_v2
diff packages/hal/synth/arch/current/doc/synth-syscalls.html @ 208:e0c0827131d1 ecos
Merge from eCos master repository on 2002-05-20-20:11:54-BST
| author | jlarmour |
|---|---|
| date | Mon, 20 May 2002 22:19:26 +0000 |
| parents | |
| children | 7c1c8dc43ba1 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/packages/hal/synth/arch/current/doc/synth-syscalls.html @@ -0,0 +1,335 @@ +<!-- Copyright (C) 2002 Red Hat, Inc. --> +<!-- This material may be distributed only subject to the terms --> +<!-- and conditions set forth in the Open Publication License, v1.0 --> +<!-- or later (the latest version is presently available at --> +<!-- http://www.opencontent.org/openpub/). --> +<!-- Distribution of substantively modified versions of this --> +<!-- document is prohibited without the explicit permission of the --> +<!-- copyright holder. --> +<!-- Distribution of the work or derivative of the work in any --> +<!-- standard (paper) book form is prohibited unless prior --> +<!-- permission is obtained from the copyright holder. --> +<HTML +><HEAD +><TITLE +>System Calls</TITLE +><meta name="MSSmartTagsPreventParsing" content="TRUE"> +<META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.64 +"><LINK +REL="HOME" +TITLE="eCos Synthetic Target" +HREF="hal-synth-arch.html"><LINK +REL="PREVIOUS" +TITLE="Overview" +HREF="synth.html"><LINK +REL="NEXT" +TITLE="Porting" +HREF="synth-porting.html"></HEAD +><BODY +CLASS="REFENTRY" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>eCos Synthetic Target</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="synth.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="synth-porting.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><H1 +><A +NAME="SYNTH-SYSCALLS" +>System Calls</A +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN51" +></A +><H2 +>Name</H2 +>cyg_hal_sys_xyz -- Access Linux system facilities</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN54" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><A +NAME="AEN55" +></A +><P +></P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <cyg/hal/hal_io.h + </PRE +></TD +></TR +></TABLE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>int cyg_hal_sys_xyz</CODE +>(...);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="SYNTH-SYSCALLS-DESCRIPTION" +></A +><H2 +>Description</H2 +><P +>On a real embedded target eCos interacts with the hardware by peeking +and poking various registers, manipulating special regions of memory, +and so on. The synthetic target does not access hardware directly. +Instead I/O and other operations are emulated by making appropriate +Linux system calls. The HAL package exports a number of functions +which allow other packages, or even application code, to make these +same system calls. However this facility must be used with care: any +code which calls, for example, <TT +CLASS="FUNCTION" +>cyg_hal_sys_write</TT +> +will only ever run on the synthetic target; that functionality is +obviously not provided on any real hardware because there is no +underlying Linux kernel to implement it. + </P +><P +>The synthetic target only provides a subset of the available system +calls, specifically those calls which have proved useful to implement +I/O emulation. This subset can be extended fairly easily if necessary. +All of the available calls, plus associated data structures and +macros, are defined in the header file <TT +CLASS="FILENAME" +>cyg/hal/hal_io.h</TT +>. There is a simple +convention: given a Linux system call such as +<TT +CLASS="FUNCTION" +>open</TT +>, the synthetic target will prefix +<TT +CLASS="LITERAL" +>cyg_hal_sys</TT +> and provide a function with that name. +The second argument to the <TT +CLASS="FUNCTION" +>open</TT +> system call is +a set of flags such as <TT +CLASS="CONSTANT" +>O_RDONLY</TT +>, and the header +file will define a matching constant +<TT +CLASS="CONSTANT" +>CYG_HAL_SYS_O_RDONLY</TT +>. There are also data +structures such as <SPAN +CLASS="STRUCTNAME" +>cyg_hal_sys_sigset_t</SPAN +>, +matching the Linux data structure <SPAN +CLASS="STRUCTNAME" +>sigset_t</SPAN +>. + </P +><P +>In most cases the functions provided by the synthetic target behave as +per the documentation for the Linux system calls, and section 2 of the +Linux man pages can be consulted for more information. There is one +important difference: typically the documentation will say that a +function returns <TT +CLASS="LITERAL" +>-1</TT +> to indicate an error, with the +actual error code held in <TT +CLASS="VARNAME" +>errno</TT +>; the actual +underlying system call and hence the +<TT +CLASS="FUNCTION" +>cyg_hal_sys_xyz</TT +> provided by eCos instead returns +a negative number to indicate an error, with the absolute value of +that number corresponding to the error code; usually it is the C +library which handles this and manipulates errno, but of course +synthetic target applications are not linked with that Linux library. + </P +><P +>However, there are some exceptions. The Linux kernel has evolved over +the years, and some of the original system call interfaces are no +longer appropriate. For example the original +<TT +CLASS="FUNCTION" +>select</TT +> system call has been superseded by +<TT +CLASS="FUNCTION" +>_newselect</TT +>, and that is what the +<TT +CLASS="FUNCTION" +>select</TT +> function in the C library actually uses. +The old call is still available to preserve binary compatibility but, +like the C library, eCos makes use of the new one because it provides +the appropriate functionality. In an attempt to reduce confusion the +eCos function is called <TT +CLASS="FUNCTION" +>cyg_hal_sys__newselect</TT +>, +in other words it matches the official system call naming scheme. The +authoritive source of information on such matters is the Linux kernel +sources themselves, and especially its header files. + </P +><P +>eCos packages and applications should never +<TT +CLASS="LITERAL" +>#include</TT +> Linux header files directly. For example, +doing a <TT +CLASS="LITERAL" +>#include </usr/include/fcntl.h></TT +> +to access additional macros or structure definitions, or alternatively +manipulating the header file search path, will lead to problems +because the Linux header files are likely to duplicate and clash with +definitions in the eCos headers. Instead the appropriate functionality +should be extracted from the Linux headers and moved into either +<TT +CLASS="FILENAME" +>cyg/hal/hal_io.h</TT +> or into +application code, with suitable renaming to avoid clashes with eCos +names. Users should be aware that large-scale copying may involve +licensing complications. + </P +><P +>Adding more system calls is usually straightforward and involves +adding one or more lines to the platform-specific file in the +appropriate platform HAL, for example +<TT +CLASS="FILENAME" +>syscall-i386-linux-1.0.S</TT +>. However it is necessary +to do some research first about the exact interface implemented by the +system call, because of issues such as old system calls that have been +superseded. The required information can usually be found fairly +easily by searching through the Linux kernel sources and possibly the +GNU C library sources. + </P +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="synth.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="hal-synth-arch.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="synth-porting.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>Overview</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +> </TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Porting</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file