# HG changeset patch # User Mychaela Falconia # Date 1600238971 0 # Node ID f19d12f5756f7df6273687949bf098156366d329 # Parent 6d97866bad79a525adf9641402ed7b99544f55a1 doc/Target-boot-control: updated for DUART28C diff -r 6d97866bad79 -r f19d12f5756f doc/Target-boot-control --- a/doc/Target-boot-control Wed Sep 16 06:10:39 2020 +0000 +++ b/doc/Target-boot-control Wed Sep 16 06:49:31 2020 +0000 @@ -1,26 +1,34 @@ 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: +fc-host-tools-r12, actually functional as of fc-host-tools-r14: 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. +* Our new FreeCalypso DUART28 adapter available as of 2020-09 has an optional + provision (requires additional wire connections and a custom patch to Linux + kernel ftdi_sio driver) for controlling Calypso target board PWON and RESET + with otherwise unused secondary channel RTS and DTR outputs - see the new + DUART28-boot-control article for the details. + +* The Mother has a plan to produce another custom FT2232D-based adapter called + FC-UJA, standing for FreeCalypso UART+JTAG Adapter. 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 @@ -49,13 +57,20 @@ 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: +configuration file which needs to be manually created if external boot control +commands are to be used. There are two target boot control models, built-in +and external: -* 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! +* Built-in target boot control integrated into FC host tools themselves is + currently available only for the DTR/RTS pulsing method implemented on our + DUART28 adapter: -Pdtr means pulse DTR and -Prts means pulse RTS. Please + refer to the DUART28-boot-control article for the details. + +* In the other case of external boot control commands, 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. @@ -64,7 +79,8 @@ 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. + configuration file. (Built-in boot control names 'dtr' and 'rts' are reserved + and cannot be used for external boot control commands.) The configuration file needs to be created in /opt/freecalypso/bootctrl.conf; let us illustrate it with some examples.