Lucretia/tamp

                    The Ada Microkernel Project (TAMP)

-------------------------------------------------------------------------------
Legal
-------------------------------------------------------------------------------

Copyright © 2011-2012, Luke A. Guest & David Rees, All Rights Reserved.

License is GPL v2 until further notice and is subject to change during
development.

-------------------------------------------------------------------------------
Prebuilt toolchains
-------------------------------------------------------------------------------

https://www.dropbox.com/s/koxes5ve57iqdvz/tinyada-libs.tbz2
https://www.dropbox.com/s/273e1pbez0qgqkp/tinyada-arm-none-eabi-4.9.0-20140122.tbz

-------------------------------------------------------------------------------
Introduction
-------------------------------------------------------------------------------

The aim of this project is to create a simple microkernel using Ada as the
implementation language.

To get the toolchain built, enter the thirdparty directory, and copy the
config-master.inc file to config.inc, edit config.inc and then run the following
command to build the native toolchain:

  ./build-tools.sh -t native

This will compile and install the latest version of GCC (4.6.1) to the directory
of your choice. With a Debian Squeeze machine, this process takes approximately
5.3GB of disk space.

The build times on my machine are as follows:

Native: Last Process Took: 170m37.16s
ARM   : Last Process Took: 34m13.37s

As the native toolchain is bootstrapped it is compiled 3 times and then we check it
explicitly, the following are my results of the testsuite (C, Ada, C++):

		=== gcc Summary ===

# of expected passes		78926
# of unexpected failures	34
# of unexpected successes	29
# of expected failures		235
# of unsupported tests		1101
/home/laguest/src/mine/tamp/thirdparty/build/native/gcc-4.6.1/gcc/xgcc  version 4.6.1 (GCC) 

