view doc/Compiling @ 600:8f50b202e81f

board preprocessor conditionals: prep for more FC hw in the future This change eliminates the CONFIG_TARGET_FCDEV3B preprocessor symbol and all preprocessor conditionals throughout the code base that tested for it, replacing them with CONFIG_TARGET_FCFAM or CONFIG_TARGET_FCMODEM. These new symbols are specified as follows: CONFIG_TARGET_FCFAM is intended to cover all hardware designs created by Mother Mychaela under the FreeCalypso trademark. This family will include modem products (repackagings of the FCDEV3B, possibly with RFFE or even RF transceiver changes), and also my desired FreeCalypso handset product. CONFIG_TARGET_FCMODEM is intended to cover all FreeCalypso modem products (which will be firmware-compatible with the FCDEV3B if they use TI Rita transceiver, or will require a different fw build if we switch to one of Silabs Aero transceivers), but not the handset product. Right now this CONFIG_TARGET_FCMODEM preprocessor symbol is used to conditionalize everything dealing with MCSI. At the present moment the future of FC hardware evolution is still unknown: it is not known whether we will ever have any beyond-FCDEV3B hardware at all (contingent on uncertain funding), and if we do produce further FC hardware designs, it is not known whether they will retain the same FIC modem core (triband), if we are going to have a quadband design that still retains the classic Rita transceiver, or if we are going to switch to Silabs Aero II or some other transceiver. If we produce a quadband modem that still uses Rita, it will run exactly the same fw as the FCDEV3B thanks to the way we define TSPACT signals for the RF_FAM=12 && CONFIG_TARGET_FCFAM combination, and the current fcdev3b build target will be renamed to fcmodem. OTOH, if that putative quadband modem will be Aero-based, then it will require a different fw build target, the fcdev3b target will stay as it is, and the two targets will both define CONFIG_TARGET_FCFAM and CONFIG_TARGET_FCMODEM, but will have different RF_FAM numbers. But no matter which way we are going to evolve, it is not right to have conditionals on CONFIG_TARGET_FCDEV3B in places like ACI, and the present change clears the way for future evolution.
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 01 Apr 2019 01:05:24 +0000
parents d25f6e216566
children b9ad7bd63f59
line wrap: on
line source

Preparing the development and build environment
===============================================

In order to compile our FreeCalypso Magnetite firmware, you will need a
Unix/Linux system.  Even though we are using a compiler which we got in the
form of Windows .exe binaries and thus have to use Wine (see below), everything
that we have built on top of it is Unix-based.  The Mother currently uses
Slackware Linux release 14.2 (32-bit) and previously used Slackware 13.37,
also 32-bit.

You will need to install the following 3 pieces of software on whatever
machine you will use to run the FC Magnetite build process:

1. Wine: self-explanatory.  The Mother uses the following Slackware package:

   https://www.freecalypso.org/members/falcon/slackware/wine-1.5.23-i486-1sg.txz

   I originally used it with Slackware 13.37 and I am still able to use it
   with 14.2 without any issues.

2. FreeCalypso Wine environment:

   ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/installed-env.tar.xz

   Extract the content of the above tarball into your ~/.wine/drive_c
   directory - that's all there is to it!

3. nowhine wrapper around Wine:

   ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/nowhine.c

   The purpose of this wrapper is to suppress the following obnoxious whine
   which wine emits on my system:

   preloader: Warning: failed to reserve range 00010000-00110000

   Wine will also emits a bunch of other whines if you have to run it
   in an environment without an X11 display (e.g., on a machine that you
   ssh into), and our nowhine wrapper suppresses those as well.

   If wine does not emit those preloader whines on your system and you
   never find yourself in a situation of having to run without an X11
   display and thus you find our nowhine wrapper to be unnecessary,
   you can skip the wrapper and create a nowhine symlink pointing directly
   to wine.

The mokosrec2bin flash image file format conversion utility is now included
locally and no longer needs to be provided externally.

Compiling the local helper utilities
====================================

(cd helpers; make)

Do the above.  Most of the build helper scripts used in the FC Magnetite build
system are written in Bourne shell, but a few were easier to implement in C.
You need to compile these C helper utilities before you can run an actual FC
Magnetite firmware build, but these utilities are totally ad hoc and specific
to the needs of our fw build system, hence they are not meant to be installed
globally on your system - instead they stay within the fc-magnetite tree.  You
just need to run make in the helpers directory once before any actual firmware
builds.

Actually building the firmware
==============================

In order to build our FreeCalypso Magnetite firmware for a particular target in
a particular configuration, run a command like this from the top level of the
fc-magnetite tree:

./configure.sh fcdev3b hybrid

The first required argument to the configure.sh script selects the target, the
second required argument selects the build configuration recipe, and any further
arguments beyond these two (optional) allow changing various configurable
settings that aren't strictly fixed by the hardware target or by the build
configuration recipe.

As of this writing, the following hardware targets are supported:

c11x		Motorola C11x/12x
c139		Motorola C139/140
c155		Motorola C155/156
dsample		TI's D-Sample C05 board (no working radio currently)
fcdev3b		FreeCalypso FCDEV3B
gtamodem	The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones
j100		Sony Ericsson J100
pirelli		Pirelli DP-L10

For the available configurations (the second required argument to the configure
script), look in the configs directory and read the various write-ups under doc.

Each configuration is built in its own directory; the name of this build
directory takes the form of build-$TARGET-$CONFIG$SUFFIX, i.e., for the example
configure.sh line above, the resulting build directory will be named
build-fcdev3b-hybrid.  The $SUFFIX part is empty by default, but can be set on
the command line in order to distinguish non-standard builds that had some
tunable settings changed to values other than the default.  For example, if you
are building the hybrid configuration for the fcdev3b target as above, but you
need to disable MELODY_E2, you could run the configure script as follows:

./configure.sh fcdev3b hybrid MELODY_E2=0 SUFFIX=-noe2

The build directory would then become build-fcdev3b-hybrid-noe2, and the
specified suffix will also be included in the firmware version ID string that
gets compiled into the image.

To actually compile the firmware, cd into the created build directory and run
make there.  Unfortunately the use of TI's proprietary compiler via Wine makes
the build quite slow, but there is a trick to speed it up: if you run some
other Wine program that stays open and does not exit on its own (e.g., wine cmd)
in another window and leave it open while you run your FC Magnetite fw build,
the build will proceed much faster - the presence of another Wine process using
the wineserver environment will keep Wine from shutting this environment down
and restarting it for every individual cl470 run, i.e., for each individual C
source file.

When the build is done, the flashable firmware image will be in fwimage.bin.
This image is to be flashed with fc-loadtool at a target-dependent base address.
The build system also produces a short text file named flash-script which is a
flashing command script for fc-loadtool that erases the correct range of flash
sectors and then programs fwimage.bin at the right address.

When building firmware for the FCDEV3B or for the Pirelli, one can build either
a flashable image or a RAM-loadable one - or both.  Because this part of the
build system is common with other targets for which only flash images can be
produced, the Makefile always builds the flashable image by default -
fwimage.bin is always meant for flash and never for RAM.  To build a RAM-
loadable image when the target allows it, run 'make ram' - the image will be in
ramimage.srec, which you can then load and run on the target with FreeCalypso
host tool fc-xram.

Running on the hardware
=======================

In order to run the firmware you have built on your Calypso phone or modem
(flash or run in RAM as appropriate), you will need to use FreeCalypso host
tools.  As of this writing, the latest packaged release is this one:

ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-r10.tar.bz2

Please see target-specific notes for more details.