RFC: README.hardware: Intel Atom device documentation

RFC: README.hardware: Intel Atom device documentation

[Darren Hart]

I ran across some issues working with USB keys while booting a couple
different Intel Atom based devices. I drafted the following documenting
what I learned from the process. I'd like to add this (or something
similar) to README.hardware.

Thoughts/Comments?


Intel Atom based PCs and devices (atom-pc)
==========================================

The atom-pc MACHINE is tested on the following platforms:

  o Asus eee901
  o Acer Aspire One
  o Toshiba NB305
  o Intel BlackSand development board (FIXME: correct name)

and is likely to work on many unlisted atom based devices. The MACHINE
type supports ethernet, wifi, sound, and i915 graphics by default in
addition to common PC input devices, busses, and so on.

Depending on the device, it can boot from a traditional hard-disk, a USB
device, or over the network. Writing poky generated images to physical
is straightforward with a caveat for USB devices. The following examples
assume the target boot device is /dev/sdb, be sure to verify this and
use the correct device as the following commands are run as root and are
not reversable.

Hard Disk:
  1. Build a directdisk image format. This will generate proper
     partition tables that will in turn be written to the physical media.
  
  2. Use the "dd" utility to write the image to the raw block device.
     For example:

     $ dd if=poky-image-minimal-live-atom-pc-20101214120906.ddimg of=/dev/sdb
     FIXME: verify image name and extension

USB Device:
  1. Build an hddimg image format. This is a simple filesystem without
     partition tables and is suitable for USB keys.

  2. Use the "dd" utility to write the image to the raw block device.
     For example:

     $ dd if=poky-image-minimal-live-atom-pc-20101214120906.hddimg of=/dev/sdb

  If the device fails to boot with "Boot error" displayed, it is likely
  the BIOS cannot understand the physical layout of the disk (or rather
  it expects it to be a particular layout and can't handle anything
  else). There are two possible solutions to this problem:

  1. Change the BIOS USB Device setting to HDD mode. The label will vary
     my device, but the idea is to force BIOS to read the
     Cylinder/Head/Sector geometry from the device.

  2. Without such an option, the BIOS generally boots the device in
     USB-ZIP mode.

     a. Configure the USB device for USB-ZIP mode:
     
     # mkdiskimage -4 /dev/sdb 0 63 62

     Where 63 and 62 are the cylinder and head count as reported by
     fdisk.  Remove and reinsert the device to allow the kernel to
     detect the new partition layout.

     b. Copy the contents of the poky image to the USB-ZIP mode device:

     # mount -o loop poky-image-minimal-live-atom-pc-20101214120906.hddimg  /tmp/image
     # mount /dev/sdb4 /tmp/usbkey
     # cp -rf /tmp/image/* /tmp/usbkey

     c. Install the syslinux boot loader:

     # syslinux /dev/sdb4

  Install the boot device in the target board and configure the BIOS to
  boot from it.

  For more details on the USB-ZIP scenario, see the syslinux documentation:
  http://git.kernel.org/?p=boot/syslinux/syslinux.git;a=blob_plain;f=doc/usbkey.txt;hb=HEAD

-- 
Darren Hart
Yocto Linux Kernel

Re: [Yocto] RFC: README.hardware: Intel Atom device documentation

[Tom Zanussi]

On Wed, 2010-12-15 at 16:17 -0800, Darren Hart wrote:
> I ran across some issues working with USB keys while booting a couple
> different Intel Atom based devices. I drafted the following documenting
> what I learned from the process. I'd like to add this (or something
> similar) to README.hardware.
> 
> Thoughts/Comments?
> 

Hey, thanks for this - it solved the same problem I was having with the
sdk image :-)  One small correction below...

