| VIO9P(4D) | Devices | VIO9P(4D) |
vio9p — Virtio 9P
Transport Driver
/dev/9p/*
The vio9p driver provides access to 9P
transport devices commonly used by hypervisors and emulators to expose a
shared file system.
The vio9p driver is not a
Committed
interface, and may change at any time.
Each device corresponds to a specific 9P channel, providing
exclusive access to one consumer at a time. The device may be opened with an
open(2) call, which must include at
least the O_EXCL and O_RDWR
flags. The O_NONBLOCK or
O_NDELAY flags may be used if non-blocking reads and
writes are required.
Once open, read(2) and write(2) calls may be made against the resulting file descriptor. Writes represent a 9P request message sent to the hypervisor, and reads represent responses to those requests.
Unlike with other transports like TCP, the channel is not explicitly reset when the device is opened or closed. After a call to open(2), the application should use a version message to open a new session. This will explicitly discard any previous session, clunking any active fids in the process and negotiating an appropriate protocol version with the hypervisor. It is likely also appropriate to do this as part of closing the device, to allow the hypervisor to free any session tracking resources.
Writes must be well-formed 9P messages, conforming
to whichever 9P protocol specification is used by the hypervisor. In
particular, each message must include a minimum of seven bytes, representing
the message size[4], type[1], and
tag[2]. In most or all available protocol specifications,
these fields are unsigned integers in little-endian order. The driver limits
request and response size to 8192 bytes, and will fail larger writes with
EMSGSIZE. Applications should, in their initial
version message, negotiate an
msize[4] value
less than or equal to 8192 bytes.
Reads are interruptible and will block waiting for a response to a
request sent in a previous write. If insufficient buffer space is provided
to the read call to receive the message, the call will fail with
EOVERFLOW and the message will remain available for
a subsequent read. Messages are provided as-is to the application, including
the size[4], type[1], and
tag[2].
Depending on the 9P server provided by the hypervisor, requests that are issued concurrently may result in responses that arrive out of order. Applications should develop a strategy for allocating unique tag[2] values, so that request and response messages can be correlated.
The driver provides an ioctl,
VIO9P_IOC_MOUNT_TAG, to expose the
Mount
Tag string if one was provided by the hypervisor. The ioctl is
defined in <sys/vio9p.h>.
The argument must be a char *, pointing to a buffer of
VIO9P_MOUNT_TAG_SIZE bytes. On success, the buffer
will contain the mount tag string as read from the hypervisor, followed by a
null-terminating zero byte added by the driver to ensure the result can
always be treated as a C string. While the hypervisor is expected to provide
a human-readable C string, applications should take care to verify that the
contents are valid for display or other purposes. Note that even if
successfully read, the string may be empty.
| August 1, 2022 | OmniOS |