# HG changeset patch # User Mychaela Falconia # Date 1532476524 0 # Node ID a68c6c7942d7d43f394d63a77088358f61b845a7 # Parent af6b7fcf7823ca3da4f198401b0747576cee0417 doc: basic build documentation written diff -r af6b7fcf7823 -r a68c6c7942d7 doc/Compiling --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Compiling Tue Jul 24 23:55:24 2018 +0000 @@ -0,0 +1,223 @@ +Selecting and preparing the compiler environment +================================================ + +FreeCalypso Selenite firmware can be built with two different compiler +toolchains: either with TI's original TMS470 compiler or with gcc. Transition +to compiling with gcc is a very bold move with very heavy fallout, and many +parts of the fw are still broken or destabilized when built with gcc instead of +the original compiler they were developed with, thus for the foreseeable future, +anyone who aspires to be a FreeCalypso developer will need to compile our fw in +both ways, compare the behaviour of the two versions, and work toward making +the gcc-built version perform as well as the TMS470-built one. Thus you need +to have both compiler toolchains installed and working - see the +Toolchain-setup-470 and Toolchain-setup-gcc articles for the instructions. + +Compiling the local helper utilities +==================================== + +(cd helpers; make) + +Do the above. Most of the build helper scripts used in the FC Selenite 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 +Selenite 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-selenite tree. You +just need to run make in the helpers directory once before any actual firmware +builds. + +Actually building the firmware +============================== + +To build our FC Selenite firmware for your hw target of interest in the default +configuration, run a command like this from the top level of the fc-selenite +tree: + +./configure-gcc.sh fcdev3b + +or + +./configure-tms470.sh fcdev3b + +As of this writing, the following hardware targets are supported: + +c11x Motorola C11x/12x +c139 Motorola C139/140 +fcdev3b FreeCalypso FCDEV3B +gtamodem The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones +pirelli Pirelli DP-L10 + +Notice the difference from FC Magnetite: there is no "configuration name" +argument after the target name. Because FC Selenite does not include any UI +code (modem functionality only) and does not offer different versions of +various fw components the way Magnetite does, it does not have named +configurations in the same sense as Magnetite. Instead any configuration +tweaks are done via var=value optional arguments on the configure command line +after the required target name argument; the following variables are currently +available for tweaking: + +ALLOW_CSIM_GSM + + Per TI's original design, the AT+CSIM command does not allow GSM APDUs + of class 0xA0. Openmoko found some need for them, and they patched + their modem fw to allow these APDUs with AT+CSIM. With our new hybrid + modem fw this policy setting is configurable at build time; the default + is ALLOW_CSIM_GSM=1 (GSM APDUs allowed). + +DISABLE_SLEEP + + The general default is DISABLE_SLEEP=0, and the firmware automatically + enables all of the chipset's available sleep modes on boot. Setting + DISABLE_SLEEP=1 causes all sleep modes to be disabled by default on + boot (they can still be enabled with the AT%SLEEP command); this + setting is needed for FCDEV3B V1 boards that have a hardware bug that + causes breakage when sleep modes are enabled. + +FCHG_STATE + + This setting enables or disables the FCHG battery charging driver. By + default it is enabled on targets that have battery charging hardware + (c11x, c139, pirelli) and disabled on those that don't have such hw + (fcdev3b, gtamodem). + +GPRS + + Self-explanatory: enables or disables GPRS. By default GPRS is enabled + on proper modem hw targets (fcdev3b and gtamodem) and disabled on c11x, + c139 and pirelli. + +L1_DYN_DSP_DWNLD + + This setting enables TI's dynamic DSP patch download mechanism. When + the firmware is built for a Calypso target with DSP ROM version 36 in + the silicon (all FreeCalypso-made hw and most of the supported legacy + targets), L1_DYN_DSP_DWNLD is enabled by default and needs to be kept + enabled for correct operation: the patch code we got from TI for this + ROM is the dynamic download version, and the ARM-side L1 code expects + all of these patches to be present, both the static part and the + dynamic parts. However, one can build our fw with L1_DYN_DSP_DWNLD=0 + for experimental testing, to see what breaks when the dynamic patches + are omitted. + +L1_VOICE_MEMO_AMR + + This setting enables or disables support in L1 and in the RiViera Audio + Service for AMR voice memo recording and playback. This code has not + been properly studied yet and no test AT commands are provided for it, + but it is enabled by default like in TI's original TCS211 fw. + +MELODY_E2 + + This setting enables or disables support in L1 and in the RiViera Audio + Service for playing E2-format melodies. The default is MELODY_E2=1 + like in TI's original TCS211 fw. Note that Melody E1 support is always + enabled; setting MELODY_E2=0 disables only Melody E2, but not E1. + +MEMSUPER + + This setting enables the memory supervision feature in TI's GPF and in + the G23M protocol stack built on top of it. This code has not been + properly studied yet; play with it at your own risk. + +SERIAL_DYNAMIC_SWITCH + + TI's TCS211 fw includes a provision (only for Bluetooth-enabled fw in + TI's original) to switch one UART between the AT command interface and + RVTMUX while the other UART is fixed for Bluetooth. In FreeCalypso we + have changed this code to work without Bluetooth, for the purpose of + switching the user-facing MODEM UART between AT commands and RVTMUX, + but the mechanism does not work properly yet and is disabled by default. + Enable it with SERIAL_DYNAMIC_SWITCH=1 if you would like to play with + it. + +SPEECH_RECO + + This setting enables or disables support in L1 and in the RiViera Audio + Service for TI's speech recognition mechanism. This code and the + underlying DSP facility itself have not been properly studied yet and + no test AT commands are provided for it, but it is enabled by default + like in TI's original TCS211 fw. + +SRVC + + TI's original config variable, selects the presence or absence of data + services other than GPRS as follows: + + SRVC=0: voice and SMS only + SRVC=1: CSD and fax enabled + SRVC=2: CSD enabled, but not fax + + The default is SRVC=1 (fax and data enabled) for proper modem hw targets + (fcdev3b and gtamodem) and SRVC=0 (voice and SMS only) on c11x, c139 + and pirelli. + +SUFFIX + + This setting is solely for configuration management. If you make a + build with any of the settings described in this document changed from + the default, you should also pass a SUFFIX=-xxx argument so your special + build will be appropriately identified in the build directory name and + in the firmware version ID string compiled into the image. The naming + of suffixes is up to you, but here are some examples: + + L1_DYN_DSP_DWNLD=0 SUFFIX=-nodyn + MELODY_E2=0 SUFFIX=-noe2 + MEMSUPER=2 SUFFIX=-ps + SERIAL_DYNAMIC_SWITCH=1 SUFFIX=-sds + SPEECH_RECO=0 SUFFIX=-nosr + TR_BAUD_CONFIG=TR_BAUD_812500 SUFFIX=-812500 + +TR_BAUD_CONFIG + + The value of this symbol is an alphanumeric keyword of the form + TR_BAUD_xxxxxx; the default is TR_BAUD_115200. See + src/cs/drivers/drv_core/uart/traceswitch.h for the available baud rate + choices; the most practical use is setting TR_BAUD_CONFIG=TR_BAUD_812500 + when you need to run the RVTMUX serial channel at the maximum possible + baud rate. + +Each configuration is built in its own directory; the name of this build +directory always begins with build- and is constructed to reflect the +configuration. The auto-generated build directory name includes the name of +the target, the selection of services to be included based on the GPRS, SRVC +and FCHG_STATE variables, and a -470 or -gcc suffix indicating the compiler +toolchain, but if you manually override any of the other config variables +described above, you should also include a SUFFIX=-xxx argument giving an +identifying suffix for your own configuration changes. + +To actually compile the firmware, cd into the created build directory and run +make there. With gcc the build proceeds very fast because the compiler runs +natively, but building with the original TMS470 compiler requires going through +Wine, which is much slower. There is, however, a trick to speed up these +TMS470 builds: 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 Selenite TMS470 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 address 0x10000 on Mot C11x and +C139 targets, and at address 0 on the more sensible targets that have the +Calypso boot ROM enabled. 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 FCDEV3B or other Calypso +device (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-r8.tar.bz2 diff -r af6b7fcf7823 -r a68c6c7942d7 doc/Toolchain-setup-470 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Toolchain-setup-470 Tue Jul 24 23:55:24 2018 +0000 @@ -0,0 +1,39 @@ +Preparing the build environment for TMS470 +========================================== + +In order to compile FC Selenite with TI's original TMS470 compiler, you will +need a Unix/Linux system. Even though the compiler itself exists in the form +of Windows .exe binaries and thus has to be run under Wine (see below), +everything that we have built on top of it is Unix-based. The Mother uses +Slackware Linux version 13.37, 32-bit. + +You will need to install the following four pieces of software on whatever +machine you will use to run the FC Selenite build process: + +1. Wine: self-explanatory. + +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 + + Note that Wine may produce different whines on your system than it + does on mine, in which case if you wish to be relieved of those + whines, you'll need to edit my nowhine.c hack for your situation. + And if wine does not whine at all on your system, you can skip the + wrapper and create a nowhine symlink pointing directly to wine. + +4. mokosrec2bin flash image file format conversion utility: + + ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c + +Note that the four host software pieces above are exactly the same as what has +been needed to build our previous TCS211-based fw works such as leo2moko-debug +and tcs211-c139 - thus if you have built those previously, you should already +have all of the necessary host tools. diff -r af6b7fcf7823 -r a68c6c7942d7 doc/Toolchain-setup-gcc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Toolchain-setup-gcc Tue Jul 24 23:55:24 2018 +0000 @@ -0,0 +1,20 @@ +Building and installing the ARM7 toolchain +========================================== + +Before you can compile FC Selenite with gcc, you first need to build and +install the necessary toolchain targeting ARM7, the CPU core in the Calypso. +The current "official" GNU ARM toolchain for FreeCalypso consists of +binutils-2.21.1, gcc-4.5.4 and newlib-2.0.0 with a specific set of patches and +build configuration options. All of the necessary bits can be downloaded here: + +ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/toolchain/ + +Please note: the toolchain that is prescribed for FreeCalypso as above is +*believed* to be equivalent to the one that was once used by OsmocomBB, but +there are no guarantees. Use any other toolchain at your own risk. + +There is also a prebuilt toolchain put together by FreeCalypso community +contributor Das Signal: + +https://www.freecalypso.org/members/ds/fc-gnu-arm-i386.tgz +https://www.freecalypso.org/members/ds/fc-gnu-arm-x86_64.tgz