[U-Boot] strawman Fastboot in U-Boot Design Doc

[U-Boot] strawman Fastboot in U-Boot Design Doc

[John Rigby]

Here a first draft design doc.  It is based in part on the Fastboot
implementation in the rowboat git repo (pointer below).

As always, comments welcome.
John

Purpose
=======

Mainline support for Android Fastboot would be useful.  Arguing the merits
of Fastboot vs DFU is not in the scope of this document.  This document
is to discuss design goals/requirements of an implementation of
Fastboot in U-Boot.

Background
==========

See the Android Fastboot page in Omappedia for an example of how
Fastboot is used to flash nand partitions on an Android device.
http://www.omappedia.org/wiki/Android_Fastboot

A description of the Fastboot protocol is available in the gitorious
rowboat git repo.
http://gitorious.org/rowboat/bootable-bootloader-legacy/blobs/master/fastboot_protocol.txt

Hooks into U-Boot
=================

Fastboot gets access to the USB subsystem via the same interfaces as USB_TTY,
namely the udc_* api's:
	udc_init
	udc_startup_events
	udc_connect
	udc_poll
	udc_setup_ep
	etc.

Startup
=======

Fastboot will be started on the target by issuing the "fastboot" command.
Optionally a board specific startup method may exist.  For example if
a certain combination of keys is pressed on reset then fastboot will be
started immediately.

Shutdown
========

Once started the fastboot command will continue until:
	<CTRL-C> is typed on the console
	a "continue" command is sent from the host
	usb cable is removed
	no commands have been sent from the host for some configurable timeout
		
Coexistance With USB_TTY and DFU
================================

One should be able to enable USB_TTY, DFU and Fastboot at compile time
and chose one at runtime.

Questions
========

Should a Fastboot host program be included in the U-Boot source?
Could Fastboot be implemented as an extension to USB_TTY?
Could Fastboot, DFU and USB_TTY share a layer of code above the
udc_* api's?

[U-Boot] strawman Fastboot in U-Boot Design Doc

[Wolfgang Denk]

Dear John Rigby,

In message <BANLkTinFHTff5Scr_uP6KNBXQKP3SvVB5A@mail.gmail.com> you wrote:
> Here a first draft design doc.  It is based in part on the Fastboot
> implementation in the rowboat git repo (pointer below).

Thanks.

> Hooks into U-Boot
> =================
> 
> Fastboot gets access to the USB subsystem via the same interfaces as USB_TTY,
> namely the udc_* api's:

Does it make sense to restrict this to USB?  Or should we decouple the
protocol part from the actual transport path?  Maybe it would make
sense to provide the same feature over plain serial line, or over
Ethernet?

Also please keep in mind that there are many ways how a system can
interact with the "operator": we have plain old serial console,
netconsole, console over serial over USB, netconsole over Ethernet
over USB, ...

We should make sure that at least on the conceptual level adding
fastboot support will not cause any conflicts.

> Startup
> =======
> 
> Fastboot will be started on the target by issuing the "fastboot" command.

OK.

> Optionally a board specific startup method may exist.  For example if
> a certain combination of keys is pressed on reset then fastboot will be
> started immediately.

This has nothing to do with fastboot, and should be kept as a separate
item.  Normally U-Boot allows, when keys are supported, to map any
combination of key presses to any commands, i. e. this is in no way
restricted to or dependent on fastboot support.

> Shutdown
> ========
> 
> Once started the fastboot command will continue until:
> 	<CTRL-C> is typed on the console
> 	a "continue" command is sent from the host
> 	usb cable is removed
> 	no commands have been sent from the host for some configurable timeout

This probably needs configuration.

"usb cable is removed" probably makes little sense when running
fastboot protocol over a serial port.

Also, this feature would require permanent polling of the USB status.
Is this needed?

> Coexistance With USB_TTY and DFU
> ================================
> 
> One should be able to enable USB_TTY, DFU and Fastboot at compile time
> and chose one at runtime.

I'm not sure what exactly you mean by "chose one at runtime". It is
pretty much clear that you don't want to run DFU and fastboot
simultaneously, but it is very likely that we will need USB_TTY (for
console over USB) or even Ethernet over USB for console and then want
to start fastboot.

I think I remember that fastboot may require "adjustments" of the USB
IDs and such - we will have to make sure that things like that do not
cause conflicts.

An area that raises additional questions is error handling. When
running fastboot over USB and with a serial console it is probably a
very good idea to provide error messages and maybe even status
reports on the console.  Will this still work with USB_TTY or
netconsole over Ethernet over USB?

> Questions
> ========
> 
> Should a Fastboot host program be included in the U-Boot source?

Seems some peole want it...

> Could Fastboot be implemented as an extension to USB_TTY?

