--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/venus/doc/USB-and-mobile-domains	Fri Nov 26 23:02:19 2021 +0000
@@ -0,0 +1,303 @@
+1. Introduction
+
+FC Venus board will consist of two principal circuit domains: the mobile domain
+corresponding to a battery-powered mobile phone and a USB computer interface
+block which becomes the USB domain.  The USB domain will be based around FT2232D
+USB to dual UART chip, it will be strictly bus-powered (never taking any power
+from the battery), and its sole purpose is to provide a host computer interface
+to the mobile, i.e., make the two Calypso UARTs accessible via USB.  The USB
+domain will get powered only when a host computer (or a USB charger) is
+connected, and will be totally unpowered at all other times, i.e., when the
+board is untethered and runs on battery power like a true mobile phone.
+
+At the top level of circuit hierarchy (see src/top/board.v), our board consists
+of the two principal domains (mobile and USB) interconnected with just a few
+wires: common ground, the set of UART signals going between the two domains, a
+charging power supply rail (user-switched, so charging won't always happen when
+a USB host is connected) and a couple of boot control signals.
+
+2. UART signals between domains
+
+The connection of UART interface signals between USB and mobile domains is
+arguably the most challenging and the most complicated part of our entire
+built-in USB-serial arrangement.  The challenges and the circuit complexity
+which we came up with in response to these challenges stem from the need to
+avoid bad things happening in partial power-down scenarios.  Most of the
+background information is provided in section 1.12.2 of our FreeCalypso Handset
+Specification (FC-handset-spec in freecalypso-docs), and this document provides
+further details that were elucidated only in the process of capturing the actual
+circuit design for FC Venus.
+
+2.1. Set of signals
+
+The set of UART interface signals implemented on FC Venus will be the same as
+listed in FC Handset Specification section 1.12.1.  We have a total of 5 signals
+running from Calypso outputs to FT2232D, and a total of 4 signals running from
+FT2232D to Calypso inputs.
+
+2.2. Buffer ICs
+
+Two Nexperia LVC family buffer ICs will be used on FC Venus for the purpose of
+ferrying our set of UART interface signals between the two domains.  These two
+ICs are U401 (74LVC125A) in the mobile domain and U705 (74LVC541A) in the USB
+domain.
+
+U401 is powered from the mobile domain's Vio rail, and it serves only the 4
+signals running from FT2232D to Calypso inputs, neatly using all 4 slots of
+74LVC125A.  This LVC buffer serves as a barrier, preventing feeding of power
+from USB domain outputs into the Calypso+Iota chipset's Vio rail in the PPD
+scenario where a USB host is connected, but the charging switch is off or the
+battery is critically low and undergoing precharge, with the chipset switched
+off.
+
+No corresponding mobile domain buffers will be used for Calypso outputs: these
+5 signals will be connected directly between Calypso pads and the interdomain
+interface, where they will go to U705.
+
+On the USB side, U705 will be powered from a USB domain 3.3V rail, i.e., the
+output of a 3.3V regulator powered from USB.  (This USB domain supply will be
+the only part of FC Venus board using 3.3V - there are no regulated voltages
+higher than 2.8V in the mobile domain.)  The 8 slots of this 74LVC541A buffer
+are split between 5 serving the Calypso to FT2232D signal direction and the
+other 3 serving FT2232D to Calypso signals.
+
+The purpose of the 5 U705 buffer slots serving the Calypso to FT2232D signal
+direction is to stop the flow of current out of Calypso UART and GPIO outputs
+in the "normal mobile usage" PPD scenario when there is no USB host connected.
+With this buffer present, Calypso UART outputs will "see" a high impedance and
+won't source any battery-drawn current (beyond leakage of about 0.1 uA typical
+per pin, according to Nexperia datasheet), no matter whether the USB domain is
+powered or not.  OTOH, if this buffer were omitted and Calypso outputs were
+connected directly to FT2232D inputs, the latter inputs would appear as shorts
+to ground when USB power is absent, putting an unacceptable load on Calypso
+outputs.
+
+The other 3 slots of U705 serve FT2232D-to-Calypso signals TxD, DTR and TxD2.
+On these 3 signals there are pull-up resistors to VBAT in front of U401 inputs
+(see section 2.4), and the U705 buffer's Ioff feature will allow those pull-up
+resistors to work as intended.  If these pulled-up-to-VBAT nets going to U401
+inputs were sourced directly from FT2232D outputs without going through U705,
+the powered-off FT2232D chip's I/O pins would present a lower resistance to GND
+than the pull-up to VBAT, drawing excessive current from the battery and making
+the pull-up ineffective.
+
+There is just one FT2232D-to-Calypso UART interface signal that does not go
+through U705, and it is RTS.  It has a pull-down resistor to GND instead of a
+pull-up to VBAT in front of its U401 input.  With only 8 signals rather than
+all 9 needing to go through a USB domain LVC buffer, the 8 slots of a single
+74LVC541A IC become sufficient.
+
+2.3. UART signals from Calypso to FT2232D
+
+In the case of these 5 signals running from Calypso outputs to U705 inputs, one
+very noteworthy detail is that there are _no_ pull-up or pull-down resistors on
+these nets.  When the Calypso+Iota chipset is switched on, all 5 Calypso outputs
+will be actively driving and there are no problem issues.  However, in the PPD
+scenario where a USB host is connected, but the Calypso+Iota chipset is switched
+off (the charging switch is off or the battery is precharging), the absence of
+pull resistors suggests that U705 inputs will be floating, which certainly looks
+bad at first glance.
+
+However, a more detailed analysis shows that floating CMOS inputs aren't bad
+"in principle", but instead they are bad when they can float around the input
+switching threshold, causing potential oscillations and high current draw from
+the buffer's Vcc supply.  And in the present case, the Mother's analysis
+suggests that the signals in question won't float around the switching threshold
+- instead we expect them to be sensed as a consistent logic low in the PPD
+scenario in which they appear to float.
+
+In this PPD scenario, the Iota chip's VRIO regulator is off, thus the Vio rail
+will be at 0 V unless something feeds wayward power into it.  Calypso chip
+outputs connected to the signal nets under consideration have clamping diodes
+to this Vio rail.  Therefore, if a stray voltage somehow accumulates on those
+nets that is high enough to approach the LVC buffer's input switching threshold,
+it will also be high enough to drain to Vio through Calypso I/O pad clamping
+diodes, and ultimately to GND.
+
+What is our reason for not adding pull-up or pull-down resistors to these nets?
+Besides the obvious reason of not wanting to throw even more PCB real estate at
+this already way overcomplicated USB-serial interface arrangement, each of the
+two options (pull-up or pull-down) would introduce its own problems.
+
+The pull-up resistor option has already proven to be problematic on the
+DUART28+Caramel2 combo, particularly in the Luna configuration in which both PPD
+scenarios become real.  When the Calypso+Iota chipset is on but there is no USB
+power present, current from Calypso outputs flows backwards through these
+pull-up resistors and feeds into the USB domain's power rail to which these
+resistors are connected.  The USB domain output buffer then powers up
+erratically, feeding garbage to Calypso inputs and preventing Calypso from
+entering sleep modes.  And in the opposite PPD scenario (USB power present,
+chipset switched off), enough power can flow through these resistors into
+Calypso I/O pad clamping diodes to feed into Vio and cause erratic LED
+behaviour!  And on FC Venus we would have the additional problem of not having
+a USB-powered 2.8V regulator, as we don't need it for anything else.
+
+Pull-down resistors to GND would be much less problematic.  However, if we use
+a resistor value that is low enough to be better than floating, such as the
+"canonical" 100 kOhm, we would be introducing a *continuous* drain on the
+battery in normal operation.  Calypso outputs corresponding to host RxD, RxD2,
+DCD and RI will normally be high, thus each of those would be a 28 uA drain.
+All 4 combine into a 112 uA continuous drain for no good justification, always
+present whether or not there is a USB host connected, unlike the other similar
+drain discussed in section 2.4.  Therefore, the Mother's decision is to do away
+with pull resistors in either direction, and hope that my reasoning is correct
+in that we won't get prolonged floating voltages around the input switching
+threshold.
+
+Because these seemingly-floating nets are expected to be sensed as logic low,
+the same logic low will be propagated to FT2232D inputs, which means a break
+condition on RxD and asserted state on all control signals.  For this reason
+the Mother's earlier software recommendation still holds: when operating in this
+scenario, only operate on the second UART channel (the data leads only one that
+also has boot controls), and don't open the AT command UART channel except when
+the mobile is switched on and regular operational firmware runs normally.
+
+2.4. Pull-up resistors to VBAT
+
+Experience with Caramel2 boards shows that Calypso UARTs don't like seeing a
+break condition presented to them for extended lengths of time, thus we need to
+design our FC Venus USB-serial interface in such a way that when there is no USB
+host present, Calypso inputs RX_MODEM and RX_IRDA will receive high levels
+(meaning RS-232 idle) rather than low (meaning RS-232 break).  Having an
+extended break condition presented to UARTs prevents entry into Calypso sleep
+modes, which is obviously bad.  The practical implication is that U401 inputs
+which this buffer propagates to Calypso RX_MODEM and RX_IRDA need to be have
+some kind of mobile domain pull-ups on them, as opposed to floating or pulled
+down.  Less critically, we do the same for the DTR signal running from the USB
+domain to the mobile domain - thus DTR will be seen as negated when there is no
+USB host connected.
+
+However, if we were to implement pull-ups to the Calypso+Iota chipset's Vio rail
+on these nets, we would have a problem in the PPD scenario of USB power present,
+chipset switched off: U705 high outputs would feed power into Vio through these
+resistors, potentially causing Calypso peripherals to turn on erratically as
+has been observed on Caramel2 boards.  Therefore, we are making a more unusual
+innovation: instead of pull-ups to Vio, we are implementing pull-ups to VBAT,
+i.e., to the unregulated raw positive battery terminal.  The resistor value
+chosen by the Mother is 22 kOhm, and the rest of this section explores the
+implications of this unusual design under all expected conditions.
+
+First let us examine what happens in the case of "normal" mobile usage: the
+device is untethered and mobile, powered by the battery, and there is no USB
+host or charger connected.  In this case the input voltage seen by U401 will be
+raw VBAT, which will always be higher than its 2.8V supply (but still safely
+below the 5.5 V limit), thus the LVC buffer will sense a good logic high as
+desired.  The current drawn from the battery through these pull resistors will
+be the sum of U705 Ioff and U401 Ii, each of which is listed as 0.1 uA typical
+in Nexperia datasheets.  The listed worst case specs are 10 uA for Ioff and 5 uA
+for Ii, thus under presumably very rare conditions, we could have a maximum
+current draw of 15 uA per each of the 3 pull-ups.  15 uA times 22 kOhm equals a
+voltage drop of 330 mV, thus U401 inputs will remain at 2.8 V or above (meaning
+no increased Vio supply current draw) with the battery as low as 3.1 V, which
+is below the operational range for the mobile.
+
+Now consider what happens when USB power is plugged in, either a host computer
+or a charger.  FT2232D will power up in UART mode and start putting out logic
+high on all of its outputs (the state when no one opens either of the two serial
+ports in host computer software); U705 will also power up and start putting out
+the same logic high on the 3 signal nets going to the mobile domain.  At this
+point U705 output pads are no longer in their Ioff state, instead they are in
+the actively driving high state, and Nexperia datasheet says that the voltage
+at these output pins should not exceed Vcc, which is 3.3 V in the present case.
+VBAT can be as high as 4.2 V, thus we are operating the 74LVC541A under somewhat
+adverse conditions.
+
+The undesirable adverse condition is that current will flow through the LVC
+buffer's output p-channel MOSFET (open for driving high) in the wrong direction.
+The maximum magnitude of this current is about 41 uA, computed as
+(4.2-3.3 V) / 22 kOhm.  This current magnitude is expected to be far too low to
+damage the 74LVC541A IC (the limiting values Iok spec is 50 mA), thus the only
+remaining concern would be feeding of a higher voltage into the USB domain's
+regulated 3.3V rail.  This concern is addressed in the following subsection.
+
+Aside from the issues of reverse current flow through the LVC buffer's output
+p-channel MOSFET, the other concern with this 41 uA current (at maximum VBAT)
+is that this current is drained from the battery.  With a total of 3 such
+pull-ups, we expect a total battery drain current of 123 uA at maximum battery
+charge - but this current only turns on when USB power is applied, and the
+current into U705 output pins goes up from 0.1 uA to 41 uA per pin.  However,
+when USB power is applied for extended periods of time, it is usually done for
+the purpose of charging the battery, and the charging current of 500 mA far
+exceeds the drain current of 123 uA.  In order for the battery to not be
+charging when USB power is present, the system would have to be in one of two
+other states: either the user connected USB for computer interface purposes and
+not for charging (the charging switch is off), or the charge cycle finished but
+the user hasn't unplugged the charger yet.  Both of these conditions are not
+expected to persist for unreasonably long time spans, hence the Mother deems it
+acceptable to impose this 123 uA battery drain during times of active computer
+interfacing.
+
+In the case when the charging switch is on and the charging cycle has finished,
+it is also important to consider that Iota ABB sleep is prevented for as long as
+VCHG remains applied to the chipset, which holds whenever USB power is present
+and the charging switch is on.  In this state (charging cycle finished, but VCHG
+not removed yet) Calypso can enter deep sleep (the main VCXO is stopped), but
+Iota ABB sleep is prevented.  According to TI's APN2_110.pdf document, the
+difference in battery power draw between deep and "superdeep" sleep modes is
+about 600 uA - thus leaving the charger plugged in after charge cycle completion
+causes even more battery drain through this other mechanism than through our
+VBAT pull-up resistors in the USB-serial interface.
+
+Finally, whenever any of the 3 USB domain outputs in question (TxD, DTR or TxD2)
+drives low, the current drawn from VBAT on that net increases from 41 uA to
+about 190 uA at maximum VBAT, computed as 4.2 V / 22 kOhm.  However, this
+condition only occurs when the operator does active host computer interfacing
+with software (the main AT command UART needs to be opened in order for DTR to
+go low, and each of the two TxD lines goes low only when the host computer
+actively transmits bytes), thus this increased battery current draw corresponds
+to explicit user activity, rather than something that happens on its own.  In
+contrast, typical user activity on an untethered phone involves the LCD and its
+backlight turning on, consuming tens of mA instead of hundreds of uA.
+
+It also needs to be noted that all of these currents are drawn directly from the
+battery without going through Iota LDO regulators, thus none of these uA numbers
+come out of the 1 mA sleep mode Vio current budget.
+
+2.4.1. USB domain 3.3V load resistor
+
+One concern raised in the analysis of VBAT pull-ups is that when current flows
+from the battery into the USB domain's P_3V3 rail through U705 outputs in
+reverse, the effect may be to raise that rail above 3.3 V.  To prevent this
+effect, the Mother's idea is to add a load resistor to the USB domain, a
+3.3 kOhm load permanently placed between P_3V3 and GND, producing a permanent
+1 mA draw from USB, going through our 3.3V regulator.  For comparison, FT2232D
+is said to draw about 30 mA of supply current, although the datasheet does not
+specify how it breaks down between Vcc and Vccio supply currents, hence most of
+this 30 mA is probably drawn directly from USB 5V, without going through our
+3.3V regulator.  The addition of 1 mA to the overall USB current draw can be
+considered insignificant (especially for 500 mA charging, but even for 30 mA
+host computer interfacing), but with a guaranteed load of at least 1 mA on
+P_3V3, any wayward current coming from the battery (123 uA maximum) will always
+be absorbed into this load without raising P_3V3 above its intended 3.3 V.
+
+2.5. Pull-down to GND on Host_RTS
+
+The effect of Host_RTS being sensed as low instead of high when there is no USB
+host connected is that any unsolicited output on the AT command channel will be
+flushed in this no-host-connected state, instead of being buffered in the
+mobile.  Given that an end user mobile phone (as opposed to a dedicated cellular
+modem) is expected to be untethered most of the time, having buffered output
+accumulate while waiting for a host computer to be connected "some day" does not
+sound like a good idea, hence having it flushed by unblocked flow control state
+soundly appears to be the better option.  And with only 3 out of the 4 FT2232D
+to Calypso signals needing pull-ups to VBAT, only 3 need U705 buffer slots,
+making a single 74LVC541A buffer IC sufficient for both directions in the USB
+domain.
+
+The value of the pull-down resistor on the Host_RTS net (running from FT2232D
+ADBUS2 output to U401 input) will be 47 kOhm.  When USB power is applied but no
+one opens the AT command UART channel, FT2232D will drive its RTS output high,
+sourcing about 70 uA of current from its USB 3.3V supply into the pull-down
+resistor - well within FT2232D output current sourcing budget.
+
+3. Boot control signals
+
+The two boot control signals RPWON and nTESTRESET properly belong in the mobile
+domain.  They are pulled up to VBAT inside the mobile domain (RPWON is pulled up
+to VBAT inside the Iota chip, nTESTRESET is pulled up to UPR with R208 per
+Leonardo schematics), many other designs don't provide any way at all for these
+signals to be pulled down, but on FC Venus we have a dual OD buffer (74LVC2G07)
+in the USB domain that can pull either signal down on host command.  This dual
+OD buffer is little different from a pair of dry contact pushbutton switches
+shorting to GND, thus the two boot control signals don't bring on any of the
+difficulties like those associated with the UART interface.