[Arm-netbook] Early UART output vs. housing board discovery

[Jonathan Neuschäfer]

Hi,

Please excuse the verbosity of some parts of this email, where I tried
to be extra clear.

On Wed, Jan 10, 2018 at 07:22:16PM +0000, Luke Kenneth Casson Leighton wrote:
> On Wed, Jan 10, 2018 at 4:11 PM, Jonathan Neuschäfer <j.neuschaefer at gmx.net> wrote:
> > On Wed, Jan 10, 2018 at 01:59:19PM +0000, Luke Kenneth Casson Leighton wrote:
[...]
> >>  no it's even more basic / simpler than that.  they don't have to do
> >> that, they can just put the Card into a break-out PCMCIA holder
> >> socket.  or anything else.
> >
> > ... and enable early debug mode through unspecified means, right?
> 
>  no, it's very clearly specified that there *is* no limit or
> restriction.  which is totally different from leaving things
> "unspecified".

The EOMA68 spec doesn't specify how to enable early debug mode, that's
what I meant.

> >> > In short: Thank you for the clarification. Now I disagree with this
> >> > decision in the spec. :-/
> >>
> >>  ok, so bear in mind that the UART wires double up as GPIO, and that
> >> it is the HOUSING DESIGNER's right, under the EOMA68 specification, to
> >> make the decision to allocate eiher one (or both) of the UART wires to
> >> GPIO - as either Input or Output.
> >
> > This is AFAICS not a big problem under my suggested change.
> >
> > For reference, this is my suggested change:
> > - CPU Cards may use the UART lines for debug purposes while they are not
> >   fully (enough) booted.
> 
>  ok so that implies that the UART lines MAY be UART... they MIGHT also
> be GPIO.  please bear in mind: anything that involves "confusion" is
> AUTOMATICALLY prohibited from being included in the EOMA68 Standard.

Confusion for which group of people?

USERS: Early debug output is a feature that probably shouldn't be
documented for Retail Endusers anyway: They can't be expected to find
it useful. Technical Endusers however can probably navigate the
confusion, and understand the feature if it's documented well enough.

CARD DESIGNERS: I don't think card hardware designs need to change.

HOUSING DESIGNERS: Yes, this puts the burden to tolerate UART mode
during early boot on housing designers.

OPERATING SYSTEM DEVELOPERS: Yes, OSes may need to do a little more in
order to use the full feature set of a housing.

BOOTLOADER DEVELOPERS: AFAICS, they need to care less about EOMA68 then
before, because they can now just print all the debug output they want,
without looking at the EEPROM.

> i  appreciate that in this case you describe a procedure that would
> remove doubt, but the procedure itself is very burdensome to
> implement.
> 
>  there is a story i told about the X25 Standard which illustrates how
> these kinds of choices result in lost opportunities and/or total
> confusion and thus destroy confidence in a standard.
> 
> 
> > - When a CPU card has fully (enough) booted, it must use the UART pins
> >   in the function that's described in the EEPROM.
> 
>  ok so the boot process you propose is:
> 
>  * bring up the CPU (DDR3, PLLs)
>  * initialise EEPROM GPIO pins and configure them as I2C
>  * read an I2C EEPROM
>  * decode it
>  * work out if it's SAFE to write to UART
>  * THEN write debug / print messages on the UART pins
> 
>  ... can you see how that's not "early" at all?

No, what I'm trying to propose (and think through) is different:

* Reset the SoC and bring the pins of the EOMA68 connector into the
  state that's mandated at reset (most pins tri-stated, etc.)
* Bring some of the SoC (configure clock trees, maybe the DRAM, too)
* Initialize the UART and start using it, because it is safe to use in
  early boot
* Continue bringing up things and printing debug messages
* Perhaps already load the OS kernel
* Configure the I2C controller and read the EEPROM
* Stop doing early debug output, and start using the UART pins in
  the way that's mandated by the EEPROM

