mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 18:21:39 +01:00
Andrew Cooper
d661611d08
c/s a3a99df44 "docs/cmdline: Rewrite the cpuid_mask_* section" completely
forgot about how markdown gets rendered to HTML (as opposed to PDF), because
we use different translators depending on the destination format.
markdown and pandoc are very similar markup languages, but a couple of details
about pandoc cause it to have far more user-friendly inline markup.
Switch all markdown documents to be pandoc (so we are using a single
translator, and therefore a single flavour of markdown), which fixes the
rendered docs on xenbits.xen.org/docs.
While changing the format, fix the remainder of the escaped underscores in the
same mannor as the previous patch. The two problem cases here are __LINE__
and __FILE__ where the first underscore still needs escaping.
In addition, dmop.markdown and dom0less.markdown didn't used to get processed,
as only .markdown files in the misc/ directory got considered.
dom0less.pandoc gets picked up automatically now, due to being in the
features/ directory, but designs/ needs adding to the pandoc directory list
for dmop.pandoc to get processed.
While edting in appropriate areas, take the opportunity to fix some markup to
the surrounding style, and drop trailing whitespace.
No change in content - only formatting. This results in the text being easier
to read and grep.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
58 lines
2.0 KiB
Plaintext
58 lines
2.0 KiB
Plaintext
# Xen PV Drivers lifecycle
|
|
|
|
## Purpose
|
|
|
|
Getting new PV drivers accepted in Xen, upstream code bases, and ABI
|
|
stable in the quickest and most efficient way possible.
|
|
|
|
|
|
## Design Phase
|
|
|
|
The first step toward acceptance of a new PV protocol is to write a
|
|
design document and send it to xen-devel. It should cover the xenstore
|
|
handshake mechanism, the ABI, how the protocol works and anything else
|
|
which is required to write an implementation of it. The usage of C-like
|
|
structs to describe language and platform agnostic protocols is
|
|
discouraged.
|
|
|
|
An attempt should be made to design the ABI such that it will be OS
|
|
agnostic, that future versions will not need to introduce
|
|
backward-incompatible changes, and so on; but these are not yet hard
|
|
requirements.
|
|
|
|
After the high level design of the protocol has been discussed and
|
|
agreed, the document is committed to xen.git.
|
|
|
|
|
|
## Prototype Stage
|
|
|
|
The contributor sends patches to implement the PV drivers for the new
|
|
protocol to the relevant open source mailing lists, such as LKML,
|
|
qemu-devel and xen-devel.
|
|
|
|
The code is expected to work, be good quality and faithfully implement
|
|
the spec. However, there are no promises about ABI and cross-platform
|
|
compatibility yet.
|
|
|
|
After careful review by the relevant maintainers, the code is committed
|
|
to the upstream code bases. The drivers are considered experimental.
|
|
|
|
|
|
## Production Stage
|
|
|
|
The quality of the drivers and the spec is improved. Bugs are fixed.
|
|
The protocol version is likely bumped. More testing leads to confidence
|
|
that the spec and the drivers are ready for production usage. Promises
|
|
about backward compatibility and cross-platform compatibility are
|
|
clearly spelled out.
|
|
|
|
|
|
## How to move forward from a stage to the next
|
|
|
|
The PV protocols Czar is responsible for determining the transitions
|
|
between stages. Our governance principles specify "lazy consensus" for
|
|
most things. It applies to this case too. New PV protocols should move
|
|
from one stage to the next within a reasonable time frame unless someone
|
|
has specific technical objections and voices them in a responsive
|
|
manner.
|