fwup-ops.conf

# Post-installation firmware operations for the Raspberry Pi
#
# Tasks include:
#
# * `factory-reset` - Clear out the writable filesystem and any other writable
#                   areas so that they can be re-initialized on the next boot.
# * `prevent-revert` - Prevent `revert` from working until the next firmware
# * `revert` - Revert to the previous firmware if it's still available
# * `validate` - Mark this firmware as a good update.
# * `status` - Print out which partition is active (`a` or `b`)
#
# To use:
#
# 1. Run `fwup -c -f fwup-ops.conf -o ops.fw` and copy ops.fw to
#    the device. This is done automatically as part of the Nerves system
#    build process. The file is stored in `/usr/share/fwup/ops.fw`.
# 2. On the device, run `fwup -t <task> -d /dev/rootdisk0 --enable-trim /usr/share/fwup/ops.fw`.
# 3. Reboot after running `revert` or `factory-reset`.
#
# It is critical that this is kept in sync with the main fwup.conf.

require-fwup-version="1.0.0"

#
# Firmware metadata
#

# All of these can be overriden using environment variables of the same name.
#
#  Run 'fwup -m' to query values in a .fw file.
#  Use 'fw_printenv' to query values on the target.
#
# These are used by Nerves libraries to introspect.
define(NERVES_FW_PRODUCT, "Nerves Firmware")
define(NERVES_FW_DESCRIPTION, "")
define(NERVES_FW_VERSION, "${NERVES_SDK_VERSION}")
define(NERVES_FW_PLATFORM, "rpi")
define(NERVES_FW_ARCHITECTURE, "arm")
define(NERVES_FW_AUTHOR, "The Nerves Team")

# This configuration file will create an image that
# has an MBR and the following layout:
#
# +----------------------------+
# | MBR                        |
# +----------------------------+
# | Firmware configuration data|
# | (formatted as uboot env)   |
# +----------------------------+
# | p0*: Boot A (FAT32)        |
# | zImage, bootcode.bin,      |
# | config.txt, etc.           |
# +----------------------------+
# | p0*: Boot B (FAT32)        |
# +----------------------------+
# | p1*: Rootfs A (squashfs)   |
# +----------------------------+
# | p1*: Rootfs B (squashfs)   |
# +----------------------------+
# | p2: Application (ext4)     |
# +----------------------------+
#
# The p0/p1 partition points to whichever of configurations A or B that is
# active.
#
# The image is sized to be less than 1 GB so that it fits on nearly any SDCard
# around. If you have a larger SDCard and need more space, feel free to bump
# the partition sizes below.

# The Raspberry Pi is incredibly picky on the partition sizes and in ways that
# I don't understand. Test changes one at a time to make sure that they boot.
# (Sizes are in 512 byte blocks)
define(UBOOT_ENV_OFFSET, 16)
define(UBOOT_ENV_COUNT, 16)  # 8 KB

define(BOOT_A_PART_OFFSET, 63)
define(BOOT_A_PART_COUNT, 38630)
define-eval(BOOT_B_PART_OFFSET, "${BOOT_A_PART_OFFSET} + ${BOOT_A_PART_COUNT}")
define(BOOT_B_PART_COUNT, ${BOOT_A_PART_COUNT})

# Let the rootfs have room to grow up to 128 MiB and align it to the nearest 1
# MB boundary
define(ROOTFS_A_PART_OFFSET, 77324)
define(ROOTFS_A_PART_COUNT, 289044)
define-eval(ROOTFS_B_PART_OFFSET, "${ROOTFS_A_PART_OFFSET} + ${ROOTFS_A_PART_COUNT}")
define(ROOTFS_B_PART_COUNT, ${ROOTFS_A_PART_COUNT})

# Application partition. This partition can occupy all of the remaining space.
# Size it to fit the destination.
define-eval(APP_PART_OFFSET, "${ROOTFS_B_PART_OFFSET} + ${ROOTFS_B_PART_COUNT}")
define(APP_PART_COUNT, 1048576)

