fc-magnetite: doc/Compiling annotate

author	Mychaela Falconia <falcon@freecalypso.org>
date	Wed, 17 Jan 2018 20:18:45 +0000 (2018-01-17)
parents	c6823ed06f9c
children	48ae9825662c

rev	line source
94 596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 Preparing the development and build environment
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 ===============================================
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4 In order to compile our FreeCalypso Magnetite firmware, you will need a
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	5 Unix/Linux system. Even though we are using a compiler which we got in the
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	6 form of Windows .exe binaries and thus have to use Wine (see below), everything
373 9399a83cb394 first round of documentation updates for 2018 Mychaela Falconia <falcon@freecalypso.org> parents: 311 diff changeset	7 that we have built on top of it is Unix-based. The Mother uses Slackware Linux
94 596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	8 version 13.37, 32-bit.
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 You will need to install the following four pieces of software on whatever
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	11 machine you will use to run the FC Magnetite build process:
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	12
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	13 1. Wine: self-explanatory.
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	14
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	15 2. FreeCalypso Wine environment:
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	16
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	17 ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/installed-env.tar.xz
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19 Extract the content of the above tarball into your ~/.wine/drive_c
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20 directory - that's all there is to it!
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 3. nowhine wrapper around Wine:
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24 ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/nowhine.c
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26 Note that Wine may produce different whines on your system than it
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27 does on mine, in which case if you wish to be relieved of those
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28 whines, you'll need to edit my nowhine.c hack for your situation.
310 8488a9ae583c doc/Compiling: added note that if wine doesn't whine, make nowhine a symlink Mychaela Falconia <falcon@freecalypso.org> parents: 251 diff changeset	29 And if wine does not whine at all on your system, you can skip the
8488a9ae583c doc/Compiling: added note that if wine doesn't whine, make nowhine a symlink Mychaela Falconia <falcon@freecalypso.org> parents: 251 diff changeset	30 wrapper and create a nowhine symlink pointing directly to wine.
94 596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32 4. mokosrec2bin flash image file format conversion utility:
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	33
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	34 ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	35
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	36 Note that the four host software pieces above are exactly the same as what has
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	37 been needed to build our previous TCS211-based fw works such as leo2moko-debug
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	38 and tcs211-c139 - thus if you have built those previously, you should already
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	39 have all of the necessary host tools.
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	40
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41 Compiling the local helper utilities
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	42 ====================================
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	43
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	44 (cd helpers; make)
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	45
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	46 Do the above. Most of the build helper scripts used in the FC Magnetite build
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	47 system are written in Bourne shell, but a few were easier to implement in C.
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	48 You need to compile these C helper utilities before you can run an actual FC
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	49 Magnetite firmware build, but these utilities are totally ad hoc and specific
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	50 to the needs of our fw build system, hence they are not meant to be installed
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	51 globally on your system - instead they stay within the fc-magnetite tree. You
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	52 just need to run make in the helpers directory once before any actual firmware
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	53 builds.
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	54
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	55 Actually building the firmware
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	56 ==============================
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58 In order to build our FreeCalypso Magnetite firmware for a particular target in
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59 a particular configuration, run a command like this from the top level of the
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60 fc-magnetite tree:
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	62 ./configure.sh gtamodem l1reconst
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	63
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	64 The first argument to the configure.sh script selects the target, and the second
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	65 argument selects the configuration. As of this writing, the following targets
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	66 are supported:
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67
381 c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	68 c11x Motorola C11x/12x
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	69 c139 Motorola C139/140
251 6c594ce434f8 doc/Compiling: update for the FCDEV3B and for fc-host-tools-r5 Mychaela Falconia <falcon@freecalypso.org> parents: 220 diff changeset	70 fcdev3b FreeCalypso FCDEV3B
94 596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	71 gtamodem The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72 pirelli Pirelli DP-L10
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74 For the available configurations (the second required argument to the configure
373 9399a83cb394 first round of documentation updates for 2018 Mychaela Falconia <falcon@freecalypso.org> parents: 311 diff changeset	75 script), look in the configs directory and read the various write-ups under doc.
94 596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	76
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	77 Each configuration is built in its own directory; by default the build directory
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	78 is named build-$TARGET-$CONFIG, i.e., for the example configure.sh line above,
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	79 the resulting build directory will be build-gtamodem-l1reconst. You can change
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 the name of this directory by appending a BUILD_DIR=dir argument to the
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81 ./configure.sh line after the two required arguments.
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	83 To actually compile the firmware, cd into the created build directory and run
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	84 make there. Unfortunately the use of TI's proprietary compiler via Wine makes
381 c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	85 the build quite slow, but there is a trick to speed it up: if you run some
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	86 other Wine program that stays open and does not exit on its own (e.g., wine cmd)
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	87 in another window and leave it open while you run your FC Magnetite fw build,
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	88 the build will proceed much faster - the presence of another Wine process using
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	89 the wineserver environment will keep Wine from shutting this environment down
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	90 and restarting it for every individual cl470 run, i.e., for each individual C
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	91 source file.
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	92
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	93 When the build is done, the flashable firmware image will be in fwimage.bin.
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	94 This image is to be flashed with fc-loadtool at address 0x10000 on Mot C11x and
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	95 C139 targets, and at address 0 on the more sensible targets that have the
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	96 Calypso boot ROM enabled. The build system also produces a short text file
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	97 named flash-script which is a flashing command script for fc-loadtool that
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	98 erases the correct range of flash sectors and then programs fwimage.bin at the
c6823ed06f9c doc/Compiling: update for C11x and for the speed-up trick Mychaela Falconia <falcon@freecalypso.org> parents: 373 diff changeset	99 right address.
94 596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	100
251 6c594ce434f8 doc/Compiling: update for the FCDEV3B and for fc-host-tools-r5 Mychaela Falconia <falcon@freecalypso.org> parents: 220 diff changeset	101 When building firmware for the FCDEV3B or for the Pirelli, one can build either
6c594ce434f8 doc/Compiling: update for the FCDEV3B and for fc-host-tools-r5 Mychaela Falconia <falcon@freecalypso.org> parents: 220 diff changeset	102 a flashable image or a RAM-loadable one - or both. Because this part of the
94 596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103 build system is common with other targets for which only flash images can be
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104 produced, the Makefile always builds the flashable image by default -
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	105 fwimage.bin is always meant for flash and never for RAM. To build a RAM-
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	106 loadable image when the target allows it, run 'make ram' - the image will be in
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	107 ramimage.srec, which you can then load and run on the target with FreeCalypso
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	108 host tool fc-xram.
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	110 Running on the hardware
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	111 =======================
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	112
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	113 In order to run the firmware you have built on your Calypso phone or modem
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	114 (flash or run in RAM as appropriate), you will need to use FreeCalypso host
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	115 tools. As of this writing, the latest packaged release is this one:
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	116
311 86a89a21078f doc/Compiling: update for fc-host-tools-r7 Mychaela Falconia <falcon@freecalypso.org> parents: 310 diff changeset	117 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-r7.tar.bz2
94 596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	118
596d86109e44 initial round of documentation Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	119 Please see target-specific notes for more details.

94

596d86109e44 initial round of documentation