FreeCalypso > hg > freecalypso-tools

annotate doc/Target-boot-control @ 582:deda54106c0e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Target-boot-control: first draft
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 03 Feb 2020 01:25:31 +0000
parents
children d3e2b23ebf1d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
582
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 There is a new feature in loadtools (fc-loadtool & friends) and rvinterf as of
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 fc-host-tools-r12: target boot control. In a typical development environment
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 where FC host tools run on a general-purpose PC or laptop and communicate with
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 various Calypso targets via general-purpose serial or USB-serial ports, adapters
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 and cables, there is generally no way for the host computer running FC host
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 tools to directly command the Calypso target to power on and/or reboot - instead
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 such control must be performed "out of band" by the operator pressing the PWON
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 or RESET button on the target device; some targets may even require complex
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 battery manipulations. However, there may be more elaborate (less casual)
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 setups where FC host tools run on a special kind of host system which does have
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 some means to directly control power and reset to an associated Calypso target:
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 * The Mother has a plan to produce a special FreeCalypso UART+JTAG Adapter, or
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 FC-UJA. This FC-UJA will be a special FT2232D adapter whose Channel A will
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 operate in MPSSE mode, connecting to the Calypso target's JTAG and nTESTRESET
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 signals, whereas Channel B will act as a standard UART, i.e., a ttyUSB device.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 This FC-UJA needs to be built as a prerequisite before embarking on the
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 ambitious HSMBP (Handset Motherboard Prototype) project, as the special
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 adapter will be required for working with the HSMBP in development. When
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 FC-UJA becomes a reality, FC host tools running on a development host with
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 this adapter will need to be given the ability to issue nTESTRESET pulses to
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 the target through the adapter's MPSSE+GPIO channel; this nTESTRESET pulse
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 will cause the Calypso target to deep-reset, power on and boot.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 * FC host tools (particularly fc-loadtool) may run on the application processor
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 of a smartphone such as Openmoko GTA02. In such environments the AP will have
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 special ad hoc control signals (typically GPIOs) to the modem, at the minimum
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 controlling the modem's PWON line. OM GTA02 added an overriding control of
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 overall power to the modem; other designs may reasonably add control of the
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 modem's RESET line.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 * There may be special commercial applications in which one or more Calypso
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 modems are subservient to a control processor that acts similarly to the AP
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 of a smartphone, with that control processor not only communicating with its
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 slave modems via UARTs, but also controlling their power and reset.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 Where does the desire for target boot control in loadtools and rvinterf come
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 from? Consider the conventional usage model where no target boot control
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 exists: you first run fc-loadtool or fc-iram or fc-xram or rvinterf on your
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 target /dev/ttyXXX, then press the PWON or RESET button on the target. Now
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 suppose that the finger-actuated button has been replaced with some magic
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 command that can be executed on the host system to produce the same effect -
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 now what? If the usage model stays the same, then you have to first run your
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 fc-loadtool or fc-iram or fc-xram or rvinterf command same as before, then as
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 it sits there waiting for the target to boot, you have to open another terminal
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 window, get another ssh session into the system or whatever, and run the magic
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 command that replaces the manual button press. Very cumbersome, hence the
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 desire for a better way.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 Support for target boot control in FC host tools consists of a new -P option
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 implemented in all of loadtools programs and in rvinterf, as well as a special
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 configuration file which needs to be manually created. The working model is as
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 follows:
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 * There exist one or more "magic commands": a magic command is any shell command
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 (anything that can be passed to /bin/sh -c) whose execution causes a connected
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 Calypso target device to power on and boot. Naturally these commands will be
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 very specific to your custom system; they are NOT part of FC host tools!
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 * These magic commands may be long, and requiring the user to include each magic
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 command in full on fc-loadtool, rvinterf etc invokation lines is undesirable.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 To save typing, we associate a short name (which you choose yourself as you
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 see fit) with each magic command, and we have a configuration file (which you
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 need to create) that defines the mapping.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 * The argument to the new -P option is the short name to be looked up in the
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 configuration file.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 The configuration file needs to be created in /opt/freecalypso/bootctrl.conf;
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 let us illustrate it with some examples.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 Example 1: FC-UJA
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 =================
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 When FC-UJA becomes a reality, there will be a program called fc-testreset that
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 will locate the attached FC-UJA by its USB ID, connect to FT2232D Channel A and
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 generate the desired reset pulse on its output. The configuration in
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 /opt/freecalypso/bootctrl.conf may look as follows:
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 uja fc-testreset
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 This configuration associates boot control name 'uja' with shell command
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 fc-testreset. A developer would then run fc-loadtool like this:
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 fc-loadtool -h fcfam -Puja /dev/ttyUSB0
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 if ttyUSB0 is where FC-UJA's UART channel ended up. fc-loadtool would run
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 normally, sending beacons to /dev/ttyUSB0 and waiting for a Calypso boot ROM
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 response, but it would also execute the fc-testreset command listed in the
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 configuration file, and if everything is connected correctly, the resulting
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 nTESTRESET pulse will cause the target to boot.
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 The possibility of a single host talking to multiple Calypso targets is fully
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 supported: if you have multiple FC-UJA adapters with different USB descriptor
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 serial numbers programmed in their EEPROMs connected to respective Calypso
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 targets, you could have a /opt/freecalypso/bootctrl.conf setup like this:
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 uja1 fc-testreset -d serial1
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 uja2 fc-testreset -d serial2
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 and then run fc-loadtool accordingly:
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 fc-loadtool -h fcfam -Puja1 /dev/ttyUSB3
deda54106c0e doc/Target-boot-control: first draft
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 fc-loadtool -h fcfam -Puja2 /dev/ttyUSB4