# Firmware archive metadata
meta-product = ${NERVES_FW_PRODUCT}
meta-description = ${NERVES_FW_DESCRIPTION}
meta-version = ${NERVES_FW_VERSION}
meta-platform = ${NERVES_FW_PLATFORM}
meta-architecture = ${NERVES_FW_ARCHITECTURE}
meta-author = ${NERVES_FW_AUTHOR}
meta-vcs-identifier = ${NERVES_FW_VCS_IDENTIFIER}
meta-misc = ${NERVES_FW_MISC}

mbr mbr-a {
    partition 0 {
        block-offset = ${BOOT_A_PART_OFFSET}
        block-count = ${BOOT_A_PART_COUNT}
        type = 0xc # FAT32
        boot = true
    }
    partition 1 {
        block-offset = ${ROOTFS_A_PART_OFFSET}
        block-count = ${ROOTFS_A_PART_COUNT}
        type = 0x83 # Linux
    }
    partition 2 {
        block-offset = ${APP_PART_OFFSET}
        block-count = ${APP_PART_COUNT}
        type = 0x83 # Linux
        expand = true
    }
    # partition 3 is unused
}

mbr mbr-b {
    partition 0 {
        block-offset = ${BOOT_B_PART_OFFSET}
        block-count = ${BOOT_B_PART_COUNT}
        type = 0xc # FAT32
        boot = true
    }
    partition 1 {
        block-offset = ${ROOTFS_B_PART_OFFSET}
        block-count = ${ROOTFS_B_PART_COUNT}
        type = 0x83 # Linux
    }
    partition 2 {
        block-offset = ${APP_PART_OFFSET}
        block-count = ${APP_PART_COUNT}
        type = 0x83 # Linux
        expand = true
    }
    # partition 3 is unused
}

# Location where installed firmware information is stored.
# While this is called "u-boot", u-boot isn't involved in this
# setup. It just provides a convenient key/value store format.
uboot-environment uboot-env {
    block-offset = ${UBOOT_ENV_OFFSET}
    block-count = ${UBOOT_ENV_COUNT}
}

##
# factory-reset
##
task factory-reset {
    on-init {
        info("Erasing all writable data")
        # Trim may not work on MicroSD card, so don't rely on it
        trim(${APP_PART_OFFSET}, ${APP_PART_COUNT})
        raw_memset(${APP_PART_OFFSET}, 256, 0xff)
    }
}

##
# prevent-revert
#
# Pass `--enable-trim` to also clear out the partition that no longer should be used.
##
task prevent-revert.a {
    # Check that we're running on B
    require-partition-offset(0, ${BOOT_B_PART_OFFSET})
    require-partition-offset(1, ${ROOTFS_B_PART_OFFSET})
    require-uboot-variable(uboot-env, "nerves_fw_active", "b")

    on-init {
        info("Preventing reverts to partition A")
        # Remove U-Boot variables that fwup uses to allow reverting images
        uboot_unsetenv(uboot-env, "a.nerves_fw_platform")
        uboot_unsetenv(uboot-env, "a.nerves_fw_architecture")
        # Clear out the old image using TRIM. This requires --enable-trim
        trim(${ROOTFS_A_PART_OFFSET}, ${ROOTFS_A_PART_COUNT})
        trim(${BOOT_A_PART_OFFSET}, ${BOOT_A_PART_COUNT})
    }
}
task prevent-revert.b {
    # Check that we're running on A
    require-partition-offset(0, ${BOOT_A_PART_OFFSET})
    require-partition-offset(1, ${ROOTFS_A_PART_OFFSET})
    require-uboot-variable(uboot-env, "nerves_fw_active", "a")

    on-init {
        info("Preventing reverts to partition B")
        # Remove U-Boot variables that fwup uses to allow reverting images
        uboot_unsetenv(uboot-env, "b.nerves_fw_platform")
        uboot_unsetenv(uboot-env, "b.nerves_fw_architecture")
        # Clear out the image using TRIM. This requires --enable-trim
        trim(${ROOTFS_B_PART_OFFSET}, ${ROOTFS_B_PART_COUNT})
        trim(${BOOT_B_PART_OFFSET}, ${BOOT_B_PART_COUNT})
    }
}
task prevent-revert.fail {
    on-init {
        error("Error detecting active partition")
    }
}