> 
> Intel Atom based PCs and devices (atom-pc)
> ==========================================
> 
> The atom-pc MACHINE is tested on the following platforms:
> 
>   o Asus eee901
>   o Acer Aspire One
>   o Toshiba NB305
>   o Intel BlackSand development board (FIXME: correct name)
> 
> and is likely to work on many unlisted atom based devices. The MACHINE
> type supports ethernet, wifi, sound, and i915 graphics by default in
> addition to common PC input devices, busses, and so on.
> 
> Depending on the device, it can boot from a traditional hard-disk, a USB
> device, or over the network. Writing poky generated images to physical
> is straightforward with a caveat for USB devices. The following examples
> assume the target boot device is /dev/sdb, be sure to verify this and
> use the correct device as the following commands are run as root and are
> not reversable.
> 
> Hard Disk:
>   1. Build a directdisk image format. This will generate proper
>      partition tables that will in turn be written to the physical media.
>   
>   2. Use the "dd" utility to write the image to the raw block device.
>      For example:
> 
>      $ dd if=poky-image-minimal-live-atom-pc-20101214120906.ddimg of=/dev/sdb
>      FIXME: verify image name and extension
> 
> USB Device:
>   1. Build an hddimg image format. This is a simple filesystem without
>      partition tables and is suitable for USB keys.
> 
>   2. Use the "dd" utility to write the image to the raw block device.
>      For example:
> 
>      $ dd if=poky-image-minimal-live-atom-pc-20101214120906.hddimg of=/dev/sdb
> 
>   If the device fails to boot with "Boot error" displayed, it is likely
>   the BIOS cannot understand the physical layout of the disk (or rather
>   it expects it to be a particular layout and can't handle anything
>   else). There are two possible solutions to this problem:
> 
>   1. Change the BIOS USB Device setting to HDD mode. The label will vary
>      my device, but the idea is to force BIOS to read the
>      Cylinder/Head/Sector geometry from the device.
> 
>   2. Without such an option, the BIOS generally boots the device in
>      USB-ZIP mode.
> 
>      a. Configure the USB device for USB-ZIP mode:
>      
>      # mkdiskimage -4 /dev/sdb 0 63 62
> 
>      Where 63 and 62 are the cylinder and head count as reported by

should be: head and sector rather than cylinder and
head.                               

Thanks,

Tom

>      fdisk.  Remove and reinsert the device to allow the kernel to
>      detect the new partition layout.
> 
>      b. Copy the contents of the poky image to the USB-ZIP mode device:
> 
>      # mount -o loop poky-image-minimal-live-atom-pc-20101214120906.hddimg  /tmp/image
>      # mount /dev/sdb4 /tmp/usbkey
>      # cp -rf /tmp/image/* /tmp/usbkey
> 
>      c. Install the syslinux boot loader:
> 
>      # syslinux /dev/sdb4
> 
>   Install the boot device in the target board and configure the BIOS to
>   boot from it.
> 
>   For more details on the USB-ZIP scenario, see the syslinux documentation:
>   http://git.kernel.org/?p=boot/syslinux/syslinux.git;a=blob_plain;f=doc/usbkey.txt;hb=HEAD
> 

Re: [Yocto] RFC: README.hardware: Intel Atom device documentation

[Richard Purdie]

On Wed, 2010-12-15 at 16:17 -0800, Darren Hart wrote:
> I ran across some issues working with USB keys while booting a couple
> different Intel Atom based devices. I drafted the following documenting
> what I learned from the process. I'd like to add this (or something
> similar) to README.hardware.
> 
> Thoughts/Comments?

I think we should add it, please send it completed as a patch!

Ultimately I'm not sure what we do with this file (would it be better on
the wiki?) but having appropriate info there is certainly desirable.

Cheers,

Richard

Re: [Yocto] RFC: README.hardware: Intel Atom device documentation

[Darren Hart]

On 12/15/2010 05:31 PM, Tom Zanussi wrote:
> On Wed, 2010-12-15 at 16:17 -0800, Darren Hart wrote:
>> I ran across some issues working with USB keys while booting a couple
>> different Intel Atom based devices. I drafted the following documenting
>> what I learned from the process. I'd like to add this (or something
>> similar) to README.hardware.
>>
>> Thoughts/Comments?
>>
>
> Hey, thanks for this - it solved the same problem I was having with the
> sdk image :-)

