Subversion Repositories openrisc

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 

URL="http://ecos.sourceware.org/">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 

        LINKEND="ecos-licensing"> 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: 

URL="http://ecos.sourceware.org/">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 

url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License

(GPL), now making it an 

url="http://www.gnu.org/philosophy/license-list.html">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 

url="http://ecos.sourceware.org/assign.html">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 

url="http://ecos.sourceware.org/anoncvs.html">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.