FreeCalypso > hg > freecalypso-tools
view doc/Target-utils @ 669:ba9523ca6ed8
fc-loadtool code: preparations for e-program-* addition
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 08 Mar 2020 01:32:08 +0000 |
parents | bdaa4e7c9c05 |
children | ff3d8167fa94 |
line wrap: on
line source
FreeCalypso target-utils suite ============================== We have a suite of standalone programs and specialized code pieces that run on the Calypso ARM7 processor, but are not regular operational phone or modem firmware; this suite of code bits is called target-utils, maintained and distributed together with FreeCalypso host tools. The primary reason for the coupling between FC host tools and target-utils is that the target-utils suite provides the loadagent target program for fc-loadtool and fc-xram host tools, as well as compalstage code pieces needed for operating on Compal phones. Most programs in the target-utils suite are meant to execute out of RAM (specifically, the Calypso chip's internal RAM or IRAM for short), loaded and run via fc-iram or fc-compalram - they are not meant to be flashed. As of this writing, the following run-from-RAM programs are available: buzplayer Player for buzzer melodies, used by fc-buzplay c139explore Mot C139 hardware exploration program calversion Calypso version ID tool, primarily for the DSP ROM version dspdump Calypso DSP ROM dump tool helloapp Hello-world program loadagent Flash manipulation and XRAM loading agent pirexplore Pirelli DP-L10 hardware exploration program simtest Low-level exerciser for the SIM interface hardware Aside from c139explore which is built as a binary to be loaded via fc-compalram (Compal's bootloader protocol), all of the above programs are built as S-record images to be loaded via fc-iram. Once loaded via the respective serial code download protocol, each of the listed programs runs interactively, listening for and executing commands given over the serial port. The specific set of available commands is different for each program as relevant to its function, but the command framework is common across the target-utils suite. The command interface is text-based, such that each program can be driven manually by a human operator once fc-iram or fc-compalram has dropped into the tty pass-thru mode, but this same text-based command interface can also be driven by other programs: fc-loadtool and fc-xram drive loadagent, and fc-buzplay drives buzplayer. Code architecture and execution environment =========================================== Our target-utils suite is built with the GNU toolchain (gcc+binutils), not TI's proprietary TMS470 compiler. Because all of target-utils are meant to run out of IRAM rather than flash or XRAM, we compile all code in ARM mode (not Thumb), and we build without interworking support (no -mthumb-interwork): the ARMv4T architecture implemented by the ARM7TDMI core in the Calypso does not support penalty-free ARM/Thumb interworking, thus ARM-only code without interworking support is the most efficient option for execution out of IRAM. Selection of UART for communication =================================== All target-utils programs are interactive, listening for text commands given over a serial port. But which UART? The Calypso chip has two UARTs, called MODEM and IrDA in the chip docs - which of the two should be used for host communication? The answer is a trick original to FreeCalypso: most of our target-utils programs that are meant to be loaded via fc-iram expect to be loaded specifically via the Calypso boot ROM and not in some other way, and they look at some of the IRAM variables left behind by the boot ROM code. The boot ROM listens on both UARTs for an interrupt-boot sequence, and once it receives that sequence on one of the UARTs, it remembers which UART it was and uses that same UART for the rest of the serial code download protocol. We read that same variable set by the boot ROM, which depends on the boot ROM version. To handle different Calypso boot ROM versions, we read the 16-bit word at 0x1FFE (the last 16 bits of the boot ROM image) where TI put the boot ROM version number, and we support boot ROM versions 0200 (Calypso C05 rev B silicon) and 0300 (Calypso C035 silicon). Most target-utils programs won't work (will fail to select the UART for communication) if the boot ROM is some unsupported version or missing altogether, or if the boot ROM is there, but didn't do the loading. The exceptions are as follows: * c139explore always uses the MODEM UART as appropriate for Mot C139; * flash-boot-test (a flashable program described later in this article) always uses the IrDA UART; * helloapp is built in 3 versions: helloapp-bootrom.srec, helloapp-irda.srec and helloapp-modem.srec. The first version depends on the boot ROM like other programs, the other two versions are built as fixed-IrDA or fixed-MODEM. Other boot ROM and fc-iram dependencies ======================================= There are two other ways in which target-utils programs that are meant to be loaded via fc-iram depend on the Calypso boot ROM: 1) The Calypso gets its clock input from the RF section of the GSM device, and the RF block can feed either 13 MHz or 26 MHz to the Calypso - some GSM RF transceiver chips require 13 MHz (TI Clara), others require 26 MHz (TI Rita and Silabs Aero II), yet others can work with either clock (Silabs Aero+), and some use a 26 MHz crystal but have the option of feeding either 13 or 26 MHz to the Calypso (Aero II). The Calypso initially boots without knowing what clock frequency it is running at, but then it needs to be told via a register setting what the input clock frequency is, so that all peripherals (both GSM-specific and general-purpose) always run at 13 MHz. When the Calypso boot process is interrupted and diverted to serial code download in the boot ROM, the boot ROM code autodetects whether the CLKTCXO input runs at 13 MHz or 26 MHz (it tries both register bit settings until the serial '<' characters sent by the host at 19200 baud are received correctly), and if the CLKTCXO input is 26 MHz, the VCLKOUT_DIV2 bit is set in the FFFF:FD02 register. Most of our target-utils programs have no hard- coded knowledge of the 13 MHz vs. 26 MHz board hardware configuration and rely on the Calypso boot ROM to set the division control bits in the FFFF:FD02 register correctly for the autodetected clock. 2) The boot ROM allows the serial download host (fc-iram in our case) to configure the Calypso DPLL, allowing the ARM7 core to run at its maximum frequency of 52 MHz on Calypso C035 or 39 MHz on the older Calypso C05 silicon. None of our target-utils programs do their own DPLL setup, instead they run with whatever they were booted with - therefore, in order for the IRAM programs to run at their intended fastest speed, the correct -h option needs to be given to fc-iram, selecting a hardware parameter file with the right pll-config setting. Delay loop timing ================= There are a few places in target-utils where a delay of some specific duration needs to be inserted. In most cases the requirement is for a certain minimum delay, with more delay time being harmless except for inefficiency, but there is one case (SPCA552E chip initialization in pirexplore) where the delay requirement is strict: if the delays are too short or too long, the LCD doesn't work. In target-utils all of these delays are implemented with CPU-cycle-count delay loops that are calibrated at software design time; if the code runs out of IRAM and the ARM7 core runs at 52 MHz, the delays will be exactly as designed, otherwise they will be longer. In the case of pirexplore the strict timing requirement is satisfied by loading and running the program via fc-iram -h pirelli, resulting in the correct 52 MHz clock configuration; in all other cases running at a frequency below 52 MHz or running out of flash (the flash-boot-test special case) produces longer-than-needed delays. Common interactive commands =========================== The exact set of implemented commands is different for each target-utils program, including commands specific to each program's unique function, but the following basic commands are included in most programs: abbinit Initialize ABB communication abbpage2 Unlock access to ABB register page 2 abbr pg reg Read ABB register <reg> on page <pg> abbw pg reg val Write <val> into register <reg> on page <pg> dump hex-start hex-len Display a human-oriented memory dump in hex and ASCII jump addr Jump to given address with BX poweroff Execute Iota ABB soft poweroff (DEVOFF) r8 addr Read an 8-bit register or memory location r16 addr Read a 16-bit register or memory location r32 addr Read a 32-bit register or memory location w8 addr data Write an 8-bit register or memory location w16 addr data Write a 16-bit register or memory location w32 addr data Write a 32-bit register or memory location For further details, please refer to the source code - if you are playing with such low-level components, you need to put on the hat of a developer rather than a mere user. ABB support in target-utils =========================== Our target-utils suite includes code for initializing and executing SPI communication with the Iota ABB device (TWL3014 or TWL3025), Calypso's analog and power management companion chip. Only Iota ABB type is supported, not Omega/Nausica or Syren. The primary reason for having this infrastructure is to be able to perform a soft poweroff operation, i.e., to return the Calypso phone or modem to its switched-off state after flashing or various standalone debug operations, but once implemented, this same ABB SPI communication infrastructure is also used in model-specific hardware exploration utilities for functions like keypad backlight and vibrator control which are implemented via the ABB on some models, and it is used in simtest to control the part of the SIM interface that resides in the Iota ABB. Aside from specialized programs like c139explore that are specific to target devices known to use the Iota ABB, most target-utils programs do not execute any ABB or SPI communication code (not even initialization) until they receive one of the ABB commands: abbinit, abbr, abbw or poweroff. This way if someone comes across a Calypso device that has a different ABB type or needs to debug a board with broken ABB communication, one can explore other functions without touching ABB commands. (simtest is another exception: even though it is not specific to one particular target device like c139explore, its main function of exercising the SIM interface depends on the Iota ABB, thus it is restricted to Calypso+Iota targets.) The abb_init() function invoked by the abbinit command may be invoked multiple times: it maintains an internal flag remembering if the initialization steps have already been done or not, and repeated invokations do nothing. User- friendly abbr, abbw and poweroff commands invoke abb_init() internally, but the special abbpage2 command does not - if you are interested in exploring the undocumented register page 2, you need to execute abbinit manually first, then abbpage2, then explore with abbr and abbw. poweroff operation details: VRPCAUX and VRPCDEV =============================================== The abb_power_off() function invoked by the poweroff command performs the following sequence of steps: * Calls abb_init() to establish ABB communication in the case that it hasn't already been done; * Executes the magic writes to TAPCTRL and TAPREG registers that unlock access to register page 2 - this step is factored out into the abb_unlock_page2() function which is also accessible as the abbpage2 command; * Writes 0x007 into the undocumented VRPCAUX register to clear the erratic state that will be there if we got booted via nTESTRESET rather than PWON; * Flushes all UART output, i.e., waits for it to finish going out on the wire; * Writes 0x001 into the VRPCDEV register, which is the actual DEVOFF command. The step of writing into VRPCAUX and its prerequisite page 2 unlock steps are a recent addition as of fc-host-tools-r11; these steps have been added to fix the erratic behaviour that was occurring on TI/FC development boards (D-Sample and FCDEV3B) when fc-loadtool (or fc-iram with some specialized target-utils program) was entered via the RESET button rather than PWON, followed by the soft poweroff operation and another switch-on via PWON. For more details, please refer to the Calypso-test-reset article in the freecalypso-docs repository. If you are interested in doing some experiments of your own with this undocumented quirk of the Calypso+Iota chipset and the odd behaviour it can cause, you can do the following: * To see the content of the undocumented VRPCAUX register resulting from different boot modes, execute these commands: abbinit abbpage2 abbr 2 30 Our abbr and abbw commands support page 2, but if you don't issue the magic register writes encapsulated in the abbpage2 command, the Iota chip itself disallows access to page 2. * To perform a DEVOFF operation without cleaning up VRPCAUX first (to see the resulting erratic behaviour with your own eyes), do it manually as follows: abbw 0 30 1 flash-boot-test =============== In addition to the repertoire of run-from-IRAM (loadable via fc-iram) programs that form the main course of target-utils, we have a flashable program called flash-boot-test - it will be called FBT for short in this article. FBT is a test case for the "main application" in flash, and it can be flashed in the place of a regular firmware image for certain very low-level tests. Because it runs via the flash boot path and does not get loaded serially, FBT is quite hardware-specific by necessity: it assumes a platform with 26 MHz Calypso clock input and always uses the IrDA UART for communication (hard-coded). FBT was written with FCDEV3B and Openmoko GTA02 boards in mind; it won't work on a D-Sample board because of the 13 MHz vs. 26 MHz clock difference. FBT is built in two versions: fbt-mode0.bin and fbt-mode1.bin, differing in the magic words at location 0x2000 which tell the Calypso boot ROM how the main application in flash should be booted - please refer to the Flash-boot-modes article in the freecalypso-docs repository. Only the magic words differ between fbt-mode0.bin and fbt-mode1.bin versions; the main body of the code is exactly the same. Once it receives control from the boot ROM in whichever mode it was booted in, FBT's own code in main.c does the absolute minimum initialization to allow serial communication (sets the VCLKOUT_DIV2 bit in the FFFF:FD02 register and initializes the IrDA UART) and falls into the same interactive mode of operation (listening for text-based commands) as our various run-from-IRAM programs, allowing the operator to explore system state as closely out of boot as possible. When a main application in flash is booted in mode 1 (with the boot ROM moved out of the way), the Calypso watchdog timer is running, and our FBT program does not a perform a watchdog disable step on its own. Therefore, if you flash fbt-mode1.bin and boot it, you will see it keep endlessly rebooting about every 9 s. To stop this endless reboot cycle, issue a wd (watchdog disable) command: it is short enough to be easily typed in the available 9 s window. The same issue does not occur in flash boot mode 0, as the Calypso boot ROM does disable the watchdog and leaves it disabled when booting mode 0 flash images or serially downloaded code. FBT also has a few other commands that have been added to facilitate further experimentation with the watchdog timer feature of the Calypso chip - please refer to the source code.