Bare Metal on the NXT

By Sivan Toledo
May 2008

If you ever wished to program the NXT at the lowest and most powerful level, but did not want (or could not) deal with SAM-BA, the native boot loader, then this project is just what you were looking for: a way to invoke bare-metal programs on the NXT from the standard firmware. Well, almost the standard firmware: a slightly modified version that John Hansen developed for this project.

If you are the developer of a programming environment that normally gets installed on the bare metal, this project would be useful for you too. It would allow users to invoke your programming environment from the (almost) standard firmware.

This project was developed in collaboration with John Hansen, who modified the NXT's standard firmware. Thanks John!

Introduction

There are now many ways to program the NXT. You can use the graphical NXT-G, or LabView, or NXC, all of which use the standard firmware. You just boot your NXT, download a program, and run it from the menu system. Programming environments that control the NXT from a program running on a PC via USB or Bluetooth also use the standard firmware.

Then there are programming environments that control the NXT's processor directly, without using the standard firmware: LeJOS, pbLua, nxtOSEK, NXTMOTE, NXTGCC, and NxOS. (RobotC uses a modified version of the standard firmware, so it is somewhere in between.) To use these, you need to replace the standard firmware with a special firmware. In some cases, you can use the NXT's software to download the special firmware, but in other cases you must use SAM-BA, the native boot loader of the NXT's processor. I never managed to get SAM-BA to work under Windows Vista, so this method was blocked for me.

What I wanted was a way to program the NXT at what is called the bare-metal level, with total control of the NXT's processor and hardware. But I wanted these programs to be invoked from the standard firmware, so I can download them to the NXT using standard tools (like NXT-G or nexttool), and so that I can run a bare-metal program, shut it down, and switch to running a NXT-G or NXC program without downloading anything, as long as all the program were already stored on the NXT.

John Hansen, who has already hacked the standard firmware and produced slightly modified versions, came to my rescue. He and I designed a simple interface that allows a slightly modified firmware to recognize an rxe file as a bare-metal binary and to jump to code stored in it. Once control passes to the bare-metal binary, it has complete control of the NXT. If it is very careful it may be able to return control to the NXT's firmware, but normally it overwrites memory and reconfigures the NXT's hardware, so it can't return to the firmware. When the program is done, it can either shut down the NXT or reset it. In both cases, you get back to the standard firmware.

I wrote a little package that shows up how to use this concept. The most important components of this package are an assembly-language startup code, which is called by John's almost-standard firmware and a simple linker script that produces a binary program in the correct format and layout. The startup code initializes the NXT, pretty much as if it was just reset, and calls a function, c_startup. This function can be written in C (this is how I wrote it), and has complete control of the NXT.

The package also includes a number of simple device drivers, which were mostly adapted from the NxOS project. Currently (May 2008), these cover raw analog sensing, simple motor control (including rotation to a given angle), input from the NXT's buttons, displaying text on the LCD, and playing sounds. I will also appreciate bug fixes.

Why?

This project has two goals. The primary goal of the project is to allow native programming of the NXT while using firmware that can also run NXT-G programs and other programs that use the standard firmware. This also implies that you can use standard tools to download native programs to the NXT.

Why write native programs? Mostly, because it allows you to experiment with embedded programming at the lowest and most powerful level. You can try to run the NXT's processor at a slow clock rate, to save power (although the NXT is not really suitable for low-power applications, since its auxiliary processor, the AVR, only enters low-power mode after turning off the main processor); You can experiment with programming the NXT to emulate a variety of USB peripherals, from a mouse to a keyboard to a speaker, using the built-in USB support in your PC's operating system; You can write programs that perform very fast sensing or actuation, to control infra-red remote-controlled devices, or to record speech; You can use a standard C or C++ compiler, rather than almost-standard C languages. I have not tried all of these, but in principle they should all be possible.

The other motivation for this project is to allow developers of alternative firmware to create versions of their firmware that can be invoked by the standard firmware. That is, I am hoping that the developers of nxtOSEK, for example, would create a version of it that would allow users to build a nxtOSEK program, download it to a NXT running John's almost-standard firmware, and run it. This would eliminate the need to replace the firmware before running any nxtOSEK program. I used nxtOSEK as a mere example here; I hope that there would be similar setups for LeJOS, NXTMOTE, and other firmware.