I think we should at least split protocol handling and communication
layer.

> Could Fastboot, DFU and USB_TTY share a layer of code above the
> udc_* api's?

At least they will have to co-exist with each other.

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
"A dirty mind is a joy forever."                       - Randy Kunkee

[U-Boot] strawman Fastboot in U-Boot Design Doc

[Detlev Zundel]

Hi John,

> Here a first draft design doc.  It is based in part on the Fastboot
> implementation in the rowboat git repo (pointer below).

Thanks for this piece of documentation.  Itcertainly helped me
understand that the "boot" part in fastboot is kind of a misnomer,
right?

Again it shows that a bad description can lead thoughts astray....

[...]

> Purpose
> =======
>
> Mainline support for Android Fastboot would be useful.  Arguing the merits
> of Fastboot vs DFU is not in the scope of this document.  This document
> is to discuss design goals/requirements of an implementation of
> Fastboot in U-Boot.

So in essence you say that fastboot is an "alternative" implementation
of the "idea" behind DFU?  Or is DFU (functionally) a subset of
fastboot?  It may be worth extending on that aspect so that people
knowing DFU can "hook into" the discussion.

[...]

> Questions
> ========
>
> Should a Fastboot host program be included in the U-Boot source?

I would certainly welcome a "reference" implementation for a GNU/Linux
host.  Hopefully this will prevent multiple works later on.  Maybe even
writing a small library and having a simple command line wrapper would
be good (like flat device tree and libfdt).

Best wishes
  Detlev

-- 
Is this a private fight or can anyone join in?
                           -- Old Irish saying
--
DENX Software Engineering GmbH,      MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich,  Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-40 Fax: (+49)-8142-66989-80 Email: dzu at denx.de

[U-Boot] strawman Fastboot in U-Boot Design Doc

[John Rigby]

Zach, I did go one more round with WD on the fastboot with a strawman
proposal.  I never followed up because I was not sure that the resources
were commited to do it in Linaro.

Forwarded conversation
Subject: [U-Boot] strawman Fastboot in U-Boot Design Doc
------------------------

From: *John Rigby* <john.rigby@linaro.org>
Date: Thu, Apr 28, 2011 at 7:07 PM
To: u-boot at lists.denx.de, Wolfgang Denk <wd@denx.de>


Here a first draft design doc.  It is based in part on the Fastboot
implementation in the rowboat git repo (pointer below).

As always, comments welcome.
John

Purpose
=======

Mainline support for Android Fastboot would be useful.  Arguing the merits
of Fastboot vs DFU is not in the scope of this document.  This document
is to discuss design goals/requirements of an implementation of
Fastboot in U-Boot.

Background
==========

See the Android Fastboot page in Omappedia for an example of how
Fastboot is used to flash nand partitions on an Android device.
http://www.omappedia.org/wiki/Android_Fastboot

A description of the Fastboot protocol is available in the gitorious
rowboat git repo.
http://gitorious.org/rowboat/bootable-bootloader-legacy/blobs/master/fastboot_protocol.txt

Hooks into U-Boot
=================

Fastboot gets access to the USB subsystem via the same interfaces as
USB_TTY,
namely the udc_* api's:
       udc_init
       udc_startup_events
       udc_connect
       udc_poll
       udc_setup_ep
       etc.

Startup
=======

Fastboot will be started on the target by issuing the "fastboot" command.
Optionally a board specific startup method may exist.  For example if
a certain combination of keys is pressed on reset then fastboot will be
started immediately.

Shutdown
========

Once started the fastboot command will continue until:
       <CTRL-C> is typed on the console
       a "continue" command is sent from the host
       usb cable is removed
       no commands have been sent from the host for some configurable
timeout

Coexistance With USB_TTY and DFU
================================

One should be able to enable USB_TTY, DFU and Fastboot at compile time
and chose one at runtime.

Questions
========

Should a Fastboot host program be included in the U-Boot source?
Could Fastboot be implemented as an extension to USB_TTY?
Could Fastboot, DFU and USB_TTY share a layer of code above the
udc_* api's?
_______________________________________________
U-Boot mailing list
U-Boot at lists.denx.de
http://lists.denx.de/mailman/listinfo/u-boot

----------
From: *Wolfgang Denk* <wd@denx.de>
Date: Fri, Apr 29, 2011 at 4:48 AM
To: John Rigby <john.rigby@linaro.org>
Cc: u-boot at lists.denx.de


Dear John Rigby,
Thanks.
Does it make sense to restrict this to USB?  Or should we decouple the
protocol part from the actual transport path?  Maybe it would make
sense to provide the same feature over plain serial line, or over
Ethernet?

Also please keep in mind that there are many ways how a system can
interact with the "operator": we have plain old serial console,
netconsole, console over serial over USB, netconsole over Ethernet
over USB, ...

