
GNAT GPL - GNAT compilation system

This version of GNAT GPL is for cross development targeting the LEGO
MINDSTORMS NXT platform. It runs on PC/x86 hosts running Microsoft
Windows XP (service pack 2 or above).

-- What is included? --

* the GPL Edition of GNAT, the Ada 2005 tool chain maintained by AdaCore,
and includes GPS, a fully integrated IDE. It also includes full html
documentation for both tools.

* A Ravenscar + SFP (small foot print) run time. This run-time is 
targeted for embedded systems and has a very small foot-print. As a 
drawback, not all Ada language features are available. For example, the 
attributes 'Image and 'Value are not included in this run time. Be sure 
to see the GNAT documentation describing these restrictions, including 
the GNAT User's Guide "Supplement for High-Integrity Edition Platforms"
in the <prefix>/share/doc/gnat-cross" directory group, where <prefix> is
the location in which GNAT was installed

* Some drivers for the NXT, including the LCD, buttons, motors, bluetooth,
and sensors. Support for sensors based on I2C (such as the ultrasonic sensor)
is included. You are encouraged to contribute new drivers. New I2C-based
sensors can be added by extending the abstract I2C driver using inheritance,
as is done for the ultrasonic sensor.

-- How to build a program? --

You simply need to write a small Makefile that defines two variables:

    PRG: the name of the main procedure.

    RAVENSCAR_SRC: the path to the Ravenscar directory. It should be 
"<prefix>/lib/mindstorms-nxt/ravenscar". For example: 

    RAVENSCAR_SRC=/GNAT/2010/lib/mindstorms-nxt/ravenscar

And also add:

    include $(RAVENSCAR_SRC)/Makefile.inc

(This Makefile.inc contains the directives to do the real work).

You can find some examples in <prefix>/share/examples/mindstorms-nxt, for 
example in the "tests" folder.

-- How to load a program? --

Programs are to be loaded in RAM. To do that, you must first unload the 
original firmware (thereby invalidating the warranties). You need to do 
this only once unless you reload the NXT firmware later. To remove it, 
turn on the NXT and press the reset button in the hole at the upper left 
rear corner of the NXT (beneath the USB connector) for more than 5 
seconds. The NXT will audibly tick when it is thus reset (it is then in 
firmware download mode). It is now ready for loading applications. 

You need a SAM-BA (SAM Boot Assistant) loader to load the application 
binary into RAM via the USB connector on the NXT. You can use samba_run 
<progname> to load your application. (This loader is derived from the 
lejos-osek loader and can load an ELF file). 

On Windows, USB ports are not available to user-level applications, 
including the "samba_run" program loader. As a result, when invoked, 
samba_run will indicate that the NXT is not found, suggesting you 
connect it via some USB port. The Windows hardware manager will show the 
connected device, and even indicate that it is recognized as a Lego 
device in a given mode (e.g., "firmware download" mode), but otherwise 
the connected USB device will not be visible.

A third-party application is therefore required to enable the loader to 
access the USB port connecting the NXT to the host computer. One such 
application is "libusb-win32", available from the following URL: 
http://sourceforge.net/apps/trac/libusb-win32/wiki.  There are two 
versions: a "filter" and a "device driver."  The "filter" version is 
known to work with the GNAT GPL tool-set and is described here.

Download the installer (e.g., "libusb-win32-devel-filter-1.2.2.0.exe") 
from the URL above. With the NXT powered and connected to the host via 
the USB port, execute the installer.  After installation it will 
automatically open a dialog box showing all the currently connected USB 
devices. Select the port connected to the Lego USB device and press OK. 
(Obviously you can run the installed application again later, without 
re-installing it.  To do so, use the regular Start->"All Programs" menu 
to find the "LibUSB-Win32" group and invoke the wizard.)

Once the driver filter is assigned to the USB port, samba-run will be 
able to access the USB port.

-- Programming --

* The Small FootPrint run-time library does not provide exception 
propagation. Unhandled exceptions go to a "last chance handler" that can 
do whatever is desired, but then the program terminates. (It must not 
return to the caller.) 

There is an NXT-appropriate last chance handler defined in the package 
NXT.Last_Chance. This procedure audibly beeps when an exception is 
raised and then displays the name of the file and the line number where 
it was raised. You can change the behavior if you wish. Note that you 
must explicitly include this package (in a with-clause) for it to be 
part of your application. If you do not, a default handler is included 
that only displays an address for the exception. See below. 

* If the display prints an address related to an exception, you can do the 
following:

    arm-eabi-objdump -dr <MAIN> > main.dump

where <MAIN> is the executable produced by the Makefile. Then look in main.dump
for the address to find out where the problem rose. You can also use 
arm-eabi-addr2line for this purpose.

See the point above regarding package NXT.Last_Chance as an alternative to this 
approach.

* If you get a compilation error like:

arm-eabi/bin/ld.exe: platform_main section `.bss' will not fit in region `ram'
arm-eabi/bin/ld.exe: region `ram' overflowed by 21504 bytes
collect2: ld returned 1 exit status

then you are probably using Ada tasks without pragma Storage_Size. The NXT is 
quite limited in memory, so be sure to use this pragma on each task.

* If multiple tasks concurrently write to the NXT display, be sure to use the 
NXT.Display.Concurrent package API. 

* For real-time analysis gurus, remember the run-time itself includes some
tasks, as does the NXT driver set.  

Also, package NXT.Priorities defines the priorities for all task objects 
and protected objects declared within the NXT hierarchy. You can change 
these priority assignments as necessary in accordance with your global 
schedulability analysis. All interrupt handlers execute with the highest 
interrupt priority (there is only one level). You are not expected to 
change these interrupt handler assignments. 

* In lib/mindstorms-nxt/facilities you will find some useful services, 
including:
 * Archetypes for sporadic and cyclic tasks. Feel free to develop new 
   archetypes!
 * the Nxt.Display.Concurrent API
 * the System_Configuation package to define a common release time for all
   tasks
