3 <!-- =============================================================== -->
5 <!-- introduction.sgml -->
7 <!-- eCos User Guide -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
12 <!-- =============================================================== -->
13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc. -->
14 <!-- Copyright (C) 2003 Nick Garnett -->
15 <!-- This material may be distributed only subject to the terms -->
16 <!-- and conditions set forth in the Open Publication License, v1.0 -->
17 <!-- or later (the latest version is presently available at -->
18 <!-- http://www.opencontent.org/openpub/) -->
19 <!-- Distribution of the work or derivative of the work in any -->
20 <!-- standard (paper) book form is prohibited unless prior -->
21 <!-- permission obtained from the copyright holder -->
22 <!-- =============================================================== -->
24 <!-- ####COPYRIGHTEND#### -->
25 <!-- =============================================================== -->
26 <!-- #####DESCRIPTIONBEGIN#### -->
28 <!-- ####DESCRIPTIONEND#### -->
29 <!-- =============================================================== -->
33 <part ID="user-guide-introduction">
34 <TITLE>Introduction</TITLE>
37 <chapter ID="FOREWORD-WHATS-NEW">
38 <TITLE>What's New?</TITLE>
41 XXXXX So what is new??? XXXXX
47 <!-- ==================================================== -->
49 <chapter ID="ecos-key-features">
50 <TITLE>Key Features</TITLE>
55 <para><productname>eCos</productname> is distributed under the GPL
56 license with an exception which permits proprietary application code
57 to be linked with <productname>eCos</productname> without itself being
58 forced to be released under the GPL. It is also royalty and buyout
64 <para>As an Open Source project, <productname>eCos</productname> is
65 under constant improvement, with an active developer community, based
66 around the <productname>eCos</productname> web site at <ULINK
67 URL="http://ecos.sourceware.org/">http://ecos.sourceware.org/</ULINK>.
72 <para>Powerful GUI-based configuration system allowing both large and
73 fine grained configuration of <productname>eCos</productname>. This
74 allows the functionality of <productname>eCos</productname> to be
75 customized to the exact requirements of the application.
80 <para>Full-featured, flexible, configurable, real time embedded
81 kernel. The kernel provides thread scheduling, synchronization,
82 timer, and communication primitives. It handles hardware resources
83 such as interrupts, exceptions, memory and caches.
88 <para>The Hardware Abstraction Layer (HAL) hides the specific features
89 of each supported CPU and platform, so that the kernel and other
90 run-time components can be implemented in a portable fashion.
95 <para>Support for µITRON and POSIX Application Programmer
96 Interfaces (APIs). It also includes a fully featured, thread-safe ISO
97 standard C library and math library.
102 <para>Support for a wide variety of devices including many serial
103 devices, ethernet controllers and FLASH memories. There is also
104 support for PCMCIA, USB and PCI interconnects.
109 <para>A fully featured TCP/IP stack implementing IP, IPv6, ICMP, UDP
110 and TCP over ethernet. Support for SNMP, HTTP, TFTP and FTP are also
116 <para>The RedBoot ROM monitor is an application that uses the
117 <productname>eCos</productname> HAL for portability. It provides
118 serial and ethernet based booting and debug services during
124 <para>Many components include test programs that validate the
125 components behaviour. These can be used both to check that hardware is
126 functioning correctly, and as examples of
127 <productname>eCos</productname> usage.
132 <para><productname>eCos</productname> documentation included this User
133 Guide, the Reference Manual and the Components Writer's Guide. These
134 are being continually updated as the system develops.
142 <!-- ==================================================== -->
144 <chapter ID="ecos-overview">
145 <TITLE><productname>eCos</productname> Overview</TITLE>
147 <PARA><productname>eCos</productname> is an open source, configurable,
148 portable, and royalty-free embedded real-time operating
149 system. The following text expands on these core aspects that
150 define <productname>eCos</productname>.</PARA>
152 <PARA><productname>eCos</productname> is provided as an open source
153 runtime system supported by the GNU open source development
154 tools. Developers have full and unfettered access to all
155 aspects of the runtime system. No parts of it are proprietary
156 or hidden, and you are at liberty to examine, add to, and
157 modify the code as you deem necessary. These rights are
158 granted to you and protected by the GNU Public License (GPL).
159 An exception clause has been added to the eCos license which
160 limits the circumstances in which the license applies to other
161 code when used in conjunction with eCos. This exception grants
162 you the right to freely develop and distribute applications
163 based on <productname>eCos</productname>. You are not expected
164 or required to make your embedded applications or any
165 additional components that you develop freely available so
166 long as they are not derived from
167 <productname>eCos</productname> code. We of course welcome all
168 contributions back to <productname>eCos</productname> such as
169 board ports, device drivers and other components, as this
170 helps the growth and development of
171 <productname>eCos</productname>, and is of benefit to the
172 entire <productname>eCos</productname> community. See <XREF
173 LINKEND="ecos-licensing"> for more details.</PARA>
175 <PARA>One of the key technological innovations in
176 <productname>eCos</productname> is the configuration
177 system. The configuration system allows the application writer
178 to impose their requirements on the run-time components, both
179 in terms of their functionality and implementation, whereas
180 traditionally the operating system has constrained the
181 application's own implementation. Essentially, this enables
182 <productname>eCos</productname> developers to create their own
183 application-specific operating system and makes
184 <productname>eCos</productname> suitable for a wide range of
185 embedded uses. Configuration also ensures that the resource
186 footprint of <productname>eCos</productname> is minimized as
187 all unnecessary functionality and features are removed. The
188 configuration system also presents
189 <productname>eCos</productname> as a component
190 architecture. This provides a standardized mechanism for
191 component suppliers to extend the functionality of
192 <productname>eCos</productname> and allows applications to be
193 built from a wide set of optional configurable run-time
194 components. Components can be provided from a variety of
195 sources including: the standard
196 <productname>eCos</productname> release; commercial third
197 party developers or open source contributors.</PARA>
199 <PARA>The royalty-free nature of <productname>eCos</productname> means that you can develop and
200 deploy your application using the standard <productname>eCos</productname> release without
201 incurring any royalty charges. In addition, there are no up-front
202 license charges for the <productname>eCos</productname> runtime source code and associated
203 tools. We provide, without charge, everything necessary for basic
204 embedded applications development.</PARA>
206 <PARA><productname>eCos</productname> is designed to be portable to a
207 wide range of target architectures and target platforms including 16,
208 32, and 64 bit architectures, MPUs, MCUs and DSPs. The
209 <productname>eCos</productname> kernel, libraries and runtime
210 components are layered on the Hardware Abstraction Layer (HAL), and
211 thus will run on any target once the HAL and relevant device drivers
212 have been ported to the target's processor architecture and
213 board. Currently <productname>eCos</productname> supports a large
214 range of different target architectures:
219 <listitem><para>ARM, Intel StrongARM and XScale</para></listitem>
221 <listitem><para>Fujitsu FR-V</para></listitem>
223 <listitem><para>Hitachi SH2/3/4</para></listitem>
225 <listitem><para>Hitachi H8/300H </para></listitem>
227 <listitem><para>Intel x86</para></listitem>
229 <listitem><para>MIPS</para></listitem>
231 <listitem><para>Matsushita AM3x</para></listitem>
233 <listitem><para>Motorola PowerPC</para></listitem>
235 <listitem><para>Motorola 68k/Coldfire</para></listitem>
237 <listitem><para>NEC V850</para></listitem>
239 <listitem><para>Sun SPARC</para></listitem>
244 including many of the popular variants of these architectures
245 and evaluation boards.</PARA>
247 <PARA><productname>eCos</productname> has been designed to support
248 applications with real-time requirements, providing features such as
249 full preemptability, minimal interrupt latencies, and all the
250 necessary synchronization primitives, scheduling policies, and
251 interrupt handling mechanisms needed for these type of
252 applications. <productname>eCos</productname> also provides all the
253 functionality required for general embedded application support
254 including device drivers, memory management, exception handling, C,
255 math libraries, etc. In addition to runtime support, the
256 <productname>eCos</productname> system includes all the tools
257 necessary to develop embedded applications, including
258 <productname>eCos</productname> software configuration and build
259 tools, and GNU based compilers, assemblers, linkers, debuggers, and
262 <PARA>To get the most out of <productname>eCos</productname> you
263 should visit the <productname>eCos</productname> open source
264 developers site: <ULINK
265 URL="http://ecos.sourceware.org/">http://ecos.sourceware.org/</ULINK>.
268 <PARA>The site is dedicated to the <productname>eCos</productname>
269 developer community and contains a rich set of resources
270 including news, FAQ, online documentation, installation guide,
271 discussion and announcement mailing lists, and runtime and
272 development tools downloads. The site also supports anonymous
273 CVS and WEBCVS access to provide direct access to the latest
274 <productname>eCos</productname> source base. </PARA>
276 <PARA><productname>eCos</productname> is released as open source
277 software because we believe that this is the most effective
278 software development model, and that it provides the greatest
279 benefit to the embedded developer community as a whole. As part
280 of this endeavor, we seek the input and participation of
281 <productname>eCos</productname> developers in its continuing
282 evolution. Participation can take many forms including:</PARA>
285 <PARA>providing us with feedback on how <productname>eCos</productname> might be made more
286 useful to you - by taking part in the ongoing mailing list discussions
287 and by submitting problem reports covering bugs, documentation issues,
288 and missing features</PARA>
291 <PARA>contributing bug fixes and enhancement patches</PARA>
294 <PARA>contributing new code including device drivers, board
295 ports, libraries, and other runtime components</PARA>
299 <PARA>Our long term aim is to make <productname>eCos</productname> a
300 rich and ubiquitous standard infrastructure for the development of
301 deeply embedded applications. This will be achieved with the
302 assistance of the <productname>eCos</productname> developer community
303 cooperating to improve <productname>eCos</productname> for all. We
304 would like to take this opportunity to extend our thanks to the many
305 <productname>eCos</productname> developers who have already
306 contributed feedback, ideas, patches, and code that have augmented and
307 improved this release.</PARA>
311 <emphasis>The <productname>eCos</productname> Maintainers</emphasis>
316 <!-- ==================================================== -->
318 <chapter ID="ecos-licensing">
319 <TITLE><productname>eCos</productname> Licence Overview</TITLE>
321 <para>As of May 2002, <productname>eCos</productname> is released
322 under a modified version of the well known <ulink
323 url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License
324 (GPL)</ulink>, now making it an <ulink
325 url="http://www.gnu.org/philosophy/license-list.html">official
326 GPL-compatible Free Software License</ulink>. An exception clause has
327 been added to the <productname>eCos</productname> license which limits
328 the circumstances in which the license applies to other code when used
329 in conjunction with <productname>eCos</productname>. The exception
330 clause is as follows:</para>
332 <programlisting width=72>
333 As a special exception, if other files instantiate templates or use macros
334 or inline functions from this file, or you compile this file and link it
335 with other works to produce a work based on this file, this file does not
336 by itself cause the resulting work to be covered by the GNU General Public
337 License. However the source code for this file must still be made
338 available in accordance with section (3) of the GNU General Public
341 This exception does not invalidate any other reasons why a work based on
342 this file might be covered by the GNU General Public License.
345 <para>The goal of the license is to serve the
346 <productname>eCos</productname> user community as a whole. It allows
347 all <productname>eCos</productname> users to develop products without
348 paying anybody anything, no matter how many developers are working on
349 the product or how many units will be shipped. The license also
350 guarantees that the <productname>eCos</productname> source code will
351 always be freely available. This applies not only to the core
352 <productname>eCos</productname> code itself but also to any changes
353 that anybody makes to the core. In particular, it should prevent any
354 company or individual contributing code to the system and then later
355 claiming that all <productname>eCos</productname> users are now guilty
356 of copyright or patent infringements and have to pay royalties. It
357 should also prevent any company from making some small improvements,
358 calling the result a completely new system, and releasing this under a
359 new and less generous license.</para>
361 <para>The license does <emphasis>not</emphasis> require users to
362 release the source code of any <emphasis>applications</emphasis> that
363 are developed with <productname>eCos</productname>. However, if
364 anybody makes any changes to code covered by the
365 <productname>eCos</productname> license, or writes new files derived
366 in any way from <productname>eCos</productname> code, then we believe
367 that the entire user community should have the opportunity to benefit
368 from this. The license stipulates that these changes must be made
369 available in source code form to all recipients of binaries based on
370 the modified code, either by including the sources along with the
371 binaries you deliver (or with any device containing such binaries) or
372 with a written offer to supply the source code to the general public
373 for three years. It is perhaps most practical for
374 <productname>eCos</productname> developers to make the source code
375 available online and inform those who are receiving binaries
376 containing <productname>eCos</productname> code, and probably also the
377 <productname>eCos</productname> maintainers, about the location of the
378 code. See the <ulink url="http://www.gnu.org/copyleft/gpl.html">full
379 text of the GPL</ulink> for the most authoritative definition of the
382 <para>Although it is not strictly necessary to contribute the modified
383 code back to the <productname>eCos</productname> open source project,
384 we are always pleased to receive code contributions and hope that
385 developers will also be keen to give back in return for what they
386 received from the <productname>eCos</productname> project completely
387 free of charge. The <productname>eCos</productname> maintainers are
388 responsible for deciding whether such contributions should be applied
389 to the public repository. In addition, a <ulink
390 url="http://ecos.sourceware.org/assign.html">copyright
391 assignment</ulink> is required for any significant changes to the core
392 <productname>eCos</productname> packages.</para>
394 <para>The result is a royalty-free system with minimal obligations on
395 the part of application developers. This has resulted in the rapid
396 uptake of <productname>eCos</productname>. At the same time,
397 <productname>eCos</productname> is fully open source with all the
398 benefits that implies in terms of quality and innovation. We believe
399 that this is a winning combination.</para>
401 <sect1 id="ecos-licensing-qna">
402 <title>Questions and answers</title>
404 <para>The following queries provide some clarification as to the
405 implications of the <productname>eCos</productname> license. They do
406 not consititute part of the legal meaning of the license.</para>
408 <para><emphasis>Q.</emphasis> What is the effect of the
409 <productname>eCos</productname> license?</para>
411 <para><emphasis>A.</emphasis> In the simplest terms, when you
412 distribute anything containing <productname>eCos</productname> code,
413 you must make the source code to <productname>eCos</productname>
414 available under the terms of the GPL.</para>
416 <para><emphasis>Q.</emphasis> What if I make changes to
417 <productname>eCos</productname>, or write new code based on
418 <productname>eCos</productname> code?</para>
420 <para><emphasis>A.</emphasis> Then you must make those changes
421 available as well.</para>
423 <para><emphasis>Q.</emphasis> Do I have to distribute the source
424 code to my application? Isn't the GPL "viral"?</para>
426 <para><emphasis>A.</emphasis> You do not have to distribute any
427 code under the terms of the GPL other than
428 <productname>eCos</productname> code or code derived from
429 <productname>eCos</productname>. For example, if you write a HAL port
430 based on copying an existing <productname>eCos</productname> HAL in
431 any way, you must make the source code available with the
432 binary. However you would not need to make available any other code,
433 such as the code of a wholly separate application linked with
434 <productname>eCos</productname>.</para>
436 <para><emphasis>Q.</emphasis> I would rather stick with the
437 RHEPL code, but I updated my anonymous CVS checkout.</para>
439 <para><emphasis>A.</emphasis> You can check out the final
440 version of anonymous CVS before the license change using the CVS tag
441 <literal>last-rhepl</literal>. See <ulink
442 url="http://ecos.sourceware.org/anoncvs.html">the anonymous CVS
448 <sect1 id="ecos-licensing-previous">
449 <title>Previous License</title>
453 Prior to May 2002, <productname>eCos</productname> was released under
454 the <ulink url="http://ecos.sourceware.org/old-license.html">Red
455 Hat eCos Public License (RHEPL)</ulink>. The RHEPL required any
456 modifications to <productname>eCos</productname> code to be made
457 available under preferential terms to Red Hat and was therefore
458 incompatible with code licensed under the GPL. The use of
459 <productname>eCos</productname> source code which was licensed under
460 the RHEPL is not affected by the switch to the modified GPL for later
468 <!-- ==================================================== -->
470 <chapter id="notation-and-conventions">
471 <title>Notation and Conventions</title>
474 Since there are many supported target architectures, notation
475 conventions are used in this manual to avoid repeating instructions
476 that are very similar.
479 <SECT1 ID="GDB-AND-GCC-COMMAND-NOTATION"><!-- <index></index> --><!-- <xref> -->
480 <TITLE>GDB and <!-- <index></index> -->GCC Command Notation</TITLE>
483 Cross-development commands like <COMMAND>gcc</COMMAND> and
484 <COMMAND>gdb</COMMAND> will be shown with a
485 <replaceable>TARGET-</replaceable> prefix. You need to replace
486 <replaceable>TARGET-</replaceable> with the correct prefix before
487 using the command. Just using <command>gcc</command> or
488 <command>gdb</command> will use the tools for the host, which is not
489 (usually) what you want.
493 For example use <command>arm-elf-gcc</command> and
494 <command>arm-elf-gdb</command> for ARM, Thumb, and StrongARM targets.
495 Use <command>xscale-elf-gcc</command> and
496 <command>xscale-elf-gdb</command> for Intel Xscale targets.
497 Use <command>i386-elf-gcc</command> and
498 <command>i386-elf-gdb</command> for IA32 targets. And so on, the exact
499 prefix to use is shown in the documentation for each target.
502 <PARA>Note that some versions of the GCC cross compiler generate
503 executable files with the <FILENAME>.exe</FILENAME> suffix on Windows,
504 but not on Linux. The suffix <FILENAME>.exe</FILENAME> will be omitted
505 from executable file names, so you will see <FILENAME>hello</FILENAME>
506 instead of <FILENAME>hello.exe</FILENAME>.</PARA>
510 <SECT1 ID="DIRECTORY-AND-FILE-SYSTEM-CONVENTIONS"><!-- <index></index> -->
511 <TITLE>Directory and File System Conventions</TITLE>
513 <PARA>The default directory for installing
514 <productname>eCos</productname> on Windows (usually
515 <FILENAME>C:/Program Files/eCos</FILENAME>) is different from that on
516 Linux (usually <FILENAME>/opt/ecos</FILENAME>). Since many command
517 line examples in the tutorials use these paths, this default (base)
518 directory will be cited as <replaceable>BASE_DIR</replaceable>.</PARA>
520 <PARA>Windows and Linux have a similar file system syntax, but the
521 MS-DOS command interpreter on Windows uses the backslash character
522 (\) as a path separator, while Linux and POSIX shells (including
523 the Cygwin bash shell for windows) use the forward slash (/).</PARA>
525 <PARA>This document will use the POSIX shell convention of forward
526 slashes throughout.</PARA>
530 <!-- ==================================================== -->
532 <SECT1 ID="VERSION-CONVENTIONS">
533 <TITLE>Version Conventions</TITLE>
536 This manual does not refer explicitly to any particular version of
537 <productname>eCos</productname>. However, version numbers form part of
538 many file path names. In all of these places the version number will
539 be shown like this: <replaceable>&Version;</replaceable>.
543 If you have used anonymous CVS to check
544 <productname>eCos</productname> out of the CVS repository, the version
545 number will always be <literal>current</literal>, since that is the
546 name of the directory in the repository. When a stable release is made
547 this directory name is changed, in the release, to the number of the
548 release, for example <literal>v2_0</literal> or
549 <literal>v2_1</literal>.
559 <chapter id="documentation-roadmap">
560 <title>Documentation Roadmap</title>
563 The <productname>eCos</productname> documentation is divided into a
569 <TERM><EMPHASIS>User Guide</EMPHASIS></TERM>
571 <PARA>This document. It includes the following sections:</PARA>
575 <TERM>Installing <productname>eCos</productname></TERM>
578 This section describes how to install the
579 <productname>eCos</productname> software, how to set up your
580 hardware and how to test that it is all working.
586 <TERM>Programming Under <productname>eCos</productname></TERM>
589 This section describes how to write programs that run under
590 <productname>eCos</productname> by running through some examples.
596 <TERM>The <productname>eCos</productname> <application>Configuration Tool</application></TERM>
599 This section describes the <productname>eCos</productname> graphical
600 configuration tool and how to use it to change how
601 <productname>eCos</productname> behaves.</para>
606 <TERM><productname>eCos</productname> Programming Concepts and Techniques</TERM>
608 <PARA>An explanation of the <productname>eCos</productname> programming
609 cycle, and a description of some debugging facilities that
610 <productname>eCos</productname> offers.
616 <TERM>Configuration and the Package
619 <PARA>Information on how to configure <productname>eCos</productname>
620 manually, including a reference on the
621 <command>ecosconfig</command> command, memory layouts,
622 and information on how to manage a package repository
623 using the <productname>eCos</productname> Package Administration
636 <TERM><EMPHASIS>Reference Guide</EMPHASIS></TERM>
639 <PARA>The Reference Guide provides detailed documentation on various
640 aspects of <productname>eCos</productname>. This document is being
641 constantly updated, so the following list just mentions the more
642 important sections, take a look at the guide itself for the full
648 <TERM>The <productname>eCos</productname> Kernel</TERM>
650 <PARA>In-depth description of <productname>eCos</productname>"s
651 native C kernel API Important considerations are given
652 for programming the <productname>eCos</productname>
653 kernel. The semantics for each kernel function are
654 described, including how they are affected by
655 configuration. </PARA>
660 <TERM>POSIX and µITRON APIs</TERM>
662 <PARA>A description of the POSIX and µITRON APIs and how they
663 are supported under <productname>eCos</productname>.
669 <TERM>The <productname>eCos</productname> Hardware Abstraction Layer (HAL)</TERM>
671 <PARA>A description of the structure and functionality of the
672 <productname>eCos</productname> HAL. This section also includes a
673 porting guide to help moving <productname>eCos</productname> to
680 <TERM>Device Drivers</TERM>
682 <PARA>A description of the philosophy behind
683 <productname>eCos</productname> device drivers, as well as a
684 presentation of the C language APIs for using the current
685 device drivers. </PARA>
687 Device driver support includes serial, ethernet and FLASH devices,
688 and support for PCI, PCMCIA and USB interconnects.
694 <TERM>RedBoot User's Guide</TERM>
696 <PARA>This describes RedBoot, which provides a complete bootstrap
697 environment for a range of embedded operating systems, such as
698 embedded Linux and <productname>eCos</productname>, and
699 includes facilities such as network downloading and
700 debugging. It also provides a simple flash file system for
707 <TERM>TCP/IP Stack Support</TERM>
709 <PARA>This describes the Common Networking for
710 <productname>eCos</productname> package, which provides
711 support for a complete TCP/IP networking stack. The design
712 allows for the actual stack to be modular and at the current
713 time two different implementations, one based on OpenBSD from
714 2000 and a new version based on FreeBSD, are available.
716 <para>Other components related to networking, including support for
717 SNMP, DNS, HTTP and FTP, are also described.
728 <TERM><EMPHASIS>Component Writer's Guide</EMPHASIS></TERM>
730 <PARA>The Component Writer's Guide is intended for developers who need
731 to add or modify parts of <productname>eCos</productname> itself. It
732 describes the following things:
737 <TERM>Overview</TERM>
739 <PARA>An explanation of the configuration technology used in
740 <productname>eCos</productname>, why it is done this way, how it
741 works and the terminology used.
747 <TERM>Package Organization</TERM>
749 <PARA>A description of the <productname>eCos</productname> package
750 repository, how it is organized and how packages themselves are
757 <TERM>The CDL Language</TERM>
759 <PARA>A description of the CDL language and how it is used to
760 control the configuration of <productname>eCos</productname>
761 components. The document also contains a complete specification of
768 <TERM>The Build Process</TERM>
770 <PARA>A description of what happens once a configuration has been
771 created and must be built into a set of executables.