NUT/OS


Modules

 Nut/OS API
 Ethernut Operating System API.
 System Initialization
 Nut/OS initialization.
 Nut/Net API
 Nut/Net TCP/IP Stack.
 Socket API
 File System API.
 Micro-ROM File System.
 Simple program space file system.
 Device Driver API.
 Input and output device functions.
 Hardware Layout.
 Definitions of I/O ports.
 C Runtime Library.
 Complementary runtime support.
 Standard I/O
 Standard stream interface to Nut/OS devices.
 Nut/OS Mods.
 Modifying system rotuines.
 Guarded heap routines.
 Contributed by Peter Scandrett.
 Port Configure
 MCan-Cfg
 Avr - ADC
 Can-Dev
 H8 - Uart
 CanSJA1000
 Unix Emulation
 Net
 Mutex
 Semaphore
 Message Queue
 gAhdlc Avr
 AhdlcAvr
 IR
 IR Sony
 Debug H8

Setting the Compiler Environment

The first decision that has to be made, is to select the development platform you want to use. The commercial ImageCraft Compiler offers an advanced IDE and is the first choice of most professional developers using a Windows PC. The GNU compiler AVR-GCC is available for Linux and Windows (WinAVR).

In order to start with your own Embedded Ethernet Application, take one of the samples like TCPS and add some modifications. Then recompile and link it with the Nut/OS library by using the prepared Makefile for the GNU compiler or simply press the "Build" button of the ImageCraft IDE. The ImageCraft IDE comes with an integrated tool to upload the resulting binary into your Ethernut Board. The GNU archive provides a command line utility named usip, which takes over this task. Also note, that Ethernut applications are linked to the Nut/OS operating system and its TCP/IP Stack. The resulting binary file contains all three parts, the application, Nut/OS and Nut/Net. The advantage is, that only those parts of the operating system are included, which your application really needs, leaving more room for application code.

The next chapters will provide more detailed instructions.

Configuring the Nut/OS Development for Linux.

Linux users are relieved of the burden choosing a compiler, but the installation is a bit different from the dumb click and clack being required under Windows.

There is no all round packet like WinAVR, you need collect all required parts first. These are

The next problem will arise, if your Linux system doesn't provide rpm support. The following steps had been tested on Redhat 9 and should work under Suse too. Different steps may be required for Debian.

To install the compiler, change to the directory where all packets have been downloaded to. When using the Ethernut Starter Kit, they are located on the CDROM. Then install the rpms. Note, that the filenames may differ, if you got newer releases.

 cd /cdrom/gnu-c/gcc_linux/
 rpm -Uvh \
 avr-binutils-2.13.90.030512-1.i386.rpm \
 avr-gcc-3.2.90.20030512-1.i386.rpm \
 avr-gcc-c++-3.2.90.20030512-1.i386.rpm \
 avr-libc-20030512cvs-1.i386.rpm \
 avr-libc-docs-20030512cvs-1.i386.rpm 

If not done previously you may install uisp now.

 cd /cdrom/tools/linux/
 tar -zxvf uisp-20030618.tar.gz -C ~/
 cd ~/uisp-20030618/
 ./configure
 make
 make install 

Finally install the Nut/OS and Nut/Net sources.

 cd /cdrom/ethernut/unix/
 tar -zxvf ethernut-3.3.2.tar.gz -C ~/
 cd ~/ethernut-3.3.2/nut/
 ./configure 

The configure script will guide you through the final steps, selecting the right CPU and the type of your programming adapter.

You may now rebuild the Nut/OS libraries by entering

 make clean
 make install 

This step should be passed without any errors or even warning. If not, you may have used the wrong compiler or library version.

Now you can check, if you are able to compile the http daemon sample and upload the resulting binary to your Ethernut board.

 cd app/httpd/
 make burn 

Configuring the Nut/OS Development for Windows.

After having choosen the compiler, you are ready to configure the development environment. You should have installed your compiler and Nut/OS. Open a command line window (DOS window) and change to the Nut/OS installation directory.

Now you need to set the correct path to the subdirectory, where all the binaries of your compiler are installed.

For ICCAVR you may enter something like

 SET PATH=C:\icc\bin;%PATH% 

The typical WinAVR installation may require

 SET PATH=C:\WinAVR\bin;C:\WinAVR\utils\bin;%PATH% 

Next enter

 nutconf 

which will start the configuration tool. Again select the right compiler, the type of CPU and the programming adapter you are using and press the Configure button. Confirm to rebuild the libraries. Nut/OS comes with ready build libraries, but when using ICCAVR, these libraries need to be copied to the compiler's lib directory. For AVRGCC there's no need to rebuild them, but it didn't hurt.

If you want to change the compiler or in case you modified any part of the system, you can call nutconf again later to change your settings and create a new library version.

Using the ImageCraft IDE.

The ImageCraft IDE should be used for your application code only. Compiling the Nut/OS libraries requires a command line environment (see next section).

Executing nutconf as described above copies all Nut/OS libraries to the ImageCraft library directory.

Before creating Nut/OS applications, you have to enter some special settings in the ImageCraft Project. On the first page of the Compiler Options Dialog you need to add the Nut/OS include file path. Note, that the path of your ImageCraft directory may differ.

 ..\..\include\;C:\icc\include\

