# HG changeset patch # User Mychaela Falconia # Date 1580693131 0 # Node ID deda54106c0eb11ec7579f8c7e4cb76a1e84a13a # Parent d43dc6dfb44c4bbd70ea40cc989a4870bd20a6d3 doc/Target-boot-control: first draft diff -r d43dc6dfb44c -r deda54106c0e doc/Target-boot-control --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Target-boot-control Mon Feb 03 01:25:31 2020 +0000 @@ -0,0 +1,104 @@ +There is a new feature in loadtools (fc-loadtool & friends) and rvinterf as of +fc-host-tools-r12: target boot control. In a typical development environment +where FC host tools run on a general-purpose PC or laptop and communicate with +various Calypso targets via general-purpose serial or USB-serial ports, adapters +and cables, there is generally no way for the host computer running FC host +tools to directly command the Calypso target to power on and/or reboot - instead +such control must be performed "out of band" by the operator pressing the PWON +or RESET button on the target device; some targets may even require complex +battery manipulations. However, there may be more elaborate (less casual) +setups where FC host tools run on a special kind of host system which does have +some means to directly control power and reset to an associated Calypso target: + +* The Mother has a plan to produce a special FreeCalypso UART+JTAG Adapter, or + FC-UJA. This FC-UJA will be a special FT2232D adapter whose Channel A will + operate in MPSSE mode, connecting to the Calypso target's JTAG and nTESTRESET + signals, whereas Channel B will act as a standard UART, i.e., a ttyUSB device. + This FC-UJA needs to be built as a prerequisite before embarking on the + ambitious HSMBP (Handset Motherboard Prototype) project, as the special + adapter will be required for working with the HSMBP in development. When + FC-UJA becomes a reality, FC host tools running on a development host with + this adapter will need to be given the ability to issue nTESTRESET pulses to + the target through the adapter's MPSSE+GPIO channel; this nTESTRESET pulse + will cause the Calypso target to deep-reset, power on and boot. + +* FC host tools (particularly fc-loadtool) may run on the application processor + of a smartphone such as Openmoko GTA02. In such environments the AP will have + special ad hoc control signals (typically GPIOs) to the modem, at the minimum + controlling the modem's PWON line. OM GTA02 added an overriding control of + overall power to the modem; other designs may reasonably add control of the + modem's RESET line. + +* There may be special commercial applications in which one or more Calypso + modems are subservient to a control processor that acts similarly to the AP + of a smartphone, with that control processor not only communicating with its + slave modems via UARTs, but also controlling their power and reset. + +Where does the desire for target boot control in loadtools and rvinterf come +from? Consider the conventional usage model where no target boot control +exists: you first run fc-loadtool or fc-iram or fc-xram or rvinterf on your +target /dev/ttyXXX, then press the PWON or RESET button on the target. Now +suppose that the finger-actuated button has been replaced with some magic +command that can be executed on the host system to produce the same effect - +now what? If the usage model stays the same, then you have to first run your +fc-loadtool or fc-iram or fc-xram or rvinterf command same as before, then as +it sits there waiting for the target to boot, you have to open another terminal +window, get another ssh session into the system or whatever, and run the magic +command that replaces the manual button press. Very cumbersome, hence the +desire for a better way. + +Support for target boot control in FC host tools consists of a new -P option +implemented in all of loadtools programs and in rvinterf, as well as a special +configuration file which needs to be manually created. The working model is as +follows: + +* There exist one or more "magic commands": a magic command is any shell command + (anything that can be passed to /bin/sh -c) whose execution causes a connected + Calypso target device to power on and boot. Naturally these commands will be + very specific to your custom system; they are NOT part of FC host tools! + +* These magic commands may be long, and requiring the user to include each magic + command in full on fc-loadtool, rvinterf etc invokation lines is undesirable. + To save typing, we associate a short name (which you choose yourself as you + see fit) with each magic command, and we have a configuration file (which you + need to create) that defines the mapping. + +* The argument to the new -P option is the short name to be looked up in the + configuration file. + +The configuration file needs to be created in /opt/freecalypso/bootctrl.conf; +let us illustrate it with some examples. + +Example 1: FC-UJA +================= + +When FC-UJA becomes a reality, there will be a program called fc-testreset that +will locate the attached FC-UJA by its USB ID, connect to FT2232D Channel A and +generate the desired reset pulse on its output. The configuration in +/opt/freecalypso/bootctrl.conf may look as follows: + +uja fc-testreset + +This configuration associates boot control name 'uja' with shell command +fc-testreset. A developer would then run fc-loadtool like this: + +fc-loadtool -h fcfam -Puja /dev/ttyUSB0 + +if ttyUSB0 is where FC-UJA's UART channel ended up. fc-loadtool would run +normally, sending beacons to /dev/ttyUSB0 and waiting for a Calypso boot ROM +response, but it would also execute the fc-testreset command listed in the +configuration file, and if everything is connected correctly, the resulting +nTESTRESET pulse will cause the target to boot. + +The possibility of a single host talking to multiple Calypso targets is fully +supported: if you have multiple FC-UJA adapters with different USB descriptor +serial numbers programmed in their EEPROMs connected to respective Calypso +targets, you could have a /opt/freecalypso/bootctrl.conf setup like this: + +uja1 fc-testreset -d serial1 +uja2 fc-testreset -d serial2 + +and then run fc-loadtool accordingly: + +fc-loadtool -h fcfam -Puja1 /dev/ttyUSB3 +fc-loadtool -h fcfam -Puja2 /dev/ttyUSB4