Harald: Created page with "
= Playing the Nut/OS Configuration Game = Initially Nut/OS had been written for a fixed hardware, the Ethernut 1 with an ATmega103 MCU and an RTL8019AS Et..."

2017-07-13T07:50:14Z

Created page with "<div id="content"> = Playing the Nut/OS Configuration Game = Initially Nut/OS had been written for a fixed hardware, the Ethernut 1 with an ATmega103 MCU and an RTL8019AS Et..."

New page

<div id="content">

= Playing the Nut/OS Configuration Game =

Initially Nut/OS had been written for a fixed hardware, the Ethernut 1 with an ATmega103 MCU and an RTL8019AS Ethernet controller. And the only supported development environment had been AVRGCC running on the Windows PC. Good old days.

Today we have to support different targets with different CPUs, Ethernet controllers, memory layouts and I/O hardware as well as different development platforms with different compilers. Thus, system configuration became an important part.

Since Nut/OS 3.9, a GUI became available to simplify the configuration task. The [[../../pdf/enswm28e.pdf|Nut/OS Software Manual]] provides a step by step guide on how to use this tool.

In this paper I will present some more details about the possibilities to configure the system and how the Configurator uses these capabibilities.

== The Make Tool ==

Regardless of which development environment is used to build Nut/OS, [http://www.gnu.org/software/make/ GNU Make] takes over the top level control. Explaining this tool in detail is beyond the scope of this paper and to many developers of embedded systems it looks like C to PASCAL programmers, quite cryptic. But as often, the number of options make a tool look complicated while the main function is quite simple.

When started without any option, Make will look for a file named Makefile, interpret it and perform the related actions. Some Makefiles may contain weird sequencies of characters, but all of them contain something like

<div class="coding">

<pre>target: dependencies
actions</pre>

</div>
This is interpreted by Make in the following way: To produce the <code>target</code>, <code>dependencies</code> and <code>actions</code> are required. The three items used here are just placeholders. A real example may look like
<div class="coding">

<pre>simple.hex: simple.c simple.h
avr-gcc -c -mmcu=atmega128 simple.c -o simple.o
avr-gcc simple.o -mmcu=atmega128 -lnutdev -lnutos -o simple.elf
avr-objcopy -O ihex simple.elf simple.hex</pre>

</div>
Be warned, this may be a real example but for Nut/OS some more steps and options are required. Anyway, it presents a good picture. If simple.c and simple.h exist, then the three given steps are required to create simple.hex. In the first step simple.c is compiled to simple.o. In the second step simple.o is linked with libnutdev.a and libnutos.a to create simple.elf. And in the final step simple.elf is converted to simple.hex.
You may now argue, that this could be done by a simple batch file or shell script. You are probably right. Now imagine, what a large number of actions would be required to compile all Nut/OS source files for all supported platforms, if we would do it this way. Make simplifies this by allowing us to specify general rules like

<div class="coding">

<pre>%o : %c
avr-gcc -c -mmcu=atmega128 $< -o $@
%elf: %o
avr-gcc $< -mmcu=atmega128 -lnutdev -lnutos -o $@
%hex: %elf
avr-objcopy -O ihex $< $@</pre>

</div>
This already looks too cryptic to many of us, but doesn't really differ from the real world example given above. The big advantage with these rules is, that we just need to write
<div class="coding">

<pre>simple.hex: simple.c simple.h</pre>

</div>
and Make knows, which steps are required to create <code>simple.hex</code> from <code>simple.c</code> and <code>simple.h</code>. That's cool, isn't it?
Another nice feature of Make is, that it checks automatically, which actions are required after you modified something. In other words, if you edit <code>simple.h</code>, save your changes and run Make again, it will run all three steps again. If you modified anything else but neither <code>simple.c</code> or <code>simple.h</code>, then Make will keep the already existing <code>simple.hex</code>.

However, the Nut/OS Makefiles are incomplete here, because they do not list all dependencies. All header files are excluded. Thus, if any header file is changed, you need to run

<div class="coding">

<pre>make clean
make</pre>

</div>
in the build tree. The first will remove all files previously created by Make. The option <code>clean</code> is an explicit target given on the command line. Somewhere in the Makefile there is something found like
<div class="coding">

<pre>clean:
rm *.o *.hex *.elf</pre>

</div>
For the Windows users: The UNIX command <code>rm</code> is similar to the DOS command <code>del</code>. To avoid complete Makefile madness, some basic UNIX commands are included in the Windows distribution of Nut/OS as executables. You can find them in the directory <code>tools/win32</code>. When running Make in a DOS window, make sure that your PATH points to this directory.
When the Configurator builds Nut/OS, it will set the correct path and will always run <code>make clean</code> first. The next chapter will show more details about how the Configurator uses Make.

== Make and the Nut/OS Configurator ==

We assume, that all Configurator settings have been specified by following the Nut/OS Software Manual and that we are ready to create a new Nut/OS build tree.

When selecting <code>Generate Build Tree</code> from the Configurators <code>Build</code> menu, then the directory for building Nut/OS will be created with all required subdirectories. In the top level directory of the build tree, the Configurator will additionally create three files, which will be used by the Make tool.

The first of these files is named Makefile. It's a very simple Makefile with three targets: <code>all</code>, <code>install</code> and <code>clean</code>.

<div class="coding">

<pre>all:
$(MAKE) -C arch
...
install:
$(MAKE) -C arch install
...
clean:
$(MAKE) -C arch clean
...</pre>

</div>
Two additional features need to be explained to understand this Makefile. First note the term <code>$(MAKE)</code>. That's how Make understands definitions similar to C makros. It may be defined somewhere else as <code>MAKE=make</code>, however, specially <code>$(MAKE)</code> is internally predefined. The second feature is the command line option <code>-C directory</code>. This instructs make to change to the specified directory before starting to read the Makefile.
As you can see, for each target Make is called for each Nut/OS module subdirectory with the same target again. Of course, the Configurator also creates the Makefiles in these subdirectories, which are much more interesting than the top level Makefile.

Let's stay at the top level, where the Configurator created two additional files, <code>NutConf.mk</code> and <code>UserConf.mk</code>.

<code>NutConf.mk</code> defines several macros, similar to the internally defined <code>$(MAKE)</code>, which I explained above. When building Nut/OS for the ATmega128 using AVRGCC, this file contains

<div class="coding">

<pre>MCU_ATMEGA128=atmega128
MCU_ATMEGA103=atmega103
MCU=$(MCU_ATMEGA128)
HWDEF=-D__HARVARD_ARCH__
CRUROM=crurom

include $(top_blddir)/UserConf.mk</pre>

</div>
Whenever <code>$(MCU)</code> appears in a Makefile, Make will replace it with <code>$(MCU_ATMEGA128)</code>, which in turn is replaced by <code>atmega128</code>.
The last line of NutConf.mk instructs Make to include <code>UserConf.mk</code>, which initially contains a single line

<div class="coding">

<pre>HWDEF += -DETHERNUT2</pre>

</div>
Here's another interesting feature of Make: We can append new string to existing macros. Together with the definition in <code>NutConf.mk</code>, <code>$(HWDEF)</code> will be finally expanded to <code>-D__HARVARD_ARCH__ -DETHERNUT2</code>. As long as you are using the Ethernut 2 hardware, this is just fine. When building Nut/OS, this compile option is simply ignored. However, the same entry is added by the Configurator when creating the sample directory and should be removed before compiling any of the samples. Hey, wait, we are building Nut/OS. More on the sample applications later.
Each time, when you re-create the build tree, the Configurator will overwrite existing files in the build tree. Thus, do not edit them, because your changes will get lost. <code>UserConf.mk</code> is an exception. It is initially created, if it doesn't exists. If it exists, the Configurator will not touch it. You can use it to add additional compile options, for example.

<div class="coding">

<pre>HWDEF += -g3 -gdwarf-2</pre>

</div>
Now let's dive into one of the subdirectories and see, what the Configurator created there. We choose subdirectory os, which mostly contains the Nut/OS kernel code. Wonder! It contains nothing but another Makefile.

<div class="coding">

<pre>PROJ = libnutos

top_srcdir = c:/ethernut/nut
top_blddir = c:/ethernut/nutbld

VPATH = $(top_srcdir)/os

SRCS = heap.c bankmem.c thread.c timer.c event.c devreg.c confos.c version.c \
semaphore.c mutex.c msg.c osdebug.c tracer.c
OBJ1 = nutinit.o

OBJS = $(SRCS:.c=.o)
include $(top_blddir)/NutConf.mk

include $(top_srcdir)/Makedefs.avr-gcc

INCFIRST=$(INCPRE)$(top_blddir)/include

all: $(PROJ).a $(OBJS) $(OBJ1)

install: $(PROJ).a $(OBJ1)
$(CP) $(PROJ).a c:/ethernut/nutbld/lib/$(PROJ).a
$(CP) $(OBJ1) c:/ethernut/nutbld/lib/$(notdir $(OBJ1))

include $(top_srcdir)/Makerules.avr-gcc

.PHONY: clean
clean: cleancc cleanedit
-rm -f $(PROJ).a
-rm -f $(OBJ1)</pre>

</div>
Here is some of the cryptic stuff like <code>OBJS = $(SRCS:.c=.o)</code>, which is hated so much by Makefile ignorants and which we will not explain here either. Instead we concentrate on those parts, which are relevant to the Nut/OS configuration. Most important is the list of source files
<div class="coding">

<pre>SRCS = heap.c bankmem.c thread.c timer.c event.c devreg.c confos.c version.c \
semaphore.c mutex.c msg.c osdebug.c tracer.c</pre>

</div>
When using the Configurator, you may have recognized, that some parts in the module tree are disabled. That's because the Configurator keeps track of module dependencies. For example, some drivers like the AVR USART driver do not make sense for the ARM CPU and will be deactivated when selecting this CPU. Now each Nut/OS module displayed in the Configurator's module tree is associated with one or more source files. When creating the build tree, the Configurator will exactly place all source files of all activated modules in the <code>SRCS</code> line. As a result, the final Nut/OS libraries will contain only those modules, which are available on your target platform.
Not less important lines in <code>os/Makefile</code> are

<div class="coding">

<pre>...
include $(top_blddir)/NutConf.mk
...
include $(top_srcdir)/Makedefs.avr-gcc
...
include $(top_srcdir)/Makerules.avr-gcc
...</pre>

</div>
The first one includes <code>NutConf.mk</code>, which we discussed above. The other two include two files from the Nut/OS source tree. If you look into the top level source directory, you will see a number of files named <code>Makedefs</code> and <code>Makerules</code> with different file extensions. When building with AVRGCC, the Configurator will add includes of <code>Makedefs.avr-gcc</code> and <code>Makerules.avr-gcc</code>. When building with ARMGCC, it will use <code>Makedefs.arm-gcc</code> and <code>Makerules.arm-gcc</code> instead. Again, newbies may consider the contents of these files weird stuff. That's just fine. Under normal circumstances you will have no reason to deal with these. Simply note, that they contain nothing but special definitions for the compiler you are using. If one of the gurus ever passes you a modified version, for example with JTAG debug options, then copy them into the top level source directory with a different extension. The Configurator automatically scans the source directory for such files. Next time you open the second page in the Configurator's settings dialog, you can select the new extension in the platform drop down box.
An important final advice: Each time you changed anything in the Configurator settings, you must recreate the build tree.

== Nut/OS Options ==

Up to this point, configurations were mainly related to the compiler and the target CPU. The majority of configurations is related to hardware specifications and various other build options, though. We will now see, how the Configurator uses C header files to pass these setting to the compiler.

Let's assume, we want to enable floating point support for <code>printf</code> and <code>scanf</code>. In the module tree we expand <code>C Runtime (Traget Specific)</code> and <code>File Streams</code> below that. Then we can enable <code>Floating Point</code> by clicking on the related check box. If we create a new or re-create an existing build tree, then the Configurator adds a new header file named <code>crt.h</code> in the subdirectory <code>include/cfg</code> of your build tree, which contains:

<div class="coding">

<pre>#define STDIO_FLOATING_POINT</pre>

</div>
The original <code>include/cfg/crt.h</code> in the source directory does not contain this entry.
Here's a snippet form the Nut/OS source code:

<div class="coding">

<pre>
#include
...
#ifdef STDIO_FLOATING_POINT
/* This is floating point stuff. */
....
#endif
...</pre>

</div>
As you noticed, the floating point code is added only, if <code>include/cfg/crt.h</code> defines <code>STDIO_FLOATING_POINT</code>. The one in the build tree does, the one in the source tree doesn't.
Now we are back to the Makefiles of the build tree, in our case <code>crt/Makefile</code>.

<div class="coding">

<pre>top_blddir = c:/ethernut/icnutbld
...
INCFIRST=$(INCPRE)$(top_blddir)/include</pre>

</div>
This is used in the following line of <code>Makerules.avr-gcc</code>:
<div class="coding">

<pre>%o : %c
$(CC) -c $(CPFLAGS) $(INCFIRST) -I$(INCDIR) $(INCLAST) $< -o $@</pre>

</div>
Confused? Don't worry. The result is, that the compiler will search <code>include/cfg/crt.h</code> in the build tree first. If it couldn't be found there, the search will continue in the source tree. This way the Configurator is able to overwrite existing default header files in the source tree without any modification of the source tree. This is a real advantage, if you want to build Nut/OS for different targets. You can use the same source tree for each target. And if you later upgrade to a new version of Nut/OS, you can replace the source tree whithout losing your specific configurations, because all of them are located in the build tree.
== The Application Tree ==

Beside the source and the build tree, a third one is used to build Nut/OS applications. It it created by selecting <code>Create Sample Directory</code> in the Configurator's <code>Build</code> menu. There's not much mystery in here, but it comes quite handy for creating your own applications.

Users of the ImageCraft IDE are lucky people. They can use the GUI to create new project files in the sample directory. Please follow the steps in the Nut/OS Software Manual.

For using GCC on the command line, just copy one of the subdirectories to a new one with a new name within the sample directory. When adding new or removing existing source files, make sure to update the Makefile accordingly. Even if you don't understand Makefiles, this is quite simple. Be aware, that actions in Makefiles are preceded with a TAB character, spaces won't work. Your text editor should preserve tabs.

Remember <code>UserConf.mk</code>? When running the compiler on the command line, the default contents created by the Configurator may hurt now, if we do not intend to run the application on Ethernut 2. All samples have been written for Ethernut 1 (including Charon II and other boards using the Realtek Ethernet Controller) and Ethernut 2. All samples with network code contain the following lines:

<div class="coding">

<pre>
#ifdef ETHERNUT2
#include <dev/lanc111.h>
#else
#include <dev/nicrtl.h>
#endif</pre>

</div>
If ETHERNUT2 is defined in <code>UserConf.mk</code>, then the application will register the LAN91C111 driver. Otherwise the driver for the RTL8019AS is used. If you want the latter, do not forget to remove the related line in <code>UserConf.mk</code>. In newer releases <code>WOLF</code> is another option and uses the AX88796 driver. For this controller simply replace <code>ETHERNUT2</code> by <code>WOLF</code> in <code>UserConf.mk</code>.
== Under the Hood ==

As stated above, the GNU Make Tool controls the top level. The bottom level is controlled by Lua, an interpreter language. Mainly because of compatibility problems with Lua libraries on various Linux platforms, the decision to use Lua had been criticized sometimes. But the author is still convinced, that this had been a good decision. The Lua interpreter is extremely small and the language is extremely powerfull. Right now this is hard to believe, because the Configurator uses Lua in a static way. But one day it will shine brighter than everything else...:-)