Running these alternative firmwares under the setup that John and I created does place one limitation: we run the native programs entirely from RAM, so the alternative firmware and whatever application it is running must fit in the NXT's 64 KB of RAM. In principle it should be possible to extend our setup to run programs directly from the file in the NXT's file system, but this would require a much more complex loader than we have now. I hope that the setup can support some alternative firmware even with this limitation.

Producing a new NXT firmware for native programs was not one of my goals. There are several reasons for that. First, there are already such projects, including nxtOSEK and NxOS. Second, I believe that there is significant learning value in having users experiment with device drivers rather than use existing sophisticated drivers. Leaving the package minimal promotes user experimentation. Having said that, I will appreciate contributions from others and will incorporate them if their style is consistent with that of the package.

How?

Let's start with the firmware's perspective. The firmware inspects the first few bytes of all rxefiles. If the file starts with "MindstormsNXT", the firmware runs it normally. John modified the firmware such that if the file starts with "NXTBINARY", the firmware reads a 32-bit integer from location 12 in the file, and then calls a function stored in that location inside the file. The firmware passes to this function two arguments: the address of the file in memory (NXT files are stored contiguously in the processor's flash memory, so they have a memory address), and the length of the file. That's all the firmware does.

The function that the firmware is written in assembly. This function disables interrupts and then copies the entire file, except for the first 16 bytes, to the beginning of RAM, which starts at address 0x200000. Then it jumps to the beginning of RAM, which contains a jump to the rest of the initialization code. Now the code sets up the stacks, zeros the uninitialized static variables, resets all the on-chip peripherals of the processors. Then it sets up a memory mapping that mirrors the beginning of RAM starting at address zero (the low area of memory contains the interrupt vectors on ARM processors), and calls a function c_startup, which can be coded in C.

At this point, the processor is at the same state after being powered up (since we reset all the on-chip peripherals), but the rest of the NXT might not be in its initial state. If the standard firmware set up the Bluetooth module and the LCD, then they remain in their current state until the native program resets them. The processor is now running very slowly, using an internal oscillator that runs at around 32 kHz. Interrupts are disabled.

If you plan to adapt these structure to some existing firmware, it helps to understand the structure of the binary file. It starts with 12 bytes that contain the string "NXTBINARY" and padded with zeros. Then the offset of the relocation routine in the file, 48 in my code. This offset is computed automatically by subtracting two addresses, so the code should work even if you reserve 64 bytes for the vectors (which some firmwares do). Now come the reset, exception, and interrupt vectors, which are eight relative branch instructions. These will be copied to the beginning of RAM and mapped to the beginning of the address space. The eight instructions take 32 bytes, so the relocation function, which follows, is at offset 48 (or 16+64 if you reserve more space for the vectors). The linker script is very simple, putting the code and data sections contiguously starting at an address that is 16 bytes before RAM starts. Therefore, the linker puts the vectors directly at the beginning of RAM.

What?

Even small embedded programs need some structure and some conventions. I tried to impose as little structure as possible, to allow users to use the code in many different program structures: with a preemptive kernel, like OSEK or eCos, or with just an infinite main loop, etc. But I had to make some assumptions. This section lists them and explains the structure of the code.

The main clock is configured to run at close to 48 MHz, which is a value that allows USB communication. Several other key drivers implicitly assume that the clock runs at that speed. If you change this speed, you may have to modify these drivers.
Both FIQ and IRQ interrupts are auto-vectored. This means that you need to declare interrupt service routines (ISRs) using special GCC syntax, as shown in the existing drivers. This leads to the fastest possible ISR invocation.
All the drivers assume that interrupts are not nested. I do not think that nesting is particularly useful, and it makes concurrency issues more complex. If you really need to give one ISR a higher priority so that it preempts other ones, declare it as a FIQ routine and use the fast forcing feature of the interrupt controller (AIC) to invoke it. If you do that, you may want to modify the inline functions that protect critical sections so that they only disable IRQ interrupts, to allow the FIQ ISR to preempt them.
I have included support for defered service routines (DSRs), which are similar to ISRs, but are defered until all interrupts are serviced, and they execute with interrupts enabled, so ISRs can preempt them. They are useful for defering non-urgent work that ISR determine must be performed. DSRs are scheduled for execution by posting them. A DSR can only be posted once; if it is posted twice before it is run, it will only run once. DSRs that are posted by non-interrupt code are typically executed immediately. I implemented DSRs by using one of the interrupt sources (IRQ1), which cannot be used if DSRs are also used; the corresponding ISR re-enables interrupts and runs the queued DSRs; it examplifies how to nest interrupts if needed. The current drivers do not use DSRs, but the support for them exists.
(A series of 10 articles by Miro Samek, "Building Bare-Metal ARM Systems with GNU", provides an excellent discussion of interrupt handling on the AT91.)
The Interval Timer of the AT91SAM7S256 is used to generate an interrupt evern 1 ms. This interrupt is used for time keeping and for running all the periodic tasks of the system. The same driver also a caliberated delay loop called busywait.
Communication with the AVR is performed via the hardware I2C peripheral of the processor. The program running on the ARM must communicate with the AVR periodically, otherwise the AVR assumes that the NXT is idle and turns it off. So in practice, any program will use this driver. It sends motor-control commands and sensor-configuration commands to the AVR every 2 ms, and receives sensor, button, and battery information every 2 ms. When the program requests information, it receives the most up-to-date information received from the AVR; when it sends motor or sensor-configuration commands, they get sent at the next scheduled transmission. There is no way to force the driver to send or receive information immediately.
The AVR reports the state of analog sensors and the buttons, but to reliably estimate which buttons are pressed or released, the program must perform some key debouncing (waiting a bit before deciding what is pressed/released, due to both switch bouncing and to the button circuit).
The display driver uses a frame buffer, from which 8 pixel-rows are sent to the display controller every 2 ms. Therefore, the entire display is refreshed every 16 ms. The user-accessible functions in the driver currently support text-based display only.
The sound driver uses the SSC peripheral to sound simple notes.
The sensorports driver controls the two digital lines in every sensor port. They control, for example, the LED in the light sensor.
The tacho driver records the rotation of the servo motors.
I implemented a very simple motor control driver, based on that of NxOS. It allows a motor to be rotated at a given power setting indefinitely or for a given number of milliseconds, or it can be configured to rotate to and stay at a given angle.

I used a number of conventions.

The entire program including all the drivers form one source file. This gives the compiler maximal opportunities to optimize the program, and in particular to remove code and static variables that are not used. (The GNU compiler and linker can also remove so-called dead code at link time, but compilation is fast enough that we can always compile the entire program.) Therefore, the drivers are include files, not separate C files.
All the functions and global variables except for c_startup are declared static, to allow the compiler to remove them if they are not used.
The functions and global variables in driver xyz start with xyz (if they are intended to be called from outside the driver) or _xyz (if they are private and intended to be used only by the driver). There are some exceptions where other names made more sense to me.
Public functions in driver xyz are named xyzDoSomething.
Callbacks in drivers are named using underscores. For example, when the tacho driver discovers that tacho counts changed, it calls tacho_change_event(), from interrupt context. This name must be defined before the driver is included in the main program. In the current code, it is defined as simplemotorcontrolTachoChangeHandler(). The periodic task callback is defined in a similar way.
Because interrupts are not nested, ISRs must never block (wait in a while loop or do something equivalent).
Drivers are initialized before interrupts are enabled. This makes the initialization code simpler.

Finally, some potential pitfalls.

Clearly, an infinite loop or a buggy ISR can cause the NXT to hang. Just press the hidden reset button in the technic hole under the USB connector. A Lego antenna works well, but any little stick will work.
In some cases, bugs in the linker script or in my assembly-language startup code caused the binary file to be huge, a megabyte or two. Trying to download these huge files (I didn't notice their size) sometimes caused the file system in the firmware to become corrupt. Further downloads would fail, and I had to reinstall the firmware. Beware of huge binary files (clearly anything above 64 KB won't work, because it won't fit in RAM), and if in trouble, reinstall the firmware.
I didn't experience any problems other than these, but the NxOS developers report that the LCD better be shut down properly, or it can get damaged. The driver includes their shutdown code. Beware.

Getting Started

It's pretty easy to get started. You need two tools: the GNU development tools for ARM processors, and some way to download the resulting programs to the NXT. I use nexttool to download programs to the NXT, but I suppose that you could use NXT-G as well. There are several distributions of the GNU tools for ARM around. I usually use a distribution called WinARM, which is for windows; GNUARM and YAGARTO are two other options (I have used GNUARM on Linux).

You will also need John Hansen's modified firmware (John tells me that any version numbered 106 or later includes the native-invocation feature), and a copy of my source code. My code is most likely still buggy, so have a Lego antenna at the ready, to reset the NXT (or any other stick that can press the reset button).

I may still tweak (and fix) the code, so the interfaces may not be completely stable in the near future. But the firmware/native interface will be stable.

Good luck!