# HG changeset patch # User Mychaela Falconia # Date 1541732642 0 # Node ID 3055bcff8050e16ebbc97ba6a61971554974e2ed # Parent 24a161f415f55f8af73700616cd55e442aefab72 doc/Developer-notes written diff -r 24a161f415f5 -r 3055bcff8050 doc/Developer-notes --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Developer-notes Fri Nov 09 03:04:02 2018 +0000 @@ -0,0 +1,146 @@ +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.