I can see two points where problems might occur:
* If software fails to disable early debug output in the UART (this
  shouldn't too hard to solve in Linux, though).
* If the CPU card spontaneously resets without first bringing the
  housing into a state where it tolerates early debug output
  (some housings might require such preparation before shutdown).

> > For example, UART
> >   connected to a Bluetooth module, GPIO connected to whatever, etc.
> > - If a housing needs to protect its components from debug traffic, it
> >   must provide (and describe in the EEPROM) a mechanism for the CPU card
> >   to signal that it has booted far enough to use the UART pins for the
> >   function intended by the housing. This can be done through a I2C
> >   register poke, toggling a (different) GPIO line, etc.[2]
> 
>  this is _way_ too complicated, and also not clear.

Sorry, what exactly is unclear?

> > - I think it should be valid for a CPU card to follow the current model
> >   and keep the UART pins tri-stated until it's fully booted. A housing
> >   that wants to capture early debug traffic can generate a well-defined
> >   idle signal on the TX line with a pull-up.
> 
>  this is even more complicated... and also unnecessary when the person
> doing the debugging may either:
> 
>  * in-situ use multiplexing of user-facing connectors (A20 MicroSD /
> UART-JTAG capability)

Yes, because this is a completely different approach.

>  * take the Card out of the Housing and test it in a home-made or
> laboratory-owned test Housing.

How can a lab housing tell a card that it's safe to do early debug
output? (Or is that still signaled out of band, e.g. by replacing the
boot loader?)

> > This is a debug facility. Not all CPU cards have to use it, but all
> > housings must accept it.
> 
>  that places a huge technical burden and complexity on Housing
> Designers *and* Card Designers, where no such complexity or burdensome
> requirements exist at the moment.
> 
> 
> > Thus it is just as (non-)optional as USB, with the difference that the
> > CPU card decides whether it prints early debug messages, and the Housing
> > decides whether it connects the USB pins to any USB devices or
> > connectors.
> 
>  the purpose of requiring the "non-optionality" is to ensure that
> there is absolutely no way that a future Card or future Housing will
> be incompatible with an older Card or an older Housing, no matter how
> much faster the peripherals on either the Card(s) or the Housing(s)
> have become.
[...]

How is speed relevant to this discussion?

> > "Fully (enough) booted" in the above doesn't just mean the CPU has left
> > the bootloader. It also has to have read the I2C EEPROM, which might
> > require quite a bit of work in the kernel (initializing the I2C
> > controller, at least). Things can go wrong before the CPU card has
> > booted far enough before it can read and interpret the I2C EEPROM, which
> > is my whole motivation.
> 
>  exactly.  and that's precisely why additional complexity should *not*
> be added to the negotiation phase.

I don't quite understand your argument here: The only way I'm
complicating the "negotiation phase" is by requiring that the software
stops any Debug UART output before it switches its use of the UART pins
over to the housing-mandated use.

I am not complicating negotiation itself (init I2C controller, read
EEPROM, parse EEPROM, act on it).

> >>  .... so what do you think would happen, in this case, if someone
> >> plugged in a Card where it was FORCIBLY REQUIRED that UART *ABSOLUTELY
> >> MUST* transmit "early boot messages" on those two wires?
> >
> > Required by which part?
> 
> sorry, the use of the word "part" is not clear.  part of the standard?
> part of the Card? part of the Housing? part of the proposed
> modification to the standard?

I mean hardware part, which would be either the CPU card or the Housing.

> > - Housings shouldn't require to see any debug messages from CPU cards,
> >   that's just silly
> 
>  the point is: if the wires are to be forced to transmit early debug
> messages, then in ABSOLUTELY NO WAY can they also be allowed to change
> over to GPIO.  there must be ABSOLUTELY NO POSSIBLE RISK that their
> use as UART could conceivably cause damage to either the CPU or to the
> Housing components.

Ok, I think I see the point here.

>  and if there is a current fight between a GPIO that is tied
> permanently to VREFTTL on the Housing and the forced requirement to
> transmit UART early debug messages tries to pull it high, we have a
> serious problem.

Permanently (through PCB traces) tying pin 23 (GPIO8/UART_TX) to VREFTTL
is not allowed under my proposal.

(And I think you meant "tries to pull it *low*", not high.)

>  i appreciate that you have come up with a solution to this, involving
> a complex process of ascertaining via the EEPROM whether the pins are
> GPIO or UART,

Figuring out (in software) whether the pins are used as UART or GPIO at
runtime, by asking the EEPROM, is no more complex than before.

> but it is complexity where *none* exists at the moment,
> and there are two easy alternatives that place absolutely no burden
> whatsoever on the Technical EndUser.

Soldering to small test pads inside the card is a burden.
Figuring out the pin muxing and ordering a microSD breakout board is
also a burden.

Those might be small burdens (depending on the experience and market
situation of the Technical Enduser), but they are still burdens.


Okay, I think I now understand the main problem with my proposal:
Ensuring that it is safe for the CPU card to use pins 23 and 57 during
early boot is hard or causes some additional complexity in the housing
and software, because (a) because it may reset (and thus enter early
boot) spontaneously, and (b) when it leaves early boot, it may have to
tell the housing about it.

My goal was to have a mechanism, specified by the EOMA68 standard, by
which an interested Technical Enduser can access early debug output of
any EOMA68 CPU card, without doing anything CPU card specific (such as
ordering a Allwinner A20 µSD breakout board, or opening the card and
soldering some wires to the right testpads, or loading a "debug enabled"
version of the particular bootloader/OS running on a card).

Here's a *completely different* and significantly simpler proposal,
which also fulfills these goals. You probably won't like it because
(a) it takes away a pin from general purpose use, (b) it breaks
compatibility [see footnote 1] with current hardware.

  Replace one of the GPIO pins (such as pin 21, GPIO 20) with a single-
  purpose Debug UART TX pin, where the CPU card may print debug messages
  in 8N1 format. Debug UART TX high/low is measured against VREFTTL.

  CPU card-agnostic applications which require EOMA68, should still not
  rely on the Debug UART TX line.

  As to why the "may" above does not hurt non-optionality: This is not a
  Retail Enduser facing feature, and should not be advertised to Retail
  Endusers. If a card doesn't use the Debug UART TX line (i.e. never
  prints a message), then this doesn't break compatibility with any
  housings, even housings that are specifically made for the purpose of
  capturing Debug UART TX output. In the worst case, a Technical Enduser
  will think "Oh, this card doesn't output anything on the debug line.
  Now I can't debug it as easily", but not "This card doesn't output
  anything on the debug line, now my application doesn't work".
  (Such a CPU card is, in a way, only "hurting itself")

Alternatively, this could be two pins (Debug UART TX and RX) so that
something like a bootloader shell may be used. But this is probably
worse because it takes another pin away from general-purpose use.


Thanks,
Jonathan Neuschäfer

[footnote 1]: Current CPU card hardware could in fact generate a valid
  (idle) Debug UART TX signal, by driving Debug UART TX high.