Versioning Scheme of skiboot

History

For roughly the first six months of public life, skiboot just presented a git SHA1 as a version “number”. This was “user visible” in two places:

  1. /sys/firmware/opal/msglog the familiar SkiBoot 71664fd-dirty starting... message

  2. device tree: /proc/device-tree/ibm,opal/firmware/git-id

Builds were also referred to by date and by corresponding PowerKVM release. Clearly, this was unlikely to be good practice going forward.

As of skiboot-4.0, this scheme has changed and we now present a version string instead. This better addresses the needs of everybody who is building OpenPower systems.

Current practice

The version string is constructed from a few places and is designed to be highly informative about what you’re running. For the most part, it should be automatically constructed by the skiboot build system. The only times you need to do something is if you are a) making an upstream skiboot release or b) building firmware to release for your platform(s).

OPAL/skiboot has several consumers, for example:

  • IBM shipping POWER8 systems with an FSP (FW810.XX and future)

  • OpenPower

  • OpenPower partners manufacturing OpenPower systems

  • developers, test and support needing to understand what code a system is running

and there are going to be several concurrent maintained releases in the wild, likely build by different teams of people at different companies.

tl;dr; is you’re likely going to see version numbers like this (for the hypothetical platforms ‘ketchup’ and ‘mustard’):

  • skiboot-4.0-ketchup-0

  • skiboot-4.0-ketchup-1

  • skiboot-4.1-mustard-4

  • skiboot-4.1-ketchup-0

If you see extra things on the end of the version, then you’re running a custom build from a developer (e.g. skiboot-4.0-1-g23f147e-stewart-dirty-f42fc40 means something to us - explained below).

If you see less, for example skiboot-4.0, then you’re running a build directly out of the main git tree. Those producing OPAL builds for users must not ship like this, even if the tree is identical.

Here are the components of the version string from master:

skiboot-4.0-1-g23f147e-debug-occ-stewart-dirty-f42fc40
^       ^^^ ^  ^^^^^^^ ^-------^    ^      ^   ^^^^^^^
|        |  |     |        |        |      |      |
|        |  |     |        |         \    /        - 'git diff|sha1sum'
|        |  |     |        |          \  /
|        |  |     |        |            - built from a dirty tree of $USER
|        |  |     |        |
|        |  |     |         - $EXTRA_VERSION (optional)
|        |  |     |
|        |  |      - git SHA1 of commit built
|        |  |
|        |   - commits head of skiboot-4.0 tag
|        |
|         - skiboot version number ---\
|                                      >--  from  the 'skiboot-4.0' git tag
 - product name (always skiboot)   ---/

When doing a release for a particular platform, you are expected to create and tag a branch from master. For the (hypothetical) ketchup platform which is going to do a release based on skiboot-4.0, you would create a tag ‘skiboot-4.0-ketchup-0’ pointing to the same revision as the ‘skiboot-4.0’ tag and then make any additional modifications to skiboot that were not in the 4.0 release. So, you could ship a skiboot with the following version string:

skiboot-4.0-ketchup-1
^       ^^^ ^       ^
|        |  |       |
|        |  |        - revision for this platform
|        |  |
|        |  |
|        |   - Platform name/version
|        |
|         - skiboot version number
|
 - product name (always skiboot)

This version string tells your users to expect what is in skiboot-4.0 plus some revisions for your platform.

Practical Considerations

You MUST correctly tag your git tree for sensible version numbers to be generated. Look at the (generated) version.c file to confirm you’re building the correct version number. You will need annotated tags (git tag -a).

If your build infrastructure does not build skiboot from a git tree, you should specify SKIBOOT_VERSION as an environment variable (following this versioning scheme), otherwise the build will fail.