Tribblix: manual page: vio9p.4d

VIO9P(4D) Devices VIO9P(4D)

NAME

vio9p - Virtio 9P Transport Driver

SYNOPSIS

/dev/9p/*

DESCRIPTION

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.

APPLICATION PROGRAMMING INTERFACE

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.

IOCTLS

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.

FILES

/dev/9p/* Character device for access to a 9P
channel.

/kernel/drv/amd64/vio9p Device driver (x86)

INTERFACE STABILITY

Uncommitted