--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Pirelli-loadtools-entry	Wed Jun 07 23:52:09 2023 +0000
@@ -0,0 +1,68 @@
+Pirelli DP-L10 phone is a quirky Calypso target in that the same hardware
+interface (USB) that provides access to the one easily accessible Calypso UART
+also feeds charging power to the phone.  The result of this arrangement is that
+whenever you connect your phone to your computer for communication, programming
+or tinkering, the charging voltage is always present and the Calypso+Iota
+chipset never enters switched-off state: every "soft poweroff" operation is
+converted by the hardware into a deep reboot.
+
+You can force a "cold programming boot" cycle on your Pirelli phone by removing
+the battery, connecting USB to the "debattered" phone, running fc-loadtool on
+the ttyUSB device that appears, and then inserting the battery in one swift
+motion - this sequence will be necessary if you brick your flash and need to
+unbrick it - but of course it is hugely inconvenient for ordinary FreeCalypso
+tinkering (such as running FreeCalypso VPM firmware builds via fc-xram), and
+doing it too often will ruin battery spring contacts.  The other alternative is
+to let Pirelli's official fw boot fully (including GSM network registration) in
+between cycles of fc-loadtool or fc-xram, and then do the switch-off operation
+from the UI (press and hold red button on unlocked home screen) with fc-loadtool
+or fc-xram running.  But this option is also unattractive, as it involves
+unwanted SIM bring-up and GSM network registration from Pirelli's fw.
+
+As of fc-host-tools-r19 we have an improved solution in the form of -Petmoff
+option to fc-loadtool, fc-xram, fc-simint etc.  The usage scenario is as
+follows:
+
+* The phone needs to be in its "booted for charging only" state.  With Pirelli's
+  official fw, this state is entered when you connect USB to a switched-off
+  phone, or when you execute the switch-off sequence from the UI with USB
+  connected.
+
+* In this state, you issue a command like the following:
+
+fc-loadtool -h pirelli -Petmoff /dev/ttyUSB0
+
+or
+
+fc-simint -h pirelli -Petmoff /dev/ttyUSB0
+
+or
+
+fc-xram -h pirelli -Petmoff /dev/ttyUSB0 ramimage.srec rvinterf
+
+etc
+
+This -Petmoff option (implemented as part of our generic boot control framework,
+see Target-boot-control article) tells loadtools programs to send an ETM ABB
+write (abbw) command to the target serial port, issuing a DEVOFF write to the
+VRPCDEV register, just before going into the loop that sends beacons aiming to
+interrupt the boot process at the Calypso boot ROM.  This trick works because
+Pirelli's official fw implements a TI-standard RVTMUX interface on the Calypso
+IrDA UART behind USB, complete with ETM, and with USB applying VCHG to Iota
+VRPC, the DEVOFF operation (soft poweroff) turns into a deep reboot.
+
+Running loadtools programs with -Petmoff against a Pirelli phone that is fully
+booted, as opposed to "booted for charging only" state, is possible but not
+recommended: it will forcibly kill the running firmware without any kind of
+clean shutdown.  Strictly speaking, this option always effects the just-
+described forced firmware kill, no matter which state the official fw happens
+to be in, but if the fw is in its "booted for charging only" state, then there
+are no ill effects to be concerned with.
+
+When fc-loadtool or fc-simint/fc-simtool finishes with a clean exit, or when a
+RAM-based firmware session started with fc-xram is cleanly finished with
+fc-shell poweroff, the phone returns to the same "booted for charging only"
+state.  Therefore, multiple operations of fc-loadtool, fc-simtool or fc-xram,
+each with -Petmoff option, may be performed back to back, just like how a
+FreeCalypso developer using a proper FC dev board would run back-to-back
+sessions starting with -Pdtr or -Prts and ending with Iota poweroff.