eCos is distributed under the GPL license with an exception which permits proprietary application code to be linked with eCos without itself being forced to be released under the GPL. It is also royalty and buyout free. As an Open Source project, eCos is under constant improvement, with an active developer community, based around the eCos web site at http://ecos.sourceware.org/. Powerful GUI-based configuration system allowing both large and fine grained configuration of eCos. This allows the functionality of eCos to be customized to the exact requirements of the application. Full-featured, flexible, configurable, real time embedded kernel. The kernel provides thread scheduling, synchronization, timer, and communication primitives. It handles hardware resources such as interrupts, exceptions, memory and caches. The Hardware Abstraction Layer (HAL) hides the specific features of each supported CPU and platform, so that the kernel and other run-time components can be implemented in a portable fashion. Support for µITRON and POSIX Application Programmer Interfaces (APIs). It also includes a fully featured, thread-safe ISO standard C library and math library. Support for a wide variety of devices including many serial devices, ethernet controllers and FLASH memories. There is also support for PCMCIA, USB and PCI interconnects. A fully featured TCP/IP stack implementing IP, IPv6, ICMP, UDP and TCP over ethernet and serial interfaces. Support for SNMP, HTTP, TFTP, PPP and FTP is also present. A lightweight TCP/IP stack (lwIP) implementing IP, ICMP, UDP and TCP over ethernet and serial interfaces. A lightweight implementation of the C++ Standard Template Library (uSTL). The RedBoot ROM monitor is an application that uses the eCos HAL for portability. It provides serial and ethernet based booting and debug services during development. Many components include test programs that validate the components behaviour. These can be used both to check that hardware is functioning correctly, and as examples of eCos usage. eCos documentation included this User Guide, the Reference Manual and the Components Writer's Guide. These are being continually updated as the system develops. eCos is an open source, configurable, portable, and royalty-free embedded real-time operating system. The following text expands on these core aspects that define eCos. eCos is provided as an open source runtime system supported by the GNU open source development tools. Developers have full and unfettered access to all aspects of the runtime system. No parts of it are proprietary or hidden, and you are at liberty to examine, add to, and modify the code as you deem necessary. These rights are granted to you and protected by the GNU Public License (GPL). An exception clause has been added to the eCos license which limits the circumstances in which the license applies to other code when used in conjunction with eCos. This exception grants you the right to freely develop and distribute applications based on eCos. You are not expected or required to make your embedded applications or any additional components that you develop freely available so long as they are not derived from eCos code. We of course welcome all contributions back to eCos such as board ports, device drivers and other components, as this helps the growth and development of eCos, and is of benefit to the entire eCos community. See for more details. One of the key technological innovations in eCos is the configuration system. The configuration system allows the application writer to impose their requirements on the run-time components, both in terms of their functionality and implementation, whereas traditionally the operating system has constrained the application's own implementation. Essentially, this enables eCos developers to create their own application-specific operating system and makes eCos suitable for a wide range of embedded uses. Configuration also ensures that the resource footprint of eCos is minimized as all unnecessary functionality and features are removed. The configuration system also presents eCos as a component architecture. This provides a standardized mechanism for component suppliers to extend the functionality of eCos and allows applications to be built from a wide set of optional configurable run-time components. Components can be provided from a variety of sources including: the standard eCos release; commercial third party developers or open source contributors. The royalty-free nature of eCos means that you can develop and deploy your application using the standard eCos release without incurring any royalty charges. In addition, there are no up-front license charges for the eCos runtime source code and associated tools. We provide, without charge, everything necessary for basic embedded applications development. eCos is designed to be portable to a wide range of target architectures and target platforms including 16, 32, and 64 bit architectures, MPUs, MCUs and DSPs. The eCos kernel, libraries and runtime components are layered on the Hardware Abstraction Layer (HAL), and thus will run on any target once the HAL and relevant device drivers have been ported to the target's processor architecture and board. Currently eCos supports a large range of different target architectures: ARM, Cortex-M, Intel StrongARM and XScale Fujitsu FR-V, FR30 Hitachi SH2/3/4 Hitachi H8/300H, H8S Intel x86 MIPS Matsushita AM3x Freescale PowerPC Freescale 68k/Coldfire NEC V850 Sun SPARC including many of the popular variants of these architectures and evaluation boards. eCos has been designed to support applications with real-time requirements, providing features such as full preemptability, minimal interrupt latencies, and all the necessary synchronization primitives, scheduling policies, and interrupt handling mechanisms needed for these type of applications. eCos also provides all the functionality required for general embedded application support including device drivers, memory management, exception handling, C, math libraries, etc. In addition to runtime support, the eCos system includes all the tools necessary to develop embedded applications, including eCos software configuration and build tools, and GNU based compilers, assemblers, linkers, debuggers, and simulators. To get the most out of eCos you should visit the eCos open source developers site: http://ecos.sourceware.org/. The site is dedicated to the eCos developer community and contains a rich set of resources including news, FAQ, online documentation, installation guide, discussion and announcement mailing lists, and runtime and development tools downloads. The site also supports anonymous CVS and WEBCVS access to provide direct access to the latest eCos source base. eCos is released as open source software because we believe that this is the most effective software development model, and that it provides the greatest benefit to the embedded developer community as a whole. As part of this endeavor, we seek the input and participation of eCos developers in its continuing evolution. Participation can take many forms including: providing us with feedback on how eCos might be made more useful to you - by taking part in the ongoing mailing list discussions and by submitting problem reports covering bugs, documentation issues, and missing features contributing bug fixes and enhancement patches contributing new code including device drivers, board ports, libraries, and other runtime components Our long term aim is to make eCos a rich and ubiquitous standard infrastructure for the development of deeply embedded applications. This will be achieved with the assistance of the eCos developer community cooperating to improve eCos for all. We would like to take this opportunity to extend our thanks to the many eCos developers who have already contributed feedback, ideas, patches, and code that have augmented and improved this release. The eCos Maintainers As of May 2002, eCos is released under a modified version of the well known GNU General Public License (GPL), now making it an official GPL-compatible Free Software License. An exception clause has been added to the eCos license which limits the circumstances in which the license applies to other code when used in conjunction with eCos. The exception clause is as follows: As a special exception, if other files instantiate templates or use macros or inline functions from this file, or you compile this file and link it with other works to produce a work based on this file, this file does not by itself cause the resulting work to be covered by the GNU General Public License. However the source code for this file must still be made available in accordance with section (3) of the GNU General Public License. This exception does not invalidate any other reasons why a work based on this file might be covered by the GNU General Public License. The goal of the license is to serve the eCos user community as a whole. It allows all eCos users to develop products without paying anybody anything, no matter how many developers are working on the product or how many units will be shipped. The license also guarantees that the eCos source code will always be freely available. This applies not only to the core eCos code itself but also to any changes that anybody makes to the core. In particular, it should prevent any company or individual contributing code to the system and then later claiming that all eCos users are now guilty of copyright or patent infringements and have to pay royalties. It should also prevent any company from making some small improvements, calling the result a completely new system, and releasing this under a new and less generous license. The license does not require users to release the source code of any applications that are developed with eCos. However, if anybody makes any changes to code covered by the eCos license, or writes new files derived in any way from eCos code, then we believe that the entire user community should have the opportunity to benefit from this. The license stipulates that these changes must be made available in source code form to all recipients of binaries based on the modified code, either by including the sources along with the binaries you deliver (or with any device containing such binaries) or with a written offer to supply the source code to the general public for three years. It is perhaps most practical for eCos developers to make the source code available online and inform those who are receiving binaries containing eCos code, and probably also the eCos maintainers, about the location of the code. See the full text of the GPL for the most authoritative definition of the obligations. Although it is not strictly necessary to contribute the modified code back to the eCos open source project, we are always pleased to receive code contributions and hope that developers will also be keen to give back in return for what they received from the eCos project completely free of charge. The eCos maintainers are responsible for deciding whether such contributions should be applied to the public repository. In addition, a copyright assignment is required for any significant changes to the core eCos packages. The result is a royalty-free system with minimal obligations on the part of application developers. This has resulted in the rapid uptake of eCos. At the same time, eCos is fully open source with all the benefits that implies in terms of quality and innovation. We believe that this is a winning combination. The following queries provide some clarification as to the implications of the eCos license. They do not consititute part of the legal meaning of the license. Q. What is the effect of the eCos license? A. In the simplest terms, when you distribute anything containing eCos code, you must make the source code to eCos available under the terms of the GPL. Q. What if I make changes to eCos, or write new code based on eCos code? A. Then you must make those changes available as well. Q. Do I have to distribute the source code to my application? Isn't the GPL "viral"? A. You do not have to distribute any code under the terms of the GPL other than eCos code or code derived from eCos. For example, if you write a HAL port based on copying an existing eCos HAL in any way, you must make the source code available with the binary. However you would not need to make available any other code, such as the code of a wholly separate application linked with eCos. Q. I would rather stick with the RHEPL code, but I updated my anonymous CVS checkout. A. You can check out the final version of anonymous CVS before the license change using the CVS tag last-rhepl. See the anonymous CVS access page for details. Prior to May 2002, eCos was released under the Red Hat eCos Public License (RHEPL). The RHEPL required any modifications to eCos code to be made available under preferential terms to Red Hat and was therefore incompatible with code licensed under the GPL. The use of eCos source code which was licensed under the RHEPL is not affected by the switch to the modified GPL for later revisions. Since there are many supported target architectures, notation conventions are used in this manual to avoid repeating instructions that are very similar. Cross-development commands like gcc and gdb will be shown with a TARGET- prefix. You need to replace TARGET- with the correct prefix before using the command. Just using gcc or gdb will use the tools for the host, which is not (usually) what you want. For example use arm-elf-gcc and arm-elf-gdb for ARM, Thumb, and StrongARM targets. Use xscale-elf-gcc and xscale-elf-gdb for Intel Xscale targets. Use i386-elf-gcc and i386-elf-gdb for IA32 targets. And so on, the exact prefix to use is shown in the documentation for each target. Note that some versions of the GCC cross compiler generate executable files with the .exe suffix on Windows, but not on Linux. The suffix .exe will be omitted from executable file names, so you will see hello instead of hello.exe. The default directory for installing eCos on Windows (usually C:/Program Files/eCos) is different from that on Linux (usually /opt/ecos). Since many command line examples in the tutorials use these paths, this default (base) directory will be cited as BASE_DIR. Windows and Linux have a similar file system syntax, but the MS-DOS command interpreter on Windows uses the backslash character (\) as a path separator, while Linux and POSIX shells (including the Cygwin bash shell for windows) use the forward slash (/). This document will use the POSIX shell convention of forward slashes throughout. This manual does not refer explicitly to any particular version of eCos. However, version numbers form part of many file path names. In all of these places the version number will be shown like this: &Version;. If you have used anonymous CVS to check eCos out of the CVS repository, the version number will always be current, since that is the name of the directory in the repository. When a stable release is made this directory name is changed, in the release, to the number of the release, for example v2_0 or v2_1. The eCos documentation is divided into a three main parts: User Guide This document. It includes the following sections: Installing eCos This section describes how to install the eCos software, how to set up your hardware and how to test that it is all working. Programming Under eCos This section describes how to write programs that run under eCos by running through some examples. The eCos Configuration Tool This section describes the eCos graphical configuration tool and how to use it to change how eCos behaves. eCos Programming Concepts and Techniques An explanation of the eCos programming cycle, and a description of some debugging facilities that eCos offers. Configuration and the Package Repository Information on how to configure eCos manually, including a reference on the ecosconfig command, memory layouts, and information on how to manage a package repository using the eCos Package Administration Tool. Reference Guide The Reference Guide provides detailed documentation on various aspects of eCos. This document is being constantly updated, so the following list just mentions the more important sections, take a look at the guide itself for the full story. The eCos Kernel In-depth description of eCos"s native C kernel API Important considerations are given for programming the eCos kernel. The semantics for each kernel function are described, including how they are affected by configuration. POSIX and µITRON APIs A description of the POSIX and µITRON APIs and how they are supported under eCos. The eCos Hardware Abstraction Layer (HAL) A description of the structure and functionality of the eCos HAL. This section also includes a porting guide to help moving eCos to different platforms. Device Drivers A description of the philosophy behind eCos device drivers, as well as a presentation of the C language APIs for using the current device drivers. Device driver support includes serial, ethernet and FLASH devices, and support for PCI, PCMCIA and USB interconnects. RedBoot User's Guide This describes RedBoot, which provides a complete bootstrap environment for a range of embedded operating systems, such as embedded Linux and eCos, and includes facilities such as network downloading and debugging. It also provides a simple flash file system for boot images. TCP/IP Stack Support This describes the Common Networking for eCos package, which provides support for a complete TCP/IP networking stack. The design allows for the actual stack to be modular and at the current time two different implementations, one based on OpenBSD from 2000 and a new version based on FreeBSD, are available. Other components related to networking, including support for SNMP, DNS, HTTP and FTP, are also described. Component Writer's Guide The Component Writer's Guide is intended for developers who need to add or modify parts of eCos itself. It describes the following things: Overview An explanation of the configuration technology used in eCos, why it is done this way, how it works and the terminology used. Package Organization A description of the eCos package repository, how it is organized and how packages themselves are organized. The CDL Language A description of the CDL language and how it is used to control the configuration of eCos components. The document also contains a complete specification of the language. The Build Process A description of what happens once a configuration has been created and must be built into a set of executables.