Excellent, glad to hear it. Did you happen to try writing a directdisk 
image to the usb stick to see if that would boot? That might be another 
option. I prefer the hddimg over the ddimg, as the hddimg can easily be 
mounted with -o loop and modified, but if ddimg works, it's a fair bit 
easier than having to deal with the USB-ZIP mode.

Thoughts on how we should present this?

> One small correction below...
>
>>

>>    2. Without such an option, the BIOS generally boots the device in
>>       USB-ZIP mode.
>>
>>       a. Configure the USB device for USB-ZIP mode:
>>
>>       # mkdiskimage -4 /dev/sdb 0 63 62
>>
>>       Where 63 and 62 are the cylinder and head count as reported by
>
> should be: head and sector rather than cylinder and
> head.

Woops, right you are. Thanks for the catch!

--
Darren--
Darren Hart
Yocto Linux Kernel

Re: [Yocto] RFC: README.hardware: Intel Atom device documentation

[Tom Zanussi]

On Thu, 2010-12-16 at 08:25 -0800, Darren Hart wrote:
> On 12/15/2010 05:31 PM, Tom Zanussi wrote:
> > On Wed, 2010-12-15 at 16:17 -0800, Darren Hart wrote:
> >> I ran across some issues working with USB keys while booting a couple
> >> different Intel Atom based devices. I drafted the following documenting
> >> what I learned from the process. I'd like to add this (or something
> >> similar) to README.hardware.
> >>
> >> Thoughts/Comments?
> >>
> >
> > Hey, thanks for this - it solved the same problem I was having with the
> > sdk image :-)
> 
> Excellent, glad to hear it. Did you happen to try writing a directdisk 
> image to the usb stick to see if that would boot? That might be another 
> option. I prefer the hddimg over the ddimg, as the hddimg can easily be 
> mounted with -o loop and modified, but if ddimg works, it's a fair bit 
> easier than having to deal with the USB-ZIP mode.
> 
> Thoughts on how we should present this?
> 

No, I will try that (ddimg).  I plan on at least putting these
instructions in the README for the Crown Bay BSP along with the dd
instructions already there - it should probably be part of a boilerplate
included ine every BSP README...

Tom

> > One small correction below...
> >
> >>
> 
> >>    2. Without such an option, the BIOS generally boots the device in
> >>       USB-ZIP mode.
> >>
> >>       a. Configure the USB device for USB-ZIP mode:
> >>
> >>       # mkdiskimage -4 /dev/sdb 0 63 62
> >>
> >>       Where 63 and 62 are the cylinder and head count as reported by
> >
> > should be: head and sector rather than cylinder and
> > head.
> 
> Woops, right you are. Thanks for the catch!
> 
> --
> Darren--
> Darren Hart
> Yocto Linux Kernel

Re: [Yocto] RFC: README.hardware: Intel Atom device documentation

[Darren Hart]

On 12/16/2010 07:44 AM, Richard Purdie wrote:
> On Wed, 2010-12-15 at 16:17 -0800, Darren Hart wrote:
>> I ran across some issues working with USB keys while booting a couple
>> different Intel Atom based devices. I drafted the following documenting
>> what I learned from the process. I'd like to add this (or something
>> similar) to README.hardware.
>>
>> Thoughts/Comments?
>
> I think we should add it, please send it completed as a patch!
>
> Ultimately I'm not sure what we do with this file (would it be better on
> the wiki?) but having appropriate info there is certainly desirable.

Just had a brief discussion with Scott R about this. Our feeling is that 
README.hardware is a reasonable place for this information. It is too 
board specific for the reference manual, but a general description of 
the various image types with a reference to README.hardware would be 
appropriate for the reference manual.

As to wiki vs. README. One user commented earlier that they prefer to 
have this sort of information packaged with the source as there are lots 
of scenarios where they must work without internet access. Given this is 
step-by-step command-line level documentation, I suggest keeping it with 
the source.

Thanks,

-- 
Darren Hart
Yocto Linux Kernel