1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2022 Oxide Computer Company 13.\" 14.Dd August 1, 2022 15.Dt VIO9P 4D 16.Os 17.Sh NAME 18.Nm vio9p 19.Nd Virtio 9P Transport Driver 20.Sh SYNOPSIS 21.Pa /dev/9p/* 22.Sh DESCRIPTION 23The 24.Nm 25driver provides access to 9P transport devices commonly used by hypervisors 26and emulators to expose a shared file system. 27.Pp 28The 29.Nm 30driver is not a 31.Sy Committed 32interface, and may change at any time. 33.Sh APPLICATION PROGRAMMING INTERFACE 34Each device corresponds to a specific 9P channel, providing exclusive access to 35one consumer at a time. 36The device may be opened with an 37.Xr open 2 38call, which must include at least the 39.Dv O_EXCL 40and 41.Dv O_RDWR 42flags. 43The 44.Dv O_NONBLOCK 45or 46.Dv O_NDELAY 47flags may be used if non-blocking reads and writes are required. 48.Pp 49Once open, 50.Xr read 2 51and 52.Xr write 2 53calls may be made against the resulting file descriptor. 54Writes represent a 9P request message sent to the hypervisor, and reads 55represent responses to those requests. 56.Pp 57Unlike with other transports like TCP, the channel is not explicitly reset when 58the device is opened or closed. 59After a call to 60.Xr open 2 , 61the application should use a 62.Sy version 63message to open a new session. 64This will explicitly discard any previous session, clunking any active fids in 65the process and negotiating an appropriate protocol version with the 66hypervisor. 67It is likely also appropriate to do this as part of closing the device, to 68allow the hypervisor to free any session tracking resources. 69.Pp 70Writes must be well-formed 9P messages, conforming to whichever 9P protocol 71specification is used by the hypervisor. 72In particular, each message must include a minimum of seven bytes, representing 73the message 74.Em size[4] , 75.Em type[1] , 76and 77.Em tag[2] . 78In most or all available protocol specifications, these fields are unsigned 79integers in little-endian order. 80The driver limits request and response size to 8192 bytes, and will fail larger 81writes with 82.Er EMSGSIZE . 83Applications should, in their initial 84.Sy version 85message, 86negotiate an 87.Em msize[4] 88value less than or equal to 8192 bytes. 89.Pp 90Reads are interruptible and will block waiting for a response to a request sent 91in a previous write. 92If insufficient buffer space is provided to the read call to receive the 93message, the call will fail with 94.Er EOVERFLOW 95and the message will remain available for a subsequent read. 96Messages are provided as-is to the application, including the 97.Em size[4] , 98.Em type[1] , 99and 100.Em tag[2] . 101.Pp 102Depending on the 9P server provided by the hypervisor, requests that are issued 103concurrently may result in responses that arrive out of order. 104Applications should develop a strategy for allocating unique 105.Em tag[2] 106values, so that request and response messages can be correlated. 107.Sh IOCTLS 108The driver provides an ioctl, 109.Dv VIO9P_IOC_MOUNT_TAG , 110to expose the 111.Em Mount Tag 112string if one was provided by the hypervisor. 113The ioctl is defined in 114.In sys/vio9p.h . 115The argument must be a 116.Vt "char *" , 117pointing to a buffer of 118.Dv VIO9P_MOUNT_TAG_SIZE 119bytes. 120On success, the buffer will contain the mount tag string as read from the 121hypervisor, followed by a null-terminating zero byte added by the driver to 122ensure the result can always be treated as a C string. 123While the hypervisor is expected to provide a human-readable C string, 124applications should take care to verify that the contents are valid for display 125or other purposes. 126Note that even if successfully read, the string may be empty. 127.Sh FILES 128.Bl -tag -width Pa 129.It Pa /dev/9p/* 130Character device for access to a 9P channel. 131.It Pa /kernel/drv/amd64/vio9p 132Device driver (x86) 133.El 134.Sh INTERFACE STABILITY 135.Sy Uncommitted 136.Sh SEE ALSO 137.Xr close 2 , 138.Xr ioctl 2 , 139.Xr open 2 , 140.Xr read 2 , 141.Xr write 2 142