Neither Lua nor all Nut/OS options will be described here. Just a few details will be discussed.

All Lua scripts are located in the subdirectory <code>conf</code> within the source tree. When the Configurator starts, it will read <code>repository.nut</code> first. This file specifies additional scripts.

<div class="coding">

<pre>{
name = "nutarch",
brief = "Target",
description = "Select one only.",
subdir = "arch",
script = "arch/arch.nut"
},</pre>

</div>
Here <code>arch/arch.nut</code> is specified as an additional script to be included, which contains:
<div class="coding">

<pre>{
macro = "MCU_ATMEGA128",
brief = "Atmel ATmega 128",
description = "8-bit RISC microcontroller with 128K bytes flash, 4K bytes RAM, "..
"4K bytes EEPROM, 64K bytes data memory space, 2 USARTs, 4 timers, "..
"8-channel ADC, SPI and TWI.",
requires = { "TOOL_CC_AVR" },
provides = {
"HW_TARGET",
"HW_MCU_AVR",
"HW_MCU_AVR_ENHANCED",
"HW_MCU_ATMEGA128",
"HW_NVMEM",
"HW_TIMER_AVR",
"HW_UART_AVR"
},
flavor = "boolean",
file = "include/cfg/arch.h",
makedefs = { "MCU=$(MCU_ATMEGA128)", "HWDEF=-D__HARVARD_ARCH__" }
},</pre>

