# HG changeset patch # User Mychaela Falconia # Date 1603044495 0 # Node ID a62e5bf88434a3e01e82f3e1d1aa4ed247e14821 # Parent 4e178a0e90f67cf185a3c1dcec55f2ba643e324a first round of documentation diff -r 4e178a0e90f6 -r a62e5bf88434 README --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README Sun Oct 18 18:08:15 2020 +0000 @@ -0,0 +1,61 @@ +FreeCalypso Tourmaline firmware project +======================================= + +In chronological terms, FC Tourmaline is our fourth firmware offering after +Citrine, Magnetite and Selenite. FC Tourmaline supports the following two +fundamental modes of operation: + +* AT-command-controlled modem operation (no UI) is currently unchanged from + Magnetite hybrid; standard modem operation is supported on Tango/Caramel2, + FCDEV3B and Openmoko hardware targets. + +* The new work being done in Tourmaline is phone handset functionality - the + goal is to produce firmware that can operate a suitable hardware unit as an + untethered end user phone. Only two hardware targets are supported in this + FC Tourmaline handset UI development venture: FC Luna development platform + and Motorola C139. + +See the following articles under doc for further details: + +C139-notes -- running smallbw version of the UI on Mot C139 +Luna-notes -- running both UI versions on FC Luna +Modem-operation -- using the modem configuration + +Technical details +================= + +Just like FC Selenite, Tourmaline is derived from the hybrid config of +Magnetite. Also in common with Selenite, Tourmaline uses the new source +version of Nucleus. However, unlike Selenite, Tourmaline retains sole use of +the original TMS470 compiler (runs under Wine), retains the original blob +versions of OSL and OSX glue components of GPF in the default config (see +doc/Blob-status), and includes both modem and handset functional configs. + +Purpose and goal +================ + +As of late 2020, FreeCalypso has achieved everything that needs to be done on +the modem side: our Magnetite hybrid or Tourmaline stdmodem firmware running on +our Tango modem module embodies complete fulfillment of our long-standing desire +for a standard GSM+GPRS modem module with fully published circuit schematics and +firmware source code. No more significant work beyond maintenance is deemed to +be needed on the modem side. + +OTOH, the other need for a FreeCalypso handset that can replace proprietary +phones like Mot C1xx or Pirelli DP-L10 running their original proprietary fw +still remains as unmet as it was when we started back in 2013. Thus the new +FreeCalypso work direction is to finally produce this FC handset, initially in +the form of FC firmware running on Mot C139 (and on FC Luna to keep up the +bigcolor config) and allowing the possibility of new FreeCalypso handset hw. + +Seen from the perspective of handset rather than modem functionality, the +direction taken in Citrine and Selenite (going for 100% blob-free compilation +with gcc) is the wrong way to go. That direction would make sense if one cared +only about modem functionality rather than handset, but we are currently in the +opposite situation. In the case of handset functionality, going for a compiler +change to gcc in our current state when so many other parts are broken and in +need of fixing would be pure insanity, and we are not going there. Let us +first produce a working FreeCalypso handset (with fw compiled with TMS470 under +Wine, keeping the tiny remaining blobs) that can replace Mot/Pirelli's original +proprietary firmwares for daily use, and *then* think about moving to 100% +blob-free gcc - in this order. diff -r 4e178a0e90f6 -r a62e5bf88434 doc/Blob-status --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Blob-status Sun Oct 18 18:08:15 2020 +0000 @@ -0,0 +1,32 @@ +State of blobs in FreeCalypso firmware +====================================== + +FC Tourmaline is almost completely deblobbed. Only the following very small +components exist in the form of blobs (prebuilt binary objects for which we +have no exact corresponding source) in the standard Tourmaline build: + +* OSL and OSX glue components of GPF: 14992 bytes of code +* TMS470 compiler's RTS library (libc/libgcc equivalent): 13152 bytes of code + +For OSL and OSX we do have reconstructed C code written based on disassembly of +the blobs, but I (Mother Mychaela) do not consider the current state of this C +reconstruction to be fit for production use - hence standard Tourmaline fw +builds use blob versions of these components. However, our configuration and +build system gives you the freedom to select which version of each component +you would rather use; the selection is made with Bourne shell config variables +on the configure.sh invokation line: + +OSL=0 use the blob version of OSL +OSL=1 use the reconstructed C version of OSL +OSX=0 use the blob version of OSX +OSX=1 use the reconstructed C version of OSX + +The current default is OSL=0 and OSX=0. + +RTS library +=========== + +We do have source code for some versions of the TMS470 compiler's RTS library, +but they may not be exactly corresponding to the blob version from TCS211 which +we are using. This area is deemed to be such a low priority that no real +investigation has been done yet. diff -r 4e178a0e90f6 -r a62e5bf88434 doc/C139-notes --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/C139-notes Sun Oct 18 18:08:15 2020 +0000 @@ -0,0 +1,22 @@ +FC Tourmaline firmware differs from Magnetite in two principal ways when it +comes to Mot C139 target support: + +* C139 LCD support is implemented in a more forward-looking manner: instead of + emulating TI's C-Sample at the lowest R2D driver level and therefore being + forever limited to 84x48 pixel display size, Tourmaline implements a new + 96x64 pixel framebuffer, matching the native LCD size of C1xx phones. The UI + configuration is still black&white only though - the Mother of FreeCalypso + has no current plans to support color UI on smaller LCD sizes than TI's + original 176x220 pix. + +* Our aftermarket FFS configuration has been changed from 64x3 at 0x3C0000 to + 64x7 at 0x300000. Our earlier 64x3 config was chosen back in 2015, at that + time we didn't know how much room we would end up needing for the firmware + image vs. how much FFS content we would eventually have, and this 64x3 config + is now deemed to be too small, allowing only one 64 KiB sector for FFS + content. Our new FC Tourmaline aftermarket FFS config supports up to 320 KiB + of FFS content, matches what we use on other platforms with 4 MiB flash chips, + leaves 3 MiB for the firmware image (our current smallbw UI fw is only 2 MiB), + and still avoids intersection with Motorola's (or rather Compal's) original + FFS, which is important for avoiding problems in converting C139 phones back + and forth between Motorola and FreeCalypso firmwares. diff -r 4e178a0e90f6 -r a62e5bf88434 doc/Compiling --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Compiling Sun Oct 18 18:08:15 2020 +0000 @@ -0,0 +1,204 @@ +Preparing the development and build environment +=============================================== + +In order to compile our FreeCalypso Tourmaline 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 Tourmaline 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. + +Compiling the local helper utilities +==================================== + +(cd helpers; make) + +Do the above. Most of the build helper scripts used in the FC Tourmaline 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 +Tourmaline 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-tourmaline 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 Tourmaline firmware for a particular target +in a particular configuration, run a command like this from the top level of +the fc-tourmaline tree: + +./configure.sh luna2 bigcolor-gprs + +The first required argument to the configure.sh script selects the hardware +target, the second required argument selects the functional configuration, and +any further arguments beyond these two (optional) allow changing various +configurable settings that go beyond basic functional selection and aren't +strictly fixed by the hardware target. + +As of this writing, the following hardware targets are supported: + +c11x Motorola C11x/12x +c139 Motorola C139/140 +c155 Motorola C155/156 +fcdev3b FreeCalypso FCDEV3B +gtamodem The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones +gtm900mgc Huawei GTM900, hardware variant MGC1GSMT or MGC2GSMT +j100 Sony Ericsson J100 +luna1 FreeCalypso Luna, based on iWOW DSK v4.0 or v5.0 motherboard +luna2 FreeCalypso Luna, based on FC Caramel2 motherboard +pirelli Pirelli DP-L10 +tangomdm FreeCalypso Tango standard modem config + +The second required argument selects the basic functional configuration; these +functional config stanzas appear in the configs directory. The following +functional configurations are currently available: + +bigcolor-gprs & bigcolor-vo + + These are UI-enabled configurations with the big (176x220 pixel) color + version of the UI. These functional configs can be built only for + luna1 and luna2 targets. + +smallbw + + Small B&W UI configuration - 96x64 pixel black&white UI version. This + functional config can be built for c139, luna1 and luna2 targets. When + running on Luna, the logical 96x64 pixel B&W LCD is centered in the + middle of the 176x220 pixel physical LCD, surrounded by a pale magenta + border. + +bwtest + + This one is a special intermediate configuration is that the UI layers + are built in the smallbw config, but the underlying R2D framebuffer + driver is 176x220 pixel B&W, rather than 96x64 pixel B&W. This config + can only be built for Luna targets; it originates from TI's own + configuration of running their !LSCREEN (smallbw) UI on D-Sample boards + with R2D driver in the BW_D_Sample config. + +stdmodem + + Standard modem config, all data services enabled, no UI functionality + included. Supported targets are fcdev3b, gtamodem, gtm900mgc and + tangomdm. + +vpm + + See the Voice-pseudo-modem article. This functional config is + applicable to c11x, c139, c155, j100 and pirelli targets. + +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-luna2-bigcolor-gprs. 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 modem firmware for an FCDEV3B V1 board where you need to disable +sleep, you should run the configure script as follows: + +./configure.sh fcdev3b stdmodem DISABLE_SLEEP=1 SUFFIX=-nosleep + +The build directory would then become build-fcdev3b-stdmodem-nosleep, 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 Tourmaline 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. + +Cached libraries +================ + +In the build architecture of all TCS211-based firmwares including Tourmaline, +each fw component is first compiled into a linkable library (*.lib file with +TI's TMS470 toolchain), and then these libraries are linked together into the +final code image. Early in FreeCalypso project history many of these component +libraries were blobs, meaning that we had to use prebuilt libraries for which +we had no corresponding source. Our fw has now been almost fully deblobbed, +meaning that we have transitioned from blobs to recompilation from source for +almost all of our fw components. But this deblobbing has had an unfortunate +downside: because our Wine-based compiler is very slow, every time we deblobbed +a component library, build times would get longer and longer. + +FC Tourmaline introduces a partial solution to this problem in the form of +cached libs. Some component libraries are completely independent of +configuration particulars, i.e., they remain exactly the same no matter which +Calypso target you are building firmware for, and are likewise unaffected by +our various supported functional configs. Prebuilt versions of these config- +independent libs have been checked into the cache directory of our source tree, +and Tourmaline fw builds use these cached libs by default. These cached libs +are NOT blobs in that we do have the corresponding source for them, and the +versions that are checked in have been built by us, not by any evil source- +withholding third parties. You can disable the use of cached libs and force +full recompilation from source by adding a USE_CACHE=0 argument to your +configure.sh line. + +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. The current version at any given moment can be found at this URL: + +ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2 + +Please see target-specific notes for more details. diff -r 4e178a0e90f6 -r a62e5bf88434 doc/Config-vars --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Config-vars Sun Oct 18 18:08:15 2020 +0000 @@ -0,0 +1,203 @@ +The following Bourne shell variables can be set on the ./configure.sh command +line to tweak the firmware build configuration: + +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. + This driver can be enabled even on targets where no charging hw exists + (it won't do anything without explicit configuration), and our UI + firmware will soon require FCHG to be always present - hence our current + config mechanism already sets FCHG_STATE=1 for UI-enabled configs. If + the firmware is built in a non-UI modem or VPM configuration, the + default FCHG_STATE setting depends on the target: enabled on targets + that have battery charging hardware (c11x, c139, c155, j100, pirelli) + and disabled otherwise. + +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. + +OSL + + This flag selects between original blob and reconstructed C versions of + the OSL glue component of GPF - see the Blob-status article. + +OSX + + This flag selects between original blob and reconstructed C versions of + the OSX glue component of GPF - see the Blob-status article. + +RVTMUX_ON_MODEM + + This setting configures the usage of Calypso UARTs. RVTMUX_ON_MODEM=0 + puts the AT command interface on the MODEM UART and RVTMUX on the IrDA + UART (TI's intended config and the default on sensible hw targets); + RVTMUX_ON_MODEM=1 (default on the crippled C1xx targets) puts RVTMUX on + the MODEM UART, sacrificing the standard AT command interface. + +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. + +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: + + DISABLE_SLEEP=1 SUFFIX=-nosleep + 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 + TI_PROFILER=1 SUFFIX=-prf + TR_BAUD_CONFIG=TR_BAUD_812500 SUFFIX=-812500 + USE_STR2IND=1 SUFFIX=-s2i + +TI_PROFILER + + TI's original firmware architecture had a built-in profiler (program + counter sampler) enabled with TI_PROFILER=1; we (FreeCalypso) are just + beginning to experiment with this debug feature in late 2020. + +TRACEMASK_IN_FFS + + TI's Test Interface (TIF) component in the GPF realm includes an + optional feature for saving trace masks in FFS, but TI's production + firmwares had it disabled. We have now switched to recompiling the + component in question from source, but we still keep this + TRACEMASK_IN_FFS code disabled by default, at least for now. + Set TRACEMASK_IN_FFS=1 to enable this code in GPF. + +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. + +USE_CACHE + + This setting enables or disables the use of cached libs - see the + Cached libraries section in the Compiling article for the explanation. + +USE_STR2IND + + Unlike TI's original firmwares, we build without str2ind by default. + You can enable str2ind with USE_STR2IND=1, but the time to build the fw + will be significantly longer as the compiler has to be run twice for + each C source file, with str2ind sandwiched in between. + +The following Bourne shell variables are used inside the build system, set by +functional configuration stanzas: + +GPRS + + Self-explanatory: enables or disables GPRS. + +MMI + + TI's original config variable: MMI=0 for the AT-command-controlled + modem configuration or MMI=2 for the UI-enabled configuration with + BMI and MFW. + +R2D_STATE + + Enables or disables inclusion of the R2D driver in the firmware. + +R2D_EMBEDDED_LCD + + This setting selects the framebuffer config to be used by the R2D + driver, valid settings are: + + R2D_EMBEDDED_LCD=7: D-Sample color framebuffer + R2D_EMBEDDED_LCD=8: D-Sample B&W framebuffer + R2D_EMBEDDED_LCD=10: new FreeCalypso 96x64 pixel B&W framebuffer + + See src/cs/drivers/drv_app/r2d/r2d_config.h for the details. + +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 + +UI_CONFIG + + The two allowed settings in FC Tourmaline are UI_CONFIG=bigcolor and + UI_CONFIG=smallbw. This setting controls the passing of -DLSCREEN and + -DCOLOURDISPLAY to all C modules in the UI layers. + +Finally, CHIPSET, DSP, RF and AMR variables reflect the physical configuration +of the selected target hw that no amount of software hacking can change. +(The AMR variable indicates the presence or absence of AMR support in the DSP.) diff -r 4e178a0e90f6 -r a62e5bf88434 doc/Luna-notes --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Luna-notes Sun Oct 18 18:08:15 2020 +0000 @@ -0,0 +1,25 @@ +FreeCalypso Luna phone handset UI development platform consists of these 3 +components: + +* A Caramel-type Calypso motherboard, either iWOW DSK or FC Caramel2 +* An LCD carrier board, currently using HaoRan HT020K1QC36S LCD module +* A 5x5 keyswitch matrix board for the keypad function + +This Luna is our primary official platform for FreeCalypso phone handset UI +development. The UI code we got from TI comes in two interesting versions: + +* Big color version: 176x220 pixels, 16-bit color +* Small B&W version: originally 84x48 pixels, we are extending it to 96x64 pix + +(Originally there was also a third version, large 176x220 pix B&W, but we find + it uninteresting and we've removed it from our supported set. It was really + nothing more than a hack to display a minimal-effort derivative of the original + small B&W UI on the large D-Sample LCD, so we are not removing anything of any + real substance here.) + +FC Luna hardware is required for anyone who wishes to work on the phone handset +UI project in FC Tourmaline: it is the only target platform that can display +both versions of our work-in-progress UI firmware. Mot C1xx and other similar +phones have small LCDs that can only display the small B&W version of our +TI-based UI, and in the Mother's opinion working solely on the smallbw version +to the exclusion of the bigcolor version is not acceptable. diff -r 4e178a0e90f6 -r a62e5bf88434 doc/Modem-operation --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Modem-operation Sun Oct 18 18:08:15 2020 +0000 @@ -0,0 +1,16 @@ +FC Tourmaline stdmodem functional configuration is equivalent to Magnetite +hybrid. The only intentional diff from Magnetite to Tourmaline in the modem +configuration is the change of Nucleus: Magnetite uses the blob version of +Nucleus which came with TCS211-20070608, whereas Tourmaline uses the source +version of Nucleus by Comrade XVilka. It is essentially a change from an +unknown version of Nucleus to a known one, thus it should generally be +considered an improvement - but as always with such changes, extensive +verification and testing needs to be done in order to ensure that nothing got +broken. + +Aside from the one intentional change of Nucleus version, FC Tourmaline is an +entirely new firmware source tree, thus it is always possible that something +could have got broken unintentionally, particularly in rarely-tested areas of +the firmware. Therefore, extensive testing will need to be done before we can +declare Tourmaline stdmodem as officially replacing Magnetite hybrid for stable +modem products. diff -r 4e178a0e90f6 -r a62e5bf88434 doc/Voice-pseudo-modem --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Voice-pseudo-modem Sun Oct 18 18:08:15 2020 +0000 @@ -0,0 +1,92 @@ +Back when TI's TCS211 fw existed in the traditional world of phone handset and +cellular modem manufacturers, there were only two principal classes of target +devices for it: handsets and modems. The former have local UI hardware (LCDs +and keypads) and run firmware that works with this UI hw, the latter have no +such hw and run firmware that expects to be controlled by an external host via +AT commands. + +But the peculiar circumstances under which our FreeCalypso family of projects +operates give rise to a third possibility: what happens if one were to run +non-UI-capable firmware that expects control via AT commands on a hardware +target device that was originally designed to be an end user phone handset, in +our case either Motorola C1xx or Pirelli DP-L10? The result is what I call a +voice pseudo-modem (VPM): the phone's LCD stays dark, the buttons do nothing +and the device expects to be controlled via AT commands as if it were a modem +like the one in GTA01/02 smartphones, but there is no practically usable way to +make use of any data services, only voice and SMS, hence my VPM term. + +It needs to be noted clearly that the VPM hack described in this article is NOT +a substitute for proper modem hardware - if your area of interest is Standard +Modem functionality (the full set of GSM and GPRS services accessed via AT +commands), then you need a proper hardware platform for it, either FCDEV3B or +Caramel2. However, support for VPM operation in FreeCalypso exists for the +following purposes: + +* On some hw targets the VPM configuration can be an intermediate stepping stone + toward potential future UI-enabled firmware - this situation holds on the + C139. + +* Being able to run FreeCalypso fw in the VPM configuration on Mot C1xx hw that + many people already have and that may still be readily and cheaply available + makes our firmware accessible to those who are not able to buy new FreeCalypso + hardware. + +* If you have a Pirelli DP-L10 phone (now very rare and hard to get, but were + readily available in early 2013 when I started FreeCalypso): while there is + unfortunately very little chance of being able to turn it into a practically + usable Libre Dumbphone with FreeCalypso (the unwanted extra chips sans docs + which we don't know how to power down are a killer), running FreeCalypso fw + on the Pirelli in the VPM configuration is so easy and convenient that I do + it all the time during development and testing. + +Playing with FreeCalypso VPM on C1xx phones +=========================================== + +If a Mot C1xx phone is flashed with a FreeCalypso firmware image in the VPM +configuration, it will behave as follows: + +* The LCD will remain dark and the buttons will do nothing no matter what. + +* If you plug in Motorola's charging adapter (it's a regulated 5 VDC power + source, but with a non-USB connector) and you had properly installed the + charging config file when creating the aftermarket FFS for FreeCalypso, the + battery will charge. When you unplug the charging adapter, if there is no + host computer running FC host program rvinterf connected to the phone + serially, the phone will power off some 15 to 20 s after the charger unplug. + +* If you press the power button while the phone is off, even momentarily, the + phone will power on and boot (with nothing on the LCD as usual), but if the + headset jack serial port is not connected to a computer running rvinterf, the + firmware will execute a power-off after at most 20 s. + +* In order to make the phone-turned-VPM do anything useful, you will need to + connect the headset jack serial port to a host computer running FC host tools, + run rvinterf to keep the phone alive (keep it from automatically powering + off), and use FC host utility fc-shell to issue AT commands to it over the + RVTMUX channel managed by rvinterf. + +* The phone will remain on (i.e., the fw won't execute an automatic power-off) + for as long as there is either a charging power adapter plugged in or a + connected host computer running rvinterf - if there is no charging power, + the fw will send periodic keepalive queries to check for the presence of a + connected rvinterf process. + +Playing with FreeCalypso VPM on a Pirelli DP-L10 +================================================ + +There are two ways in which one can play with FC VPM firmware on a Pirelli: + +* FC VPM fw can be flashed into the phone just like on Mot C1xx. To make this + approach sensible, you will also need to craft and install a charging config + file that will cause our FCHG driver to initiate the charging process + automatically when the battery voltage falls below some sensible threshold, + without requiring manual charging start via AT@CHG=1. In this case the + reflashed phone will behave like C1xx in the previous section, except that + the charging power source and the host computer connection are one and the + same in the case of Pirelli's USB. + +* The other approach is to keep Pirelli's original fw in the flash, let the + phone function normally when not in the middle of a FreeCalypso VPM session, + and load our FC VPM fw into RAM via fc-xram, making use of this phone's huge + RAM that can hold an entire functional fw image without flashing. This is + the Mother's preferred method.