make[2]: [check-parallel-gcc] Error 1 (ignored)
make[2]: Leaving directory `/home/laguest/src/mine/tamp/thirdparty/build/native/gcc-4.6.1/gcc'
Test Run By laguest on Mon Jan  9 15:58:46 GMT 2012

		=== acats Summary ===
# of expected passes		2321
# of unexpected failures	0

		=== gnat Summary ===

# of expected passes		869
# of unexpected failures	1
# of expected failures		10
# of unresolved testcases	1
# of unsupported tests		2

		=== g++ Summary ===

# of expected passes		27536
# of expected failures		164
# of unsupported tests		359


The toolchain has been built on the following machines:

* Ubuntu 10.4; GNAT/GCC 4.4.3
* Debian Squeeze; GNAT/GCC 4.4.5, GNAT/GPL GCC 4.3.6

You then need to build a target toolchain, here we are targeting ARM:
NB. Currently, on my machine, this process requires approximately 1.2GB
free disk space to build the native toolchain and the arm-none-eabi
toolchain.

  ./build-tools.sh -t arm-none-eabi

-------------------------------------------------------------------------------
RTS
-------------------------------------------------------------------------------

After building the toolchain, you will then require a runtime library for the
board you intend to build TAMP for.

  ./build-rts.sh <boardname>

Where <boardname> can be stm32f4.

N.B: Just a quick note to say that GNAT is extremely flaky. I did manage using a
previous toolchain build to build an RTS using gnatmake and a project file;
for some reason, this is not working providing me with an internal compiler
error (or ICE):

<log>
arm-none-eabi-gcc -c -gnat05 -gnatg -O2 -ffunction-sections -fdata-sections --RTS=/home/laguest/src/mine/tamp/thirdparty/../rts/boards/stm32f4 -I- -gnatA /home/laguest/src/mine/tamp/rts/src/common/g-souinf.ads
Exception name: SYSTEM.ASSERTIONS.ASSERT_FAILURE
Message: namet.adb:655

arm-none-eabi-gnatmake: INTERNAL ERROR. Please report.
</log>

So, for the moment, I will use a makefile with the build-rts.sh script.

-------------------------------------------------------------------------------
Targets
-------------------------------------------------------------------------------

We intend to target the following architectures initially:

* ARM, using the STM32F4DISCOVERY board.
* PIC32, using the ChipKIT UNO32 board.

We will expand on the supported targets as we progress.

-------------------------------------------------------------------------------
Getting started
-------------------------------------------------------------------------------

TAMP uses GCC-4.6.1 due to the total inability of previous versions to build an
Ada cross compiler. We've managed to use the information from [12] & [13] to
create an Ada compiler targetted to a Zero Footprint Runtime so we can start
to build an application for bare hardware and still have some support from the
language, like exceptions.

So the first thing you will need is a toolchain:

1) Native Toolchain for your host OS, you need the same version of GNAT to build GNAT.
2) Cross Toolchain for the target you want to build TAMP for (i.e. ARM)

cd thirdparty
cp config-master.inc config.inc

Edit config.inc for your enviroment, i.e. installation directory.
For help on commands: ./build-tools.sh --help 

Note: You can use sudo to install as root, but that would create root owned dirs.

By default the native compiler will also run the testsuite.

***********************
**** IMPORTANT!!!! ****
***********************

If you decide to use the SVN GCC tree rather than a snapshot of GCC 4.6, you
will need to update the tree yourself if you want to get a newer revision:

cd src/gcc
svn update

N.B: I've enforced this as using the script to update the tree causes the
patches to be overwritten and the build will fail, not only that, the cross
build will completely destroy the TAMP native build! It is very important
that this is understood!

-------------------------------------------------------------------------------
Dependencies
-------------------------------------------------------------------------------

Building the native compiler will also run the testsuite on GNAT, there is no
flag to turn this on/off yet so you will require the following packages:

  dejagnu, expect, tcl, bison, flex, patch.

  libusb for stlink, see https://github.com/texane/stlink.

-------------------------------------------------------------------------------
Common problems
-------------------------------------------------------------------------------

* When building the cross gnattools, if the following error occurs:

  make.adb:7388:07: "Create_Temp_Output_File" is undefined

GNAT is not using the right version of the compiler to build itself! Check
that the native tools have built and installed themselves properly into $TAMP
otherwise the gnatmake found will be the system one and s-os_lib may not
have Create_Temp_Output_File subprogram defined.

* The configure script has stated that GNAT Tools will not be built:

Make sure the following flag is not on the configure line "-disable-libada"

-------------------------------------------------------------------------------
The new patch seems to work!
-------------------------------------------------------------------------------

Here are the instructions on building the toolchain for native and arm-none-eabi.

I've added a 4.6.1 patch that attempts to enable GCC to build fully without
horrible hacks, I have managed to get this to build with no errors. The patch 
is based on the info from [13].

I tested this with the following packages:

gcc-4.6.1 (C, C++, Ada)
binutils-2.22
newlib-1.19.0
gdb-7.3a

Before you try this, make sure there are no arm-none-eabi-* tools in your $PATH

Obviously, you will require the gcc-4.6.1.diff patch applied to GCC.

Even though I mention above in the "common problems" I totally forgot about that
and yes, you do have to build the native GCC first.

1) Extract all source archives.
2) Make symbolic links from gcc to mpc, mpfr, gdb, gmp:
   cd gcc-4.6.1
   ln -s ../mpfr-3.0.1 mpfr
   ln -s ../gmp-5.0.2 gmp
   ln -s ../mpc-0.9 mpc
   ln -s ../gdb-7.3 gdb

3) Native
---------

../../../src/gcc-4.6.1/configure --prefix=$HOME/opt/tamp --enable-multilib --enable-shared --with-gnu-as --with-gnu-ld --enable-languages=c,c++,ada --without-ppl --without-cloog --with-system-zlib --disable-libgomp --without-libffi  --without-libiconv-prefix --disable-libmudflap --disable-nls --disable-libstdcxx-pch  &> ../log.native.gcc.config.txt

make -j4 bootstrap &> ../log.gcc.make.txt
make install &> ../log.gcc.make.install.txt

export PATH=$HOME/opt/tamp/bin:$PATH

4) Cross
--------

../../../src/binutils-2.22/configure --prefix=$HOME/opt/tamp --target=arm-none-eabi --enable-interwork --enable-multilib --disable-nls --disable-shared --disable-threads --with-gcc --with-gnu-as --with-gnu-ld --without-ppl --without-cloog &> ../log.binutils.config.txt

make -j4 &> ../log.binutils.make.txt
make install &> ../log.binutils.make.install.txt

../../../src/gcc-4.6.1/configure --prefix=$HOME/opt/tamp --target=arm-none-eabi --enable-interwork --enable-multilib --with-newlib --disable-nls --disable-shared --disable-threads --disable-lto --with-gnu-as --with-gnu-ld --enable-languages=c --disable-libssp --without-headers --without-ppl --without-cloog &> ../log.gcc1.config.txt

make all-gcc  &> ../log.gcc1.make.txt
make install-gcc &> ../log.gcc1.make.install.txt

../../../src/newlib-1.19.0/configure --prefix=$HOME/opt/tamp --target=arm-none-eabi --enable-interwork --enable-multilib --disable-nls --disable-shared --disable-threads  --with-gnu-as --with-gnu-ld --without-ppl --without-cloog &> ../log.newlib.config.txt

make -j4 &> ../log.newlib.make.txt
make install &> ../log.newlib.make.install.txt

# GCC2

../../../src/gcc-4.6.1/configure --prefix=$HOME/opt/tamp --target=arm-none-eabi --enable-interwork --enable-multilib --with-newlib --disable-nls --disable-shared --disable-threads --disable-lto --with-gnu-as --with-gnu-ld --enable-languages=c,c++,ada --disable-libssp --without-ppl --without-cloog &> ../log.gcc2.config.txt

make -j4 &> ../log.gcc2.make.txt
make install &> ../log.gcc2.make.install.txt

Caveats
-------

When building with gcc-4.6.2, there is a failure in newlib, apparently the fix is to add this

  --disable-newlib-supplied-syscalls

to the configure command, but this also fails later down the line in GCC itself. So, I will not be using 4.6.2
until we can get a patch.

Sample outputs
--------------

$ arm-none-eabi-gnatlink -v

GNATLINK 4.6.1
Copyright (C) 1995-2010, Free Software Foundation, Inc.
Usage: arm-none-eabi-gnatlink switches mainprog.ali [non-Ada-objects] [linker-options]

  mainprog.ali   the ALI file of the main program

  -f    force object file list to be generated
  -g    Compile binder source file with debug information
  -n    Do not compile the binder source file
  -R    Do not use a run_path_option
  -v    verbose mode
  -v -v very verbose mode

  -o nam     Use 'nam' as the name of the executable
  -b target  Compile the binder source to run on target
  -Bdir      Load compiler executables from dir
  --GCC=comp Use comp as the compiler
  --LINK=nam Use 'nam' for the linking rather than 'gcc'

  [non-Ada-objects]  list of non Ada object files
  [linker-options]   other options for the linker

$ arm-none-eabi-gnatls -v

GNATLS 4.6.1
Copyright (C) 1997-2010, Free Software Foundation, Inc.

Source Search Path:
   <Current_Directory>
   /home/laguest/opt/tamp/lib/gcc/arm-none-eabi/4.6.1/adainclude/


Object Search Path:
   <Current_Directory>
   /home/laguest/opt/tamp/lib/gcc/arm-none-eabi/4.6.1/adalib/


Project Search Path:
   <Current_Directory>
   /home/laguest/opt/tamp/lib/gnat/

I think I finally have something to build on.

-------------------------------------------------------------------------------
Bugs
-------------------------------------------------------------------------------

I've submitted the following bug as the compiler cannot create a libgnat.a from
a GPR file, this has to be done via make, it is no longer a blocker:

  http://gcc.gnu.org/bugzilla/show_bug.cgi?id=47717 - CLOSED

Using Long_Long_Integer in a divide generates a call to __aeabi_ldivmod, which
means we could really do with sorting out a proper target build for GNAT so
we don't have to hack it together. This will then build GCC support libs.

-------------------------------------------------------------------------------
LPCXpresso1769 JTAG
-------------------------------------------------------------------------------

We need to remove the LPC-Link board from the LPXpresso1769 board. This then
leaves us open for an external JTAG debugger. The following are my notes and
given I know next to nothing about electronics, some help here would be
appreciated.

These are from [5]:

      J4 Xpresso1769 side (page 4: SWD/JTAG Interface)
Pins  Name
 2    VIO_3V3X
 4    JTAG_TMS_SWDIOX
 6    JTAG_TCLK_SWCLKC
 8    JTAG_TDO_SWOX
10    JTAG_TDIX
12    JTAG_RESETX
14    EXT_POWX
16    GNDX

Pin  2 = TRST_N (From page 5: LPC176X Side)
Pin 12 = SRST??

I came to the conclusion that Pin 12 would be the soft reset if pin 2 is
the test reset. Or are these the other way around?

-------------------------------------------------------------------------------
External JTAG interfaces
-------------------------------------------------------------------------------

This section will list various external JTAG debugger's and their pinouts and
we will gradually provide schematics for connecting them to J4 on the
LPCXpresso1769 board.

Opendous-JTAG [7], [10]

Pin	Function  LPCXpresso
0	TDI       10
1	TMS        4
2	TRST      ??
3	SRST      ??
4	TCK        6
5	TDO        8

USBprog [8]

Would this be possible?

FTDI V2DIP1-32 [9]

Would this be possible? Cheap, OpenOCD already works with the FTDI chip. Just
need to know which pins on this board would become with JTAG pins.

From oliver117 (on #Ada - Oliver Kleinke):

J4 pin connections
------------------

 2    VIO_3V3X               Vcc
 4    JTAG_TMS_SWDIOX        TMS
 6    JTAG_TCLK_SWCLKC       TCLK/TCK
 8    JTAG_TDO_SWOX          TDO
10    JTAG_TDIX              TDI
12    JTAG_RESETX            RESET/SRST
14    EXT_POWX               connected to USB power (5V)
16    GNDX                   GND

ARM 10p JTAG
------------

1 Vcc  |  2 TMS
3 GND  |  4 TCK
5 GND  |  6 TDO
7 RTCK |  8 TDI
9 GND  | 10 nRESET/nSRST

=>
ARM JTAG Header -> Board
1 -> 2
2 -> 4
3, 5, 9-> 16
4 -> 6
6 -> 8
7 -> (no RTCK on board, connect to GND)
8 -> 10
10 -> 12
(optional 5v) -> 14

References
----------

http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0184b/I1037757.html

-------------------------------------------------------------------------------
REFERENCES
-------------------------------------------------------------------------------

Cortex-M3:

[1] Cortex™-M3 Technical Reference Manual:
http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0337i/index.html

[2] ARMv7-M Architecture Reference Manual:
http://infocenter.arm.com/help/topic/com.arm.doc.ddi0403c/index.html

[3] Procedure Call Standard for the ARM Architecture:
http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042d/index.html

[4] Run-time ABI for the ARM architecture:
http://infocenter.arm.com/help/topic/com.arm.doc.ihi0043c/index.html

[5] LPCXpresso1769 schematics:
http://www.embeddedartists.com/sites/default/files/docs/schematics/LPCXpressoLPC1769revB.pdf

[6] Strict Conformance to the ARM:
http://gcc.gnu.org/onlinedocs/gcc-4.6.0/gnat_rm/Strict-Conformance-to-the-Ada-Reference-Manual.html#Strict-Conformance-to-the-Ada-Reference-Manual

[7] Opendous-JTAG:
http://code.google.com/p/opendous-jtag/

[8] USBprog:
http://www2.embedded-projects.net/index.php?page_id=165

[9] FTDI V2DIP1-32:
http://uk.farnell.com/ftdi/v2dip1-32/module-dev-32-pin-1x-usb-vnc2/dp/1825829

[10] eStick:
http://embsys.technikum-wien.at/staff/horauer/estick/estick.php

[11] GNAT Pro User's Guide Supplement for Cross Platforms:
http://www.adacore.com/wp-content/files/auto_update/gnat-cross-docs/html/gnat_ugx.html

[12] GNAT Pro User's Guide Supplement for High-Integrity Edition Platforms:
http://www.adacore.com/wp-content/files/auto_update/gnat-hie-docs/html/gnathie_ug.html

[13] Ada’05 compiler for ARM based systems:
http://www.zsk.p.lodz.pl/~morawski/Dyplomy/Praca%20dyplomowa%20p.%20Horna.pdf