Firmware release procedures: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Update.)
No edit summary
 
(37 intermediate revisions by 17 users not shown)
Line 1: Line 1:
{{OLPC}}
{{Developers}}
{{Procedures}}
<noinclude>{{Translations}}</noinclude>

== Release procedure ==
== Release procedure ==


=== EC Firmware ===
Here is a draft of a BIOS release procedure.

===Stage one: EC:===


* Quanta e-mails EC release and changelog to the OLPC BIOS contact, signed and encrypted with PGP
* Quanta e-mails EC release and changelog to the OLPC BIOS contact, signed and encrypted with PGP
** see notes below
** see notes below
* Quanta and OLPC test this version of EC
* Quanta and OLPC test this version of EC
* When the new EC code has passed preliminary engineering tests, the OLPC firmware team (currently Mitch and Richard) puts it in http://dev.laptop.org/pub/ec/ .
* '''NOTE:''' Due to personnel changes at Quanta, the EC development is currently (as of late Q4 '07)being done by Richard Smith OLPC, for all practical purposes. We may want to revise these EC release procedures to reflect that reality.


===Stage two: Buildrom:===
=== Wireless Firmware ===


* Marvell sends new wireless firmware to OLPC.
* Pull EC release from http://dev.laptop.org/pub/ec/, check hashes
* The connectivity team evaluates it
* Update buildrom changelog and tag for release
* If it passes muster, the connectivity team puts it in http://dev.laptop.org/pub/firmware/libertas/
* Update SPI flash version string in buildrom binary
* The connectivity team announces/recommends it by sending email to the firmware and OS teams
* Create buildrom SRPM
* Build two flavors of binary RPM for the two RAM variants


=== Source Tree Stabilization ===
===Stage three: Testing:===


* The OFW source repository is at http://dev.laptop.org/git/users/quozl/openfirmware/
* announce build to BIOS team and Ray, release candidate testing begins
git clone git://dev.laptop.org/users/quozl/openfirmware
* test on a 256M board
* The firmware team develops and tests OFW changes with private (not-released, not-tracked) builds
* install the binary RPMs on Tinderbox machines
* Anyone can make a private build by checking out the source tree and running "make" in
* >12 hours of burn-in warm reboot testing on Tinderbox
:*cpu/x86/pc/olpc/build/ for XO-1,
* cold boot tests
:*cpu/x86/pc/olpc/via/build/ for XO-1.5,
** we need a cold boot solution; X10 doesn't seem to like the power at OLPC
:*cpu/arm/olpc/1.75/build for XO-1.75,
* After automated tests, send "Who has tested?" mail asking for problem reports
:*cpu/arm/olpc/3.0/build for XO-3,
* Release after twelve hours if no problem reports
:*cpu/arm/olpc/4.0/build for XO-4,
* To set the version number of a build, edit the files:
:*cpu/x86/pc/olpc/versions.fth for XO-1,
:*cpu/x86/pc/olpc/via/fw-version.fth for XO-1.5,
:*cpu/arm/olpc/1.75/fw-version.fth for XO-1.75,
:*cpu/arm/olpc/3.0/fw-version.fth for XO-3,
:*cpu/arm/olpc/4.0/fw-version.fth for XO-4,
* To select specific versions of EC, wireless firmware and touchscreen firmware for inclusion in a build, edit the same files or those nearby,
* Private versions are tested by the firmware team and selected others, typically by issuing "brown bag" releases distributed from the engineer's public_html directory on dev.laptop.org
* "Brown bag" private versions have names that are distinct from the normal release name schema. We add two letters to the previous release build. First letter is release engineer's name (r,m,j,p,d), second letter is a version (a-z). (Instead of editing fw-version.fth to make FW_MINOR be, e.g. 05ma, you can now just create a file "build/fw-suffix" containing ma . The first 2 characters of that file, if it exists, will be automatically appended to FW_MINOR.)
* "Real" release builds are only done after the firmware engineer is fairly certain that the most recent private version is solid and ready to be promoted to an official release.
* Prior to a release build, the firmware release engineer (e.g. Mitch or James) ensures that all approved changes have been checked in to the repository and that the versions refer to the correct EC and wireless firmware.
* The firmware release engineer edits a version file<!-- see the list above --> to set the firmware major and minor version strings to the new release number, then checks in the new version of that file.
* The firmware release engineer then builds a private version from the clean tree and tests it well.


===Stage four: Release:===
===Building a Release===


The firmware release engineer follows these steps:
* Release builds kept in a separate directory
* Update the version number in LB from release candidate to final
* Announce new build and hashes to devel-boards@ (requires moderation).


* firmware releases are built on "koji2" for ARM (discussion in progress), and "firmware" VM for x86, in in the directory "/home/firmware"
==Using PGP for EC code==


$ cd /home/firmware/
Download and run ftp://ftp.gnupg.org/gcrypt/binary/gnupg-w32cli-1.4.5.exe
$ ./newrelease qNxNN
$ cd ../qNxNN
$ ./pullme
$ ./buildme


* Do a quick "brick test" of the roms/<version>.rom file prior to making it public. Typically that just involves flashing the .rom file into a machine and making sure that it boots. You might also run ''test-all'' and ''autorun-mfg-tests''.
Download and install from http://www.mozilla.com/thunderbird/
* If something goes wrong, either a problem with the build process (e.g. a missing file that was not checked in properly) or a test failure on the .rom image, delete all copies of the .rom file, delete the new build directory, fix the source tree, and start over (this is not painful because ./pullme + ./buildme goes quickly).


See also [[Firmware/Building]].
Download Enigmail from http://www.mozilla-enigmail.org/downloads/enigmail-0.94.1.1-tb15-linux.xpi


===Issuing the Release===
Download http://dev.laptop.org/pub/ec/olpc-bios-key.pub

* After a clean build and a successful "brick test", make the release public with:

$ ./releaseme

* That copies the files from the build tree's "roms/" subdirectory to http://dev.laptop.org/pub/firmware/qNxNN/ and changes the symlink http://dev.laptop.org/pub/firmware/LATEST to point to it. LATEST is platform agnostic.
* Create a wiki page http://wiki.laptop.org/go/OLPC_Firmware_qNxNN, typically by copying the text of the previous release page and editing it as necessary.
* Edit the wiki page http://wiki.laptop.org/go/Firmware to create a new index line for the new release
* Send an announcement of the new release to devel@laptop.org

===Validating the Release===

* OLPC testers install the new release on some number of systems at 1CC and perhaps other test sites
* Assuming that the testing goes well, the ECO team sends mail to Quanta approving the use of the new release in production

===Withdrawing a Release===

If a dangerous bug is found in a release, it can be withdrawn. A dangerous bug is one that potentially results in bricked systems. To withdraw a release:

* Manually remove the release directory from http://dev.laptop.org/pub/firmware
* Edit http://wiki.laptop.org/go/Firmware and http://wiki.laptop.org/go/OLPC_Firmware_<release_name> to note that the release has been withdrawn and why.
* Remove the RPMs from the dropbox at dev.laptop.org:~rsmith/public_rpms/joyride
* Send mail to devel@laptop.org announcing the withdrawal and the reason

===Cherry-Picking Changes into an Incremental Release===

Releases are normally built from the master of the git repository, but there are cases where it is necessary to build from an older base version with a few "cherry-picked" changes from later checkins.

*identify the base revision to use, and place it in a ''revision'' file before the ''pullme'' step, (this can be a branch name or a git commit hash),
*place patch files in the directory in strict naming order, each ending in .patch,
*run ''pullme'' and proceed as normal,

==Using PGP for EC code==


=== For first release only: This is already done ===
Run Thunderbird


Download and install GPG4Win from http://www.gpg4win.org/download.html
Set up an e-mail account; when asked for name, use "Quanta OLPC BIOS"


Create a PGP key and get dwmw2 to sign it to verify that it is Quanta's.
Tools menu->Extensions:
* Click install, find downloaded Enigmail .xpi
* Restart Thunderbird


=== For subsequent releases ===
OpenPGP menu->Key Management:
* choose "No", don't use wizard
* Generate menu->new key pair:
** Enter passphrase twice
** Set key expiry to 2 months
** Supply key fingerprint to OLPC


Right-click on the EC binary and select the option to create a "detached signature", in plain text. It should create a separate file like 'ECv21.bin.asc', which looks something like this:
Tools menu->Account Settings->OpenPGP Security:
* OpenPGP support should be enabled
* Check "encrypt messages by default" and "sign encrypted messages by default"


-----BEGIN PGP SIGNATURE-----
Tools menu->Account Settings->Copies & folders:
Version: GnuPG v1.4.5 (MingW32)
* Uncheck "Place a copy in"
iD8DBQBFTxvGmfQ2bFM/BesRAoKzAJ0RNczipB pul5sEUR wCYIQvt /wCguqrV
5GRPVDpdH155fwsDwnu7B4M=
=URby
-----END PGP SIGNATURE-----


Send the EC binary as you normally would, and _also_ attach the separate signature file which is used to verify the binary.
Tools menu->Account Settings->Composition & Addressing:
There is no need to send another copy of the key itself (0x533F05EB.asc), because we already have that.
* Uncheck "Compose messages in HTML format"


Send the EC binary and signature (2 attachments) to software-team@laptop.org
OpenPGP menu->Key Management:
* File menu->import keys from file
* Choose the downloaded olpc-bios-key.pub file


[[Category:Hardware]]
Click "Write":
[[Category:Developers]]
* To: bios@laptop.org
[[Category:Firmware]]
* OpenPGP menu->"Send My Public Key"
[[Category:Procedures]]
* Attach changelog
[[Category:Build system]]
* Attach EC file
{{cleanup}}
* Click "Send"
* Choose "inline pgp"

Latest revision as of 05:32, 11 January 2016

  This page is monitored by the OLPC team.
  For Developers
  english | 한국어 HowTo [ID# 298346]  +/-  


Release procedure

EC Firmware

  • Quanta e-mails EC release and changelog to the OLPC BIOS contact, signed and encrypted with PGP
    • see notes below
  • Quanta and OLPC test this version of EC
  • When the new EC code has passed preliminary engineering tests, the OLPC firmware team (currently Mitch and Richard) puts it in http://dev.laptop.org/pub/ec/ .
  • NOTE: Due to personnel changes at Quanta, the EC development is currently (as of late Q4 '07)being done by Richard Smith OLPC, for all practical purposes. We may want to revise these EC release procedures to reflect that reality.

Wireless Firmware

  • Marvell sends new wireless firmware to OLPC.
  • The connectivity team evaluates it
  • If it passes muster, the connectivity team puts it in http://dev.laptop.org/pub/firmware/libertas/
  • The connectivity team announces/recommends it by sending email to the firmware and OS teams

Source Tree Stabilization

git clone git://dev.laptop.org/users/quozl/openfirmware
  • The firmware team develops and tests OFW changes with private (not-released, not-tracked) builds
  • Anyone can make a private build by checking out the source tree and running "make" in
  • cpu/x86/pc/olpc/build/ for XO-1,
  • cpu/x86/pc/olpc/via/build/ for XO-1.5,
  • cpu/arm/olpc/1.75/build for XO-1.75,
  • cpu/arm/olpc/3.0/build for XO-3,
  • cpu/arm/olpc/4.0/build for XO-4,
  • To set the version number of a build, edit the files:
  • cpu/x86/pc/olpc/versions.fth for XO-1,
  • cpu/x86/pc/olpc/via/fw-version.fth for XO-1.5,
  • cpu/arm/olpc/1.75/fw-version.fth for XO-1.75,
  • cpu/arm/olpc/3.0/fw-version.fth for XO-3,
  • cpu/arm/olpc/4.0/fw-version.fth for XO-4,
  • To select specific versions of EC, wireless firmware and touchscreen firmware for inclusion in a build, edit the same files or those nearby,
  • Private versions are tested by the firmware team and selected others, typically by issuing "brown bag" releases distributed from the engineer's public_html directory on dev.laptop.org
  • "Brown bag" private versions have names that are distinct from the normal release name schema. We add two letters to the previous release build. First letter is release engineer's name (r,m,j,p,d), second letter is a version (a-z). (Instead of editing fw-version.fth to make FW_MINOR be, e.g. 05ma, you can now just create a file "build/fw-suffix" containing ma . The first 2 characters of that file, if it exists, will be automatically appended to FW_MINOR.)
  • "Real" release builds are only done after the firmware engineer is fairly certain that the most recent private version is solid and ready to be promoted to an official release.
  • Prior to a release build, the firmware release engineer (e.g. Mitch or James) ensures that all approved changes have been checked in to the repository and that the versions refer to the correct EC and wireless firmware.
  • The firmware release engineer edits a version file to set the firmware major and minor version strings to the new release number, then checks in the new version of that file.
  • The firmware release engineer then builds a private version from the clean tree and tests it well.

Building a Release

The firmware release engineer follows these steps:

  • firmware releases are built on "koji2" for ARM (discussion in progress), and "firmware" VM for x86, in in the directory "/home/firmware"
$ cd /home/firmware/
$ ./newrelease qNxNN
$ cd ../qNxNN
$ ./pullme
$ ./buildme
  • Do a quick "brick test" of the roms/<version>.rom file prior to making it public. Typically that just involves flashing the .rom file into a machine and making sure that it boots. You might also run test-all and autorun-mfg-tests.
  • If something goes wrong, either a problem with the build process (e.g. a missing file that was not checked in properly) or a test failure on the .rom image, delete all copies of the .rom file, delete the new build directory, fix the source tree, and start over (this is not painful because ./pullme + ./buildme goes quickly).

See also Firmware/Building.

Issuing the Release

  • After a clean build and a successful "brick test", make the release public with:
 $ ./releaseme

Validating the Release

  • OLPC testers install the new release on some number of systems at 1CC and perhaps other test sites
  • Assuming that the testing goes well, the ECO team sends mail to Quanta approving the use of the new release in production

Withdrawing a Release

If a dangerous bug is found in a release, it can be withdrawn. A dangerous bug is one that potentially results in bricked systems. To withdraw a release:

Cherry-Picking Changes into an Incremental Release

Releases are normally built from the master of the git repository, but there are cases where it is necessary to build from an older base version with a few "cherry-picked" changes from later checkins.

  • identify the base revision to use, and place it in a revision file before the pullme step, (this can be a branch name or a git commit hash),
  • place patch files in the directory in strict naming order, each ending in .patch,
  • run pullme and proceed as normal,

Using PGP for EC code

For first release only: This is already done

Download and install GPG4Win from http://www.gpg4win.org/download.html

Create a PGP key and get dwmw2 to sign it to verify that it is Quanta's.

For subsequent releases

Right-click on the EC binary and select the option to create a "detached signature", in plain text. It should create a separate file like 'ECv21.bin.asc', which looks something like this: 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (MingW32)

iD8DBQBFTxvGmfQ2bFM/BesRAoKzAJ0RNczipB pul5sEUR wCYIQvt /wCguqrV
5GRPVDpdH155fwsDwnu7B4M=
=URby
-----END PGP SIGNATURE-----

Send the EC binary as you normally would, and _also_ attach the separate signature file which is used to verify the binary. There is no need to send another copy of the key itself (0x533F05EB.asc), because we already have that.

Send the EC binary and signature (2 attachments) to software-team@laptop.org

This page needs clean-up and editing for coherence, clarity, and completeness.

Please improve this article if you can.

Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=Firmware_release_procedures&oldid=298346"