FreeCalypso > hg > fc-selenite
view doc/Developer-notes @ 213:f2a59f3c4f8f
targets/*.h: sync with FC Tourmaline
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Mon, 31 Oct 2022 00:54:52 +0000 |
parents | 3055bcff8050 |
children |
line wrap: on
line source
The present article is a Selenite-specific addendum to the TCS211-fw-arch document in the freecalypso-docs repository; the latter document needs to be read first before this one. Also because FC Selenite is derived from FC Magnetite, you should also read the Developer-notes document in the fc-magnetite source repository before the present one. Source tree layout ================== The principal difference between Magnetite and Selenite in terms of the source tree layout is that Magnetite supports building two different code base variants (either pure TCS211 with G23M PS blobs or our FreeCalypso signature TCS2/TCS3 hybrid), whereas Selenite only supports the hybrid code base. Dropping support for the non-hybrid version is necessary in order to have a saner code base for new forward developments such as the compiler migration to gcc (the objective of FC Selenite) or the future planned UI development work which will be done in yet another to-be-created source tree after we build the necessary hardware. The source tree change is the elimination of parallel versions: in Magnetite we have to maintain two parallel versions for many firmware components, whereas in Selenite there is only one version, the one corresponding to our FreeCalypso signature TCS2/TCS3 hybrid explained in the TCS211-fw-arch document. The directories under src/ are now as follows: condat This subtree is the amalgamation of condat2 and condat3 from Magnetite, hybridized as detailed in the TCS211-fw-arch document. cs This subtree is an import of chipsetsw from TCS211, plus our own reconstruction of those parts of TCS211 chipsetsw which were censored out in our starting copy: src/cs/layer1, src/cs/system/main and the src/cs/system/bootloader/src stub. This subtree is kept in sync with Magnetite as much as possible; the diffs from Magnetite are to support gcc and the new version of Nucleus. g23m-aci g23m-fad g23m-gprs g23m-gsm These directories contain the new TCS3 version of the G23M PS+ACI code realm for our blob-free hybrid. The directory layout comes directly from our TCS3.2 source from Peek/FGW: TI previously kept all G23M code under g23m/condat/ms/src, but then they moved to these new g23m-* directories which I (Mother Mychaela) like for their shortness, so we enthusiastically kept the new directory layout. Only two pieces still resided under g23m/condat/ms/src in our TCS3.2 source: ati_ext and upm, which we moved into g23m-aci and g23m-gprs, respectively, where they properly belong. Just like in Magnetite, our TCS2/TCS3 hybrid uses the TCS2 version of ALR; in Selenite it has been moved to g23m-gsm/alr2. These directories are kept in sync with Magnetite as much as possible; the diffs from Magnetite are fixes (band-aids in some cases) to pass compilation with gcc. gpf This subtree is the amalgamation of gpf2 and gpf3 from Magnetite; see TCS211-fw-arch for the explanation of how our version of GPF has been reconstructed from the surviving bits and pieces. One additional change is that the old Nucleus header files have been moved out of the way so that we always use the new Nucleus headers without ambiguity or conflict. libsys This library is specific to the gcc-built configuration. We use newlib that is built as part of our gcc toolchain (see Toolchain-setup-gcc) as our libc implementation for the most part, but for a few functions we are not able to use newlib's implementation because it uses malloc or depends on a Unix syscall environment which we don't have; libsys provides our own replacements for these few libc functions. nucleus We use a non-TI-sourced version of Nucleus from Comrade XVilka; because it does not come from any of our TI-sourced components, it gets its own top-level source directory. Assembly code pieces ==================== Like any other software that runs on the bare metal as opposed to an application under some high-level OS like Linux, our FreeCalypso GSM fw necessarily includes some assembly code pieces in addition to the main body of C code. The differences between TI's TMS470 and GNU ARM environments and ABIs are great, hence entirely different versions of all assembly code pieces and linker script magic are needed between the two. For the TMS470 compiler environment all assembly code pieces and linker scripts are essentially unchanged from TI's TCS211, whereas for the gcc version all assembly code is entirely new. This assembly code and other support pieces that are specific to the gcc environment (see libsys above) originate from our first attempts at gcc-built GSM fw from the 2013-2015 timeframe. The use of two entirely independent assembly code implementations between the two compiler environments gives rise to some minor architectural differences: the new gcc version takes the approach of routing interrupts and exceptions through the Calypso internal ROM (on all targets in both flashed and RAM-loaded builds) and uses flash boot mode 0 instead of flash boot mode 1 on the sensible non-Compal targets. Both of these design decisions require that the Calypso chip version be one of the new ones with boot ROM version 0300 (the one with all of the earlier bugs fixed); this requirement poses no problem for our own FreeCalypso hw and for the use case of running FreeCalypso fw on the historical hw from Motorola, Openmoko and Pirelli, but if anyone besides the Mother has an ancient D-Sample or Leonardo board with a Calypso C05 chip on it, those boards cannot run Selenite-gcc. Configuration and build system ============================== The configuration and build system of FC Selenite is based on that of Magnetite; please read the Developer-notes document in the fc-magnetite source repository. The first difference from Magnetite is that Selenite does not have overall fw configuration recipes like Magnetite has in configs/* - instead the recipe for the hybrid modem configuration (the only config in the Magnetite sense that is supported in Selenite) has been incorporated into the new configure-gcc.sh and configure-tms470.sh scripts. The selection of which components will be included or excluded is driven by GPRS, SRVC and FCHG_STATE config variables - these config vars exist in Magnetite too, but in Selenite they can be set by the user on the configure command line. The individual component build recipes in components/* are similar between Magnetite and Selenite, but the following aspects are different: * There are no component variants: for each given foo.lib (TMS470) or foo.a (gcc) firmware component, there is only one components/foo recipe. * Except for a few gcc-specific components and one TMS470-specific component (the empty bootloader stub, see TCS211-fw-arch), every components/foo recipe has to work for both TMS470 and gcc environments. The CFLAGS Bourne shell variable is for TI's cl470 compiler, CFLAGS_gcc is for gcc, and CPPFLAGS are common for both. * The shell function call for compiling C source files is c_file, replacing Magnetite's cfile_plain and cfile_str2ind - there is no support for str2ind in Selenite. Because there is no hybrid vs. classic TCS211 dichotomy in Selenite, there are no more header file selection shell variables - see the ex script in scripts/convert-from-magnetite.ex for the idea.