[Skiboot] OPAL Spec and conformance

[Stewart Smith]

Hi all,

This is something I'm sending both to the System Software Workgroup at
OpenPower fonudation and the skiboot list as it's relevant to both
audiences.

SYSSW people: note that the skiboot list is *public* to the world.

There is a need to have an OPAL Specification as part of the OpenPower
effort along with a conformance test suite.

Goal:
- OPAL API specification (including device-tree)
  - i.e. what host OS interacts with
- spec for petitboot environment
  - i.e. how you can boot an OS, what filesystems/device drivers are
  supported.

The first goal should be suitably complete so that somebody could
implement an OS or re-implement skiboot without having to look at the
source for Linux or skiboot and yet remain compatible.


Current state
-------------

We have:
- skiboot/doc/opal-api
  - incomplete
- skiboot/doc/device-tree
  - incomplete
  - much is "same as others" but not necessarily written down anywhere
- old internal wiki pages
  - I'm gradually going through these and extracting them out, very
    raw, so that others can easily use them as a starting point.
  - I'm pushing (as we speak) a bunch of documentation into the skiboot
    repo from these old pages, along with suitable warnings that the
    docs should be taking with a *giant* grain of salt until someone
    does a second pass.

The TODO list
-------------
- device tree
  - somebody needs to go and find everything that isn't already
    specified either in linux kernel dt docs or skiboot docs.
  - after that, we have a TODO list for DT documentation
- OPAL calls
  - OPAL_LAST is currently 115, we have about 25 with *any*
    documentation currently
- OPAL messages
- environment for skiboot payload
- come up with a plan to document and standardize petitboot environment
  - (i.e. what can you boot from. XFS? ext4?)


It'd be great if someone could put their hand up for *any* of these
tasks, especially good if you just pick an OPAL call or a part of the
device tree.