* [virtio-comment] [RFC PATCH 1/8] README.md: convert html to proper Markdown format
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
@ 2020-03-27 10:37 ` Alex Bennée
2020-04-30 7:39 ` [virtio-comment] Re: [virtio-dev] " Michael S. Tsirkin
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 2/8] CONTRIBUTING.md: convert to proper MarkDown Alex Bennée
` (8 subsequent siblings)
9 siblings, 1 reply; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 10:37 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
README.md | 258 +++++++++++++++++++++---------------------------------
1 file changed, 100 insertions(+), 158 deletions(-)
diff --git a/README.md b/README.md
index 2bdf485..8bb10e0 100644
--- a/README.md
+++ b/README.md
@@ -1,173 +1,115 @@
-<div>
-<h2>README</h2>
+Members of the [OASIS Virtual I/O Device (VIRTIO) TC](https://www.oasis-open.org/committees/virtio/) create and manage technical content in this TC GitHub repository ( [https://github.com/oasis-tcs/virtio-spec](https://github.com/oasis-tcs/virtio-spec) ) as part of the TC's chartered work (_i.e._, the program of work and deliverables described in its [charter](https://www.oasis-open.org/committees/virtio/charter.php)).
-<p>Members of the <a href="https://www.oasis-open.org/committees/virtio/">OASIS Virtual I/O Device (VIRTIO) TC</a> create and manage technical content in this TC GitHub repository ( <a href="https://github.com/oasis-tcs/virtio-spec">https://github.com/oasis-tcs/virtio-spec</a> ) as part of the TC's chartered work (<i>i.e.</i>, the program of work and deliverables described in its <a href="https://www.oasis-open.org/committees/virtio/charter.php">charter</a>).</p>
+OASIS TC GitHub repositories, as described in [GitHub Repositories for OASIS TC Members' Chartered Work](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work), are governed by the OASIS [TC Process](https://www.oasis-open.org/policies-guidelines/tc-process), [IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr), and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from [OASIS Open Repositories](https://www.oasis-open.org/resources/open-repositories), which are used for development of open source [licensed](https://www.oasis-open.org/resources/open-repositories/licenses) content.
-<p>OASIS TC GitHub repositories, as described in <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">GitHub Repositories for OASIS TC Members' Chartered Work</a>, are governed by the OASIS <a href="https://www.oasis-open.org/policies-guidelines/tc-process">TC Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/ipr">IPR Policy</a>, and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from <a href="https://www.oasis-open.org/resources/open-repositories">OASIS Open Repositories</a>, which are used for development of open source <a href="https://www.oasis-open.org/resources/open-repositories/licenses">licensed</a> content.</p>
-</div>
+### Description
-<div>
-<h3>Description</h3>
+This repository includes the [authoritative source](https://github.com/oasis-tcs/virtio-spec/releases) of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine — and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms.
-<p>This repository includes the <a href="https://github.com/oasis-tcs/virtio-spec/releases">authoritative source</a> of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine — and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms. </p>
+The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.
-<p>The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.</p>
-</div>
+### Contributions
-<div>
-<h3>Contributions</h3>
-<p>As stated in this repository's <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING file</a>, contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and <a href="https://www.oasis-open.org/join/participation-instructions">participate</a> in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
-</div>
+As stated in this repository's [CONTRIBUTING file](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md), contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and [participate](https://www.oasis-open.org/join/participation-instructions) in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
+### Licensing
+Please see the [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file.
-<div>
-<h3>Licensing</h3>
-<p>Please see the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file.</p>
-</div>
+### Further Description of this Repository
-<div>
+#### Building Instructions
-<h3>Further Description of this Repository</h3>
-<h4>Building Instructions</h4>
-Authoritative version of the specification is maintained in the
-TeX document format. PDF and HTML versions are made available for
-ease of use and review.
-In order to build the HTML and PDF versions of the spec you will need the
-TeX document production system.
-The easiest way to get it up and running is probably by installing
-<a href="https://www.tug.org/texlive/">Tex-Live</a>.
+Authoritative version of the specification is maintained in the TeX document format. PDF and HTML versions are made available for ease of use and review. In order to build the HTML and PDF versions of the spec you will need the TeX document production system. The easiest way to get it up and running is probably by installing [Tex-Live](https://www.tug.org/texlive/).
+
+Installation cheat sheet:
+
+Fedora:
+
+`sudo dnf install texlive-scheme-full`
-<dl>Installation cheat sheet:
-<dt>Fedora:</dt>
-<dd>
-<code>
-sudo dnf install texlive-scheme-full
-</code></dd>
-<dt>
Ubuntu and other Debian derivatives:
-</dt>
-<dd>
-<code>
-sudo apt-get install texlive-full
-</code></dd>
-<dt>OSX:<dt>
-<dd>OSX users don't need to install Tex-Live because they already have
-<a href="http://www.tug.org/mactex/">MacTeX</a> installed.
-</dd>
-</dl>
-<dl>The build process generates a ZIP package file including the
-original TeX sources, as well as HTML and PDF formatted
-versions of the specification.
-<dt>To generate the ZIP package, run:<dt>
-<dd>
-<code>
-./makeall.sh
-</code>
-</dd>
-<dt>Troubleshooting notes:</dt>
-<dd> PDFs of the specification can be generated with
-either MicroSoft's Core fonts for the Web: Arial and Courier New,
-or Liberation fonts: Liberation Sans and Liberation Mono.
-Most systems come with one of these two variants included:
-should you get an error message about missing fonts,
-you will need to downloads and install one of the above
-font packages.
-<dd>
-</dl>
-<h4>Providing Feedback</h4>
-Feedback must be provided the <strong>virtio-comment</strong> mailing list,
-and archived in the mailing list archives.
-<p>See <A
-HREF="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback">
-https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback</A>
-<p>Note that only plain text part of the message is archived, and all
-attachments are stripped. Accordingly, messages sent to the
-mailing list should use text/plain encoding and not
-have any attachments.
-<p>The preferred form of providing feedback is in form of a patch.
-A patch can be generated and sent by cloning the spec repository,
-creating a commit, formatting it as a patch and then sending it.
-For example:
-<code>
-<p>
-git clone https://github.com/oasis-tcs/virtio-spec.git<br>
-... edit spec text, and save ...<br>
-<p>
-git commit -a<br>
-... describe the proposed change, in the following format:<br>
-single line summary<br>
-<br>
-detailed description, including motivation for the change<br>
-<br>
-Signed-off-by: Name <email><br>
-... then save and close the editor ... <br>
-<p>
-git format-patch -o proposal1/ HEAD~1..<br>
-... generates a new directory proposal1/ and a file starting with 0001- ...<br>
-<p>
-git send-email --to=virtio-comment@lists.oasis-open.org proposal1/0001-*
-</code>
-<h4>Note for TC Members</h4>
-<p>TC Members should review TC specific
-process rules under "Further Description of this Repository"
-in <A
-HREF="https://github.com/oasis-tcs/virtio-admin">https://github.com/oasis-tcs/virtio-admin</A>.
-
-</div>
-<h4>Implementation discussion</h4>
-Implementation discussion should take place on the <strong>virtio-dev</strong> mailing list,
-and be archived in the mailing list archives.
-<p>See <A
-HREF="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback">
-https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback</A>
-<p>This is the correct list to copy on Linux virtio UAPI change proposals.
-<p>Note that only the plain text part of the message is archived, and all
-attachments are stripped. Accordingly, messages sent to the
-mailing list should use text/plain encoding and not
-have any attachments.
-<h4>Use of github issues</h4>
-Note: according to the virtio TC rules, all official TC communication
-is taking place on one of the TC mailing lists.
-In particular, all comments must be provided on
-one of the TC mailing lists. Accordingly, the TC will not respond
-to comments provided in github issues: github issues are
-used solely to track integration of comments into the
-specification.<p>
+
+`sudo apt-get install texlive-full`
+
+OSX:
+
+OSX users don't need to install Tex-Live because they already have [MacTeX](http://www.tug.org/mactex/) installed.
+
+The build process generates a ZIP package file including the original TeX sources, as well as HTML and PDF formatted versions of the specification.
+
+To generate the ZIP package, run:
+
+`./makeall.sh`
+
+Troubleshooting notes:
+
+PDFs of the specification can be generated with either MicroSoft's Core fonts for the Web: Arial and Courier New, or Liberation fonts: Liberation Sans and Liberation Mono. Most systems come with one of these two variants included: should you get an error message about missing fonts, you will need to downloads and install one of the above font packages.
+
+#### Providing Feedback
+
+Feedback must be provided the **virtio-comment** mailing list, and archived in the mailing list archives.
+
+See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=virtio#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback)
+
+Note that only plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
+
+The preferred form of providing feedback is in form of a patch. A patch can be generated and sent by cloning the spec repository, creating a commit, formatting it as a patch and then sending it. For example:
+
+`git clone https://github.com/oasis-tcs/virtio-spec.git
+... edit spec text, and save ...
+`
+
+`git commit -a
+... describe the proposed change, in the following format:
+single line summary
+
+detailed description, including motivation for the change
+
+Signed-off-by: Name <email>
+... then save and close the editor ...
+`
+
+`git format-patch -o proposal1/ HEAD~1..
+... generates a new directory proposal1/ and a file starting with 0001- ...
+`
+
+`git send-email --to=virtio-comment@lists.oasis-open.org proposal1/0001-*`
+
+#### Note for TC Members
+
+TC Members should review TC specific process rules under "Further Description of this Repository" in [https://github.com/oasis-tcs/virtio-admin](https://github.com/oasis-tcs/virtio-admin).
+
+#### Implementation discussion
+
+Implementation discussion should take place on the **virtio-dev** mailing list, and be archived in the mailing list archives.
+
+See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=virtio#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback)
+
+This is the correct list to copy on Linux virtio UAPI change proposals.
+
+Note that only the plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
+
+#### Use of github issues
+
+Note: according to the virtio TC rules, all official TC communication is taking place on one of the TC mailing lists. In particular, all comments must be provided on one of the TC mailing lists. Accordingly, the TC will not respond to comments provided in github issues: github issues are used solely to track integration of comments into the specification.
+
To request a TC vote on resolving a specific comment:
-<ol>
-<li>Create a github issue, or edit an existing issue, with
-a short summary of the comment.
-The issue MUST specify
-the link to the latest proposal in the TC mailing list
-archives. <em>Note:</em> the link MUST be in the issue description itself -
-<em>not</em> in the comments.</li>
-<li>Reply by email to the comment email, requesting that the TC vote
-on resolving the issue.
-The mail requesting the vote should include the following, on a line by itself:<br>
-<code>
-Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN
-</code>
-(NNN is the issue number)</li>
-<li>Please make sure to allow time for review between posting a comment
-and asking for a vote. </li>
-</ol>
-<h4>TC standing rules</h4>
+
+1. Create a github issue, or edit an existing issue, with a short summary of the comment. The issue MUST specify the link to the latest proposal in the TC mailing list archives. _Note:_ the link MUST be in the issue description itself - _not_ in the comments.
+2. Reply by email to the comment email, requesting that the TC vote on resolving the issue. The mail requesting the vote should include the following, on a line by itself:
+ `Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN` (NNN is the issue number)
+3. Please make sure to allow time for review between posting a comment and asking for a vote.
+
+#### TC standing rules
+
The TC adopted the following standing rule:
-<p>
-<em>
-Minor cleanups, including editorial formatting changes, spelling
-and typo fixes can be committed directly into git for approval as
-part of the next specification approval ballot.
-</em>
-<ol>
-<li>To request such a commit, reply by email to the comment email, requesting that the
-issue is resolved under the minor cleanups standing rule.
-</li>
-<li>Please make sure to allow time for review between posting a comment
-and asking for a commit. </li>
-</ol>
-
-<h3>Contact</h3>
-<p>Please send questions or comments about <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">OASIS TC GitHub repositories</a> to <a href="mailto:robin@oasis-open.org">Robin Cover</a> and <a href="mailto:chet.ensign@oasis-open.org">Chet Ensign</a>. For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's <a href="https://www.oasis-open.org/committees/virtio/">home page</a>.</p>
-</div>
+
+_Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot._
+
+1. To request such a commit, reply by email to the comment email, requesting that the issue is resolved under the minor cleanups standing rule.
+2. Please make sure to allow time for review between posting a comment and asking for a commit.
+
+### Contact
+
+Please send questions or comments about [OASIS TC GitHub repositories](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work) to [Robin Cover](mailto:robin@oasis-open.org) and [Chet Ensign](mailto:chet.ensign@oasis-open.org). For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's [home page](https://www.oasis-open.org/committees/virtio/).
--
2.20.1
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply related [flat|nested] 17+ messages in thread* [virtio-comment] Re: [virtio-dev] [RFC PATCH 1/8] README.md: convert html to proper Markdown format
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 1/8] README.md: convert html to proper Markdown format Alex Bennée
@ 2020-04-30 7:39 ` Michael S. Tsirkin
0 siblings, 0 replies; 17+ messages in thread
From: Michael S. Tsirkin @ 2020-04-30 7:39 UTC (permalink / raw)
To: Alex Bennée; +Cc: Robin Cover, virtio-dev, virtio-comment
On Fri, Mar 27, 2020 at 10:37:56AM +0000, Alex Bennée wrote:
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
I don't mind, but OASIS admins asked us to keep the boiler plate as is.
I assume it's fine as it's just re-formatting. Cc Robin Cover to make
sure.
> ---
> README.md | 258 +++++++++++++++++++++---------------------------------
> 1 file changed, 100 insertions(+), 158 deletions(-)
>
> diff --git a/README.md b/README.md
> index 2bdf485..8bb10e0 100644
> --- a/README.md
> +++ b/README.md
> @@ -1,173 +1,115 @@
> -<div>
> -<h2>README</h2>
> +Members of the [OASIS Virtual I/O Device (VIRTIO) TC](https://www.oasis-open.org/committees/virtio/) create and manage technical content in this TC GitHub repository ( [https://github.com/oasis-tcs/virtio-spec](https://github.com/oasis-tcs/virtio-spec) ) as part of the TC's chartered work (_i.e._, the program of work and deliverables described in its [charter](https://www.oasis-open.org/committees/virtio/charter.php)).
>
> -<p>Members of the <a href="https://www.oasis-open.org/committees/virtio/">OASIS Virtual I/O Device (VIRTIO) TC</a> create and manage technical content in this TC GitHub repository ( <a href="https://github.com/oasis-tcs/virtio-spec">https://github.com/oasis-tcs/virtio-spec</a> ) as part of the TC's chartered work (<i>i.e.</i>, the program of work and deliverables described in its <a href="https://www.oasis-open.org/committees/virtio/charter.php">charter</a>).</p>
> +OASIS TC GitHub repositories, as described in [GitHub Repositories for OASIS TC Members' Chartered Work](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work), are governed by the OASIS [TC Process](https://www.oasis-open.org/policies-guidelines/tc-process), [IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr), and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from [OASIS Open Repositories](https://www.oasis-open.org/resources/open-repositories), which are used for development of open source [licensed](https://www.oasis-open.org/resources/open-repositories/licenses) content.
>
> -<p>OASIS TC GitHub repositories, as described in <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">GitHub Repositories for OASIS TC Members' Chartered Work</a>, are governed by the OASIS <a href="https://www.oasis-open.org/policies-guidelines/tc-process">TC Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/ipr">IPR Policy</a>, and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from <a href="https://www.oasis-open.org/resources/open-repositories">OASIS Open Repositories</a>, which are used for development of open source <a href="https://www.oasis-open.org/resources/open-repositories/licenses">licensed</a> content.</p>
> -</div>
> +### Description
>
> -<div>
> -<h3>Description</h3>
> +This repository includes the [authoritative source](https://github.com/oasis-tcs/virtio-spec/releases) of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine — and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms.
>
> -<p>This repository includes the <a href="https://github.com/oasis-tcs/virtio-spec/releases">authoritative source</a> of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine — and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms. </p>
> +The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.
>
> -<p>The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.</p>
> -</div>
> +### Contributions
>
> -<div>
> -<h3>Contributions</h3>
> -<p>As stated in this repository's <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING file</a>, contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and <a href="https://www.oasis-open.org/join/participation-instructions">participate</a> in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
> -</div>
> +As stated in this repository's [CONTRIBUTING file](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md), contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and [participate](https://www.oasis-open.org/join/participation-instructions) in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
>
> +### Licensing
>
> +Please see the [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file.
>
> -<div>
> -<h3>Licensing</h3>
> -<p>Please see the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file.</p>
> -</div>
> +### Further Description of this Repository
>
> -<div>
> +#### Building Instructions
>
> -<h3>Further Description of this Repository</h3>
> -<h4>Building Instructions</h4>
> -Authoritative version of the specification is maintained in the
> -TeX document format. PDF and HTML versions are made available for
> -ease of use and review.
> -In order to build the HTML and PDF versions of the spec you will need the
> -TeX document production system.
> -The easiest way to get it up and running is probably by installing
> -<a href="https://www.tug.org/texlive/">Tex-Live</a>.
> +Authoritative version of the specification is maintained in the TeX document format. PDF and HTML versions are made available for ease of use and review. In order to build the HTML and PDF versions of the spec you will need the TeX document production system. The easiest way to get it up and running is probably by installing [Tex-Live](https://www.tug.org/texlive/).
> +
> +Installation cheat sheet:
> +
> +Fedora:
> +
> +`sudo dnf install texlive-scheme-full`
>
> -<dl>Installation cheat sheet:
> -<dt>Fedora:</dt>
> -<dd>
> -<code>
> -sudo dnf install texlive-scheme-full
> -</code></dd>
> -<dt>
> Ubuntu and other Debian derivatives:
> -</dt>
> -<dd>
> -<code>
> -sudo apt-get install texlive-full
> -</code></dd>
> -<dt>OSX:<dt>
> -<dd>OSX users don't need to install Tex-Live because they already have
> -<a href="http://www.tug.org/mactex/">MacTeX</a> installed.
> -</dd>
> -</dl>
> -<dl>The build process generates a ZIP package file including the
> -original TeX sources, as well as HTML and PDF formatted
> -versions of the specification.
> -<dt>To generate the ZIP package, run:<dt>
> -<dd>
> -<code>
> -./makeall.sh
> -</code>
> -</dd>
> -<dt>Troubleshooting notes:</dt>
> -<dd> PDFs of the specification can be generated with
> -either MicroSoft's Core fonts for the Web: Arial and Courier New,
> -or Liberation fonts: Liberation Sans and Liberation Mono.
> -Most systems come with one of these two variants included:
> -should you get an error message about missing fonts,
> -you will need to downloads and install one of the above
> -font packages.
> -<dd>
> -</dl>
> -<h4>Providing Feedback</h4>
> -Feedback must be provided the <strong>virtio-comment</strong> mailing list,
> -and archived in the mailing list archives.
> -<p>See <A
> -HREF="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback">
> -https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback</A>
> -<p>Note that only plain text part of the message is archived, and all
> -attachments are stripped. Accordingly, messages sent to the
> -mailing list should use text/plain encoding and not
> -have any attachments.
> -<p>The preferred form of providing feedback is in form of a patch.
> -A patch can be generated and sent by cloning the spec repository,
> -creating a commit, formatting it as a patch and then sending it.
> -For example:
> -<code>
> -<p>
> -git clone https://github.com/oasis-tcs/virtio-spec.git<br>
> -... edit spec text, and save ...<br>
> -<p>
> -git commit -a<br>
> -... describe the proposed change, in the following format:<br>
> -single line summary<br>
> -<br>
> -detailed description, including motivation for the change<br>
> -<br>
> -Signed-off-by: Name <email><br>
> -... then save and close the editor ... <br>
> -<p>
> -git format-patch -o proposal1/ HEAD~1..<br>
> -... generates a new directory proposal1/ and a file starting with 0001- ...<br>
> -<p>
> -git send-email --to=virtio-comment@lists.oasis-open.org proposal1/0001-*
> -</code>
> -<h4>Note for TC Members</h4>
> -<p>TC Members should review TC specific
> -process rules under "Further Description of this Repository"
> -in <A
> -HREF="https://github.com/oasis-tcs/virtio-admin">https://github.com/oasis-tcs/virtio-admin</A>.
> -
> -</div>
> -<h4>Implementation discussion</h4>
> -Implementation discussion should take place on the <strong>virtio-dev</strong> mailing list,
> -and be archived in the mailing list archives.
> -<p>See <A
> -HREF="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback">
> -https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback</A>
> -<p>This is the correct list to copy on Linux virtio UAPI change proposals.
> -<p>Note that only the plain text part of the message is archived, and all
> -attachments are stripped. Accordingly, messages sent to the
> -mailing list should use text/plain encoding and not
> -have any attachments.
> -<h4>Use of github issues</h4>
> -Note: according to the virtio TC rules, all official TC communication
> -is taking place on one of the TC mailing lists.
> -In particular, all comments must be provided on
> -one of the TC mailing lists. Accordingly, the TC will not respond
> -to comments provided in github issues: github issues are
> -used solely to track integration of comments into the
> -specification.<p>
> +
> +`sudo apt-get install texlive-full`
> +
> +OSX:
> +
> +OSX users don't need to install Tex-Live because they already have [MacTeX](http://www.tug.org/mactex/) installed.
> +
> +The build process generates a ZIP package file including the original TeX sources, as well as HTML and PDF formatted versions of the specification.
> +
> +To generate the ZIP package, run:
> +
> +`./makeall.sh`
> +
> +Troubleshooting notes:
> +
> +PDFs of the specification can be generated with either MicroSoft's Core fonts for the Web: Arial and Courier New, or Liberation fonts: Liberation Sans and Liberation Mono. Most systems come with one of these two variants included: should you get an error message about missing fonts, you will need to downloads and install one of the above font packages.
> +
> +#### Providing Feedback
> +
> +Feedback must be provided the **virtio-comment** mailing list, and archived in the mailing list archives.
> +
> +See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=virtio#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback)
> +
> +Note that only plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
> +
> +The preferred form of providing feedback is in form of a patch. A patch can be generated and sent by cloning the spec repository, creating a commit, formatting it as a patch and then sending it. For example:
> +
> +`git clone https://github.com/oasis-tcs/virtio-spec.git
> +... edit spec text, and save ...
> +`
> +
> +`git commit -a
> +... describe the proposed change, in the following format:
> +single line summary
> +
> +detailed description, including motivation for the change
> +
> +Signed-off-by: Name <email>
> +... then save and close the editor ...
> +`
> +
> +`git format-patch -o proposal1/ HEAD~1..
> +... generates a new directory proposal1/ and a file starting with 0001- ...
> +`
> +
> +`git send-email --to=virtio-comment@lists.oasis-open.org proposal1/0001-*`
> +
> +#### Note for TC Members
> +
> +TC Members should review TC specific process rules under "Further Description of this Repository" in [https://github.com/oasis-tcs/virtio-admin](https://github.com/oasis-tcs/virtio-admin).
> +
> +#### Implementation discussion
> +
> +Implementation discussion should take place on the **virtio-dev** mailing list, and be archived in the mailing list archives.
> +
> +See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=virtio#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback)
> +
> +This is the correct list to copy on Linux virtio UAPI change proposals.
> +
> +Note that only the plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
> +
> +#### Use of github issues
> +
> +Note: according to the virtio TC rules, all official TC communication is taking place on one of the TC mailing lists. In particular, all comments must be provided on one of the TC mailing lists. Accordingly, the TC will not respond to comments provided in github issues: github issues are used solely to track integration of comments into the specification.
> +
> To request a TC vote on resolving a specific comment:
> -<ol>
> -<li>Create a github issue, or edit an existing issue, with
> -a short summary of the comment.
> -The issue MUST specify
> -the link to the latest proposal in the TC mailing list
> -archives. <em>Note:</em> the link MUST be in the issue description itself -
> -<em>not</em> in the comments.</li>
> -<li>Reply by email to the comment email, requesting that the TC vote
> -on resolving the issue.
> -The mail requesting the vote should include the following, on a line by itself:<br>
> -<code>
> -Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN
> -</code>
> -(NNN is the issue number)</li>
> -<li>Please make sure to allow time for review between posting a comment
> -and asking for a vote. </li>
> -</ol>
> -<h4>TC standing rules</h4>
> +
> +1. Create a github issue, or edit an existing issue, with a short summary of the comment. The issue MUST specify the link to the latest proposal in the TC mailing list archives. _Note:_ the link MUST be in the issue description itself - _not_ in the comments.
> +2. Reply by email to the comment email, requesting that the TC vote on resolving the issue. The mail requesting the vote should include the following, on a line by itself:
> + `Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN` (NNN is the issue number)
> +3. Please make sure to allow time for review between posting a comment and asking for a vote.
> +
> +#### TC standing rules
> +
> The TC adopted the following standing rule:
> -<p>
> -<em>
> -Minor cleanups, including editorial formatting changes, spelling
> -and typo fixes can be committed directly into git for approval as
> -part of the next specification approval ballot.
> -</em>
> -<ol>
> -<li>To request such a commit, reply by email to the comment email, requesting that the
> -issue is resolved under the minor cleanups standing rule.
> -</li>
> -<li>Please make sure to allow time for review between posting a comment
> -and asking for a commit. </li>
> -</ol>
> -
> -<h3>Contact</h3>
> -<p>Please send questions or comments about <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">OASIS TC GitHub repositories</a> to <a href="mailto:robin@oasis-open.org">Robin Cover</a> and <a href="mailto:chet.ensign@oasis-open.org">Chet Ensign</a>. For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's <a href="https://www.oasis-open.org/committees/virtio/">home page</a>.</p>
> -</div>
> +
> +_Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot._
> +
> +1. To request such a commit, reply by email to the comment email, requesting that the issue is resolved under the minor cleanups standing rule.
> +2. Please make sure to allow time for review between posting a comment and asking for a commit.
> +
> +### Contact
> +
> +Please send questions or comments about [OASIS TC GitHub repositories](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work) to [Robin Cover](mailto:robin@oasis-open.org) and [Chet Ensign](mailto:chet.ensign@oasis-open.org). For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's [home page](https://www.oasis-open.org/committees/virtio/).
> --
> 2.20.1
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply [flat|nested] 17+ messages in thread
* [virtio-comment] [RFC PATCH 2/8] CONTRIBUTING.md: convert to proper MarkDown
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 1/8] README.md: convert html to proper Markdown format Alex Bennée
@ 2020-03-27 10:37 ` Alex Bennée
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 3/8] LICENSE.md: convert html " Alex Bennée
` (7 subsequent siblings)
9 siblings, 0 replies; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 10:37 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
CONTRIBUTING.md | 22 +++++++---------------
1 file changed, 7 insertions(+), 15 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1330a98..f07cb32 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,20 +1,12 @@
-<div>
-<h2>Repository Contributions, Participation, and Public Access</h2>
+Repository Contributions, Participation, and Public Access
+----------------------------------------------------------
-<p><b>Who may Contribute?</b> Contributors to <a href="https://github.com/oasis-tcs/virtio-spec/">this repository</a> are expected to be <a href="https://www.oasis-open.org/policies-guidelines/oasis-defined-terms-2017-05-26#dMember">Members</a> of the
-<a href="https://www.oasis-open.org/committees/virtio/">OASIS Virtual I/O Device (VIRTIO) TC</a>, for any
-substantive contributions. Anyone wishing to <a href="https://www.oasis-open.org/org/faq#committee-participation">participate</a>
-in the TC's technical activity is invited to <a href="https://www.oasis-open.org/committees/join">join</a> as a TC Member.
-<i>Member</i> in this context means any TC role or office other than OASIS TC Observer, per
-<a href="https://www.oasis-open.org/policies-guidelines/tc-process#membership">TC Process</a>
-(Member, Voting Member, Persistent Non-Voting Member; Chair, Secretary...)</p>
+**Who may Contribute?** Contributors to [this repository](https://github.com/oasis-tcs/virtio-spec/) are expected to be [Members](https://www.oasis-open.org/policies-guidelines/oasis-defined-terms-2017-05-26#dMember) of the [OASIS Virtual I/O Device (VIRTIO) TC](https://www.oasis-open.org/committees/virtio/), for any substantive contributions. Anyone wishing to [participate](https://www.oasis-open.org/org/faq#committee-participation) in the TC's technical activity is invited to [join](https://www.oasis-open.org/committees/join) as a TC Member. _Member_ in this context means any TC role or office other than OASIS TC Observer, per [TC Process](https://www.oasis-open.org/policies-guidelines/tc-process#membership) (Member, Voting Member, Persistent Non-Voting Member; Chair, Secretary...)
-<p>Persons who are not TC members are invited to open issues and provide comments using this repository's <a href="https://github.com/oasis-tcs/virtio-spec/issues/new">GitHub Issues</a> tracking facility or using the
-TC's <a href="https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=virtio">comment list</a>. All such content created in GitHub Issues and/or posted to the TC's <a href="https://lists.oasis-open.org/archives/virtio-comment/">archived comment list</a> is governed by the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
+Persons who are not TC members are invited to open issues and provide comments using this repository's [GitHub Issues](https://github.com/oasis-tcs/virtio-spec/issues/new) tracking facility or using the TC's [comment list](https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=virtio). All such content created in GitHub Issues and/or posted to the TC's [archived comment list](https://lists.oasis-open.org/archives/virtio-comment/) is governed by the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
-<p><b>Use of Contributions</b>. As with all OASIS Technical Committee assets (TC <a href="https://wiki.oasis-open.org/">Wiki</a>, TC <a href="https://issues.oasis-open.org/secure/Dashboard.jspa">Issues Tracker</a>, TC <a href="https://lists.oasis-open.org/archives/">General Discussion List archives</a>, TC <a href="http://docs.oasis-open.org/">OASIS Library</a> assets), content placed into this GitHub repository is visible and publicly accessible. Subject to applicable <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">licensing</a> rules, the repository content may be re-used freely, including the creation and publication of derivative works.</p>
+**Use of Contributions**. As with all OASIS Technical Committee assets (TC [Wiki](https://wiki.oasis-open.org/), TC [Issues Tracker](https://issues.oasis-open.org/secure/Dashboard.jspa), TC [General Discussion List archives](https://lists.oasis-open.org/archives/), TC [OASIS Library](http://docs.oasis-open.org/) assets), content placed into this GitHub repository is visible and publicly accessible. Subject to applicable [licensing](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) rules, the repository content may be re-used freely, including the creation and publication of derivative works.
-<p><b>Cloning and forking</b>. May users clone and fork this repository? Yes. Just as versioned content maintained in any OASIS TC's <a href="https://tools.oasis-open.org/version-control/browse/">SVN/Subversion repository</a> may be checked out to a remote SVN repository and used by anyone, this GitHub repository may be forked or cloned for use by any party. Compare, <i>e.g.</i>, <tt>svn checkout https://tools.oasis-open.org/version-control/svn/dita/trunk/doctypes/ dita-doctypes</tt>.</p>
+**Cloning and forking**. May users clone and fork this repository? Yes. Just as versioned content maintained in any OASIS TC's [SVN/Subversion repository](https://tools.oasis-open.org/version-control/browse/) may be checked out to a remote SVN repository and used by anyone, this GitHub repository may be forked or cloned for use by any party. Compare, _e.g._, svn checkout https://tools.oasis-open.org/version-control/svn/dita/trunk/doctypes/ dita-doctypes.
-<p>Please see the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/README.md">README</a> for general description of this repository, and the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file for licensing.</p>
-</div>
+Please see the [README](https://github.com/oasis-tcs/virtio-spec/blob/master/README.md) for general description of this repository, and the [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file for licensing.
--
2.20.1
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply related [flat|nested] 17+ messages in thread* [virtio-comment] [RFC PATCH 3/8] LICENSE.md: convert html to proper MarkDown
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 1/8] README.md: convert html to proper Markdown format Alex Bennée
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 2/8] CONTRIBUTING.md: convert to proper MarkDown Alex Bennée
@ 2020-03-27 10:37 ` Alex Bennée
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 4/8] makeall.sh: add explicit shebang to script Alex Bennée
` (6 subsequent siblings)
9 siblings, 0 replies; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 10:37 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
LICENSE.md | 9 ++++-----
1 file changed, 4 insertions(+), 5 deletions(-)
diff --git a/LICENSE.md b/LICENSE.md
index ef558ec..600b966 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,7 +1,6 @@
-<div>
-<h2>License Terms</h2>
+License Terms
+-------------
-<p>Content in this GitHub code repository has been <a href="https://www.oasis-open.org/policies-guidelines/ipr#def-contribution">contributed</a> by OASIS TC Members, and is governed by the OASIS policies, including the <a href="https://www.oasis-open.org/policies-guidelines/ipr">Intellectual Property Rights (IPR) Policy</a>, the <a href="https://www.oasis-open.org/policies-guidelines/tc-process">Technical Committee (TC) Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/bylaws">Bylaws</a>, and the Technical Committee's choice of <a href="https://www.oasis-open.org/policies-guidelines/ipr#def-ipr-mode">IPR Mode</a> (<i>viz</i>, <a href="https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode">Non-Assertion Mode</a>), including any applicable <a href="https://www.oasis-open.org/committees/virtio/ipr.php">declarations</a>. Feedback from non-TC members, if any, is governed by the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
+Content in this GitHub code repository has been [contributed](https://www.oasis-open.org/policies-guidelines/ipr#def-contribution) by OASIS TC Members, and is governed by the OASIS policies, including the [Intellectual Property Rights (IPR) Policy](https://www.oasis-open.org/policies-guidelines/ipr), the [Technical Committee (TC) Process](https://www.oasis-open.org/policies-guidelines/tc-process), [Bylaws](https://www.oasis-open.org/policies-guidelines/bylaws), and the Technical Committee's choice of [IPR Mode](https://www.oasis-open.org/policies-guidelines/ipr#def-ipr-mode) (_viz_, [Non-Assertion Mode](https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode)), including any applicable [declarations](https://www.oasis-open.org/committees/virtio/ipr.php). Feedback from non-TC members, if any, is governed by the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
-<p>Description of this repository is presented in the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/README.md">README</a> file, and guidelines for contribution/participation are given in the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING</a> file.</p>
-</div>
+Description of this repository is presented in the [README](https://github.com/oasis-tcs/virtio-spec/blob/master/README.md) file, and guidelines for contribution/participation are given in the [CONTRIBUTING](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md) file.
--
2.20.1
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply related [flat|nested] 17+ messages in thread* [virtio-comment] [RFC PATCH 4/8] makeall.sh: add explicit shebang to script
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
` (2 preceding siblings ...)
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 3/8] LICENSE.md: convert html " Alex Bennée
@ 2020-03-27 10:37 ` Alex Bennée
2020-03-27 10:47 ` Cornelia Huck
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 5/8] Cleanup old changelog files Alex Bennée
` (5 subsequent siblings)
9 siblings, 1 reply; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 10:37 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
makeall.sh | 2 ++
1 file changed, 2 insertions(+)
diff --git a/makeall.sh b/makeall.sh
index 20f568e..37e6c34 100755
--- a/makeall.sh
+++ b/makeall.sh
@@ -1,3 +1,5 @@
+#!/bin/sh
+
export SPECDOC=${SPECDOC:-`cat REVISION`}
export DATESTR=${DATESTR:-`cat REVISION-DATE`}
./makezip.sh
--
2.20.1
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply related [flat|nested] 17+ messages in thread* [virtio-comment] [RFC PATCH 5/8] Cleanup old changelog files
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
` (3 preceding siblings ...)
2020-03-27 10:37 ` [virtio-comment] [RFC PATCH 4/8] makeall.sh: add explicit shebang to script Alex Bennée
@ 2020-03-27 10:38 ` Alex Bennée
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 6/8] Remove all mentioned of subversion Alex Bennée
` (4 subsequent siblings)
9 siblings, 0 replies; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 10:38 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
These are no longer included in the document although their contents
will be forever available in the repositories history.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
cl-cs01.tex | 86 ----
cl-cs02.tex | 52 ---
cl-cs03.tex | 328 ---------------
cl-cs04.tex | 134 -------
cl-csprd02.tex | 1043 ------------------------------------------------
cl-csprd03.tex | 400 -------------------
6 files changed, 2043 deletions(-)
delete mode 100644 cl-cs01.tex
delete mode 100644 cl-cs02.tex
delete mode 100644 cl-cs03.tex
delete mode 100644 cl-cs04.tex
delete mode 100644 cl-csprd02.tex
delete mode 100644 cl-csprd03.tex
diff --git a/cl-cs01.tex b/cl-cs01.tex
deleted file mode 100644
index 234e420..0000000
--- a/cl-cs01.tex
+++ /dev/null
@@ -1,86 +0,0 @@
-418 & 11 Aug 2014 & Michael S. Tsirkin & { Acknowledge input from
-Brian Foley
-
-See \ref{chap:Acknowledgements}
-}
- \\
-417 & 11 Aug 2014 & Pawel Moll & { VIRTIO-110: ARM's feedback for MMIO chapter, clarifications
-
-\begin{itemize}
- \item Extra clarifications for QueueReady and ConfigGeneration
- \item Added alignment requirement section, to formalise
- hidden assumptions about register accesses
-\end{itemize}
-
-See \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO
-Device Register Layout}, \ref{devicenormative:Virtio Transport
-Options / Virtio Over MMIO / MMIO Device Register Layout} and
-\ref{drivernormative:Virtio Transport
-Options / Virtio Over MMIO / MMIO Device Register Layout}
-}
- \\
-\hline
-\hline
-416 & 05 Aug 2014 & Pawel Moll & { VIRTIO-110: ARM's feedback for MMIO chapter, legacy section
-
-Make it clear that the legacy section is non-normative,
-removing all MUSTs.
-
-See \ref{sec:Virtio Transport Options / Virtio Over MMIO / Legacy
-interface}.
- } \\
-\hline
-415 & 05 Aug 2014 & Pawel Moll & { VIRTIO-110: ARM's feedback for MMIO chapter, trivial changes
-\begin{itemize}
-\item Typos and language mistakes in 4.2, 4.2.1, 4.2.2 and 4.2.2.2.
-\item Extra clarifications for InterruptACK.
-\end{itemize}
- } \\
-\hline
-414 & 04 Aug 2014 & Michael S. Tsirkin & { legacy: grammar fixup
-
-Legacy devices are "they" not "it".
-
-See \ref{sec:General Initialization And Device Operation / Device
-Initialization / Legacy Interface: Device Initialization}
-
-Resolves VIRTIO-113
- } \\
-\hline
-413 & 04 Aug 2014 & Michael S. Tsirkin & { legacy: consistently use past tense
-
-Paragraph with general description of feature negotiation
-for legacy devices mixed present and past tense.
-As rest of legacy sections all use past tense,
-fix the only instance of the present tense:
-s/do/did/ for consistency.
-
-It might be argued that legacy devices still have these
-properties so present tense is more appropriate, on the
-other hand, using the past tense helps stress the fact
-that current spec does not attempt to fully describe the legacy
-device/driver behaviour: this text is only here to serve as
-motivation for the transitional device/driver requirements.
-
-See \ref{sec:General Initialization And Device Operation / Device
-Initialization / Legacy Interface: Device Initialization}
-
-Resolves VIRTIO-112
- } \\
-\hline
-412 & 30 Jul 2014 & Michael S. Tsirkin & { VIRTIO-111: Fix minor typos
-
-Fix minor typos as reported in ARM's feedback.
-
-See \ref{drivernormative:Basic Facilities of a Virtio Device /
-Device Configuration Space}, \ref{sec:Basic Facilities of a
-Virtio Device / Device Configuration Space / Legacy Interface:
-Device Configuration Space}, \ref{sec:General Initialization And
-Device Operation / Device Operation / Supplying Buffers to The
-Device} and
-\ref{drivernormative:Device Types / Network Device / Device
-Operation / Control Virtqueue / Offloads State Configuration /
-Setting Offloads State}
- }
- \\
-\hline
diff --git a/cl-cs02.tex b/cl-cs02.tex
deleted file mode 100644
index 61aa6fd..0000000
--- a/cl-cs02.tex
+++ /dev/null
@@ -1,52 +0,0 @@
-448 & 22 Dec 2014 & Michael S. Tsirkin & {VIRTIO-120: virtio:
-fix used element size
-
-General ring description lists size for
-used ring elements as 4, it must be 8.
-
-See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
- } \\
-\hline
-449 & 22 Doc 2014 & Cornelia Huck & {VIRTIO-125: block: fixup section levels
- The specification for the configuration layout for block devices
- should be its own subsection as for all other devices and not be
- hidden beneath "Feature bits".
-
- The normative sections for device operation should appear under
- the device operation section.
-See \ref{sec:Device Types / Block Device / Device configuration
-layout}.
- } \\
-\hline
-450 & 22 Dec 2014 & Cornelia Huck & {VIRTIO-127: ccw: two-stage
-indicators for legacy devices
-
- Some legacy devices will support two-stage queue indicators
-and therefore
- won't reject CCW_CMD_SET_IND_ADAPTER. Note this.
-
-See \ref{sec:Virtio Transport Options / Virtio over channel I/O /
-Device Initialization / Setting Up Indicators / Legacy
-Interfaces: A Note on Setting Up Indicators}.
- } \\
-\hline
-452 & 22 Dec 2014 & Michael S. Tsirkin & {VIRTIO-115:
-formatting: escape {\textbackslash}ldots in lstlisting
-
- {\textbackslash}ldots does not work within lstlisting, the result is
- {\textbackslash}ldots verbatim in the PDF output.
-
- To fix, make \$ an escape character, and escape the sequence:
- \${\textbackslash}ldots\$
-
-See \ref{sec:Device Types / SCSI Host Device / Device Operation /
-Device Operation: controlq}.
-} \\
-\hline
-455,457 & 23 Dec 2014 & Michael S. Tsirkin & {acknowledgements: acknowledge dgilbert
-
- Acknowledge David Alan Gilbert for reporting VIRTIO-120.
-
-See \ref{chap:Acknowledgements}.
-} \\
-\hline
diff --git a/cl-cs03.tex b/cl-cs03.tex
deleted file mode 100644
index 72925ca..0000000
--- a/cl-cs03.tex
+++ /dev/null
@@ -1,328 +0,0 @@
-478 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-129: legacy:
-clean up virtqueue layout definitions
-
-Generalize "Legacy Interfaces: A Note on Virtqueue Layout" to allow
-for different alignment requirements. Have pci and ccw refer to that
-section for legacy devices. Remove the double definition of virtqueue
-alignment (which referred to legacy, but was not tagged as such) from
-the ccw section.
-See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues /
-Legacy Interfaces: A Note on Virtqueue Layout}, \ref{sec:Virtio
-Transport Options / Virtio Over PCI Bus / PCI-specific
-Initialization And Device Operation / Device Initialization /
-Virtqueue Configuration / Legacy Interface: A Note on Virtqueue
-Configuration} and \ref{sec:Virtio Transport Options / Virtio
-over channel I/O / Device Initialization / Configuring a
-Virtqueue / Legacy Interface: A Note on Configuring a Virtqueue}.
- } \\
-\hline
-479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-118:
-ccw: clarify basic channel commands
-
-"Basic channel commands" seems to be not as clear as it
-could, so let's spell out which channel commands we refer to.
-See \ref{sec:Virtio Transport Options / Virtio over channel I/O /
-Basic Concepts}.
-} \\
-\hline
-479 & 15 Mar 2015 & Cornelia Huck & {VIRTIO-116:
-ccw: allow WRITE_STATUS to fail
-
-We want to be able to fail setting a status on the device
-(e.g. FEATURES_OK if the device can't work with the features
-negotiated).
-The easiest way to do that is to allow the device to fail the
-WRITE_STATUS command by posting a command reject.
-See \ref{sec:Virtio Transport Options / Virtio over channel I/O /
-Device Initialization / Communicating Status Information}.
- } \\
-\hline
-485 & 15 Mar 2015 & Jason Wang & {VIRTIO-135:
-virtio-ring: comment fixup
-
-virtio_ring.h included with spec has this text:
-/* Support for avail_idx and used_idx fields */
-it should really refer to avail_event and used_event.
-See Appendix \ref{sec:virtio-queue.h}.
- } \\
-\hline
-486 & 15 Mar 2015 & Jason Wang & {VIRTIO-136:
-document idx field in virtqueue used ring
-
-Section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues
-/ The Virtqueue Used Ring} The Virtqueue Used Ring
-listed the idx field, but never documented it.
-See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues /
-The Virtqueue Used Ring}.
- } \\
-\hline
-487 & 15 Mar 2015 & Rusty Russell & {VIRTIO-130:
-ISR status: Fix incorrect diagram
-
-ISR status capability diagram has the "Device Configuration
-Interrupt " as bit 0, and the "Queue Interrupt" as bit 1. This is
-the wrong way around: it disagrees with the legacy
-implementations, as well as the spec elsewhere.
-
-All current guests correctly follow the text, fix
-up the diagram to match.
-See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI
-Device Layout / ISR status capability}.
- } \\
-\hline
-488 & 15 Mar 2015 & Rusty Russell & {VIRTIO-133:
-Change 4.1.5.1.2.1 to device requirement
-
-4.1.5.1.2.1 is incorrectly labelled as a driver requirement; it's
-self-evidently referring to the device.
-See \ref{sec:Conformance / Driver Conformance / PCI Driver
-Conformance}, \ref{sec:Conformance / Device Conformance / PCI
-Device Conformance} and \ref{devicenormative:Virtio
-Transport Options / Virtio Over PCI Bus / PCI-specific
-Initialization And Device Operation / Device Initialization /
-Non-transitional Device With Legacy Driver}.
- } \\
-\hline
-504 & 22 Apr 2015 & Rusty Russell & {VIRTIO-137:
-define the meaning and requirements of the len field.
-
-We said what it was for, and noted why. We didn't place any
-requirements on it, nor clearly spell out the implications of its use.
-
-This clarification comes particularly from noticing that QEMU
-didn't set len correctly, and philosophising over the correct value
-when an error has occurred.
-See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues /
-The Virtqueue Used Ring}, \ref{devicenormative:Basic Facilities
-of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and
-\ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The
-Virtqueue Used Ring}.
- } \\
-\hline
-506 & 22 Apr 2015 & Michael S. Tsirkin & {VIRTIO-138:
-multiple errors: Non-transitional With Legacy
-
-virtio 1.0 has two sections titled "Non-transitional Device With
-Legacy Driver" the first says devices SHOULD fail, the second
-says devices MUST fail. Clearly a mistake.
-
-Other issues: devices don't really fail - they cause drivers to
-fail. second section seems to be in the wrong place, and also
-have a section followed by subsection with no explanatory text in
-between, which is ugly.
-Finally, this text was originally ritten to handle buggy windows
-drivers gracefully, but later we changed device IDs so it's not
-really required there. Might be handy for some other buggy legacy
-drivers, though no such drivers are known.
-
-To fix, drop the duplicate section variant, add some explanatory
-text, clarify what does "same ID" mean here, and clarify
-that the work-around is only needed if a buggy driver
-is known to bind to a transitional device.
-
-See \ref{sec:Virtio Transport Options / Virtio
-Over PCI Bus / PCI Device Layout / Non-transitional Device With
-Legacy Driver: A Note on PCI Device Layout},
-\ref{devicenormative:Virtio Transport Options / Virtio Over PCI
-Bus / PCI-specific Initialization And Device Operation / Device
-Initialization / Non-transitional Device With Legacy Driver} and
-\ref{sec:Virtio Transport Options / Virtio Over PCI Bus /
-PCI-specific Initialization And Device Operation / Device
-Initialization}.
-} \\
-\hline
-508 & 22 Apr 2015 & Michael S. Tsirkin & {VIRTIO-139:
-pci: missing documentation for dealing with 64 bit config fields
-
-pci spec says what width access to use for 32, 16 and 8
-bit fields, but does not explicitly say what to do for
-32 bit fields. As we have text that says driver must
-treat 64 bit accesses as non-atomic, this seems
-to imply driver should always do two 32 bit wide accesses.
-
-Let's make this an explicit requirement, and require
-devices to support this.
-
-See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI
-Device Layout}, \ref{drivernormative:Virtio Transport Options /
-Virtio Over PCI Bus / PCI Device Layout},
-\ref{devicenormative:Virtio Transport Options / Virtio Over PCI
-Bus / PCI Device Layout} and \ref{sec:Conformance / Driver
-Conformance / PCI Driver Conformance}.
- } \\
-\hline
-509 & 22 Apr 2015 & Michael S. Tsirkin & {balloon:
-MUST -> has to
-
-MUST shouldn't be used outside normative statements,
-that's confusing. Replace with "has to".
-
-See \ref{sec:Device Types / Memory Balloon Device / Feature
-bits}.
- } \\
-\hline
-510 & 22 Apr 2015 & Michael S. Tsirkin & {conformance:
-add VIRTIO-137 statement links
-
-Add links to new conformance statements added to
-resolve VIRTIO-137 (describing used ring entry len usage).
-
-See \ref{sec:Conformance / Device Conformance}
-and \ref{sec:Conformance / Driver Conformance}.
- } \\
-\hline
-517 & 22 Apr 2015 & Michael S. Tsirkin & {acknowledgements:
-contributors+minor fixup
-
-acknowledge feedback by Jason Wang, add Richard Sohn who
-joined the TC, sort acknowledged reviewers alphabetically.
-
-See \ref{chap:Acknowledgements}.
-} \\
-\hline
-520 & 30 Apr 2015 & James Bottomley & {VIRTIO-140:
-give explicit guidance on the use of 64 bit fields
-
-Just saying 64 bit fields may not be atomic is true, but less
-helpful than it might be. Add explicit guidance about what the
-consequences of non-atomicity are.
-
-See \ref{sec:Creating New Device Types / What Device
-Configuration Space Layout?}
-} \\
-\hline
-521 & 30 Apr 2015 & Rusty Russell & {VIRTIO-134:
-Spell out details of indirect elements in chains
-
-1) It's implied that a chain terminates with an indirect descriptor (since
-VIRTIO-15) but we didn't spell out that a device MUST NOT
-continue it.
-
-2) We allow [direct]->[direct]->[indirect], and qemu and
-bhyve both accept it. Make it clear that this is valid, thus devices MUST
-handle it.
-
-See \ref{drivernormative:Basic Facilities of a Virtio Device /
-Virtqueues / The Virtqueue Descriptor Table / Indirect
-Descriptors} and \ref{devicenormative:Basic Facilities of a
-Virtio Device / Virtqueues / The Virtqueue Descriptor Table /
-Indirect Descriptors}
-} \\
-\hline
-522 & 30 Apr 2015 & Michael S. Tsirkin & {VIRTIO-141:
-used ring: specify legacy behaviour for len field
-
-many hypervisors implemented len field incorrectly.
-Document existing bugs in the legacy sections.
-
-See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues
-/ The Virtqueue Used Ring/ Legacy Interface: The Virtqueue Used
-Ring}, \ref{sec:Device Types / Network Device / Device Operation
-/ Legacy Interface: Device Operation}, \ref{sec:Device Types /
-Block Device / Device Operation / Legacy Interface: Device
-Operation}, \ref{sec:Device Types / Console Device / Device
-Operation / Legacy Interface: Device Operation}, \ref{sec:Device
-Types / Memory Balloon Device / Device Operation / Legacy
-Interface: Device Operation}, \ref{sec:Device
-Types / SCSI Host Device / Device Operation / Legacy
-Interface: Device Operation} and \ref{sec:Conformance / Legacy
-Interface: Transitional Device and Transitional Driver
-Conformance}.
-} \\
-\hline
-523 & 30 Apr 2015 & Michael S. Tsirkin & {VIRTIO-142:
-entropy device: typo fix
-
-Current text: "The driver MUST examine the length written by the
-driver" makes no sense. length is written by the device.
-
-See \ref{drivernormative:Device Types / Entropy Device / Device
-Operation}.
-} \\
-\hline
-526 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-143:
-balloon: transitional device support
-
-Support a transitional balloon device: this has the advantage of supporting
-existing drivers, transparently, as well as transports that don't allow mixing
-virtio 0 and virtio 1 devices. And balloon is an easy device to test, so it's
-also useful for people to test virtio core handling of transitional devices.
-
-Three issues with legacy hypervisors have been identified:
-\begin{enumerate}
-\item
-Actual value is actually used, and is necessary for management
-to work. Luckily 4 byte config space writes are now atomic.
-When using old guests, hypervisors can detect access to the last byte.
-When using old hypervisors, drivers can use atomic 4-byte accesses.
-\item Hypervisors actually didn't ignore the stats from the first
-buffer supplied. This means the values there would be
-incorrect until hypervisor resends the request.
-Add a note suggesting hypervisors ignore the 1st buffer.
-\item QEMU simply over-writes stats from each buffer it gets.
-Thus if driver supplies a different subset of stats
-on each request, stale values will be there.
-Require drivers to supply the same subset on each
-request. This also gives us a simple way to figure out
-which stats are supported.
-\end{enumerate}
-
-See
-\ref{sec:Device Types / Memory Balloon Device},
-\ref{devicenormative:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery},
-\ref{sec:Conformance / Driver Conformance / Traditional Memory Balloon Driver Conformance},
-\ref{sec:Conformance / Device Conformance / Traditional Memory Balloon Device Conformance},
-\ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance},
-\ref{sec:Conformance / Device Conformance} and \ref{sec:Conformance / Driver Conformance}.
-} \\
-\hline
-527 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-126:
-document deflate on oom
-
-Document the new option, and also clarify behaviour
-without it.
-
-In particular, actual field is not the
-actual number of pages in the balloon as
-driver might do inflate followed by deflate.
-
-Also, device isn't always driven by interrupts,
-driver can inflate/deflate in response to e.g.
-memory compaction.
-
-See \ref{sec:Device Types / Memory Balloon Device / Feature bits},
-\ref{sec:Device Types / Memory Balloon Device / Device Operation} and
-\ref{drivernormative:Device Types / Memory Balloon Device / Device Operation}.
-} \\
-\hline
-528 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-123:
-network device: xmit/receive cleanup
-
-Fix up multiple issues in xmit/receive sections:
-\begin{itemize}
- \item drop MAY/MUST/SHOULD outside normative statements
- \item spell out conformance requirements for both drivers and
- devices, for xmit and receive paths
- \item document the missing VIRTIO_NET_HDR_F_DATA_VALID
- \item document handling of unrecognized flag bits so we can extend
- flags in the future, similar to VIRTIO_NET_HDR_F_DATA_VALID
-\end{itemize}
-
-\ref{sec:Device Types / Network Device / Device Initialization},
-\ref{drivernormative:Device Types / Network Device / Device Operation / Packet Transmission},
-\ref{devicenormative:Device Types / Network Device / Device Operation / Packet Transmission},
-\ref{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets},
-\ref{sec:Conformance / Driver Conformance / Network Driver Conformance} and
-\ref{sec:Conformance / Device Conformance / Network Device Conformance}.
-} \\
-\hline
-529 & 18 May 2015 & Michael S. Tsirkin & {VIRTIO-124:
-network device: document VIRTIO_NET_F_CTRL_RX_EXTRA
-
-See
-\ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering},
-\ref{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering},
-\ref{sec:Conformance / Driver Conformance / Network Driver Conformance} and
-\ref{sec:Conformance / Device Conformance / Network Device Conformance}.
-} \\
-\hline
diff --git a/cl-cs04.tex b/cl-cs04.tex
deleted file mode 100644
index fc12cdd..0000000
--- a/cl-cs04.tex
+++ /dev/null
@@ -1,134 +0,0 @@
-540 & 11 Oct 2015 & Greg Kurz & {virtqueues: fix
-trivial typo
-
-See
-\ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.
-} \\
-\hline
-541 & 11 Oct 2015 & Paolo Bonzini & {virtio-blk: fix typo
-in legacy framing requirements section
-
-See
-\ref{sec:Device Types / Block Device / Legacy Interface: Framing Requirements}.
-} \\
-\hline
-545 & 18 Oct 2015 & Paolo Bonzini & {virtio-blk: restore VIRTIO_BLK_F_FLUSH and VIRTIO_BLK_F_CONFIG_WCE
-
-VIRTIO_BLK_F_CONFIG_WCE is important in order to achieve good performance
-(up to 2x, though more realistically +30-40\%) in latency-bound workloads.
-However, it was removed by mistake together with VIRTIO_BLK_F_FLUSH.
-
-In addition, even removing VIRTIO_BLK_F_FLUSH was probably not a great
-idea, because it simplifies simple drivers (e.g. firmware) that are okay
-with a writethrough cache but still need data to persist after power loss.
-What really should have been removed is just the possibility that devices
-not propose VIRTIO_BLK_F_FLUSH, but even that only deserves a "SHOULD" in
-the new world of conformance statements.
-
-Restore these, with the following changes:
-
-* clarify and use conformance statements in order to define writeback
-and writethrough caching according to what is commonly done by high-end
-storage.
-
-* clarify (with conformance statements) the influence of the
-VIRTIO_BLK_F_FLUSH feature on caching and how to proceed if only one of
-VIRTIO_BLK_F_FLUSH and VIRTIO_BLK_F_CONFIG_WCE is negotiated.
-
-* strengthen the requirement for persisting writes to MUST after
-a VIRTIO_BLK_T_FLUSH request (and in other cases too involving the
-new features).
-
-The suggested behavior upon feature negotiation is okay for the Linux
-implementation of virtio1, even after the implementation is modified to
-support the two new features.
-
-This fixes VIRTIO-144.
-
-See \ref{sec:Device Types / Block Device},
-\ref{sec:Conformance / Driver Conformance / Block Driver Conformance} and
-\ref{sec:Conformance / Device Conformance / Block Device Conformance}.
-} \\
-\hline
-546 & 18 Oct 2015 & Michael S. Tsirkin & {pci: clarify configuration access capability rules
-
-The point of the configuration access capability is to enable
-access to other capabilities. The intent never was to allow
-writes to a random place within device BARs.
-Limiting drivers simplifies devices - and devices can always
-add another capability if drivers ever want to access
-some other range.
-
-This resolves VIRTIO-145.
-
-See \ref{drivernormative:Virtio Transport Options / Virtio Over
-PCI Bus / PCI Device Layout / PCI configuration access
-capability}.
-} \\
-\hline
-547 & 18 Oct 2015 & Michael S. Tsirkin & {add advice on transition from legacy interfaces
-
-Reading legacy chapters gives a hint about what changed,
-let's help readers discover this useful shortcut.
-
-This resolves VIRTIO-146.
-
-See \ref{sec:Transition from earlier specification drafts}.
-} \\
-\hline
-554 & 16 Feb 2016 & Thomas Huth & {virtio-net: fix inconsistent legacy header size
-
- Current text says:
- The legacy driver only presented num_buffers in the struct
- virtio_net_hdr when VIRTIO_NET_F_MRG_RXBUF was not negotiated;
-
- Should be:
- "\dots was negotiated \dots" instead of "\dots was not negotiated \dots"
-
- To be consistent with the following:
- without that feature the structure was 2 bytes shorter.
-
-See \ref{sec:Device Types / Network Device / Device Operation / Legacy Interface: Device Operation}.
-} \\
-\hline
-555 & 16 Feb 2016 & Michael S. Tsirkin & {virtio header: tweak
-change motivation
-
- The changes are not just to remove Linux assumptions,
- we have also renamed ring->queue.
- Tweak the header description accordingly.
-
-See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Helpers for Operating Virtqueues}.
-} \\
-\hline
-558 & 16 Feb 2016 & Michael S. Tsirkin & {rename virtio_ring.h to virtio_queue.h
-
- Since vring* and VRING* have been replaced with virtq* and VIRTQ*
- respectively, rename the header virtio_ring.h to virtio_queue.h.
-
-See \ref{sec:virtio-queue.h}.
-} \\
-\hline
-559 & 16 Feb 2016 & Michael S. Tsirkin & {init: sort status bits
-
- Status bit order is inconsistent: they are neither in increasing
- order nor in the order they are likely to be used.
-
- The second approach seems more useful since there aren't
- that many bits, so the numerical order does not help much.
-
- A typical order of use would be:
-
-\begin{itemize}
-\item ACKNOWLEDGE
-\item DRIVER
-\item then either FAILED or FEATURES_OK
-\item then either FAILED or DRIVER_OK
-\item then DEVICE_NEEDS_RESET (if device detects an error)
-\end{itemize}
-
- Sort the bits accordingly.
-
-See \ref{sec:Basic Facilities of a Virtio Device / Device Status Field}.
-} \\
-\hline
diff --git a/cl-csprd02.tex b/cl-csprd02.tex
deleted file mode 100644
index 1e0f53d..0000000
--- a/cl-csprd02.tex
+++ /dev/null
@@ -1,1043 +0,0 @@
-316 & 05 Mar 2014 & Michael S. Tsirkin & { legacy framing: scsi host
- } \\
-\hline
-315 & 05 Mar 2014 & Michael S. Tsirkin & { legacy message framing: console device
- } \\
-\hline
-314 & 05 Mar 2014 & Michael S. Tsirkin & { block: legacy message framing
- } \\
-\hline
-313 & 05 Mar 2014 & Michael S. Tsirkin & { message framing: rusty's comments
-
-generic note on message framing
-
-specific requirements listed for net device only
- } \\
-\hline
-312 & 05 Mar 2014 & Michael S. Tsirkin & { legacy devices: get rid of MUST assume
-
-as Rusty points out MUST assume is not very good requirement.
-
-clarify it.
- } \\
-\hline
-311 & 05 Mar 2014 & Michael S. Tsirkin & { transitional driver features: fix typos noted by Rusty
- } \\
-\hline
-310 & 03 Mar 2014 & Rusty Russell & { Formatting: use latex-style quoting everywhere.
-
-Doesn't look any different, but consistent.
- } \\
-\hline
-309 & 03 Mar 2014 & Rusty Russell & { Use ellipsis (aka \textbackslash ldots) everywhere.
-
-And use the ellipsis package, which makes it symmetrical.
- } \\
-\hline
-308 & 03 Mar 2014 & Rusty Russell & { PCI: Tighten requirements.
-
-1) make it clear that queue_enable is 0 on reset.
-
-2) device MUST present a VIRTIO_PCI_CAP_DEVICE_CFG if needed for type.
- } \\
-\hline
-307 & 02 Mar 2014 & Michael S. Tsirkin & { initialization: minor clarification
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-"it" could refer to failed bit or the driver.
-
-clarify.
- } \\
-\hline
-306 & 02 Mar 2014 & Michael S. Tsirkin & { fix rfc2119 reference
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-VIRTIO-68
-
-Cc: Patrick Durusau <patrick@durusau.net>
- } \\
-\hline
-305 & 02 Mar 2014 & Michael S. Tsirkin & { VIRTIO-67: fix html redirects
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-1. oasis switched to https
-
-2. Red Hat is www.redhat.com
-
-Cc: Patrick Durusau <patrick@durusau.net>
- } \\
-\hline
-304 & 02 Mar 2014 & Michael S. Tsirkin & { feedback: clarify device status bits
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-VIRTIO-70
-
-Cc: Patrick Durusau <patrick@durusau.net>
- } \\
-\hline
-303 & 02 Mar 2014 & Michael S. Tsirkin & { legacy interface: move to terminology
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-VIRTIO-64
-
-Cc: Patrick Durusau <patrick@durusau.net
- } \\
-\hline
-302 & 02 Mar 2014 & Michael S. Tsirkin & { introduction: add link to 0.9.5 specification
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-this version replaces it, so it's a non normative reference.
-
-VIRTIO-69
-
-note: the link is added here but isn't used yet: will be used
-
-when we cleanup terminology definitions, by
-
-addressing VIRTIO-64
-
-Cc: Patrick Durusau <patrick@durusau.net
- } \\
-\hline
-301 & 02 Mar 2014 & Michael S. Tsirkin & { non-transitional devices with legacy drivers
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-weaken hacky requirements helpful for graceful failure
-
-for non transitional PCI devices from MUST to SHOULD.
-
-It's nice to have but it's not like it makes things work, and you
-
-can avoid trouble simply by using the most recent drivers.
-
-also move them out to a separate section
- } \\
-\hline
-300 & 02 Mar 2014 & Michael S. Tsirkin & { conformance: document two types of devices
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-document that there are two conformance levels
- } \\
-\hline
-299 & 02 Mar 2014 & Michael S. Tsirkin & { legacy device initialization: confirmance statements
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-298 & 02 Mar 2014 & Michael S. Tsirkin & { legacy virtqueue layout: confirmance
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-297 & 02 Mar 2014 & Michael S. Tsirkin & { legacy: make all notes on endian-ness confirmance clauses
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-296 & 02 Mar 2014 & Michael S. Tsirkin & { legacy feature bits: confirmance statements
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-295 & 02 Mar 2014 & Michael S. Tsirkin & { leacy: layout detection confirmance
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-294 & 02 Mar 2014 & Michael S. Tsirkin & { legacy pci layout: extra confirmance statement
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-293 & 02 Mar 2014 & Michael S. Tsirkin & { legacy pci layout: confirmance statements
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-292 & 02 Mar 2014 & Michael S. Tsirkin & { legacy: make message framing normative
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-TODO: we really should be more specific
- } \\
-\hline
-291 & 02 Mar 2014 & Michael S. Tsirkin & { legacy: make note on legacy VQ endian-ness normative
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-290 & 02 Mar 2014 & Michael S. Tsirkin & { Legacy Interface: Device Configuration Space
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-legacy has no generation field.
-
-add SHOULD statement to document multi-byte field
-
-access rules.
- } \\
-\hline
-289 & 02 Mar 2014 & Michael S. Tsirkin & { legacy: clarify general note on endian-ness
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
-
-this is a non normative section.
-
-we merely mention that details are given
-
-for each device.
- } \\
-\hline
-288 & 02 Mar 2014 & Michael S. Tsirkin & { content: explain that legacy support is optional
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-287 & 02 Mar 2014 & Michael S. Tsirkin & { drop /* LEGACY version was not little endian */
-
-Two issues with the comment:
-
- - it mixes legacy documentation in main part of the spec
-
- - it says what format *isn't* - instead of what it *is*
-
-Now that we have documented that LE can mean
-
-legacy endian, there's no need for the comment.
-
-Resolves issues:
-
- VIRTIO-58
-
-Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014
- } \\
-\hline
-286 & 27 Feb 2014 & Rusty Russell & { Fixed path of linux version of virtio_ring.h
- } \\
-\hline
-285 & 26 Feb 2014 & Pawel Moll & { mmio: Clarify normative requirement on QueueNum
-
-Minor fix: add explicit reference to QueueNumMax in the
-
-normative paragraph describing QueueNum.
- } \\
-\hline
-284 & 26 Feb 2014 & Pawel Moll & { mmio: Fix double register macro
-Minor fix: commit 238 wrapped register names in \textbackslash field\{\}s
-
-and modified one of the register table macros, but missed
-
-the other one.
- } \\
-\hline
-283 & 26 Feb 2014 & Pawel Moll & { mmio: Fix Device Tree example
-
-Minor fix: the size of 0x100 was obviously wrong,
-
-as it didn't allow for configuration space.
- } \\
-\hline
-282 & 26 Feb 2014 & Cornelia Huck & { introduction: typo in terminology section
-
-s/device/driver/ for the transitional driver description.
- } \\
-\hline
-281 & 26 Feb 2014 & Rusty Russell & { ccw: Fix requirements for processing adapter interrupts.
-
-We currently mandate that the driver clears the summary indicator
-
-before processing the queue indicator; this is bogus, as the requirement
-
-for interrupt avoidance is rather that the driver unsets the summary
-
-indicator before before it stops looking at the queue indicator.
-
-In fact, the best way to get a race-free implementation of the interrupt
-
-handler is to process the queue indicators twice; let's add a recommondation
-
-to do that.
- } \\
-\hline
-280 & 26 Feb 2014 & Rusty Russell & { VIRTIO-45: Add a reserved ID for Timer/Clock device
-
-Just add a reserved ID for Timer/Clock device. There is no work
-
-on it yet but it is nice to have the ID which could be used safely
-
-in preliminary implementations.
- } \\
-\hline
-279 & 26 Feb 2014 & Rusty Russell & { VIRTIO-28: Deprecate balloon device, add number for new one.
- } \\
-\hline
-278 & 26 Feb 2014 & Rusty Russell & { Feedback: VIRTIO-77 Conformance clause.
-
-Now we have grouped all the normative statements, the conformance
-
-clauses for drivers and devices can simply reference them.
- } \\
-\hline
-277 & 26 Feb 2014 & Rusty Russell & { Feedback: Separate normative requirements for Reserved Feature Bits.
- } \\
-\hline
-276 & 26 Feb 2014 & Rusty Russell & { Feedback: SCSI: Separate normative and descriptive texts.
-
-This could use some more rigour, I think: there are still many
-
-implied requirements which could be called out.
- } \\
-\hline
-275 & 26 Feb 2014 & Rusty Russell & { Feedback: console \& entropy: separate normative and descriptive texts.
- } \\
-\hline
-274 & 26 Feb 2014 & Rusty Russell & { Feedback: block: separate normative and descriptive text.
- } \\
-\hline
-273 & 26 Feb 2014 & Rusty Russell & { Feedback: net: separate normative and instructional text.
- } \\
-\hline
-272 & 26 Feb 2014 & Rusty Russell & { Feedback: CCW: Separate normative and descriptive sections.
- } \\
-\hline
-271 & 26 Feb 2014 & Rusty Russell & { Feedback: MMIO: Separate normative and descriptive text.
-
-The section on initialization is now non-normative.
- } \\
-\hline
-270 & 26 Feb 2014 & Rusty Russell & { Feedback: PCI: Separate explanatory and normative text.
-
-Rather than treat selectors 0 and 1 as special, the wording for features
-
-is made more general (though still the same effect).
-
-I split the interrupt handler into a separate subsection: it was
-
-misleading because it didn't handle configuration interrupts until
-
-the next section. It's also non-normative.
- } \\
-\hline
-269 & 26 Feb 2014 & Rusty Russell & { Feedback: Separate the rest of chapter 2 into normative vs explanatory.
-
-The big change here is in introducing new subsections for interrupt and notification
-
-suppression, and moving all requirements into them.
-
-The example processing loop is also moved into a note, to show clearly
-
-that it's not normative.
- } \\
-\hline
-268 & 26 Feb 2014 & Rusty Russell & { Feedback: Normative split for Basic Facilities of a Virtio Device / Virtqueues / Message Framing
- } \\
-\hline
-267 & 26 Feb 2014 & Rusty Russell & { Feedback: Normative split in Basic Facilities of a Virtio Device / Virtqueues
- } \\
-\hline
-266 & 26 Feb 2014 & Rusty Russell & { Feedback: split Basic Facilities feature bits and config space into normative.
-
-Split text into descriptive and normative.
- } \\
-\hline
-265 & 26 Feb 2014 & Rusty Russell & { Feedback: add normative marker.
-From \url{http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html:}
-
- Normative statements MUST be referenceable so that a statement may be
-
- referenced from another part of a specification, but more importantly
-
- so they can be referenced from Conformance Clauses.
- } \\
-\hline
-264 & 26 Feb 2014 & Rusty Russell & { Feedback: 2.1 Device Status field: Separate description from normative.
-
-Start with explanation, progress to normative requirements.
- } \\
-\hline
-263 & 26 Feb 2014 & Rusty Russell & { Feedback: move legacy/transitional definitions into terminology.
- } \\
-\hline
-262 & 26 Feb 2014 & Rusty Russell & { Feedback: hoist the one legacy-related requirement out of legacy section.
-
-This requirement applies to any system which *did* have legacy drivers.
- } \\
-\hline
-261 & 26 Feb 2014 & Rusty Russell & { Feedback: add old draft to normative references (VIRTIO-77)
- } \\
-\hline
-260 & 26 Feb 2014 & Rusty Russell & { Feedback: use proper list in introduction (VIRTIO-82)
-
-Also avoid extra spacing before footnote markers.
- } \\
-\hline
-259 & 26 Feb 2014 & Rusty Russell & { Feedback: move new device design section to Appendix.
-
-It's non-normative.
- } \\
-\hline
-258 & 26 Feb 2014 & Rusty Russell & { Feedback: Bug TAB-553 (VIRTIO-76)
-
-Haven't marked them non-normative yet, but it makes sense to put the header
-
-in an appendix.
- } \\
-\hline
-257 & 26 Feb 2014 & Rusty Russell & { Feedback: TAB-555 Bad sub-sectioning (VIRTIO-80)
- } \\
-\hline
-256 & 26 Feb 2014 & Rusty Russell & { Feedback: TAB-557 Spelling errors, etc (VIRTIO-75)
- } \\
-\hline
-255 & 26 Feb 2014 & Rusty Russell & { PCI: better document driver and device requirements
-
-Feedback:
-
-10) 4.1.3.1.2 Queue Vector Configuration
-
-Some of the information from section 8.4 needs to be moved to
-
-here, for example that the device may have an MSI-X table size
-
-other than 2048.
-
-Otherwise, this reads as though the MSI-X table must always have
-
-2048 entries.
-
-11) Please explicitly describe the device behavior when writing
-
-a vector value beyond the MSI-X table size.
-
-Address these comments.
-
-Cc: Arun Subbarao <asubbarao@lnxw.com>
- } \\
-\hline
-254 & 26 Feb 2014 & Rusty Russell & { feedback: minor wording cleanups
-
-We already mention requirement for natural width
-
-accesses for non device specific configuration.
-
-Don't repeat this in legacy section.
-
-Further, mention virtio pci structure in
-
-preamble to help link sections together.
-
-Cc: Arun Subbarao <asubbarao@lnxw.com>
-
-Conflicts:
-
- content.tex
- } \\
-\hline
-253 & 26 Feb 2014 & Rusty Russell & { SCSI: fix up more fields.
-Some missing \textbackslash field\{\} markings, and a few redundant "the XXX field".
- } \\
-\hline
-252 & 20 Feb 2014 & Rusty Russell & { SCSI: missing space.
- } \\
-\hline
-251 & 19 Feb 2014 & Rusty Russell & { Gratuitous Packet Sending: clarify wording.
-
-The device can ask, not the driver.
- } \\
-\hline
-250 & 19 Feb 2014 & Rusty Russell & { net: fix incorrect reference.
-
-It pointed into the block section for some reason.
- } \\
-\hline
-249 & 13 Feb 2014 & Cornelia Huck & { ccw: padding annotations
-
-Remove __packed__ annotation from all ccw structures that don't need it,
-
-and make the length requirements explicit for those that do.
-
-This is the part of the patch to resolve VIRTIO-56 that had been missed.
- } \\
-\hline
-248 & 12 Feb 2014 & Michael S. Tsirkin & { PCI: minor wording change
-
-Since access width requirement is a confirmance clause, make it
-
-explicit that it applies to 4,2 and 1 byte fields.
-
-Also explain what happens to fields of other widths (such as
-
-the 6 byte MAC).
- } \\
-\hline
-247 & 12 Feb 2014 & Michael S. Tsirkin & { content: more strict confirmance language
-
-Correct new language to explicitly use MAY/SHOULD/MUST
-
-in more places or simply drop the somewhat vague "can" where
-
-we are describing the only way to operate the device.
-
-Most of the changes are in the PCI section.
- } \\
-\hline
-246 & 12 Feb 2014 & Michael S. Tsirkin & { introduction: address lnovich comments
-
-generally list of buses is out of date, list all supported buses.
-
-Drop explicit mention of lguest since it's not part of the spec.
- } \\
-\hline
-245 & 12 Feb 2014 & Michael S. Tsirkin & { abstract: address lnovich comment
-
-lnovich@redhat.com suggested rewording abstract,
-
-making the following point:
-
-. from what point of view is virtio like a physical device?
-
- it's very different from host POV
-
-. "the guest" appears out of nowhere. It's the guest that runs
-
- in the vm of course.
-
-. "not all that different" means similar so there's not need to
-
- be verbose
-
-Address this comment
- } \\
-\hline
-244 & 12 Feb 2014 & Rusty Russell & { VIRTIO-55: Add a reserved ID for GPU devices
-
-As existing work on virtio-gpu is using device ID 16, reflect this in
-
-the spec. This closes out VIRTIO-55.
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-243 & 12 Feb 2014 & Rusty Russell & { Fix S390 normative references.
-
-As pointed out in TAB-539 and TAB-540:
-
-- Add an URL to the documents. (Unfortunately, there is no link that
-
- always points to the latest version.)
-
-- State that we include any future revisions as well.
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-242 & 12 Feb 2014 & Rusty Russell & { ccw: Further use of RFC2119 language.
-
-Some more instances of MAY and SHOULD, as reported in TAB comments
-
-TAB-548 and TAB-550.
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-241 & 12 Feb 2014 & Rusty Russell & { PCI: explicitly document ISR status field
-
-Feedback on ISR status register:
-
- It would be helpful if this section provided the meaning of each
-
- bit in the register.
-
-ISR use is scattered all around the place.
-
-Add a section describing the format and semantics.
-
-[ Merged to combine with new ISR-specific section --RR ]
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
-
-Cc: Arun Subbarao <asubbarao@lnxw.com>
- } \\
-\hline
-240 & 12 Feb 2014 & Rusty Russell & { PCI: consistent device/PCI configuration space
-
-Re section:
-
-4.1.3.4 Notification of Device Configuration Changes
-
-Feedback:
-
- Please use "PCI configuration space" and "device configuration
-
- state" consistently, without abbreviation. For example, from the
-
- first sentence it looks like "device configuration state" can be
-
- changed, but the first bullet claims it's "configuration space".
-
- So, which one? Does "configuration space" mean "PCI configuration
-
- space" or is it a synonym for "device configuration state"?
-
- Because those are two different things; the driver needs to know
-
- what exactly to rescan.
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
-
-Cc: Arun Subbarao <asubbarao@lnxw.com>
- } \\
-\hline
-239 & 12 Feb 2014 & Rusty Russell & { Feedback \#8: Applied.
-
-[ Includes fixup! removing MSI-X ]
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-238 & 12 Feb 2014 & Rusty Russell & { Feedback \#7: Applied
-
-Some minor merging required.
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-237 & 12 Feb 2014 & Rusty Russell & { Feedback \#6: Applied
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-236 & 12 Feb 2014 & Rusty Russell & { Feedback \#5: Applied.
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-235 & 12 Feb 2014 & Rusty Russell & { Feedback \#4: applied.
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-234 & 12 Feb 2014 & Rusty Russell & { PCI: minor changes for previous patch.
- } \\
-\hline
-233 & 12 Feb 2014 & Rusty Russell & { PCI: rearrange it all
-
-This is the re-arrangement originally suggested by Rusty,
-
-except I made some fixes and also tweaked a couple of places
-
-where behaviour changes where suggested - if we want these,
-
-they should go in separately.
-
-Rearrange discovery section to make it clearer what goes on.
-
-Wording changes MUST/MAY/etc. Clarify cfg gateway use. No
-
-behavioural changes.
-
-[ Merged "fixup! PCI: rearrange it all" --RR ]
-
-As per minutes:
- \url{https://lists.oasis-open.org/archives/virtio/201402/msg00121.html}
- } \\
-\hline
-232 & 12 Feb 2014 & Rusty Russell & { PCI: rearrange it all
-
-This is the re-arrangement originally suggested by Rusty,
-
-except I made some fixes and also tweaked a couple of places
-
-where behaviour changes where suggested - if we want these,
-
-they should go in separately.
-
-Rearrange discovery section to make it clearer what goes on.
-
-Wording changes MUST/MAY/etc. Clarify cfg gateway use. No
-
-behavioural changes.
- } \\
-\hline
-231 & 12 Feb 2014 & Rusty Russell & { C struct specifications.
-
-Explicitly specify that our C struct specifications are without padding,
-
-and add some definitions for our integer data types.
-
-[ Rusty - added /* comments */ and removed redundant old le* explanation ]
- } \\
-\hline
-225 & 10 Feb 2014 & Rusty Russell & { REVERT LAST 15 JUNK COMMITS.
-
-Back to r211. It's been a long day.
- } \\
-\hline
-224 & 10 Feb 2014 & Rusty Russell & { patch feedback-8-9.patch
- } \\
-\hline
-223 & 10 Feb 2014 & Rusty Russell & { patch feedback-8-7.patch
- } \\
-\hline
-222 & 10 Feb 2014 & Rusty Russell & { patch feedback-8-6.patch
- } \\
-\hline
-221 & 10 Feb 2014 & Rusty Russell & { patch feedback-8-5.patch
- } \\
-\hline
-220 & 10 Feb 2014 & Rusty Russell & { feedback: s/virtio header/virtio common configuration/
-
-While most places now sat virtio common configuration
-
-structure, some places still use the term virtio header.
-
-Since it's not necessarily before the
-
-common configuration anymore, rename it
-
-to virtio common configuration structure for consistency.
-
-Cc: Arun Subbarao <asubbarao@lnxw.com>
- } \\
-\hline
-219 & 10 Feb 2014 & Rusty Russell & { We'll add more non-normative sections with hints for
-
-implementing registers such as PCI class, status
-
-and command registers.
- } \\
-\hline
-218 & 10 Feb 2014 & Rusty Russell & { example code does not have to be optimal but it
-
-seems cleaner to disable interrupts after we
-
-recheck the ring empty state.
- } \\
-\hline
-217 & 10 Feb 2014 & Rusty Russell & { patch feedback-7-orig.patch
- } \\
-\hline
-216 & 10 Feb 2014 & Rusty Russell & { patch feedback-6.patch
- } \\
-\hline
-215 & 10 Feb 2014 & Rusty Russell & { patch feedback-5.patch
- } \\
-\hline
-214 & 10 Feb 2014 & Rusty Russell & { patch feedback-4.patch
- } \\
-\hline
-213 & 10 Feb 2014 & Rusty Russell & { PCI Section Rework
-
-1) Minor changes from must to MUST etc.
-
-2) More references using \textbackslash ref.
-
-3) Move section on capabilities first, before we talk about the common
-
- config layout. The previous order made sense for legacy.
-
-4) Make explicit subsections for each type of capability and move more
-
- information into them.
-
-5) Make it clear that there must be one or more.
-
-6) Include 'struct virtio_pci_cap cap;' in struct virtio_pci_cfg_cap to
-
- match virtio_pci_notify_cap.
-
-7) Explicitly note there's no way to negotiate the queue size for a
-
- legacy device.
-
-8) Fix old language on config change event: config is not in the pci
-
- configuration space.
-
-9) Explicitly state what the driver should do to use virtio_pci_cfg_cap.
- } \\
-\hline
-212 & 10 Feb 2014 & Rusty Russell & { C struct specifications.
-
-Explicitly specify that our C struct specifications are without padding,
-
-and add some definitions for our integer data types.
-
-[ Rusty - added /* comments */ and removed redundant old le* explanation ]
- } \\
-\hline
-207 & 07 Feb 2014 & Rusty Russell & { Cleanup and setup clarifications
-
-1) Explicitly allow drivers to read config space during feature
-
- negotiation.
-
-2) Add the concept of a "live" virtqueue, and explicitly disallow
-
- moving it backwards or changing descriptors.
- } \\
-\hline
-204 & 07 Feb 2014 & Rusty Russell & { block: legacy SCSI command fix.
-
-When describing the historical layout requirements, it says
-
- "status field is a separate read-only buffer of size 1 byte, by itself."
-
-That's clearly wrong, as it says above "The final status byte is written by the device"
- } \\
-\hline
-203 & 06 Feb 2014 & Rusty Russell & { whitespace: make all examples unindented, and avoid tabs.
-
-This makes the formatting far nicer. Applying now as it touches almost
-
-all examples and layouts, so we can rebase future changes on top of
-
-common ground.
-
-(Based on feedback from Thomas Huth for one example, and generalized).
- } \\
-\hline
-201 & 31 Jan 2014 & Rusty Russell & { 3.2.1: Language tightening.
-
-1) Lots of "we", replace with "the driver".
-
-2) Use MAY and MUST NOT for spurious notifications.
-
-3) Don't refer to PCI configuration space for notification.
- } \\
-\hline
-198 & 29 Jan 2014 & Pawel Moll & { 4.1.2.5: Legacy: PCI Device Layout: fix PCI header fields order
-
-The order of the fields in the legacy PCI header seems to get
-
-messed up in the new spec, with the "Queue Address" moved
-
-behind "Queue Notify". According to the 0.9.5 version of the spec
-
-it should be:
-
-* Device Features 32
-
-* Driver Features 32
-
-* Queue Address 32
-
-* Queue Size 16
-
-* Queue Select 16
-
-* Queue Notify 16
-
-* Device Status 8
-
-* ISR Status 8
-
---
-
-1.8.3.2
- } \\
-\hline
-197 & 29 Jan 2014 & Rusty Russell & { Feedback \#3: Feedback from Pranavkumar Sawargaonkar (VIRTIO_CONSOLE_F_EMERG_WRITE)
-
-Document: virtio-v1.0-csprd01
-
-Number: 3
-
-Date: Tue, 21 Jan 2014 15:09:54 +0530
-Link to Mail: \url{https://lists.oasis-open.org/archives/virtio-comment/201401/msg00037.html}
-
-Commenter name: Pranavkumar Sawargaonkar <pranavkumar@linaro.org>
-
-Approved at meeting 2014-01-28:
- \url{https://lists.oasis-open.org/archives/virtio/201401/msg00054.html}
- } \\
-\hline
-196 & 29 Jan 2014 & Rusty Russell & { Feedback \#2: More feedback from Thomas Huth
-
-Document: virtio-v1.0-csprd01
-
-Number: 2
-
-Date: Fri, 10 Jan 2014 13:49:49 +0100
-Link to Mail: \url{https://lists.oasis-open.org/archives/virtio-comment/201401/msg00001.html}
-
-Commenter name: Thomas Huth <thuth@linux.vnet.ibm.com>
-
-Approved at meeting 2014-01-28:
- \url{https://lists.oasis-open.org/archives/virtio/201401/msg00054.html}
- } \\
-\hline
-195 & 29 Jan 2014 & Rusty Russell & { Feedback \#1: fixes from Thomas Huth
-
-Document: virtio-v1.0-csprd01
-
-Number: 1
-
-Date: Fri, 10 Jan 2014 11:01:44 +0100
-Link to Mail: \url{https://lists.oasis-open.org/archives/virtio-comment/201401/msg00000.html}
-
-Commenter name: Thomas Huth <thuth@linux.vnet.ibm.com>
-
-Approved at meeting: 2014-01-28
- \url{https://lists.oasis-open.org/archives/virtio/201401/msg00054.html}
- } \\
-\hline
-194 & 28 Jan 2014 & Pawel Moll & { mmio: Move QueueReady register from offset 0x03c to 0x044
-
-Legacy devices have QueueAlign register at 0x03c. To stay
-
-on the safe side and avoid any potential clashes (also to
-
-be able to abort any wrong writes), move it to previously
-
-unused offset 0x044.
- } \\
-\hline
-193 & 23 Jan 2014 & Cornelia Huck & { virtio-ccw: fix set_revision payload definition
-
-The members of struct virtio_rev_info are big endian: use be16 types.
- } \\
-\hline
-191 & 23 Jan 2014 & Rusty Russell & { Formatting: fix feature bits for console device.
-
-Make them a description list like every other device.
- } \\
-\hline
-190 & 23 Jan 2014 & Rusty Russell & { Michael's patch adding MQ support added some u16s; they are u16 in
-
-legacy mode but should be le16 for modern devices.
- } \\
-\hline
-185 & 17 Jan 2014 & Rusty Russell & { net/multiqueue: tighten wording
- } \\
-\hline
-184 & 17 Jan 2014 & Rusty Russell & { Fixes for first WD front page.
-
-Based on feedback from Paul Knight <paul.knight@oasis-open.org>.
- } \\
-\hline
-179 & 03 Jan 2014 & Pawel Moll & { mmio: Obviously wrong notification register name
-
-The "4.2.3.3 Notifying The Device" section said "writing
-
-the index of the updated queue to the QueueNum". This
-
-is obviously wrong - should read "QueueNotify".
- } \\
-\hline
-178 & 16 Dec 2013 & Pawel Moll & { title \& acknowledgements: Make ARM less limited
-
-... by removing the "Limited" bit of the name.
- } \\
-\hline
-177 & 16 Dec 2013 & Pawel Moll & { 2.3.2 MMIO: Configuration space offset corrected
-
-The offset in the MMIO configuration space description
-
-(table 4.1) became wrong at some time (0x0fff). Fixed.
- } \\
-\hline
-176 & 12 Dec 2013 & Pawel Moll & { 2.3.2 MMIO: Notifications \& interrupts clarifications
-
-(Hopefully) clarified the way notifications are being
-
-passed between the device and the driver and about
-
-the meaning of the interrupt registers.
- } \\
-\hline
-175 & 12 Dec 2013 & Pawel Moll & { 1. Introduction: Removed left-over "PCI"
-
-The "Extensible" paragraph of the introduction still
-
-referred to "Virtio PCI devices". Changed to
-
-"Virtio devices".
- } \\
-\hline
-174 & 12 Dec 2013 & Pawel Moll & { 2.3.2 MMIO: Further clarifications
-
-Clarified driver behaviour for out-of-spec MagicValue,
-
-Version and DeviceID values.
- } \\
-\hline
-173 & 12 Dec 2013 & Cornelia Huck & { ccw: feature bit endianness
-
-In contrast to the other values transmitted in ccw payload, feature bits
-
-are little endian. Fix it in the structure definition.
- } \\
-\hline
-172 & 12 Dec 2013 & Cornelia Huck & { ccw: clarify passing of subchannel id
-
-Make clear that the upper half of the register must be ignored, just
-
-like normal I/O instructions do.
- } \\
-\hline
-171 & 12 Dec 2013 & Cornelia Huck & { ccw: Tighten specification language.
-
-must -> MUST changes, removed inappropriate mays.
- } \\
-\hline
-170 & 09 Dec 2013 & Pawel Moll & { 2.3.2 MMIO: LaTeXisation
-
-Converter the register layout descriptions into
-
-tables.
-
-Also hardened the specification language, using
-
-MUSTs and MUST NOTs.
- } \\
-\hline
-168 & 09 Dec 2013 & Michael S. Tsirkin & { commands-pdf.tex: align title page
-
-Section titles are currently misaligned on the title
-
-page. This patch aligns them back.
- } \\
-\hline
-167 & 09 Dec 2013 & Michael S. Tsirkin & { net: document VIRTIO_NET_F_MAC_ADDR
-
-VIRTIO-50
-
- virtio-spec: set mac address by a new vq command
-
-Approved Dec 3, 2013
- } \\
-\hline
-166 & 09 Dec 2013 & Michael S. Tsirkin & { net: add _F_MQ support
-
-VIRTIO-49
-
-Includes git commits:
-
- virtio-spec: fix two typos
-
- virtio-spec: virtio network device multiqueue support
-
- net: add note that you can defer rx queue init until mq enable.
-
-Approved Dec 3, 2013
- } \\
-\hline
diff --git a/cl-csprd03.tex b/cl-csprd03.tex
deleted file mode 100644
index 81f9bfb..0000000
--- a/cl-csprd03.tex
+++ /dev/null
@@ -1,400 +0,0 @@
-399 & 27 Jun 2014 & Michael S. Tsirkin & { changelog: fill changelog since draft2
-
-This will make review easier.
- } \\
-\hline
-398 & 27 Jun 2014 & Michael S. Tsirkin & { acknowledgements: add draft 3 reviewers, sort
-
-Add new reviewers and sort by name.
- } \\
-\hline
-397 & 27 Jun 2014 & Michael S. Tsirkin & { add draft2 acknowledgements
-
-List people that provided comments on draft01 in the
-acknowledgements section. Might be a nice way to encourage
-reviews.
- } \\
-396 & 26 Jun 2014 & Michael S. Tsirkin & { diff: back to green for added text
-
-using blue does not work well for html
-
- } \\
-\hline
-393 & 26 Jun 2014 & Michael S. Tsirkin & { makediff: cleanup using begingroup/endgroup
-
-Pawel Moll found a way to work around xetex bugs
-without mangling latexdiff output using perl:
-
-- define DIFbegin/DIFFend commands in preample
-
-- pass --config FLOATENV= to latexdiff
-
-Use this in preference to the fixupdiff perl script.
-
- } \\
-\hline
-391 & 26 Jun 2014 & Michael S. Tsirkin & { more latexdiff hacks
-
-- change link color from green to pinegreen. Looks better to me.
-
-- split footnotes out from their text, so that latexdiff
- does not consider them as a unit
-
-- mark field command as safe for latexdiff, otherwise it's not shown in red
-
-- hack adding DIFaddtext within footnotes could not handle
- case where latexdiff inserted multiple DIFadd within the
- footnote. Instead, detect when footnote is within
- DIFaddbegin/DIFdelbegin, add an extra DIFaddbegin/DIFdelbegin
- within the footnote.
-
- } \\
-\hline
-390 & 26 Jun 2014 & Michael S. Tsirkin & { diffpreamble: fix colors for links within diff
- } \\
-\hline
-389 & 26 Jun 2014 & Michael S. Tsirkin & { work around xetex bug
-
-Too many \textbackslash color directives produce corrupted output
-and this warning:
-
-WARNING ** Color stack overflow. Just ignore.
-
-Use script to reduce \# of these directives.
-
- } \\
-\hline
-388 & 26 Jun 2014 & Michael S. Tsirkin & { diffpreamble: remove duplicate text
-
-latexdiff adds some
-
- } \\
-\hline
-387 & 26 Jun 2014 & Michael S. Tsirkin & { makediffpdf.sh: tool to create marked-up diff
-
-make pdf diff using latexpand and latexdiff-fast
-styles are set in diffpreamble.tex
-in diff, links are coloured green instead of blue
-
-Must be run within a git-svn clone of the spec repository.
-
-Note: latexdiff has --flatten option, this and options
-to select diff style don't seem to work well.
-
-So flatten by script myself, and add our own preamble.
-
- } \\
-\hline
-386 & 25 Jun 2014 & Michael S. Tsirkin & { pci: minor fomatting tweak
-
-Make table look better. Drop spaces that make
-latexdiff stumble.
-
- } \\
-\hline
-385 & 25 Jun 2014 & Michael S. Tsirkin & { fixup pci: switch from subsystem id to device id
-
-Patch sent to list (and applied by Rusty in
-
- pci: switch from subsystem id to device id
-
-) did not actually implement what commit log said
-it implements.
-
-The result is wrong for transitional devices:
-
-Adding 0xfff works for for net+block only;
-
-for transitional pci devices there is no fixed scheme:
-\~{}/projects/qemu/include \# grep VIRTIO_ID hw/virtio/*.h
-
-hw/virtio/virtio-balloon.h:\#define VIRTIO_ID_BALLOON 5
-
-hw/virtio/virtio-blk.h:\#define VIRTIO_ID_BLOCK 2
-
-hw/virtio/virtio-net.h:\#define VIRTIO_ID_NET 1
-
-hw/virtio/virtio-rng.h:\#define VIRTIO_ID_RNG 4
-
-hw/virtio/virtio-scsi.h:\#define VIRTIO_ID_SCSI 8
-
-hw/virtio/virtio-serial.h:\#define VIRTIO_ID_CONSOLE 3
-
-\~{}/projects/qemu/include \# grep VIRTIO hw/pci/*.h
-
-hw/pci/pci.h:\#define PCI_DEVICE_ID_VIRTIO_NET 0x1000
-
-hw/pci/pci.h:\#define PCI_DEVICE_ID_VIRTIO_BLOCK 0x1001
-
-hw/pci/pci.h:\#define PCI_DEVICE_ID_VIRTIO_BALLOON 0x1002
-
-hw/pci/pci.h:\#define PCI_DEVICE_ID_VIRTIO_CONSOLE 0x1003
-
-hw/pci/pci.h:\#define PCI_DEVICE_ID_VIRTIO_SCSI 0x1004
-
-hw/pci/pci.h:\#define PCI_DEVICE_ID_VIRTIO_RNG 0x1005
-
-hw/pci/pci.h:\#define PCI_DEVICE_ID_VIRTIO_9P 0x1009
-
-I am guessing TC went by commit log when it approved the change,
-so fixing it up directly.
-
-Cc: Andrew Thornton <andrewth@google.com>
-
-Cc: Rusty Russell <rusty@ozlabs.org>
-
-Cc: Gerd Hoffmann <kraxel@redhat.com>
-
- } \\
-\hline
-384 & 17 Jun 2014 & & { content.tex: VIRTIO-106: mention possibility of failing TMFs
-
-This completes the review of virtio-scsi based on observations
-from Google.
-
- } \\
-\hline
-383 & 16 Jun 2014 & & { fix erroneous reference to Subsystem Device ID
-
-Subsystem device ID only exists for PCI.
-
- } \\
-\hline
-382 & 16 Jun 2014 & Rusty Russell & { small virtio-serial fix
-
-nr_ports does not exist in the spec.
-
- } \\
-\hline
-381 & 09 Jun 2014 & & { virtio-scsi: support well-known logical units
-
-The REPORT LUNS well-known logical unit is useful because it lets you
-retrieve information about all targets with a single command. It
-also provides an easy way to send a no-op request.
-
- } \\
-\hline
-380 & 09 Jun 2014 & & { consistent formatting of footnotes
-
-Put the indicator before punctuation, and terminate the footnote with
-a period.
-
- } \\
-\hline
-379 & 09 Jun 2014 & & { virtio-scsi: additional SHOULDification
-
- } \\
-\hline
-378 & 09 Jun 2014 & & { virtio-scsi: fixes to protection information
-
-pi_bytesin is in the device-readable section. Document lack of residual
-field. Use le32 instead of u32.
-
-This matches the new patch series that Nicholas sent for vhost-scsi.
-
-Cc: <nab@daterainc.com>
-
- } \\
-\hline
-377 & 05 Jun 2014 & Rusty Russell & { PCI: remove duplicate paragraph.
-
-I chose the one which used the full nomenclature.
-
- } \\
-\hline
-376 & 05 Jun 2014 & Rusty Russell & { pci: switch from subsystem id to device id
-
-Switch virtio pci to use standard device id instead of using the
-subsystem id.
-
-Unfortunately, there's no system to the way KVM allocated
-device IDs to virtio devices, we'll just have to
-specify these using a table, and use a new range for
-future devices. For existing devices this results in
-two possible IDs that all drivers will need to match.
-Unfortunate, but the cost is small.
-
-As a nice side effect, this allows us to make non-transitional
-devices use IDs 0x40 and up, this reduces even further the
-chance that a non transitional device will match legacy drivers.
-
-And, it's probably a good idea to allow drivers to match
-specific subsystem IDs if they
-
-want to, so relax requirement for drivers to match all
-subsystem/vendor ID configurations, but allow them to do so.
-To avoid confusion, say "PCI Device ID" and
-"PCI Subsystem ID" everywhere, prefix "PCI"
-for other standard registers, for consistency.
-
-VIRTIO-102
-
-Note: issue reporter suggested 0x10XX where XX is the virtio
-device ID. This would conflict with legacy devices, which seem
-to have used 7 IDs in the range 0x1000 to 0x103f without any
-system. Let's use a new range 0x1040 to 0x107f for
-non-transitional devices, and add a table documenting the
-transitional IDs used by in practice.
-
-(Approved at 2014-06-04 meeting:
-
- \url{https://lists.oasis-open.org/archives/virtio/201406/msg00013.html} )
-
-Cc: Andrew Thornton <andrewth@google.com>
-
- } \\
-\hline
-375 & 05 Jun 2014 & Rusty Russell & { pci: set ISR bit on config change with MSI-X
-
-config changes are slow path anyway, so we
-can as well set ISR bit to help drivers detect changes.
-This allows sharing config interrupts which is what
-issue reporter seems to ask for.
-
-VIRTIO-104
-
-(Approved at 2014-06-04 meeting:
-
- \url{https://lists.oasis-open.org/archives/virtio/201406/msg00013.html} )
-
- } \\
-\hline
-374 & 01 Jun 2014 & Michael S. Tsirkin & { NEEDS_RESET: trivial clarification
-
-If device sets NEEDS_RESET before DRIVER_OK, it
-can't send notifications to driver.
-
-Make this clear.
-
- } \\
-\hline
-373 & 22 May 2014 & Rusty Russell & { Fix build of document
-
-Error introduced in "VIRTIO-98: Add DEVICE_NEEDS_RESET":
-seems that underscores in labels are verboten:
-
-[133] [134] (./virtio-v1.0-csprd02.aux
-
-! Missing \textbackslash endcsname inserted.
-
-<to be read again>
-
- \textbackslash unhbox
-
-l.45 ...ts: Device Status Field\}\}\{subsection.1\}\{\}\}
-
- } \\
-\hline
-372 & 22 May 2014 & Rusty Russell & { content.tex: virtio-scsi review (VIRTIO-106)
-
-As prompted by Rusty, add a few more MUST/SHOULD items for both devices
-and drivers. Clarify semantics of max_channel/max_id/max_lun, task_attr
-and task management functions.
-
-(As per minutes of meeting 2014-05-20:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00034.html} )
-
- } \\
-\hline
-371 & 22 May 2014 & Rusty Russell & { content.tex: add support for protection information (VIRTIO-108)
-
-This is a new feature that was suggested by Nicholas Bellinger, who
-
-also provided a prototype implementation for vhost-scsi.
-
-(As per minutes of meeting 2014-05-20:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00034.html} )
-
- } \\
-\hline
-370 & 12 May 2014 & Rusty Russell & { VIRTIO-96: Assign device id to virtio input
-
-Assign device id to virtio input
-
-As passed at meeting 2014-05-06:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00016.html}
-
- } \\
-\hline
-369 & 12 May 2014 & Rusty Russell & { VIRTIO-52: Make mac field read only.
-
-As passed at meeting 2014-05-06:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00016.html}
-
- } \\
-\hline
-368 & 12 May 2014 & Rusty Russell & { VIRTIO-107: Clarify net mac commands.
-
-As passed at meeting 2014-05-06:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00016.html}
-
- } \\
-\hline
-367 & 12 May 2014 & Rusty Russell & { VIRTIO-98: Add DEVICE_NEEDS_RESET.
-
-As passed at meeting 2014-05-06:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00016.html}
-
- } \\
-\hline
-366 & 12 May 2014 & Rusty Russell & { VIRTIO-87: limit descriptor chain length even with INDIRECT.
-
-As passed at meeting 2014-05-06:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00016.html}
-
- } \\
-\hline
-365 & 12 May 2014 & Rusty Russell & { VIRTIO-103: PCI: Note that turning off queue_enable is not supported.
-
-As passed at meeting 2014-05-06:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00016.html}
-
- } \\
-\hline
-364 & 12 May 2014 & Rusty Russell & { VIRTIO-103: PCI: require read-after-write on device_status reset.
-
-As passed at meeting 2014-05-06:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00016.html}
-
- } \\
-\hline
-363 & 12 May 2014 & Rusty Russell & { VIRTIO-99: Typo fixes.
-
-As passed at meeting 2014-05-06:
-
- \url{https://lists.oasis-open.org/archives/virtio/201405/msg00016.html}
-
- } \\
-\hline
-362 & 07 May 2014 & Cornelia Huck & { net: fix device conformance sections
-
-For the network device, we had two device normative sections both called
-"setting up receive buffers", neither of which was referenced in the
-conformance section.
-
-Let's rename the second one to "processing of packets" which seems to
-better match the actual contents and reference both of them from the
-conformance statement for network devices.
-
-Resolves VIRTIO-97.
-
-Agreed on the 2014/05/06 TC meeting.
-
- } \\
-\hline
-361 & 07 Apr 2014 & Michael S. Tsirkin & { conformance.tex: fix references to mmio
-
-Both device and driver conformance referred to ccw twice; let's add the
-correct mmio references.
-
- } \\
-\hline
--
2.20.1
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply related [flat|nested] 17+ messages in thread* [virtio-comment] [RFC PATCH 6/8] Remove all mentioned of subversion
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
` (4 preceding siblings ...)
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 5/8] Cleanup old changelog files Alex Bennée
@ 2020-03-27 10:38 ` Alex Bennée
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 7/8] make*: remove reliance on REVISION-DATE and use git Alex Bennée
` (3 subsequent siblings)
9 siblings, 0 replies; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 10:38 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
The repo hasn't been hosted in subversion for a while so the documents
are no longer relevant to working with the repo. Also remove the
unused code in the makezip.sh tool.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
getchangelog.pl | 114 ------------------------------------------------
git-svn.txt | 34 ---------------
makezip.sh | 9 +---
3 files changed, 1 insertion(+), 156 deletions(-)
delete mode 100755 getchangelog.pl
delete mode 100644 git-svn.txt
diff --git a/getchangelog.pl b/getchangelog.pl
deleted file mode 100755
index 5619ce4..0000000
--- a/getchangelog.pl
+++ /dev/null
@@ -1,114 +0,0 @@
-#!/usr/bin/perl
-
-use strict;
-
-my $rev = undef;
-if ($#ARGV >= 0) {
- $rev = shift @ARGV;
-} else {
- open(REV, "git svn log REVISION|") || die;
- while (<REV>) {
- next unless (m/^(r[0-9]+)/);
- #top revision is WD, skip it
- if (not defined $rev) {
- $rev = $1;
- next;
- } else {
- $rev = $1;
- last;
- }
- }
-}
-
-die unless $rev =~ m/^r([0-9]+)$/;
-$rev = $1;
-
-sub escapelatex {
- my $s = shift;
- $s =~ s/[\\]/\\textbackslash /go;
- $s =~ s/([&#%{}\$])/\\$1/go;
- $s =~ s/[~]/\\~{}/go;
- $s =~ s/(https?:\S*)/\\url{$1}/go;
-#1st line always on a separate paragraph
- $s =~ s/\n/\n\n/o;
-#Guess where new paragraph starts
- $s =~ s/\\.\n/.\n\n/go;
- $s =~ s/\n-/\n\n-/go;
- return $s;
-}
-
-#map editors to authors
-my %editors = {};
-$editors{'rusty'} = 'Rusty Russell <rusty@au1.ibm.com>';
-$editors{'hornet'} = 'Pawel Moll <pawel.moll@arm.com>';
-$editors{'cornelia.huck'} = 'Cornelia Huck <cornelia.huck@de.ibm.com>';
-$editors{'mstsirkin'} = 'Michael S. Tsirkin <mst@redhat.com>';
-
-my $cl = "";
-my $signoff = undef;
-my $editor = undef;
-my $date = undef;
-my $r = undef;
-open(LOG, "git svn log *tex|") || die;
-my $line = undef;
-while (<LOG>) {
- if (m/^------------------------------------------------------------------------$/) {
- next if ($cl eq "");
- # act on it
- my $author;
- if (defined $signoff) {
- $author = $signoff;
- } else {
- $author = $editors{$editor};
- }
- #strip mail info
- $author =~ s/\s*<.*//;
- $cl = escapelatex($cl);
- print "$r & $date & $author & { $cl } \\\\\n";
- print "\\hline\n";
-
- $cl = "";
- $signoff = undef;
- $editor = undef;
- $date = undef;
- $r = undef;
-
- $line = 0;
- next;
- }
- $line++;
-#r164 | mstsirkin | 2013-12-08 14:30:55 +0200 (Sun, 08 Dec 2013)| 6 lines
-
- if ($line eq 1) {
- die unless (m/^r[0-9]/);
- my @rinfo = split(/\s*\Q|\E\s*/, $_);
- $r = $rinfo[0];
-
- die unless $r =~ m/^r([0-9]+)$/;
- $r = $1;
- last if ($r <= $rev);
-
- $editor = $rinfo[1];
- $date = $rinfo[2];
- die unless ($date =~ m/^[^(]*\([^,]*,\s*([^)]+)\)\s*$/);
- $date = $1;
- next;
- }
- next if (m/^$/);
-
- # First signature is the author: needed?
- # ignore for now
- #if (not defined $signoff and m/^Signed-off-by:\s*(.*)/) {
- # $signoff = $1;
- #}
- # skip signatures
- next if (m/^\s*[A-Z][A-Za-z-]*-by:/);
-
-
- # fix bug: wrong date in some commit logs
- if (/Change accepted on VIRTIO TC Meeting, 3 December 2013/) {
- $_ = "Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014\n";
- }
-
- $cl .= $_;
-}
diff --git a/git-svn.txt b/git-svn.txt
deleted file mode 100644
index e094217..0000000
--- a/git-svn.txt
+++ /dev/null
@@ -1,34 +0,0 @@
-Using git svn with virtio svn repository:
-
-Initial clone (fetches all branches, takes a very long time):
- git svn clone -s https://tools.oasis-open.org/version-control/svn/virtio
-Pull:
- git svn rebase
-Push:
- git svn dcommit
-
-Tagging 1.0 cs02 to match the released specification:
- git branch -t v1.0-cs02
-
-Updating the trunk with all changes made on 1.0 branch:
-
- git config --global svn.pushmergeinfo true
- git checkout -b master origin/trunk
- git svn fetch
- git svn rebase -l
- git merge --no-ff origin/v1.0
- [ resolve merge conflicts ]
- git svn dcommit
-
-Faster initial clone from git mirror (example using mst's mirror at kernel.org):
-
- git clone git://git.kernel.org/pub/scm/virt/kvm/mst/virtio-text.git
- cd virtio-text
- git config --remove-section remote.origin
- git svn init -s https://tools.oasis-open.org/version-control/svn/virtio
- git svn rebase
- git checkout -b trunk origin/trunk
-
-Updating a git mirror from git-svn repository (after setting up a
-remote named "mirror"):
- git push mirror --prune +refs/remotes/origin/*:refs/heads/*
diff --git a/makezip.sh b/makezip.sh
index 3c94f8e..806fa52 100755
--- a/makezip.sh
+++ b/makezip.sh
@@ -3,15 +3,8 @@ export DATESTR=${DATESTR:-`cat REVISION-DATE`}
rm -f $SPECDOC.zip
if test -d .git; then
git archive --format=zip --prefix=tex/ -o $SPECDOC.zip HEAD
-elif test -d .svn; then
- rm -fr export-from-svn
- mkdir -p export-from-svn
- svn export . export-from-svn/tex
- cd export-from-svn/
- zip ../$SPECDOC.zip tex/
- cd ..
else
- echo Neither .git nor .svn found.
+ echo .git not found.
echo Falling back to generated list.
fi
zip -d $SPECDOC.zip tex/.gitattributes
--
2.20.1
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply related [flat|nested] 17+ messages in thread* [virtio-comment] [RFC PATCH 7/8] make*: remove reliance on REVISION-DATE and use git
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
` (5 preceding siblings ...)
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 6/8] Remove all mentioned of subversion Alex Bennée
@ 2020-03-27 10:38 ` Alex Bennée
2020-04-30 7:46 ` [virtio-comment] [mst@redhat.com: Re: [virtio-comment] [RFC PATCH 7/8] make*: remove reliance on REVISION-DATE and use git] Michael S. Tsirkin
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 8/8] Makefile: add simple make automation with clean target Alex Bennée
` (2 subsequent siblings)
9 siblings, 1 reply; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 10:38 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
Rather than manually tweaking REVISION-DATE and loading it into
DATESTR move all the logic into make-setup-generated.sh. While we are
at it we can query git directly for the state of tree and use that to
fill in the meta-data.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
REVISION-DATE | 1 -
make-setup-generated.sh | 54 +++++++++++++++++++++++++++++------------
makeall.sh | 1 -
makediff.sh | 1 -
makediffall.sh | 1 -
makediffwithbase.sh | 1 -
maketex.sh | 1 -
makezip.sh | 2 --
8 files changed, 38 insertions(+), 24 deletions(-)
delete mode 100644 REVISION-DATE
diff --git a/REVISION-DATE b/REVISION-DATE
deleted file mode 100644
index 59c9d17..0000000
--- a/REVISION-DATE
+++ /dev/null
@@ -1 +0,0 @@
-11 April 2019
diff --git a/make-setup-generated.sh b/make-setup-generated.sh
index f15d148..2faea0b 100755
--- a/make-setup-generated.sh
+++ b/make-setup-generated.sh
@@ -1,39 +1,61 @@
#! /bin/sh
+#
+# Generate version and metadata preamble for the document
+#
-VERSION=1.1
-DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
-if [ x"$DATESTR" = x ]; then
- ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
- DATESTR=`date -d "$DATE" +'%d %B %Y'`
+# Currently this works of the closest lightweight tag but we can
+# update this when we start using proper signed and annotated tags.
+TAG=$(git describe 2> /dev/null)
+if [ x"$TAG" = x ]; then
+ # no tag on head
+ TAG=$(git describe --dirty --tags)
+ # base date on now
+ DATESTR=$(date +'%d %B %Y')
+ COMMIT=$(git rev-parse --short HEAD)
+else
+ # base date on tag
+ DATESTR=$(git log HEAD^..HEAD --format=format:"%cd" --date=format:"%d %B %Y")
+ COMMIT=""
+fi
+
+VERSION=$(cut -d'-' -f2 <<EOF
+$TAG
+EOF
+ )
+
+# Finally check if we have un-committed changes in the tree
+if git diff-index --quiet HEAD -- ; then
+ COMMIT="$COMMIT with local changes"
+fi
+
+if [ x"$COMMIT" = x ]; then
+ WORKINGDRAFT=""
+else
+ WORKINGDRAFT=" (@ git $COMMIT)"
fi
case "$1" in
*-wd*)
STAGE=wd
STAGENAME="Working Draft"
- WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
;;
*-os*)
STAGE=os
STAGENAME="OASIS Standard"
- WORKINGDRAFT=""
;;
*-csd*)
STAGE=csd
- WORKINGDRAFT=`basename "$1" | sed 's/.*-csd//'`
- STAGENAME="Committee Specification Draft $WORKINGDRAFT"
+ STAGENAME="Committee Specification Draft$WORKINGDRAFT"
;;
*-csprd*)
STAGE=csprd
- WORKINGDRAFT=`basename "$1" | sed 's/.*-csprd//'`
- STAGENAME="Committee Specification Draft $WORKINGDRAFT"
- STAGEEXTRATITLE=" / \newline Public Review Draft $WORKINGDRAFT"
- STAGEEXTRA=" / Public Review Draft $WORKINGDRAFT"
+ STAGENAME="Committee Specification Draft$WORKINGDRAFT"
+ STAGEEXTRATITLE=" / \newline Public Review Draft$WORKINGDRAFT"
+ STAGEEXTRA=" / Public Review Draft$WORKINGDRAFT"
;;
*-cs*)
STAGE=cs
- WORKINGDRAFT=`basename "$1" | sed 's/.*-cs//'`
- STAGENAME="Committee Specification $WORKINGDRAFT"
+ STAGENAME="Committee Specification$WORKINGDRAFT"
;;
*)
echo Unknown doc type >&2
@@ -54,7 +76,7 @@ cat > setup-generated.tex <<EOF
% define VIRTIO Working Draft number and date
\newcommand{\virtiorev}{$VERSION}
\newcommand{\virtioworkingdraftdate}{$DATESTR}
-\newcommand{\virtioworkingdraft}{$WORKINGDRAFT}
+\newcommand{\virtioworkingdraft}{$COMMIT}
\newcommand{\virtiodraftstage}{$STAGE}
\newcommand{\virtiodraftstageextra}{$STAGEEXTRA}
\newcommand{\virtiodraftstageextratitle}{$STAGEEXTRATITLE}
diff --git a/makeall.sh b/makeall.sh
index 37e6c34..1e25b82 100755
--- a/makeall.sh
+++ b/makeall.sh
@@ -1,7 +1,6 @@
#!/bin/sh
export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
./makezip.sh
./makehtml.sh
./makepdf.sh
diff --git a/makediff.sh b/makediff.sh
index ef538c5..03f6731 100755
--- a/makediff.sh
+++ b/makediff.sh
@@ -1,7 +1,6 @@
#force revision and date in environment
#this way they don't appear in the diff
export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
export FROMVERSION=${FROMVERSION:-`cat DIFFVERSION`}
#make pdf diff using latexpand and latexdiff-fast
diff --git a/makediffall.sh b/makediffall.sh
index caff23e..f1a3333 100755
--- a/makediffall.sh
+++ b/makediffall.sh
@@ -1,5 +1,4 @@
export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
export FROMVERSION=${FROMVERSION:-`cat DIFFVERSION`}
./makezip.sh
mv -f $SPECDOC.zip $SPECDOC-diff-from-${FROMVERSION}.pdf
diff --git a/makediffwithbase.sh b/makediffwithbase.sh
index 8cd3c7a..3916c83 100755
--- a/makediffwithbase.sh
+++ b/makediffwithbase.sh
@@ -1,5 +1,4 @@
export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
./makezip.sh
./makehtml.sh
./makepdf.sh
diff --git a/maketex.sh b/maketex.sh
index c3b458f..1fee32b 100755
--- a/maketex.sh
+++ b/maketex.sh
@@ -1,3 +1,2 @@
export SPECDOC=${SPECDOC:-`cat REVISION`}-tex
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
./makezip.sh
diff --git a/makezip.sh b/makezip.sh
index 806fa52..40b13cc 100755
--- a/makezip.sh
+++ b/makezip.sh
@@ -1,5 +1,4 @@
export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
rm -f $SPECDOC.zip
if test -d .git; then
git archive --format=zip --prefix=tex/ -o $SPECDOC.zip HEAD
@@ -15,6 +14,5 @@ zip $SPECDOC.zip listings/virtio_queue.h
rm -fr tmpfilesforzip
mkdir -p tmpfilesforzip/tex
echo "$SPECDOC" > tmpfilesforzip/tex/REVISION
-echo "$DATESTR" > tmpfilesforzip/tex/REVISION-DATE
cd tmpfilesforzip
zip ../$SPECDOC.zip tex/*
--
2.20.1
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply related [flat|nested] 17+ messages in thread* [virtio-comment] [mst@redhat.com: Re: [virtio-comment] [RFC PATCH 7/8] make*: remove reliance on REVISION-DATE and use git]
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 7/8] make*: remove reliance on REVISION-DATE and use git Alex Bennée
@ 2020-04-30 7:46 ` Michael S. Tsirkin
0 siblings, 0 replies; 17+ messages in thread
From: Michael S. Tsirkin @ 2020-04-30 7:46 UTC (permalink / raw)
To: Alex Bennée; +Cc: virtio-comment
Forgot to Cc list by mistake.
Apropos, please do not copy both virtio-dev and virtio-comment.
virtio-dev is for implementation, virtio-comment for spec feedback.
----- Forwarded message from "Michael S. Tsirkin" <mst@redhat.com> -----
Date: Thu, 30 Apr 2020 03:44:57 -0400
From: "Michael S. Tsirkin" <mst@redhat.com>
To: Alex Bennée <alex.bennee@linaro.org>
Subject: Re: [virtio-comment] [RFC PATCH 7/8] make*: remove reliance on REVISION-DATE and use git
Message-ID: <20200430034211-mutt-send-email-mst@kernel.org>
In-Reply-To: <20200327103803.10460-8-alex.bennee@linaro.org>
On Fri, Mar 27, 2020 at 10:38:02AM +0000, Alex Bennée wrote:
> Rather than manually tweaking REVISION-DATE and loading it into
> DATESTR move all the logic into make-setup-generated.sh. While we are
> at it we can query git directly for the state of tree and use that to
> fill in the meta-data.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
I frankly find it more robust not to depend on current date,
git tags, or anything like this. People should be able to
generate exactly the same pdf/html from same sources without effort.
Additionally, it needs to be possible to build from tarball,
not just from git.
One exception where it's not possible ATM is
with redline, that requires git. Would be nice to fix.
> ---
> REVISION-DATE | 1 -
> make-setup-generated.sh | 54 +++++++++++++++++++++++++++++------------
> makeall.sh | 1 -
> makediff.sh | 1 -
> makediffall.sh | 1 -
> makediffwithbase.sh | 1 -
> maketex.sh | 1 -
> makezip.sh | 2 --
> 8 files changed, 38 insertions(+), 24 deletions(-)
> delete mode 100644 REVISION-DATE
>
> diff --git a/REVISION-DATE b/REVISION-DATE
> deleted file mode 100644
> index 59c9d17..0000000
> --- a/REVISION-DATE
> +++ /dev/null
> @@ -1 +0,0 @@
> -11 April 2019
> diff --git a/make-setup-generated.sh b/make-setup-generated.sh
> index f15d148..2faea0b 100755
> --- a/make-setup-generated.sh
> +++ b/make-setup-generated.sh
> @@ -1,39 +1,61 @@
> #! /bin/sh
> +#
> +# Generate version and metadata preamble for the document
> +#
>
> -VERSION=1.1
> -DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
> -if [ x"$DATESTR" = x ]; then
> - ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
> - DATESTR=`date -d "$DATE" +'%d %B %Y'`
> +# Currently this works of the closest lightweight tag but we can
> +# update this when we start using proper signed and annotated tags.
> +TAG=$(git describe 2> /dev/null)
> +if [ x"$TAG" = x ]; then
> + # no tag on head
> + TAG=$(git describe --dirty --tags)
> + # base date on now
> + DATESTR=$(date +'%d %B %Y')
> + COMMIT=$(git rev-parse --short HEAD)
> +else
> + # base date on tag
> + DATESTR=$(git log HEAD^..HEAD --format=format:"%cd" --date=format:"%d %B %Y")
> + COMMIT=""
> +fi
> +
> +VERSION=$(cut -d'-' -f2 <<EOF
> +$TAG
> +EOF
> + )
> +
> +# Finally check if we have un-committed changes in the tree
> +if git diff-index --quiet HEAD -- ; then
> + COMMIT="$COMMIT with local changes"
> +fi
> +
> +if [ x"$COMMIT" = x ]; then
> + WORKINGDRAFT=""
> +else
> + WORKINGDRAFT=" (@ git $COMMIT)"
> fi
>
> case "$1" in
> *-wd*)
> STAGE=wd
> STAGENAME="Working Draft"
> - WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
> ;;
> *-os*)
> STAGE=os
> STAGENAME="OASIS Standard"
> - WORKINGDRAFT=""
> ;;
> *-csd*)
> STAGE=csd
> - WORKINGDRAFT=`basename "$1" | sed 's/.*-csd//'`
> - STAGENAME="Committee Specification Draft $WORKINGDRAFT"
> + STAGENAME="Committee Specification Draft$WORKINGDRAFT"
> ;;
> *-csprd*)
> STAGE=csprd
> - WORKINGDRAFT=`basename "$1" | sed 's/.*-csprd//'`
> - STAGENAME="Committee Specification Draft $WORKINGDRAFT"
> - STAGEEXTRATITLE=" / \newline Public Review Draft $WORKINGDRAFT"
> - STAGEEXTRA=" / Public Review Draft $WORKINGDRAFT"
> + STAGENAME="Committee Specification Draft$WORKINGDRAFT"
> + STAGEEXTRATITLE=" / \newline Public Review Draft$WORKINGDRAFT"
> + STAGEEXTRA=" / Public Review Draft$WORKINGDRAFT"
> ;;
> *-cs*)
> STAGE=cs
> - WORKINGDRAFT=`basename "$1" | sed 's/.*-cs//'`
> - STAGENAME="Committee Specification $WORKINGDRAFT"
> + STAGENAME="Committee Specification$WORKINGDRAFT"
> ;;
> *)
> echo Unknown doc type >&2
> @@ -54,7 +76,7 @@ cat > setup-generated.tex <<EOF
> % define VIRTIO Working Draft number and date
> \newcommand{\virtiorev}{$VERSION}
> \newcommand{\virtioworkingdraftdate}{$DATESTR}
> -\newcommand{\virtioworkingdraft}{$WORKINGDRAFT}
> +\newcommand{\virtioworkingdraft}{$COMMIT}
> \newcommand{\virtiodraftstage}{$STAGE}
> \newcommand{\virtiodraftstageextra}{$STAGEEXTRA}
> \newcommand{\virtiodraftstageextratitle}{$STAGEEXTRATITLE}
> diff --git a/makeall.sh b/makeall.sh
> index 37e6c34..1e25b82 100755
> --- a/makeall.sh
> +++ b/makeall.sh
> @@ -1,7 +1,6 @@
> #!/bin/sh
>
> export SPECDOC=${SPECDOC:-`cat REVISION`}
> -export DATESTR=${DATESTR:-`cat REVISION-DATE`}
> ./makezip.sh
> ./makehtml.sh
> ./makepdf.sh
> diff --git a/makediff.sh b/makediff.sh
> index ef538c5..03f6731 100755
> --- a/makediff.sh
> +++ b/makediff.sh
> @@ -1,7 +1,6 @@
> #force revision and date in environment
> #this way they don't appear in the diff
> export SPECDOC=${SPECDOC:-`cat REVISION`}
> -export DATESTR=${DATESTR:-`cat REVISION-DATE`}
> export FROMVERSION=${FROMVERSION:-`cat DIFFVERSION`}
>
> #make pdf diff using latexpand and latexdiff-fast
> diff --git a/makediffall.sh b/makediffall.sh
> index caff23e..f1a3333 100755
> --- a/makediffall.sh
> +++ b/makediffall.sh
> @@ -1,5 +1,4 @@
> export SPECDOC=${SPECDOC:-`cat REVISION`}
> -export DATESTR=${DATESTR:-`cat REVISION-DATE`}
> export FROMVERSION=${FROMVERSION:-`cat DIFFVERSION`}
> ./makezip.sh
> mv -f $SPECDOC.zip $SPECDOC-diff-from-${FROMVERSION}.pdf
> diff --git a/makediffwithbase.sh b/makediffwithbase.sh
> index 8cd3c7a..3916c83 100755
> --- a/makediffwithbase.sh
> +++ b/makediffwithbase.sh
> @@ -1,5 +1,4 @@
> export SPECDOC=${SPECDOC:-`cat REVISION`}
> -export DATESTR=${DATESTR:-`cat REVISION-DATE`}
> ./makezip.sh
> ./makehtml.sh
> ./makepdf.sh
> diff --git a/maketex.sh b/maketex.sh
> index c3b458f..1fee32b 100755
> --- a/maketex.sh
> +++ b/maketex.sh
> @@ -1,3 +1,2 @@
> export SPECDOC=${SPECDOC:-`cat REVISION`}-tex
> -export DATESTR=${DATESTR:-`cat REVISION-DATE`}
> ./makezip.sh
> diff --git a/makezip.sh b/makezip.sh
> index 806fa52..40b13cc 100755
> --- a/makezip.sh
> +++ b/makezip.sh
> @@ -1,5 +1,4 @@
> export SPECDOC=${SPECDOC:-`cat REVISION`}
> -export DATESTR=${DATESTR:-`cat REVISION-DATE`}
> rm -f $SPECDOC.zip
> if test -d .git; then
> git archive --format=zip --prefix=tex/ -o $SPECDOC.zip HEAD
> @@ -15,6 +14,5 @@ zip $SPECDOC.zip listings/virtio_queue.h
> rm -fr tmpfilesforzip
> mkdir -p tmpfilesforzip/tex
> echo "$SPECDOC" > tmpfilesforzip/tex/REVISION
> -echo "$DATESTR" > tmpfilesforzip/tex/REVISION-DATE
> cd tmpfilesforzip
> zip ../$SPECDOC.zip tex/*
> --
> 2.20.1
>
>
> This publicly archived list offers a means to provide input to the
> OASIS Virtual I/O Device (VIRTIO) TC.
>
> In order to verify user consent to the Feedback License terms and
> to minimize spam in the list archive, subscription is required
> before posting.
>
> Subscribe: virtio-comment-subscribe@lists.oasis-open.org
> Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
> List help: virtio-comment-help@lists.oasis-open.org
> List archive: https://lists.oasis-open.org/archives/virtio-comment/
> Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
> List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
> Committee: https://www.oasis-open.org/committees/virtio/
> Join OASIS: https://www.oasis-open.org/join/
----- End forwarded message -----
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply [flat|nested] 17+ messages in thread
* [virtio-comment] [RFC PATCH 8/8] Makefile: add simple make automation with clean target
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
` (6 preceding siblings ...)
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 7/8] make*: remove reliance on REVISION-DATE and use git Alex Bennée
@ 2020-03-27 10:38 ` Alex Bennée
2020-04-30 7:50 ` Michael S. Tsirkin
2020-03-27 10:53 ` [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Cornelia Huck
2020-04-06 11:14 ` [virtio-comment] " Alex Bennée
9 siblings, 1 reply; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 10:38 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
This will remove all intermediate files in the checkout.
---
Makefile | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
create mode 100644 Makefile
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..f11d871
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,17 @@
+# -*- Mode: makefile -*-
+#
+# Basic Makefile to aid automation of document building
+#
+
+.PHONY: help
+help:
+ @echo "Build the VIRTIO specification documents."
+ @echo ""
+ @echo "Possible operations are:"
+ @echo
+ @echo " $(MAKE) clean Remove all intermediate files"
+
+
+.PHONY: clean
+clean:
+ @rm -f (git ls-files --others --exclude-standard)
--
2.20.1
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply related [flat|nested] 17+ messages in thread* Re: [virtio-comment] [RFC PATCH 8/8] Makefile: add simple make automation with clean target
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 8/8] Makefile: add simple make automation with clean target Alex Bennée
@ 2020-04-30 7:50 ` Michael S. Tsirkin
0 siblings, 0 replies; 17+ messages in thread
From: Michael S. Tsirkin @ 2020-04-30 7:50 UTC (permalink / raw)
To: Alex Bennée; +Cc: virtio-comment
On Fri, Mar 27, 2020 at 10:38:03AM +0000, Alex Bennée wrote:
> This will remove all intermediate files in the checkout.
> ---
> Makefile | 17 +++++++++++++++++
> 1 file changed, 17 insertions(+)
> create mode 100644 Makefile
>
> diff --git a/Makefile b/Makefile
> new file mode 100644
> index 0000000..f11d871
> --- /dev/null
> +++ b/Makefile
> @@ -0,0 +1,17 @@
> +# -*- Mode: makefile -*-
> +#
> +# Basic Makefile to aid automation of document building
> +#
> +
> +.PHONY: help
> +help:
> + @echo "Build the VIRTIO specification documents."
> + @echo ""
> + @echo "Possible operations are:"
> + @echo
> + @echo " $(MAKE) clean Remove all intermediate files"
> +
> +
> +.PHONY: clean
> +clean:
> + @rm -f (git ls-files --others --exclude-standard)
This makefile is not going to work in a tarball, so how about
just a shell script for now? E.g. makegitclean.sh?
> --
> 2.20.1
>
>
> This publicly archived list offers a means to provide input to the
> OASIS Virtual I/O Device (VIRTIO) TC.
>
> In order to verify user consent to the Feedback License terms and
> to minimize spam in the list archive, subscription is required
> before posting.
>
> Subscribe: virtio-comment-subscribe@lists.oasis-open.org
> Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
> List help: virtio-comment-help@lists.oasis-open.org
> List archive: https://lists.oasis-open.org/archives/virtio-comment/
> Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
> List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
> Committee: https://www.oasis-open.org/committees/virtio/
> Join OASIS: https://www.oasis-open.org/join/
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
` (7 preceding siblings ...)
2020-03-27 10:38 ` [virtio-comment] [RFC PATCH 8/8] Makefile: add simple make automation with clean target Alex Bennée
@ 2020-03-27 10:53 ` Cornelia Huck
2020-03-27 11:58 ` Alex Bennée
2020-04-06 11:14 ` [virtio-comment] " Alex Bennée
9 siblings, 1 reply; 17+ messages in thread
From: Cornelia Huck @ 2020-03-27 10:53 UTC (permalink / raw)
To: Alex Bennée; +Cc: virtio-dev, virtio-comment
On Fri, 27 Mar 2020 10:37:55 +0000
Alex Bennée <alex.bennee@linaro.org> wrote:
> Hi,
>
> I was reviewing someones virtio-spec and realised that I wasn't quite
> sure what it had been built from. Seeing as the standard is hosted in
> git I've tried to clean up some of the automation to make it clearer
> what a particular rendering was built from. Going forward it would be
> nice to use signed annotated tags for the final build version but I
> don't know how much of the boilerplate is down to OASIS requirements.
OASIS requirements are my concern here as well.
>
> What do people think? Is this worth improving on?
>
> Alex Bennée (8):
> README.md: convert html to proper Markdown format
> CONTRIBUTING.md: convert to proper MarkDown
> LICENSE.md: convert html to proper MarkDown
We should double-check first if the html snippets in there are sourced
into some official web page somewhere. If not, I'm all for converting
this.
> makeall.sh: add explicit shebang to script
> Cleanup old changelog files
I'm not sure if there are any requirements for keeping this -- even if
they are available in the history forever.
> Remove all mentioned of subversion
That's probably fine.
> make*: remove reliance on REVISION-DATE and use git
> Makefile: add simple make automation with clean target
>
> CONTRIBUTING.md | 22 +-
> LICENSE.md | 9 +-
> Makefile | 17 +
> README.md | 258 ++++------
> REVISION-DATE | 1 -
> cl-cs01.tex | 86 ----
> cl-cs02.tex | 52 --
> cl-cs03.tex | 328 ------------
> cl-cs04.tex | 134 -----
> cl-csprd02.tex | 1043 ---------------------------------------
> cl-csprd03.tex | 400 ---------------
> getchangelog.pl | 114 -----
> git-svn.txt | 34 --
> make-setup-generated.sh | 54 +-
> makeall.sh | 3 +-
> makediff.sh | 1 -
> makediffall.sh | 1 -
> makediffwithbase.sh | 1 -
> maketex.sh | 1 -
> makezip.sh | 11 +-
> 20 files changed, 169 insertions(+), 2401 deletions(-)
> create mode 100644 Makefile
> delete mode 100644 REVISION-DATE
> delete mode 100644 cl-cs01.tex
> delete mode 100644 cl-cs02.tex
> delete mode 100644 cl-cs03.tex
> delete mode 100644 cl-cs04.tex
> delete mode 100644 cl-csprd02.tex
> delete mode 100644 cl-csprd03.tex
> delete mode 100755 getchangelog.pl
> delete mode 100644 git-svn.txt
>
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply [flat|nested] 17+ messages in thread* Re: [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process
2020-03-27 10:53 ` [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Cornelia Huck
@ 2020-03-27 11:58 ` Alex Bennée
0 siblings, 0 replies; 17+ messages in thread
From: Alex Bennée @ 2020-03-27 11:58 UTC (permalink / raw)
To: Cornelia Huck; +Cc: virtio-dev, virtio-comment
Cornelia Huck <cohuck@redhat.com> writes:
> On Fri, 27 Mar 2020 10:37:55 +0000
> Alex Bennée <alex.bennee@linaro.org> wrote:
>
>> Hi,
>>
>> I was reviewing someones virtio-spec and realised that I wasn't quite
>> sure what it had been built from. Seeing as the standard is hosted in
>> git I've tried to clean up some of the automation to make it clearer
>> what a particular rendering was built from. Going forward it would be
>> nice to use signed annotated tags for the final build version but I
>> don't know how much of the boilerplate is down to OASIS requirements.
>
> OASIS requirements are my concern here as well.
I've tried to do some digging although the Oasis website has a lot of
policy documents. I think the most relevant one is:
https://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html
which as far as I can make out is mostly concerned that the final work
product meets the naming standard by version and stage. Although ZIP
files are mentioned a couple of times it is in the context of a file
containing work products for local use. My personal interpretation is
that if the final work products are correctly named and have the version
information in them the rest is just ephemera. However I could be wrong
so defer to anyone more familiar with the policies.
An random sampling of ZIP files on https://www.oasis-open.org/standards
has shown them all to just contain the individual work products without
any extraneous REVISION/REVISION-DATE files.
Anyway I defer to those with more experience of the process and I'll
leave the question of tex vs rst for another day ;-)
--
Alex Bennée
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply [flat|nested] 17+ messages in thread
* [virtio-comment] Re: [RFC PATCH 0/8] some tweaks to the document build process
2020-03-27 10:37 [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Alex Bennée
` (8 preceding siblings ...)
2020-03-27 10:53 ` [virtio-comment] [RFC PATCH 0/8] some tweaks to the document build process Cornelia Huck
@ 2020-04-06 11:14 ` Alex Bennée
9 siblings, 0 replies; 17+ messages in thread
From: Alex Bennée @ 2020-04-06 11:14 UTC (permalink / raw)
To: virtio-dev; +Cc: virtio-comment, Alex Bennée
Alex Bennée <alex.bennee@linaro.org> writes:
> Hi,
>
> I was reviewing someones virtio-spec and realised that I wasn't quite
> sure what it had been built from. Seeing as the standard is hosted in
> git I've tried to clean up some of the automation to make it clearer
> what a particular rendering was built from. Going forward it would be
> nice to use signed annotated tags for the final build version but I
> don't know how much of the boilerplate is down to OASIS requirements.
>
> What do people think? Is this worth improving on?
Ping? Any other feedback?
> Alex Bennée (8):
> README.md: convert html to proper Markdown format
> CONTRIBUTING.md: convert to proper MarkDown
> LICENSE.md: convert html to proper MarkDown
> makeall.sh: add explicit shebang to script
> Cleanup old changelog files
> Remove all mentioned of subversion
> make*: remove reliance on REVISION-DATE and use git
I've been looking at other OASIS zipfiles and I think I could dump
REVISION as well as it's all in the rendered docs.
> Makefile: add simple make automation with clean target
>
> CONTRIBUTING.md | 22 +-
> LICENSE.md | 9 +-
> Makefile | 17 +
> README.md | 258 ++++------
> REVISION-DATE | 1 -
> cl-cs01.tex | 86 ----
> cl-cs02.tex | 52 --
> cl-cs03.tex | 328 ------------
> cl-cs04.tex | 134 -----
> cl-csprd02.tex | 1043 ---------------------------------------
> cl-csprd03.tex | 400 ---------------
> getchangelog.pl | 114 -----
> git-svn.txt | 34 --
> make-setup-generated.sh | 54 +-
> makeall.sh | 3 +-
> makediff.sh | 1 -
> makediffall.sh | 1 -
> makediffwithbase.sh | 1 -
> maketex.sh | 1 -
> makezip.sh | 11 +-
> 20 files changed, 169 insertions(+), 2401 deletions(-)
> create mode 100644 Makefile
> delete mode 100644 REVISION-DATE
> delete mode 100644 cl-cs01.tex
> delete mode 100644 cl-cs02.tex
> delete mode 100644 cl-cs03.tex
> delete mode 100644 cl-cs04.tex
> delete mode 100644 cl-csprd02.tex
> delete mode 100644 cl-csprd03.tex
> delete mode 100755 getchangelog.pl
> delete mode 100644 git-svn.txt
--
Alex Bennée
This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.
Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
^ permalink raw reply [flat|nested] 17+ messages in thread