</div>
The last two definitions are the interesting ones. The first one specifies the include file, which will be created by the Configurator when <code>Atmel ATmega 128</code> is activated. In addition, the Configurator will <code>#define MCU_ATMEGA128</code> in this file.
The last definition <code>makedefs =</code> looks familiar, doesn't it? Indeed it specifies a list of entries, which will be added to <code>NutConf.mk</code>.

However, before you are able to access the module tree in the Configurator's main window, you will be asked to select a configuration file. These files got the extension <code>.conf</code> and are also located in the <code>conf</code> subdirectory of the Nut/OS source tree. They contain simple assignments. Here's the one, which specifies options for running Nut/OS on the STK501 with an ATmega128 and the AVRGCC:

<div class="coding">

<pre>AVR_GCC = ""
MCU_ATMEGA128 = ""
NUTMEM_SIZE = "4096"
NUTMEM_START = "0x100"
NUTMEM_RESERVED = "64"</pre>

</div>
The entries are related to the same named <code>macro = </code>entries in the Lua scripts. The first two do not assign any values. The fact, that they appear in this file, sets the related boolean Lua macro definitions to true.
There are other options handled by Lua, but you should have got the picture. In the current state of the Configurator this is quite helpful, because this tool is far from being perfect. For example, radio boxes are not implemented and the user must take care to enable one CPU or one compiler only and disable all others. One annoying thing is, that the compiler needs to be specified at two places, in the Configurator's setting notebook as well as in the component tree. Furthermore, not all options seem to make their way into the final build. If something seems to go wrong, check the <code>include/cfg</code> directory in the build tree and further check, wether these files are actually included in the related Nut/OS code. But before panic breaks out: The mainstream works fine, exotic options may fail.

