FreeCalypso > hg > freecalypso-tools
view doc/Loadtools-usage @ 438:2ba7512efae5
CHANGES: Mot C155 flashing fix documented
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Tue, 06 Nov 2018 16:48:51 +0000 |
parents | 30f6d1c32c6f |
children | 131eefcbe4d7 |
line wrap: on
line source
The loadtools subset of FreeCalypso host tools consists of: fc-loadtool The tool for operating on Calypso GSM devices at a low level. After "breaking" into the target GSM device in its boot process and getting FreeCalypso loadagent running on the target (out of Calypso internal RAM, aka IRAM), loadtool presents an interactive command prompt with commands for peeking and poking registers and most importantly, reading and writing any part of the device's non-volatile flash memory. fc-iram & fc-xram These utilities are intended for FreeCalypso developers only. They load an S-record code image into IRAM or XRAM, respectively, induce a transfer of control to the loaded code, and then drop into a serial line pass-thru mode for the operator to interact with the thus loaded target code. The currently supported target devices are (in the order of decreasing preference) official Calypso development boards (TI's D-Sample and our own FCDEV3B), Openmoko's GTA0x GSM modem, and two "alien" Calypso phone families: Mot C1xx by Compal and Pirelli DP-L10 by Foxconn. All tools in the FreeCalypso loadtools suite work by feeding pieces of code to the target device as it boots, preventing the booting of its regular firmware and diverting control to these externally-loaded code pieces. These pieces of ARM7 target code need to be installed on the host system running loadtools, normally in /opt/freecalypso/target-bin: loadagent This is the "agent" code that runs on the target device when fc-loadtool is operating on it: loadtool carries out its operations by sending commands to loadagent. There is only one version of loadagent for all currently supported Calypso targets: loadagent does not access any resources outside of the Calypso chip itself unless commanded to do so, and loadtool supports different target devices with different hardware configurations by sending different commands to loadagent as appropriate. compalstage For Compal phones only: a little piece of code that is fed to the original fw's bootloader via the serial download protocol provided by the latter; it re-enables the Calypso chip boot ROM and jumps to it, allowing our loadagent to be loaded in the same way as on freedom-enabled devices. If you are working with a development snapshot of the freecalypso-tools source tree, you will need to compile and install a GNU cross-compiler toolchain targeting ARM7 (see ../toolchain) and then use that toolchain to compile loadagent and compalstage (see ../target-utils) before you can successfully use loadtools to operate on a target device. End-user oriented releases of FreeCalypso host tools include prebuilt loadagent and compalstage binaries. Basic usage =========== The steps for bringing up fc-loadtool to operate on a target Calypso device are as follows: 1. If you are using a USB serial adapter, or operating on a Pirelli phone that has one built in, connect the USB side first so that the necessary /dev/ttyUSB* device node appears. If you are working with a target such as FCDEV3B or D-Sample on which both Calypso UARTs are equally accessible with equal convenience, you can arbitrarily pick either one for fc-loadtool - it will work exactly the same through either port. 2. Run fc-loadtool like this: fc-loadtool $TARGETOPT /dev/ttyXXX Change /dev/ttyXXX to the actual serial port you are using, and change $TARGETOPT to: Device Needed options ----------------------------------- FreeCalypso FCDEV3B -h fcfam Mot C11x/123 -h compal Mot C139/140 -h compal -c 1004 Mot C155/156 -h c155 Openmoko GTA02 -h gta02 Pirelli DP-L10 -h pirelli TI D-Sample -h dsample 3. Cause the target device to execute its boot path. TI/Openmoko/FreeCalypso and Pirelli targets have the Calypso boot ROM enabled, and will interrupt and divert their normal boot path when they "hear" the beacons which fc-loadtool will be sending down the serial line. Compal phones have this boot ROM disabled at the board level, but their standard firmware includes a flash-resident bootloader that offers a different way of interrupting the boot path and loading code over the serial line; fc-loadtool will be set up to speak the latter protocol when run with the corresponding options from the table above. You will see messages showing fc-loadtool's progress with feeding first compalstage (if needed), then loadagent (always needed) to the target device, followed by some target-specific initialization done via loadagent commands. If all of the above succeeds, you will land at a loadtool> prompt. Type 'help', and it will guide you from there. Alternatively, you can familiarize yourself with loadtool commands and operations without actually running it by reading the loadtool.help text file. fc-loadtool batch mode ====================== In addition to the interactive mode described above, fc-loadtool can be used in a scripted or batch mode where it makes contact with the target device as it boots, interrupts and diverts the boot process to loadagent, executes a given command script, cleans up the target state as appropriate (usually powers off) and exits. This mode is used by the FreeCalypso factory for initial flash programming on the device production line, but it can also be used by end users to install firmware updates in a more automated manner. The batch mode is entered when there is a command script given on the fc-loadtool invokation command line. Command line options ==================== The fc-loadtool command lines shown above will usually be sufficient. However, here is the complete command line description for all 3 tools: fc-iram [options] ttyport iramimage.srec [2ndprog] fc-xram [options] ttyport xramimage.srec [2ndprog] fc-loadtool [options] ttyport [batch-script] The available options are common for all 3 utilities, with a few noted exceptions: -a /path/to/loadagent This option applies only to fc-loadtool and fc-xram. It specifies the pathname at which the required loadagent.srec image should be sought, overriding the compiled-in default. -b baud This option is common for all 3 utilities. It selects the baud rate to be used when pushing the IRAM image to the Calypso boot ROM. In the case of fc-iram, the selected baud rate will be in effect when the loaded IRAM image is jumped to and fc-iram drops into the serial tty pass-thru mode; in the case of fc-loadtool, it will be the initial baud rate for communicating with loadagent, which can be switched later with the baud command. The default is 115200 baud. -B baud (fc-loadtool) This option is specific to the batch mode of fc-loadtool, and has no effect when no batch mode command script is specified on the command line. In the batch mode this option commands a baud rate switch to be performed before the command script is executed. -B baud (fc-xram) This option is specific to fc-xram. It selects the baud rate to be used when pushing the XRAM image to loadagent. If no -B option is specified, fc-xram will communicate with loadagent at the same baud rate that was used to load loadagent itself via the Calypso boot ROM download protocol, i.e., the rate selected with -b, defaulting to 115200 baud if no -b option was given either. Neither -b nor -B affects the baud rate that will be in effect when the loaded XRAM image is jumped to and fc-xram drops into the serial tty pass-thru mode: that baud rate independently defaults to 115200 baud and can only be changed with the -r option. -c <compalstage flavor> This option is common for all 3 utilities. It directs the tools to perform the Compal loading stage before proceeding with the Calypso boot ROM serial protocol, and selects the "flavor" of compalstage to use. As you can see in the source, compalstage is built in 3 different versions, for different C1xx models which exhibit different quirks. This option overrides the compal-stage setting given in the hardware parameter file selected with -h or -H; the -c or -C option must be given after -h or -H in order to take effect. -c none disables the Compal stage and causes the tools to proceed directly to the Calypso boot ROM phase, even on targets for which the hardware parameter file specifies compal-stage. -C /path/to/compalstage-binary This option is just like -c, except that the given argument is used directly as the compalstage binary file pathname (absolute or relative) without checking or alteration. -h hwtype This option is common for all 3 utilities. It selects the specific target device configuration to be used. More precisely, it constructs a pathname of the form /opt/freecalypso/loadtools/%s.config, where %s is the argument given to this option, and uses that file as the hardware parameter file. The hardware configurations known to the present release of FreeCalypso loadtools are listed in the "Basic usage" section above. -H /path/to/hwparam-file This option is just like -h, except that the given argument is used directly as the hardware parameter file pathname (absolute or relative) without alteration. -i num This option is common for all 3 utilities. It specifies the interval in milliseconds at which the tool will send "please interrupt the boot process" beacons out the serial port, hoping to catch the Calypso internal boot ROM. The default is 13 ms. -n This option does anything only when loadtools have been compiled to run on GTA0x AP (see the Loadtools-on-GTA0x article). If you've compiled loadtools with the -DGTA0x_AP_BUILD option, it has an effect of making each tool automatically toggle the modem power control upon startup, removing the need for manual sequencing of the Calypso boot process. This -n option suppresses that action, making the AP build behave like the standard build in this regard. -r baud (fc-loadtool) This option is specific to fc-loadtool. It causes the tool to skip its normal steps of feeding loadagent and possibly compalstage to the target via special serial protocols, and instead assume that the target is already running loadagent, communicating at the specified baud rate. In other words, reattach to an already running loadagent. Use this option if your fc-loadtool session has been terminated ungracefully and you would like to reattach and resume, rather than forcibly reset the target by yanking and reinserting the battery and restart from the beginning. -r baud (fc-xram) This option is specific to fc-xram. It selects the serial line baud rate which should be set just before the loaded XRAM image is jumped to; the default is 115200 baud. fc-iram & fc-xram 2nd program invokation ======================================== Our fc-iram and fc-xram utilities can take two possible actions after they have loaded the specified S-record image into RAM: * The default action, in the absence of additional command line arguments, is to drop into a serial tty pass-thru mode. * The alternative action is to invoke a 2nd program and pass the serial communication channel to it. This 2nd program invokation facility is intended primarily for passing the serial communication channel to rvinterf or rvtdump from the FreeCalypso host tools suite, not for launching any arbitrary 3rd-party programs from fc-xram or fc-iram. This feature was originally implemented in fc-xram only, and the intended usage scenario is that one builds a version of one of our FreeCalypso GSM firmwares (or some subset thereof, such as an "in vivo" FFS editing agent) in the ramImage configuration, fc-xram is used to load that ramImage into the target device, and then the serial communication channel (RVTMUX) is immediately taken over by rvinterf or rvtdump. This second program invokation capability was later extended to fc-iram for no purpose other than to facilitate a boot hack that was only needed on one (1) defective FCDEV3B board.