Firmware/Storage: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
The XO laptop has internal storage, which acts like a hard disk drive but has no moving parts.
Firmware commands that work with internal storage.


The technology varies by XO laptop model:
= fs-update =
*the [[XO-1.75]] and [[XO-4]] have [http://en.wikipedia.org/wiki/MultiMediaCard#eMMC e•MMC], and an external [http://en.wikipedia.org/wiki/MultiMediaCard SD] slot,
*the [[XO-1.5]] has a [http://en.wikipedia.org/wiki/MultiMediaCard microSD] slot, and an external SD slot,
*the [[XO-1]] has host managed NAND FLASH (not covered on this page), and an external SD slot,

The [[firmware]] has special support for each storage technology.

= Commands =

Firmware commands that work with internal storage on XO-1.5, XO-1.75 and XO-4.

== fs-update ==


* installs a {{Code|.zd}} file to the internal storage,
* installs a {{Code|.zd}} file to the internal storage,
Line 8: Line 19:
The {{Code|fs-update}} command has two variants; ''signed'' and ''unsigned''.
The {{Code|fs-update}} command has two variants; ''signed'' and ''unsigned''.


== unsigned ==
=== unsigned ===


* used during development,
* used during development,
Line 17: Line 28:
fs-update u:\os.zd
fs-update u:\os.zd


== signed ==
=== signed ===


* used during deployment,
* used during deployment,
Line 26: Line 37:
* reboots automatically on completion,
* reboots automatically on completion,


= fs-verify =
== fs-verify ==


* verifies that {{Code|fs-update}} worked correctly,
* verifies that {{Code|fs-update}} worked correctly,
Line 36: Line 47:
* reports progress,
* reports progress,
* reports all block numbers where the calculated hash does not match the hash in the {{Code|.zsp}} file,
* reports all block numbers where the calculated hash does not match the hash in the {{Code|.zsp}} file,
* for builds that clear block zero to prevent boot after incomplete install, always reports block zero as not matching,


= fs-verify-quick =
== fs-verify-quick ==


* verifies that {{Code|fs-update}} worked correctly,
* verifies that {{Code|fs-update}} worked correctly,
Line 46: Line 58:
* reports the first block number where the calculated hash does not match the hash in the {{Code|.zsp}} file,
* reports the first block number where the calculated hash does not match the hash in the {{Code|.zsp}} file,


= fs-save =
== fs-save ==


* writes an {{Code|.img}} file using the internal storage as source,
* writes an {{Code|.img}} file using the internal storage as source,
* is very slow, intended for diagnostic use only.
* is very slow, intended for diagnostic use only.


= fs-load =
== fs-load ==


* installs an {{Code|.img}} file to the internal storage, without any verification,
* installs an {{Code|.img}} file to the internal storage, without any verification,
* is very slow, intended for field support use only.
* is very slow, intended for field support use only.


= fs-resize =
== fs-resize ==


The {{Code|fs-resize}} command enlarges the second partition of the internal storage so that it takes up all the remaining space on the device. It was an interim fix until <trac>10040</trac> was fixed. The partition resize is now handled in OLPC OS by the startup scripts. {{Code|fs-resize}} remains applicable to builds that were created before this fix. The method to install them was:
The {{Code|fs-resize}} command enlarges the second partition of the internal storage so that it takes up all the remaining space on the device. It was an interim fix until <trac>10040</trac> was fixed. The partition resize is now handled in OLPC OS by the startup scripts. {{Code|fs-resize}} remains applicable to builds that were created before this fix. The method to install them was:
Line 65: Line 77:
* use {{Code|resize2fs /dev/mmcblk0p2}} to resize the root filesystem to the new size of the partition.
* use {{Code|resize2fs /dev/mmcblk0p2}} to resize the root filesystem to the new size of the partition.


= devalias fsdisk =
== devalias fsdisk ==


* used before an [[#fs-update|{{Code|fs-update}}]], [[#fs-verify|{{Code|fs-verify}}]], or [[#fs-save|{{Code|fs-save}}]] to choose which storage device will be used,
* used before an [[#fs-update|{{Code|fs-update}}]], [[#fs-verify|{{Code|fs-verify}}]], or [[#fs-save|{{Code|fs-save}}]] to choose which storage device will be used,
Line 74: Line 86:


= Recipes =
= Recipes =

== How to find the size ==

{{/Size}}


== How to install to SD card ==
== How to install to SD card ==


The laptop has an external SD card slot which can be used instead of internal storage. To install to the SD card requires a special command:
The laptop has an external SD card slot which can be used instead of internal storage.

On locked laptops:
* for [[XO-1]], see [[Release_notes/13.2.7/Installation/XO-1/SD|How to install 13.2.7 on SD card]],
* for XO-1.5, XO-1.75, and XO-4, is not supported,

On unlocked XO-1.5, XO-1.75, and XO-4 laptops, install to the SD card requires a special command:
* instead of only [[#fs-update|{{Code|fs-update}}]], use [[#devalias fsdisk|{{Code|devalias fsdisk ext:0}}]] followed by the [[#fs-update|{{Code|fs-update}}]] command, like this:
* instead of only [[#fs-update|{{Code|fs-update}}]], use [[#devalias fsdisk|{{Code|devalias fsdisk ext:0}}]] followed by the [[#fs-update|{{Code|fs-update}}]] command, like this:
devalias fsdisk ext:0
devalias fsdisk ext:0
fs-update u:\os.zd
fs-update u:\os.zd
* requires extra care to type the command properly,
* does not work for signed install,
* laptop can be locked after install if necessary.
* does not work on [[XO-1]],

* requires extra care to type the command properly.
<font color="red">Note</font>: it is best to leave the SD card in the same laptop. Booting from it and then moving the card to another laptop can cause problems. In particular you may need to ''Discard wireless connections'' in the ''Network'' panel of ''My Settings''. See also [[Imaging/Side_effects]], in particular the sections regarding .olpc-configured, and network.


== How to automatically install an unsigned build ==
== How to automatically install an unsigned build ==
Line 128: Line 151:
The screen will fill with grey blocks, and these will turn ''red'' indicating progress.
The screen will fill with grey blocks, and these will turn ''red'' indicating progress.


Note: [[#fs-save|{{Code|fs-save}}]] and [[#fs-load|{{Code|fs-load}}]] can be used for [[Backup|backup]] and restore, or for cloning one laptop to another, but there are much faster methods, such as [[Tiny Core Linux]]. The process is very slow, roughly 15 minutes for 4GB to a USB HDD, or three hours over NFS over USB ethernet. See also [[Imaging_for_XO-1.5]] and [[Imaging/Side_effects]].
Note: [[#fs-save|{{Code|fs-save}}]] and [[#fs-load|{{Code|fs-load}}]] can be used for [[Backup|backup]] and restore, or for cloning one laptop to another. It is very slow; roughly 15 minutes for 4GB to a USB HDD, or three hours over NFS over USB ethernet. There are much faster methods, such as [[Tiny Core Linux]], but the advantage of using the firmware is that the tools are already in place. See also [[Imaging_for_XO-1.5]] and [[Imaging/Side_effects]].

== How to quickly erase everything ==

Sends a command to the storage firmware asking for all blocks to be erased.

Use case for this is an SD card, microSD card, or eMMC that has been in storage for many years and has developed bad blocks which give timeout errors on reading. Reflash alone does not always fix the problem, so the next step is to ask the storage firmware to treat all blocks as unused. Reading each block is then redirected away from the bad flash blocks, and new writes will schedule flash block erasure and test.

<font color="red">WARNING</font>: this is practically irreversible. However, this is not a secure erase operation, and may be reversed in an integrated circuit laboratory or by the chip manufacturer for a large fee,

*works on XO-1.5, XO-1.75, and XO-4 only,
* if you have used devalias fsdisk since power up, the alias disk is erased,
*may not work on certain microSD cards or eMMC; says so with an error,
*is not required before operating system installation,
*takes about three seconds on XO-4 8GB eMMC,
*get to the [[Ok]] prompt, and type this:
\ XO-1.5 XO-1.75 XO-4 quick erasure of internal storage
: erase-storage
open-nand
" size" $call-nand ( #bytes-lo #bytes-hi )
d# 512 um/mod nip 0 swap ( 0 #blocks )
" erase-blocks" $call-nand ( )
close-nand
;
erase-storage

== How to verify erasure ==

An erasure can be proven to be successful like this:

*boot from USB using [[Tiny Core Linux]],
*type this shell command to dump the internal storage contents to screen:
od -a -A x /dev/mmcblk0
*wait for the command to complete; about five minutes on an XO-4.

When the storage is not erased, the output of od is extensive, and scrolls up the screen. When the storage is erased, all the repeating zeroes are suppressed and only three or four lines are output.

== How to check eMMC revision ==

Different eMMC used in production may have different revision of eMMC standard.

*boot to the [[Ok]] prompt, via [[Serial_adapters|serial]], display, or [[Firmware/Remote#Using_telnetd|network]], then enter these commands:
dev /sd
: .ext-csd-rev ." ext-csd-rev=" ext-csd-buf d# 192 + c@ .d cr ;
: get-ext-csd' get-ext-csd .ext-csd-rev ;
patch get-ext-csd' get-ext-csd configure-mmc
dend
select int:0
*examine the output, it will be 6 for eMMC 4.5 to 5.0, and 7 for eMMC 5.1.


= See Also =
= See Also =


*[[Tiny_Core_Linux/eMMC|Using the Linux kernel to test the storage device]]
*[[XO Debugging tips]]
*[[XO Debugging tips]]
*[[Forth Lesson 23#read a .zd file]]
*[[Forth Lesson 23#read a .zd file]]

Latest revision as of 05:59, 16 December 2016

The XO laptop has internal storage, which acts like a hard disk drive but has no moving parts.

The technology varies by XO laptop model:

  • the XO-1.75 and XO-4 have e•MMC, and an external SD slot,
  • the XO-1.5 has a microSD slot, and an external SD slot,
  • the XO-1 has host managed NAND FLASH (not covered on this page), and an external SD slot,

The firmware has special support for each storage technology.

Commands

Firmware commands that work with internal storage on XO-1.5, XO-1.75 and XO-4.

fs-update

  • installs a .zd file to the internal storage,
  • is optimised for maximum speed by overlaying the read and write streams,

The fs-update command has two variants; signed and unsigned.

unsigned

  • used during development,
  • during install, verifies the block hashes in the .zd file against the block data in the .zd file,
  • does not require or use the .zip file,
  • does not reboot on completion,
  • example:
fs-update u:\os.zd

signed

  • used during deployment,
  • triggered by four game key hold during startup,
  • searches for fs.zip or fsN.zip where N is the model tag; this file must be present on boot media,
  • verifies the signature in the .zip file,
  • during install, verifies the block hashes in the .zip file against the block data in the .zd file,
  • reboots automatically on completion,

fs-verify

  • verifies that fs-update worked correctly,
fs-verify filename.zsp
  • reads a .zsp file, in particular the block numbers and block hashes,
  • reads corresponding blocks from internal storage, calculating block hashes,
  • reports progress,
  • reports all block numbers where the calculated hash does not match the hash in the .zsp file,
  • for builds that clear block zero to prevent boot after incomplete install, always reports block zero as not matching,

fs-verify-quick

  • verifies that fs-update worked correctly,
fs-verify-quick filename.zsp
  • like fs-verify but stops on first mismatch,
  • reports the first block number where the calculated hash does not match the hash in the .zsp file,

fs-save

  • writes an .img file using the internal storage as source,
  • is very slow, intended for diagnostic use only.

fs-load

  • installs an .img file to the internal storage, without any verification,
  • is very slow, intended for field support use only.

fs-resize

The fs-resize command enlarges the second partition of the internal storage so that it takes up all the remaining space on the device. It was an interim fix until <trac>10040</trac> was fixed. The partition resize is now handled in OLPC OS by the startup scripts. fs-resize remains applicable to builds that were created before this fix. The method to install them was:

  • on a 4GB or 8GB laptop, use fs-update to install the 2GB build,
  • use fs-resize to resize the partition that holds the root filesystem,
  • boot the build,
  • use resize2fs /dev/mmcblk0p2 to resize the root filesystem to the new size of the partition.

devalias fsdisk

Recipes

How to find the size

Bring up the ok prompt. The firmware banner shows the internal storage size. For instance on an XO-4 made with an 8GB eMMC, the banner shows:

OLPC 4B1, 1196 MHz, 2 GiB memory, 8 GB internal storage, S/N SHC2380007F
OpenFirmware  Q7B37   EC Firmware 0.4.10   2014-01-02 00:06:43 UTC

ok █

Or, the exact size in bytes can be displayed:

ok decimal internal-disk-size d.
7952400384
ok █

How to install to SD card

The laptop has an external SD card slot which can be used instead of internal storage.

On locked laptops:

On unlocked XO-1.5, XO-1.75, and XO-4 laptops, install to the SD card requires a special command:

devalias fsdisk ext:0
fs-update u:\os.zd
  • requires extra care to type the command properly,
  • laptop can be locked after install if necessary.

Note: it is best to leave the SD card in the same laptop. Booting from it and then moving the card to another laptop can cause problems. In particular you may need to Discard wireless connections in the Network panel of My Settings. See also Imaging/Side_effects, in particular the sections regarding .olpc-configured, and network.

How to automatically install an unsigned build

For signed builds, the install sequence is:

  • prepare the USB drive with signed files, see release notes,
  • insert the USB drive,
  • hold down the four game keys and turn on the laptop,
  • wait for the laptop to turn itself off.

However, for unsigned custom builds the user is often asked to use fs-update manually. As an alternative, an Open Firmware boot script may be used. The laptop must still be unlocked. Here is an example script:

\ OLPC XO-1.5 XO-1.75 XO-4 automatic unsigned install script
: zd$  " u:\32001xx1.zd"  ;
: installer
    visible

    ." press 'y' to install" cr  \ avoid accidental damage
    begin  key  [char] y  =  until
    page

    zd$ $fs-update
    page

    .os
    ." install done," cr
    ." please remove USB drive and turn off."
    begin halt again
;
installer

Place this script in a file olpc.fth in a directory boot on the USB drive. Place the install file on the USB drive. Insert the USB drive in the laptop and turn it on, without holding down the four game keys. The laptop will ask "press 'y' to install". Press 'y' and the install will start.

How to make an image copy of internal storage

  • determine the size of the internal storage, as shown by banner,
  • choose a USB flash drive, USB hard drive, or SD card that is larger than the internal storage size,
  • choose a size higher than the internal storage, because filesystems add some overhead,
  • choose ext2 or FAT filesystems, because these offer the best compatibility,
  • choose a device that has no critical data on it already, because the feature is not well tested and may corrupt filesystems,
  • use the fs-save command to make the image copy, for example:
ok fs-save u:\os.img

The screen will fill with grey blocks, and these will turn red indicating progress.

Note: fs-save and fs-load can be used for backup and restore, or for cloning one laptop to another. It is very slow; roughly 15 minutes for 4GB to a USB HDD, or three hours over NFS over USB ethernet. There are much faster methods, such as Tiny Core Linux, but the advantage of using the firmware is that the tools are already in place. See also Imaging_for_XO-1.5 and Imaging/Side_effects.

How to quickly erase everything

Sends a command to the storage firmware asking for all blocks to be erased.

Use case for this is an SD card, microSD card, or eMMC that has been in storage for many years and has developed bad blocks which give timeout errors on reading. Reflash alone does not always fix the problem, so the next step is to ask the storage firmware to treat all blocks as unused. Reading each block is then redirected away from the bad flash blocks, and new writes will schedule flash block erasure and test.

WARNING: this is practically irreversible. However, this is not a secure erase operation, and may be reversed in an integrated circuit laboratory or by the chip manufacturer for a large fee,

  • works on XO-1.5, XO-1.75, and XO-4 only,
  • if you have used devalias fsdisk since power up, the alias disk is erased,
  • may not work on certain microSD cards or eMMC; says so with an error,
  • is not required before operating system installation,
  • takes about three seconds on XO-4 8GB eMMC,
  • get to the Ok prompt, and type this:
\ XO-1.5 XO-1.75 XO-4 quick erasure of internal storage
: erase-storage
  open-nand
  " size" $call-nand  ( #bytes-lo #bytes-hi )
  d# 512 um/mod nip 0 swap  ( 0 #blocks )
  " erase-blocks" $call-nand ( )
  close-nand
;
erase-storage

How to verify erasure

An erasure can be proven to be successful like this:

  • boot from USB using Tiny Core Linux,
  • type this shell command to dump the internal storage contents to screen:
od -a -A x /dev/mmcblk0
  • wait for the command to complete; about five minutes on an XO-4.

When the storage is not erased, the output of od is extensive, and scrolls up the screen. When the storage is erased, all the repeating zeroes are suppressed and only three or four lines are output.

How to check eMMC revision

Different eMMC used in production may have different revision of eMMC standard.

  • boot to the Ok prompt, via serial, display, or network, then enter these commands:
dev /sd
: .ext-csd-rev  ." ext-csd-rev="  ext-csd-buf d# 192 + c@ .d  cr  ;
: get-ext-csd'  get-ext-csd .ext-csd-rev  ;
patch get-ext-csd' get-ext-csd configure-mmc
dend
select int:0
  • examine the output, it will be 6 for eMMC 4.5 to 5.0, and 7 for eMMC 5.1.

See Also