On the second page the macro define

 _MCU_enhanced 

has to be added if you are developing for the ATmega128.

On the last page you must add the following additional libs.

 nutpro nutnet nutfs nutos nutdev nutcrt 

On the same page enter

 -ucrtnut.o c:\icc\lib\nutinit.o 

in the field named Other Options. Again, your path to the ImageCraft directory may differ. Please refer to the ICCAVR Online Manuals for further assistance.

Command Line Environment for ICCAVR

In case you avoid IDEs in general or if you want to make your own modifications to Nut/OS libraries, then you must use a shell, also known as the DOS window or command line.

Change to the Nut/OS installation directory and make sure, that your PATH includes the ICCAVR bin directory.

To rebuild the complete library, enter

 make clean 

followed by

 make install 

All Nut/OS and Nut/Net libraries should compile and link without problem and will be copied to the Nut/OS lib directory. The configure tool will then copy these libraries to the ImageCraft lib directory.

Get yourself familiar with the GNU make utility.

Most applications written for AVR-GCC will not run properly when compiled by ICCAVR. Specifically the macro PSTR() will not work with ICCAVR. For porting, refer to the samples in subdirectory appicc.

Command Line Environment for WinAVR

Open a shell and change to the directory, which contains your application source code. Make sure, that your PATH includes the AVRGCC bin directory. WinAVR users must include two directories in their path.

 SET PATH=C:\WinAVR\bin;C:\WinAVR\utils\bin;%PATH% 

To build you application's hex file, simply enter

 make 

If you are using uisp for uploading the hex file to the target system, you can enter

 make burn 

This will build your application and, if successful, automatically program your target.

To rebuild the complete Nut/OS library, change to the Nut/OS installation directory and enter

 make clean 

followed by

 make install 

If successful, the new libraries will be copied to the Nut/OS lib directory.

How to contribute.

Contributions to Nut/OS are most welcome. If you want to, please try to follow some rules to keep the code consistent and easy to read.

No one will reject your code, if you don't follow these rules. However, it may take more time until it appears in an official release.

History

Since version 3.3 this list has been replaced by a standard ChangeLog file.

Version 3.3.2

Version 3.3.1

Version 3.3.0

Version 3.2.2

Version 3.2.1

Version 3.1.9

Version 3.0.1

Version 2.6.0

Note: IDE, Compact Flash and PPP are still experimental code.

Version 2.5.91 (unstable)

Version 2.5.9 (unstable)

This driver is stable for my configuration but will need work if it is going to be generally useful, as such it is being released as a pre-alpha driver at this stage. Specific things that are known to be missing or need work are:

User Authentication

Link state management (please discuss with me if you are planning to work on this)

CRC should be table based

DNS server update handling (Ethernut native resolver not presently supported)

Outbound Async Character mapping should be improved

Version 2.5.2

Version 2.5.1

Version 2.5.0

Version 2.4.2

Version 2.4.1

Version 2.3.4

Version 2.3.3

Version 2.3.2

Version 2.3.1

Version 2.2.2

Version 2.2.1

Version 2.1.3

Version 2.1.1

Copyright Statement

Nut/OS and Nut/Net are

Copyright (C) 2000-2003 by egnite Software GmbH. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgement:

This product includes software developed by egnite Software GmbH and its contributors.

THIS SOFTWARE IS PROVIDED BY EGNITE SOFTWARE GMBH AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL EGNITE SOFTWARE GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This file is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You can redistribute this file and/or modify it under the terms of the GNU General Public License (GPL) as published by the Free Software Foundation; either version 2 of the License, or (at your discretion) any later version. See the accompanying file "copying-gpl.txt" for more details.

As a special exception to the GPL, permission is granted for additional uses of the text contained in this file.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgement: This product includes software developed by the University of California, Berkeley and its contributors. 4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies, and that the name of Digital Equipment Corporation not be used in advertising or publicity pertaining to distribution of the document or software without specific, written prior permission.

THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL DIGITAL EQUIPMENT CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Preamble

Whilst the GNU General Public License is generally suitable for most operating system applications within a workstation or server environment, it presents certain obstacles that prevent its wide acceptance within many embedded application fields. In particular the requirements that prevent the linking of software licensed under the GPL with software that is not licensed under the GPL present a serious problem to many would-be users who for various reasons are unable to comply with this.

With this in mind, Liquorice is released with the a special exception to the GNU Public License that permits some additional uses of the software.

Special Exception

If you choose to link software from Liquorice with other files to produce an executable, this does not by itself cause the resulting executable to be covered by the GNU General Public License. Your use of the executable is in no way restricted on account of linking the Liquorice code with it.

This exception does not however invalidate any other reason why the executable file might be covered by the GNU General Public License.

This exception applies only to the code released by David J. Hudson and any other identified copyright holder under the name Liquorice. If you copy other code that is released by its copyright holder under the GNU General Public License into a copy of Liquorice, as the GNU General Public License permits, then this exception does not apply to the code that you add in this way. To avoid misleading anyone as to the status of such modified files, you must delete references to this exception notice from them.

If you write modifications of your own for Liquorice, it is your choice whether to permit this exception to apply to your modifications. If you do not wish this, delete references to this exception notice from the affected files.


Generated on Tue Jan 23 21:12:26 2007 for BTnut System Software by doxygen 1.4.7