Firmware/Storage

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

• used before an fs-update, fs-verify, or fs-save to choose which storage device will be used,
• defaults to the internal storage,
• configuration setting is lost on restart,
• is typically used with external SD card slot, see below,
• see also Forth_Lesson_9#Devaliases.

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:

• for XO-1, see 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, use devalias fsdisk ext:0 followed by the fs-update command, like this:

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

• Using the Linux kernel to test the storage device
• XO Debugging tips
• Forth Lesson 23#read a .zd file
• Operating system image installation methods