Re: [PATCH v4 2/2] docs: driver-api: virtio: virtio on Linux

On Thu, Aug 11, 2022 at 03:46:46PM +0200, Cornelia Huck wrote:

On Wed, Aug 10 2022, Ricardo Cañuelo [off-list ref] wrote:

quoted

Basic doc about Virtio on Linux and a short tutorial on Virtio drivers.

Signed-off-by: Ricardo Cañuelo <redacted>
---
 Documentation/driver-api/index.rst            |   1 +
 Documentation/driver-api/virtio/index.rst     |  11 ++
 Documentation/driver-api/virtio/virtio.rst    | 144 ++++++++++++++
 .../virtio/writing_virtio_drivers.rst         | 186 ++++++++++++++++++
 MAINTAINERS                                   |   1 +
 5 files changed, 343 insertions(+)
 create mode 100644 Documentation/driver-api/virtio/index.rst
 create mode 100644 Documentation/driver-api/virtio/virtio.rst
 create mode 100644 Documentation/driver-api/virtio/writing_virtio_drivers.rst

(...)

quoted

+.. rubric:: Footnotes
+
+.. [#f1] that's why they may be also referred as virtrings.

"referred to"

(...)

quoted

+The ``probe`` method does the minimum driver setup in this case
+(memory allocation for the device data) and initializes the
+virtqueue. The virtqueues are automatically enabled after ``probe``
+returns, sending the appropriate "DRIVER_OK" status signal to the
+device. If the virtqueues need to be enabled before ``probe`` ends, they
+can be manually enabled by calling virtio_device_ready():
+
+.. kernel-doc:: include/linux/virtio_config.h
+    :identifiers: virtio_device_ready

Hm, not quite sure what the actual expectations are here: Should the
driver set DRIVER_OK in its probe function, and the core only set it as
a fallback? Michael, Jason?

(...)

LGTM in general.

Generally driver should either call device_ready
or defer adding device to linux in a scan callback.

Doing neither is likely a bug since you might
then be asked to add buffers before DRIVER_OK is set,
though e.g. if you are interrupt driven things might work
correctly.

-- 
MST