Cornelia Huck
2022-Oct-11 07:57 UTC
[RESEND PATCH v5 1/1] docs: driver-api: virtio: virtio on Linux
On Tue, Oct 11 2022, Bagas Sanjaya <bagasdotme at gmail.com> wrote:> On 10/11/22 13:51, Cornelia Huck wrote: >> On Mon, Oct 10 2022, "Michael S. Tsirkin" <mst at redhat.com> wrote: >> >>> On Mon, Oct 10, 2022 at 03:43:46PM +0200, Cornelia Huck wrote: >>>> On Mon, Oct 10 2022, Bagas Sanjaya <bagasdotme at gmail.com> wrote: >>>> >>>>> On Mon, Oct 10, 2022 at 08:43:59AM +0200, Ricardo Ca?uelo wrote: >>>>>> + >>>>>> +References >>>>>> +=========>>>>>> + >>>>>> +_`[1]` Virtio Spec v1.2: >>>>>> +https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html >>>>>> + >>>>>> +Check for later versions of the spec as well. >>>>>> + >>>>> >>>>> The version checking should be made comment (not visible on the output): >>>>> >>>>> ---- >8 ---- >>>>> diff --git a/Documentation/driver-api/virtio/virtio.rst b/Documentation/driver-api/virtio/virtio.rst >>>>> index 70b3aa6bcf5518..4f3abbec4e8b2c 100644 >>>>> --- a/Documentation/driver-api/virtio/virtio.rst >>>>> +++ b/Documentation/driver-api/virtio/virtio.rst >>>>> @@ -134,7 +134,7 @@ References >>>>> _`[1]` Virtio Spec v1.2: >>>>> https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html >>>>> >>>>> -Check for later versions of the spec as well. >>>>> +.. Check for later versions of the spec as well. >>>>> >>>>> _`[2]` Virtqueues and virtio ring: How the data travels >>>>> https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels >>>>> >>>>>> diff --git a/Documentation/driver-api/virtio/writing_virtio_drivers.rst b/Documentation/driver-api/virtio/writing_virtio_drivers.rst >>>>>> new file mode 100644 >>>>>> index 000000000000..e14c58796d25 >>>>>> --- /dev/null >>>>>> +++ b/Documentation/driver-api/virtio/writing_virtio_drivers.rst >>>>>> <snipped>... >>>>>> +References >>>>>> +=========>>>>>> + >>>>>> +_`[1]` Virtio Spec v1.2: >>>>>> +https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html >>>>>> + >>>>>> +Check for later versions of the spec as well. >>>>> >>>>> Same reply. >>>> >>>> I don't think we should hide that in a comment -- unless you want to >>>> update this file every time a new version of the virtio spec gets >>>> released. >>> >>> What do you suggest? Just http://docs.oasis-open.org/virtio/virtio/ ? >> >> That one is ugly, as it is just a directory listing... my preference is >> to link to the latest version at the time of writing, and mentioning >> that there may be later versions available, i.e. what the patch does >> right now. >> > > IMO, we can link to current spec version and update it as newer version > becomes public; without adding "check for later version" comment note.Is it really that important to update? Unless the virtio innards change radically, looking at an older version is likely to be sufficient. ["We should update it" is likely to become "Oh, we should have updated it some time ago" IME :)]