virtio: add introduction to virtio, document virtio.h

[freebsd_igalic.co]

Summary

Add an entry page for the virtio subsystem and explain how it's held
together, then describe all virtio.h functions

Sponsored by: The FreeBSD Foundation

[freebsd_igalic.co]

I'd like to first hear some feedback on language, grammar, consistency, before opening this up to the people who know the code.
But I will say this: I'm not happy with this man page.
I'd much rather virtio(9) was an intro page into the virtio APIs, but I don't know how to slice it, yet.

[pstef]

share/man/man9/virtio.9

159

Not clear to me what is supposed to be plural or possessive here.

199

buses?

240

I'd remove the however or at least move it to the beginning of the sentence.

304

buses?
I'd move See to the next line

309

reinitialization or re-initialization

313

New sentence, new line?
There are more instances of this, I'll skip some of them.

340

I'd definitely move Conversely to the next line

[freebsd_igalic.co]

thank you for the review @pstef .
This update should address it.

[freebsd_igalic.co]

add more reviewers

[fernape]

My small take on this.

Thanks for working on this!

share/man/man9/virtio.9

62

VirtIO vs virtio in the rest of the document, including the summary.
For consistency, I would use VirtIO, since that seems to be the name of the technology/framework.

219

Avoid contractions:

it's --> it is

356

Since it is mentioned in the manual page, I'd probably add a cross reference for devmatch(8) and pci(9)

[freebsd_igalic.co]

address @fernape's review

[freebsd_igalic.co]

share/man/man9/virtio.9

62

i think i do that. I only use "virtio" once, in .Xr virtio 4

[fernape]

share/man/man9/virtio.9

62

I was thinking in the brief initial description:

virtio kernel programming interfaces vs VirtIO kernel programming interfaces

[freebsd_igalic.co]

*actually* address @fernape's review

[fernape]

One additional thing: virtio.9 is not hooked to the build. Could you add it to the Makefile?

[freebsd_igalic.co]

In D41853#955715, @fernape wrote:

One additional thing: virtio.9 is not hooked to the build. Could you add it to the Makefile?

I just realized I haven't stated that anywhere in the review, only in my request for review: https://lists.freebsd.org/archives/freebsd-virtualization/2023-September/001607.html

so then: does this man page make sense in this shape or would it benefit from being split thematically?
if the latter, where should it be split?

if the former, I'll happily hook it to the Makefile, including all of its aliases.

[fernape]

In D41853#955723, @freebsd_igalic.co wrote:

In D41853#955715, @fernape wrote:

One additional thing: virtio.9 is not hooked to the build. Could you add it to the Makefile?

I just realized I haven't stated that anywhere in the review, only in my request for review: https://lists.freebsd.org/archives/freebsd-virtualization/2023-September/001607.html

so then: does this man page make sense in this shape or would it benefit from being split thematically?
if the latter, where should it be split?

if the former, I'll happily hook it to the Makefile, including all of its aliases.

Ah, ok. I missed that, sorry.

I'm not sure we should split it.
I'm not familiar with the VirtIO API so I would like others to have a look at this :-)