##
# revert
##
task revert.a {
    # This task reverts to the A partition, so check that we're running on B
    require-partition-offset(0, ${BOOT_B_PART_OFFSET})
    require-partition-offset(1, ${ROOTFS_B_PART_OFFSET})
    require-uboot-variable(uboot-env, "nerves_fw_active", "b")

    # Verify that partition A has the expected platform/architecture
    require-uboot-variable(uboot-env, "a.nerves_fw_platform", "${NERVES_FW_PLATFORM}")
    require-uboot-variable(uboot-env, "a.nerves_fw_architecture", "${NERVES_FW_ARCHITECTURE}")

    on-init {
        info("Reverting to partition A")

	# Switch over
        uboot_setenv(uboot-env, "nerves_fw_active", "a")
        mbr_write(mbr-a)
    }
}

task revert.b {
    # This task reverts to the B partition, so check that we're running on A
    require-partition-offset(0, ${BOOT_A_PART_OFFSET})
    require-partition-offset(1, ${ROOTFS_A_PART_OFFSET})
    require-uboot-variable(uboot-env, "nerves_fw_active", "a")

    # Verify that partition B has the expected platform/architecture
    require-uboot-variable(uboot-env, "b.nerves_fw_platform", "${NERVES_FW_PLATFORM}")
    require-uboot-variable(uboot-env, "b.nerves_fw_architecture", "${NERVES_FW_ARCHITECTURE}")

    on-init {
        info("Reverting to partition B")

	# Switch over
        uboot_setenv(uboot-env, "nerves_fw_active", "b")
        mbr_write(mbr-b)
    }
}

task revert.unexpected.a {
    require-uboot-variable(uboot-env, "a.nerves_fw_platform", "${NERVES_FW_PLATFORM}")
    require-uboot-variable(uboot-env, "a.nerves_fw_architecture", "${NERVES_FW_ARCHITECTURE}")
    on-init {
        # Case where A is good, and the desire is to go to B.
        error("It doesn't look like there's anything to revert to in partition B.")
    }
}
task revert.unexpected.b {
    require-uboot-variable(uboot-env, "b.nerves_fw_platform", "${NERVES_FW_PLATFORM}")
    require-uboot-variable(uboot-env, "b.nerves_fw_architecture", "${NERVES_FW_ARCHITECTURE}")
    on-init {
        # Case where B is good, and the desire is to go to A.
        error("It doesn't look like there's anything to revert to in partition A.")
    }
}

task revert.wrongplatform {
    on-init {
        error("Expecting platform=${NERVES_FW_PLATFORM} and architecture=${NERVES_FW_ARCHITECTURE}")
    }
}

##
# status
#
# Run "fwup /usr/share/fwup/ops.fw -t status -d /dev/rootdisk0 -q -U" to check the status.
##
task status.aa {
    require-path-at-offset("/", ${ROOTFS_A_PART_OFFSET})
    require-uboot-variable(uboot-env, "nerves_fw_active", "a")
    on-init { info("a") }
}
task status.ab {
    require-path-at-offset("/", ${ROOTFS_A_PART_OFFSET})
    require-uboot-variable(uboot-env, "nerves_fw_active", "b")
    on-init { info("a->b") }
}
task status.bb {
    require-path-at-offset("/", ${ROOTFS_B_PART_OFFSET})
    require-uboot-variable(uboot-env, "nerves_fw_active", "b")
    on-init { info("b") }
}
task status.ba {
    require-path-at-offset("/", ${ROOTFS_B_PART_OFFSET})
    require-uboot-variable(uboot-env, "nerves_fw_active", "a")
    on-init { info("b->a") }
}
task status.fail {
    on-init { error("fail") }
}

##
# validate
#
# The fwup configuration for this device always validates, so this doesn't do anything.
##
task validate {
    on-init {
        info("Validate")
        uboot_setenv(uboot-env, "nerves_fw_validated", "1")
    }
}