We should make sure that at least on the conceptual level adding
fastboot support will not cause any conflicts.
OK.
This has nothing to do with fastboot, and should be kept as a separate
item.  Normally U-Boot allows, when keys are supported, to map any
combination of key presses to any commands, i. e. this is in no way
restricted to or dependent on fastboot support.
This probably needs configuration.

"usb cable is removed" probably makes little sense when running
fastboot protocol over a serial port.

Also, this feature would require permanent polling of the USB status.
Is this needed?
I'm not sure what exactly you mean by "chose one at runtime". It is
pretty much clear that you don't want to run DFU and fastboot
simultaneously, but it is very likely that we will need USB_TTY (for
console over USB) or even Ethernet over USB for console and then want
to start fastboot.

I think I remember that fastboot may require "adjustments" of the USB
IDs and such - we will have to make sure that things like that do not
cause conflicts.

An area that raises additional questions is error handling. When
running fastboot over USB and with a serial console it is probably a
very good idea to provide error messages and maybe even status
reports on the console.  Will this still work with USB_TTY or
netconsole over Ethernet over USB?
Seems some peole want it...
I think we should at least split protocol handling and communication
layer.
At least they will have to co-exist with each other.

Best regards,

Wolfgang Denk

--
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
"A dirty mind is a joy forever."                       - Randy Kunkee

----------
From: *Detlev Zundel* <dzu@denx.de>
Date: Fri, Apr 29, 2011 at 5:02 AM
To: John Rigby <john.rigby@linaro.org>
Cc: u-boot at lists.denx.de


Hi John,
Thanks for this piece of documentation.  Itcertainly helped me
understand that the "boot" part in fastboot is kind of a misnomer,
right?

Again it shows that a bad description can lead thoughts astray....

[...]
So in essence you say that fastboot is an "alternative" implementation
of the "idea" behind DFU?  Or is DFU (functionally) a subset of
fastboot?  It may be worth extending on that aspect so that people
knowing DFU can "hook into" the discussion.

[...]
I would certainly welcome a "reference" implementation for a GNU/Linux
host.  Hopefully this will prevent multiple works later on.  Maybe even
writing a small library and having a simple command line wrapper would
be good (like flat device tree and libfdt).

Best wishes
 Detlev

--
Is this a private fight or can anyone join in?
                          -- Old Irish saying
--
Phone: (+49)-8142-66989-40 Fax: (+49)-8142-66989-80 Email: dzu at denx.de

[U-Boot] strawman Fastboot in U-Boot Design Doc

[Wolfgang Denk]

Dear John,

In message <BANLkTikYX2c9T0aebUQLjMgH9FqmmVV8qw@mail.gmail.com> you wrote:
>
> From: *Wolfgang Denk* <wd@denx.de>
> Date: Fri, Apr 29, 2011 at 4:48 AM
> To: John Rigby <john.rigby@linaro.org>
> Cc: u-boot at lists.denx.de
> 
> 
> Dear John Rigby,
> Thanks.
> Does it make sense to restrict this to USB?  Or should we decouple the
> protocol part from the actual transport path?  Maybe it would make
> sense to provide the same feature over plain serial line, or over
> Ethernet?
> 
> Also please keep in mind that there are many ways how a system can
> interact with the "operator": we have plain old serial console,
> netconsole, console over serial over USB, netconsole over Ethernet
> over USB, ...
> 
> We should make sure that at least on the conceptual level adding
> fastboot support will not cause any conflicts.
> OK.
> This has nothing to do with fastboot, and should be kept as a separate
> item.  Normally U-Boot allows, when keys are supported, to map any
> combination of key presses to any commands, i. e. this is in no way
> restricted to or dependent on fastboot support.
> This probably needs configuration.
> 
> "usb cable is removed" probably makes little sense when running
> fastboot protocol over a serial port.
> 
> Also, this feature would require permanent polling of the USB status.
> Is this needed?
> I'm not sure what exactly you mean by "chose one at runtime". It is
> pretty much clear that you don't want to run DFU and fastboot
> simultaneously, but it is very likely that we will need USB_TTY (for
> console over USB) or even Ethernet over USB for console and then want
> to start fastboot.

Do you think anybody can make heads or tails from this text where you
removed all references to context without even marking these changes?

It was a very bad idea to edit this text in such a way.  Crippeling my
text in such a way is something which makes me actually really angry.
It gives the words a different meaning, and I will not accept this.


Why don't you simply provide a reference to the respective postings in
the list archives, so everybody can actually understand what you are
talking about?

Here it is:

http://thread.gmane.org/gmane.comp.boot-loaders.u-boot/98754/focus=98783


Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
The only time the world beats a path to your door is when you are  in
the bathroom.