ECos.mw

== Introduction ==

eCos is a popular, open source, real-time operating system. 
It has been used in a wide variety of applications[http://www.ecoscentric.com/ecos/examples.shtml].

eCos is a highly configurable system. 
Using provided tools, it is possible to perform a detailed configuration of all packages 
and therefore fulfill different requirements. 
Using eCos HAL, it is also possible to build RedBoot, the popular bootstrap environment.

== Status of the port ==

The port introduces a target called ORPSoC. 
This target refers to the [http://opencores.org/or1k/ORPSoC ORPSoC project]. 
It is also suitable for [http://opencores.org/or1k/OR1K:MinSoC MinSoC], but some configuration options (such as memory size) may need to be changed.

The current version of the port is tracking the mainline eCos repository.
All changes have been rewritten against the code already checked in the official eCos repository.

The port is under constant development.
It has been tested under or1ksim, version 0.5.1rc1, and under ordb2 hardware.
The provided default configuration passes all eCos test cases.

== Device Drivers ==

Following peripherals are supported:
* UART 16550 ([http://opencores.org/project,uart16550 uart16550])
* SPI ([http://opencores.org/project,simple_spi simple_spi])
* Ethernet MAC 10/100 Mbps ([http://opencores.org/project,ethmac ethmac])
* SD Card Controller ([http://opencores.org/project,sdcard_mass_storage_controller sdcard_mass_storage_controller])

== Requirements ==

The [http://opencores.org/or1k/OpenRISC_GNU_tool_chain OpenRISC GNU toolchain], built with newlib is required.

== Getting eCos ==

Currently, eCos is hosted on OpenCores SVN:

  svn co http://opencores.org/ocsvn/openrisc/openrisc/trunk/rtos/ecos-3.0

== Installing eCos ==

eCos uses two tools to build and configure the system: configtool and ecosconfig.
ecosconfig is a handy command line program that allows to select the desired eCos target and packages.
configtool is a windowed application that provides a clear and intuitive environment 
to adjust all of the possible configuration options.

There is a pre-built binary of configtool available:

  wget http://www.ecoscentric.com/snapshots/configtool-100305.bz2
  bunzip2 configtool-100305.bz2
  chmod u+x configtool-100305
  ln -s configtool-100305 /usr/local/bin/configtool

ecosconfig needs to be built from scratch. 
In order to build ecosconfig, go to the ecos-3.0 directory downloaded from SVN.

  ./host/configure

''Note'': If the build fails saying it cannot find the hosts's TCL config information, you'll need to install the tcl-dev and tk-dev packages

By default, ecosconfig installs itself in the /usr/local/ directory. 
If you like, you can change that directory to something else:

  ./host/configure --prefix=/desired_path

Finally build the tool

  make
  make install

Both ecosconfig and configtool require environmental variable ECOS_REPOSITORY.
The variable must point to the packages directory, inside ecos-3.0 tree.
To set the variable, go to the downloaded ecos-3.0 tree.

  ECOS_REPOSITORY=`pwd`/packages
  export ECOS_REPOSITORY

== Configuring eCos for OpenRISC ==

Create a directory to build the eCos library.

 mkdir ecos-work
 cd ecos-work

First start with the default template:

  ecosconfig new orpsoc

The default configuration fits ORPSoC port for [http://opencores.org/or1k/Ordb2a-ep4ce22 ordb2 reference platform].
It assumes that hardware multiplication and division are implemented.
Floating point variables are handled by software.
System clock runs at 50 MHz.
If you are using MinSoC, or ORPSoC with different configuation, you need to alter the settings:

  configtool ecos.ecc

[[File:configtool.png|700px]]

After all modifications are done, save the changes to the ecc file.
It is always a good idea to check for possible conflicts.

  ecosconfig check

== Building eCos with tests ==

  ecosconfig tree
  make
  make tests  

Note that <code>ecosconfig tree</code> will create the skeleton build tree directory structure.

== Writing a program with eCos ==

It is now possible to write programs linked with eCos.
The most simple hello world program would look like this:

  #include <stdio.h>
  int main(void) {
    printf("Hello World\n");
    return 0;
  }

Refer to the [http://www.ecoscentric.com/ecospro/doc/html/ref/index.html eCos Reference Manual] 
for additional information about kernel mechanisms and drivers.

To do a stand-alone compilation of the program, you have to use a number of compiler flags: -mhard-mul/-msoft-mul, div, float, branch etc. It is therefore a bit cumbersome to compile eCos applications this way - a far better option is to use GNU make instead and import flags that have already been computed based on the eCos configuration, as they already contain everything that is necessary. A small, heavily commented Makefile example given below can easily be adapted to your needs.

  # This variable should point to the directory where you 
  # installed your eCos build.
  ECOS_INSTALL := ../ecos_build/install/
  
  # As part of the build process, eCos automatically creates
  # a file with compiler flags. Those flags are computed based
  # on the ecc configuration file. It is smart to use them when
  # compiling your application.
  include $(ECOS_INSTALL)/include/pkgconf/ecos.mak
  
  # Unfortunately, some flags are C++ flags and some are C. We
  # need to separate them. The file rules.mak shipped with the eCos
  # repository contains the rules to do it. So we need to include
  # this file in the end of the makefile and use more generic
  # names. We also add the paths to the installation directory.
  CFLAGS := $(ECOS_GLOBAL_CFLAGS) -I $(ECOS_INSTALL)/include
  LDFLAGS := $(ECOS_GLOBAL_LDFLAGS) -L $(ECOS_INSTALL)/lib -T $(ECOS_INSTALL)/lib/target.ld
  
  # Rules to build the application
  all: hello_world
  
  hello_world: hello_world.c
    $(ECOS_COMMAND_PREFIX)gcc $(ACTUAL_CFLAGS) $(LDFLAGS) $< -o $@
  
  # Now include the file with rules. This file must be included
  # in the end, otherwise it interferes with the makefile target.
  include $(ECOS_REPOSITORY)/pkgconf/rules.mak

== Running eCos programs in or1ksim ==

Running programs in or1ksim is very easy.

  or32-elf-sim -f sim.cfg program_elf

sim.cfg is a simulator configuration. 
You can find the configuration that fits ordb2 board in the ORPSoC project tree.

== Running eCos programs on ordb2 hardware ==

The most convenient way is to run the program using GDB debugger.
First, start or_debug_proxy:

  or_debug_proxy -r 50001

Then, open the UART link:

  picocom -b 115200 /dev/ttyUSB1

Finally, upload the program via gdb:

  or32-elf-gdb program_elf
    target remote :50001
    load
    spr npc 0x100
    c

It is also possible to execute ecos tests.
The following screen presents reslts of the timelice test.

[[File:ecos_timeslice.png]]

== Coming soon ==

* Fix the cache bug
* Add option to use l.nop opcode for printch
* Add option whether MAC unit is present or not
* Add configuration options for peripheral addresses and interrupt numbers
* Add interrupt mode for SPI driver
* Add support for multiple UARTs
* Review ETHMAC driver (problem with jamming descriptors)
* Fix assembly code to use find first instructions
* Add ordb2 platform HAL with m25pxx flash driver
* Prepare the code structure to support non-compatible OR2k
* Send the code to eCos repositories

== Bugs and patches ==

If you want to file a bug report or patch, please send them on the mailing lists.