== Changing Environments ==

In the previous chapter we learned, that the configuration of the Configurator's settings notebook isn't always syncronized with the Configurators component tree. That's because they are kept in different places.

All modifications of the component tree are manually stored in platform configuration files with extension <code>.conf</code>. All modifications of the settings notebook are automatically stored in the Windows registry or in <code>nutconf.ini</code> when running Linux. This could be quite annoying, when you regularly have to change your environment. The problem isn't finally solved, but for now it helps to call the Configurator with command line option <code>-s</code> followed by a keyword of your choice. For example, on Windows you can call

<div class="coding">

<pre>nut\nutconf</pre>

</div>
for projects using ICCAVR and
<div class="coding">

<pre>nut\nutconf -s arm</pre>

</div>
for projects with ICCARM. In this case the Configurator will use an alternative registry entry for ICCARM settings. [This example had been transfered to us from the future via PastBeam(tm). ICCARM isn't supported yet.]
== More Hints ==

'''1.''' After modifying Lua scripts the component tree never appears again. Check for missing commas. The configurator displays the name of the script and the line number of the error.

'''2.''' You can use <code>UserConf.mk</code> to create a debug enabled binary with AVRGCC by appending

<pre>HWDEF += -g3 -gdwarf-2</pre>
'''3.''' If you need additional include files to be used by several of your applications, then create an include directory in your application tree and add the following line to <code>UserConf.mk</code>

<pre>INCFIRST += $(INCPRE)../include</pre>
'''4.''' Building Nut/OS fails with something like <code>Unsupported target</code>. Probably the settings in the Configurator's notebook and the component tree specify different compilers.

<br />
<br />

Harald Kipp<br />
Herne, May 12th, 2005.

<br />

</div>

Documents/NTN-5 Config - Revision history

Harald: Created page with " = Playing the Nut/OS Configuration Game = Initially Nut/OS had been written for a fixed hardware, the Ethernut 1 with an ATmega103 MCU and an RTL8019AS Et..."

Harald: Created page with "
= Playing the Nut/OS Configuration Game = Initially Nut/OS had been written for a fixed hardware, the Ethernut 1 with an ATmega103 MCU and an RTL8019AS Et..."