NutOsFaq
This FAQ is quite old and strangely formatted. I've started a new one.
Contents
General
Terms
Q: What are Nut/OS, Nut/Net and Ethernut?
A: Ethernut is the name of an Open Source Hardware and Software Project for building Embedded Ethernet Devices. The hardware part is a small board, also named Ethernut. Nut/OS is the name of a tiny real time operating system, which had been written to implement a TCP/IP stack. The TCP/IP part has been named Nut/Net.
Why use Nut/OS?
Q: I plan to use an ATmega128 with two serial ports and SPI or I2C. Is it necessary to put an OS in it?
A: It depends. One advantage of using an operating system like Nut/OS is, that you don't need to deal with low level hardware. For example, you can use C stdio calls like printf for the serial ports and thus write very portable code, which may also run on your desktop computer. For SPI and I2C (called TWI by Atmel) there is a very basic support only.
Q: If I use Nut/OS, can I separate Nut/OS from TCP/IP?
A: Yes. Nut/OS is a modular RTOS. Only those parts are linked to the application code, which are actually referenced.
Q: Can I use Nut/Net with a different OS like FreeRTOS?
A: Not easily. Nut/Net uses many Nut/OS specific calls and it might be difficult to map them to similar routines offered by another system. Also note, that Nut/Net depends on cooperative multithreading.
Getting Started
Q: How Do I Get Started?
A: In the first place you need the hardware. The hardware design is free, but typically hardware itself costs money. Nut/OS is very flexible and can be adopted to a wide range of embedded systems.
If you are a professional developer, we'd recommend to buy any ready-to-run hardware with official Nut/OS support. While a few boards are directly programmable via standard PC interfaces (RS-232, USB, Ethernet), most of them require a special programming adapter (JTAG, SPI). Many vendors offer so called starter or evaluation kits with the programming adapter included. While some vendors add all cables and the power supply to their starter kits, others don't. Carefully check, what else may be required to get your board up and running (typically RS-232 cable, Ethernet cable, power supply and programming/debugging adapter).
As a hobbyist with some experience in building boards with fine pitch SMD chips you may prefer to build the hardware yourself. Eagle CAD files for all reference designs are provided and can be used freely.
All required software including documentation and sample code can be downloaded from project's website. While a few specific tools like the Configurator and the UROM filesystem builder are included in the distribution, you need to get the compiler and related tools from other sources. For all supported platforms Nut/OS can be build with the free GNU Compiler Collection (GCC) on Linux, Windows and Mac OS X. For AVR targets the commercial ImageCraft Compiler offers an advanced IDE and is a convenient alternative for professional developers using a Windows PC.
Timing Issues
Q: Nut/OS is multithreaded. What about the context switch overhead?
A: Last calculations had been done for the AVR platform by Oliver Schulz on Nut/OS 3.4 and 3.5. Result was 115 cycles. They should be still valid for 3.9 and upcoming 4.0.
Q: What about the interrupt overhead?
A: Again only the AVR platform had been investigated. When using a separate interrupt stack, 64 cycles are required. Interrupts using the application stack need 45 cycles.
Q: Does Nut/OS provide real-time guarantees?
A: This part still has to be investigated. Several system routines disable interrupts by calling ~NutEnterCritical(). The duration depends on various conditions like the number of active timers, the number of ready-to-run threads etc. It has been reported, that the UART driver sometimes loses characters at 115.200 baud on a 7.328 Mhz AVR CPU. That means, that interrupts may be blocked for more than 170 microseconds or more than 1000 instructions. It's unknown, which critical section consumes this large number of cycles.
AVR Board Hardware Design
Homebrewing
Q: Can I make the PCB myself?
A: Probably not the same board in low quantities for a low price. The PCB has 4 layers with solder mask, hot air leveling finish (or gold plated with Ethernut 2) and component print. Each has been electrically tested against the Gerber data. However, it is possible, to create a 2 layer PCB from the schematics, which should be cheaper. If you want to do that or if you need a specific layout or different board dimensions, then you can download the original CAD files from the download area. The layout has been done with Eagle 4.0 from CadSoft. This software had been choosen because it is relatively cheap and easy to use. Windows, Linux and Mac OS X are supported and a limited freeware version as well as a low cost, non profit version are offered.
Q: Are there any CAD files for Protel, Orcad, XYZ?
A: Mohammad Reza Khalaj kindly contributed a version for Protel DXP.
CPU Speed
Q: Why do you use a 14.7456 MHz crystal?
A: Baudrates for the serial ports depend on the CPU crystal. For the 16 MHz ATmega 128, 14.7456 MHz is the optimal crystal frequency to allow most standard baudrates. If you don't need standard baudrates, you can change the crystal to the maximum CPU frequency.
Q: Can I overclock the CPU?
A: We tried to run an ATmega 128 at 18.430 MHz without problems.
Q: Can I replace the ATmega128 with the AT90CAN128?
A: Yes, but this requires hardware as well as software changes. Henrik Maier posted
some info in the Ethernut Mailing List.
"The current Nut/OS source needs some minor changes to allow recompilation for the AT90CAN128 device.
The main areas where changes are needed is the external memory interface configuration registers and
interrupt vectors and a lot of #ifdef sections of the type ~__AVR_ATmega128__ which also need to be
compiled for the AT90CAN128.
The accuracy of the baud rates depends on the crystal frequency used. The following table has been
calculated for the AT90CAN128 for typical crystal values.
At 14.7456 the CAN baud rate error rate is greater than the 0.5% allowed by the CAN spec for typical
CAN baud rates.
At 16.0 MHz the UART baud rates are acceptable for up to 57600 bps. 115200 has an error of 2.12% which
above the 1.5% mark recommended by Atmel but still below the 3% mark usually mentioned in the literature.
However if a low baud rate error for 115200 bps is required then I recommend to use a 12 MHz crystal as
the table below shows. The UART baud rate error is only 0.16% and the CAN baud rate error 0%."
UART MHz 14.7456 12.0000 12.2880 14.0000 14.3182 16.0000 9600 0.00% 0.16% 0.00% 0.16% 0.23% 0.16% 38400 0.00% 0.16% 0.00% 0.93% 0.83% 0.16% 57600 0.00% 0.16% 1.23% 1.27% 0.23% 0.79% 115200 0.00% 0.16% 2.56% 1.27% 2.90% 2.12% 230400 0.00% 6.99% 4.76% 5.06% 2.90% 3.55% CAN MHz 14.7456 12.0000 12.2880 14.0000 14.3182 16.0000 100k 1.70% 0.00% 2.40% 0.00% 0.57% 0.00% 125k 1.70% 0.00% 0.31% 0.00% 0.48% 0.00% 250k 1.70% 0.00% 1.70% 0.00% 2.27% 0.00% 500k 1.70% 0.00% 2.40% 0.00% 2.27% 0.00% 1000k 5.33% 0.00% 2.40% 0.00% 2.27% 0.00%
In a second post Henik added:
"I just looked up the CAN specification again and found that 0.5% was for CAN 1.0 and CAN 1.1. Since 2.0 they allow a maximum oscill
ator tolerance of 1.58%. With the 1.70% baud rate error for the classic 14.7456 Mhz crystal still far out and there is still the cry
stal's tolerance to be added to the overall error budget as well."
Ethernet Controller
Q: Is the Ethernet Controller attached to the CPU address and data bus?
A: Yes, in order to provide maximum performance the Ethernet Controller is connected to the address and data bus.
Q: How much address space is used by the RTL8019AS?
A: The Realtek controller has an on-chip address decoder. On the Ethernut board it occupies addresses 8300 through 831F hex.
Q: Many other 8-bit systems use the CS8900. Why did you select the Realtek chip?
A: In the early design stage we've been told, that the Crystal chip can't handle interrupts reliable in 8-bit mode.
So the sample, which had been kindly provided by Crystal never made it on a board. We are not able to confirm the
above statement, but we have to learn, that the Realtek has some flaws. For a long time Ethernuts crashed under
heavy traffic. Luckily we were able to solve these problems by software.
Back to the CS8900. It is working fine in polled mode, but when running in 8 bit mode, the chip suddenly stops
generating interrupts. This could be provoked by ping flooding the controller. Using a hybrid method looks like a
reliable solution. That means, that the driver will use interrupts and additionally poll the device in timed intervals.
When the chip stops generating interrupts, the next poll will reenable them. Jon Anders Haugum reported, that
this worked excellent on another embedded system. Mike Cornelius contributed a polling CS8900 Ethernut driver, which
is included in the distribution.
Q: Is there any 100 Mbps Ethernet Controller supported?
A: Yes, on Ethernut 2 a LAN91C111 from SMSC is used. This device supports 10 and 100 Mbps Ethernet.
Expansion Connector
Q: Does the Ethernut expansion connector provide 5V or 3.3V logic levels?
A: Ethernut 1 provides 5V CMOS logic levels on all signal pins. Ethernut 2 is almost similar, except for the data bus and the lower 8 bits of the address bus. These signals are driven by a 3.3V CPLD. The data bus inputs are 5V tolerant. This means, they can be driven by 3.3V and 5V devices. Low byte address and data bus output signals from Ethernut can drive all 3.3V and almost all 5V devices. Because the upper address bus and all port bits use 5V logic levels, you should either choose 3.3V devices, which are 5V tolerant. Or use 5V devices after checking their datasheets to make sure, that Vih of your 5V device is below 3V. This is true for the majority of 5V devices. More infos are available in the Xilinx Application Note 112 - Designing With XC9500XL CPLDs.
TCP/IP Protocols
SNMP
Q: I plan to implement an SNMP agent. Do I need an OS?
A: SNMP is a very simple request/answer protocol based on UDP. It could be even done in assembly language. However, parsing and assembling SNMP datagrams isn't trivial. But this still doesn't require an OS.
ICMP
Q: Nut/Net responds to pings. Has somebody implemented request sending?
A: You can find ICMP socket function at the Ethernut Projects Page.
PPP
Q: Does Nut/Net provide PPP?
A: PPP client mode is provided, but not PPP server mode. This means, that Nut/Net can dial out but cannot receive incoming calls.
Q: Will Nut/Net provide PPP server mode in the future?
A: This is difficult to predict. The related protocol layers are not really difficult to extend, but PPP servers typically need a lot of configuration parameters including user accounts. Right now there are no plans for its implementation.
Other Interfaces
USB Support
Q: What about USB?
A: No USB Stack had been implemented so far. One option is to connect a USB/RS232 brigde to one of the UARTs, like the CP2102 from Sylabs or the FT232 from FTDI.
Building the System
Specific to GCC ARM (YAGARTO)
Q: How to fix compile error "conflicting types for unsetenv" when building for ARM?
A: Nut/OS borrowed a lot of code from BSD, where unsetenv is a void function, while Posix specifies an integer return type. Initially newlib used the BSD variant, but changed to Posix after versions 1.17. The newlib maintainers, in their infinite wisdom, decided to use a string constant as a version identifier and refuse to add an integer variant, which could have been checked automatically by the preprocessor. This is why you have to select Posix conformance of unsetenv manually in the Configurator under C Runtime (target specific) / Environment.
Personally I'm switching library versions often and my simple solution is to change int _EXFUN(unsetenv... to void _EXFUN(unsetenv... in arm-elf\sys-include\stdlib.h.
Specific to GCC AVR (WinAVR)
Q: Why does rebuilding Nut/OS fails with compiler warnings?
A: In order to force clean code, warnings are considered errors during Nut/OS rebuild. When upgrading Nut/OS, the compiler or avr-libc, such warnings may appear for different reasons. The Nut/OS code may not have been tested with your compiler version, the compiler may have upgraded to more strict rules etc. Instead of wasting time with different versions, you can remove the -Werror option of CPFLAGS in the file nut/Makedefs.avr-gcc to get the job done. However, be aware, that compiler warnings are still an alarm signal for something being wrong.
Q: Why does rebuilding Nut/OS fails with compiler error in avr/include/avr/eeprom.h?
A: Looks like a problem with C++ and avr-libc 1.6+. Either switch back to an earlier version of avr-libc (WinAVR-20081205 seems to work) or remove C++ support from Nut/OS by deleting the line sources = { "nutcpp.c" } in nut/conf/cpp/cpp.nut.
Specific to ImageCraft for AVR
Q: When rebuilding Nut/OS I got "Unlicensed compiler cannot be run in command line mode!". How can I rebuild Nut/OS with the ICCA VR Demo?
A: The demo version of the compiler will only work within the IDE. Start the Configurator from within the Imagecraft IDE by adding it as a tool.
Q: How to fix compile error "found pointer to const char expected pointer to __flash char"?
A: Select the right platform in the Configurator Settings, avr-icc for ICCAVR version 6 and avr-icc7 for ICCAVR version 7.
Building Applications
All Environments
Q: How to fix linker error "undefined reference to xyz"?
A: Most often this happens after updating Nut/OS without rebuilding the system, because the new header files may not fit to the libraries. Make sure to rebuild Nut/OS after updating.
Q: How to fix linker error "undefined reference to NutDecodeBase64"?
A: Nut/OS 4.8 introduced a new library named nutgorp. Base64 encoding had been moved from library nutpro to this new library. You can fix the linker problem by appending -lnutgorp at the end of the LIBS line in your application's Makefile.
LIBS = $(LIBDIR)/nutinit.o -lnutpro ... -lnutgorp
Q: How to fix compiler error "devEth0 undeclared"?
A: You probably want to run your network application on a special target board, for which no Ethernet controller had been defined by default. Edit the file include/dev/board.h and specify the default Ethernet device for your target hardware.
Specific to ARM GCC (YAGARTO)
Q: Why does the binary RAM image becomes so large?
A: Typically the code is built for being loaded into Flash memory. The RAM will be initialized during system initialization. However, during debugging or when using a boot loader on a system with sufficient RAM, then it is often an advantage to directly build the code for uploading into RAM. Some targets like the Elektor Internet Radio provide internal and external RAM areas, which may be both used by the final application. Binary images however do not contain any location information and the final image must include internal and external RAM contents plus the gap between both areas, which may be very large. Actually the binary image is unusable and you will probably use the hex file, which does contain location information and don't need to contain memory gaps. You can disable the binary image creation by removing $(ITARG) from your application's Makefile.
Contributing
Q: Is there a public access to the CVS?
A: Not anymore. Since version 4.8 the project switched to Subversion (SVN).
Q: Is there a public access to the SVN trunk?
A: Yes, anonymous read access is available at Sourceforge.
Q: We would like to make our changes available to the community and ideally they could become part of the main Ethernut source tree. What is the best approach to do this?
A: If you made very minor changes, best ask one of the developers at the Ethernut Mailing
List to add them to the CVS repository.
If your changes require modifications of several files or add a set of new functions, you may
think about becoming an active developer.
Q: How to become an active developer?
A: Write access to the CVS repository requires a subscription to SourceForge Net. As soon as you got a working login, write an email to the project admin, harald dot kipp at egnite dot de and apply for the developer status by providing your ~SourceForge login name (only the name, not your password). Typically write access is granted to anybody who applies for.
Q: What kind of experience is expected for active developers?
A: Not much, we try to encourage everybody to take part. You should have some basic knowledge about C programming and follow the project's programming style. You should make yourself familiar with CVS before committing more than one or two changes. Remember to document your modifications in the ChangeLog file.
Q: If just anybody receives CVS write access, who takes care of code quality? Who guarantees, that a single person is not breaking all the code or adding unwanted changes or features? What's the role of egnite ~GmbH then?
A: Until today, all registered developers have been most responsible and careful.
If critical changes are planned, they are announced and discussed in the mailing list
first. If still someone unknowingly breaks existing code, CVS allows to roll back.
Beside that, developers should conform to some basic rules, which are described
here.
One of the major rules is, that the CVS HEAD should be kept as stable as possible.
Commits, which make one of the compilers fail, may be removed immediately.
Beside CVS, egnite took over responsibility for official releases and thus reserves the right to exclude or include parts of the code in an authoritarian way, without discussing topics to the very end.
Q: I'm too scared to break something. How can I contribute anyway?
A: If you feel unsure about CVS or supported compilers and platforms, ask
someone else in the mailing list to have a look to your code. Please do not post
large files to the mailing list directly.
If you feel uncomfortable with CVS, ask one of the registered developers to
commit your contribution.
Q: Why do Nut/OS C comments look so strange? Do I have to follow this style?
A: Yes, you should follow this alien code commenting style. Not, because it
is absolutely required, but because otherwise nobody may use the functions you
added.
If you follow this style, your contribution will be automatically documented
in the Nut/OS API Manual. With each release, egnite will run Doxygen on the
complete source code. This smart tool creates the final documentation without
any user intervention.
Q: I do not speak English very well. Should I still add comments to the code?
A: Matthias Neuhaus, one of my old colleagues in several commercial projects, used to say: "Wrong and misleading comments are much worse than no comments at all". He is definitely right, but it doesn't mean, that you should completely avoid commenting code. Try to use simple sentences. If you are lost, use your own language. Someone else may later translate it.
