1 /* SPDX-License-Identifier: MIT */ 2 /* 3 * 9pfs.h -- Xen 9PFS transport 4 * 5 * Refer to docs/misc/9pfs.markdown for the specification 6 * 7 * Copyright (C) 2017 Stefano Stabellini <stefano@aporeto.com> 8 */ 9 10 #ifndef __XEN_PUBLIC_IO_9PFS_H__ 11 #define __XEN_PUBLIC_IO_9PFS_H__ 12 13 #include "../grant_table.h" 14 #include "ring.h" 15 16 /* 17 * See docs/misc/9pfs.pandoc in xen.git for the full specification: 18 * https://xenbits.xen.org/docs/unstable/misc/9pfs.html 19 */ 20 21 /* 22 ****************************************************************************** 23 * Xenstore 24 ****************************************************************************** 25 * 26 * The frontend and the backend connect via xenstore to exchange 27 * information. The toolstack creates front and back nodes with state 28 * XenbusStateInitialising. The protocol node name is **9pfs**. 29 * 30 * Multiple rings are supported for each frontend and backend connection. 31 * 32 ****************************************************************************** 33 * Backend XenBus Nodes 34 ****************************************************************************** 35 * 36 * Backend specific properties, written by the backend, read by the 37 * frontend: 38 * 39 * versions 40 * Values: <string> 41 * 42 * List of comma separated protocol versions supported by the backend. 43 * For example "1,2,3". Currently the value is just "1", as there is 44 * only one version. N.B.: this is the version of the Xen transport 45 * protocol, not the version of 9pfs supported by the server. 46 * 47 * max-rings 48 * Values: <uint32_t> 49 * 50 * The maximum supported number of rings per frontend. 51 * 52 * max-ring-page-order 53 * Values: <uint32_t> 54 * 55 * The maximum supported size of a memory allocation in units of 56 * log2n(machine pages), e.g. 1 = 2 pages, 2 == 4 pages, etc. It 57 * must be at least 1. 58 * 59 * Backend configuration nodes, written by the toolstack, read by the 60 * backend: 61 * 62 * path 63 * Values: <string> 64 * 65 * Host filesystem path to share. 66 * 67 * security_model 68 * Values: "none" 69 * 70 * *none*: files are stored using the same credentials as they are 71 * created on the guest (no user ownership squash or remap) 72 * Only "none" is supported in this version of the protocol. 73 * 74 * max-files 75 * Values: <uint32_t> 76 * 77 * The maximum number of files (including directories) allowed for 78 * this device. Backend support of this node is optional. If the node 79 * is not present or the value is zero the number of files is not 80 * limited. 81 * 82 * max-open-files 83 * Values: <uint32_t> 84 * 85 * The maximum number of files the guest is allowed to have opened 86 * concurrently. Multiple concurrent opens of the same file are counted 87 * individually. Backend support of this node is optional. If the node 88 * is not present or the value is zero a backend specific default is 89 * applied. 90 * 91 * max-space 92 * Values: <uint32_t> 93 * 94 * The maximum file space in MiBs the guest is allowed to use for this 95 * device. Backend support of this node is optional. If the node is 96 * not present or the value is zero the space is not limited. 97 * 98 * auto-delete 99 * Values: <bool> 100 * 101 * When set to "1" the backend will delete the file with the oldest 102 * modification date below <path> in case the allowed maximum file 103 * space (see <max-space>) or file number (see <max-files>) is being 104 * exceeded due to guest activity (creation or extension of files). 105 * Files currently opened by the guest won't be deleted. Backend 106 * support of this node is optional. 107 * 108 ****************************************************************************** 109 * Frontend XenBus Nodes 110 ****************************************************************************** 111 * 112 * version 113 * Values: <string> 114 * 115 * Protocol version, chosen among the ones supported by the backend 116 * (see **versions** under [Backend XenBus Nodes]). Currently the 117 * value must be "1". 118 * 119 * num-rings 120 * Values: <uint32_t> 121 * 122 * Number of rings. It needs to be lower or equal to max-rings. 123 * 124 * event-channel-<num> (event-channel-0, event-channel-1, etc) 125 * Values: <uint32_t> 126 * 127 * The identifier of the Xen event channel used to signal activity 128 * in the ring buffer. One for each ring. 129 * 130 * ring-ref<num> (ring-ref0, ring-ref1, etc) 131 * Values: <uint32_t> 132 * 133 * The Xen grant reference granting permission for the backend to 134 * map a page with information to setup a share ring. One for each 135 * ring. 136 * 137 * tag 138 * Values: <string> 139 * 140 * Alphanumeric tag that identifies the 9pfs share. The client needs 141 * to know the tag to be able to mount it. 142 * 143 ****************************************************************************** 144 * State Machine 145 ****************************************************************************** 146 * 147 * Initialization: 148 * 149 * *Front* *Back* 150 * XenbusStateInitialising XenbusStateInitialising 151 * - Query backend device 152 * identification data. 153 * - Publish backend features 154 * and transport parameters. 155 * | 156 * | 157 * V 158 * XenbusStateInitWait 159 * 160 * - Query virtual device 161 * properties. 162 * - Query backend features and 163 * transport parameters. 164 * - Setup OS device instance. 165 * - Allocate and initialize the 166 * request ring(s) and 167 * event-channel(s). 168 * - Publish transport parameters 169 * that will be in effect during 170 * this connection. 171 * | 172 * | 173 * V 174 * XenbusStateInitialised 175 * 176 * - Query frontend transport 177 * parameters. 178 * - Connect to the request ring(s) 179 * and event channel(s). 180 * | 181 * | 182 * V 183 * XenbusStateConnected 184 * 185 * - Query backend device properties. 186 * - Finalize OS virtual device 187 * instance. 188 * | 189 * | 190 * V 191 * XenbusStateConnected 192 * 193 * Once frontend and backend are connected, they have a shared page per 194 * ring, which are used to setup the rings, and an event channel per ring, 195 * which are used to send notifications. 196 * 197 * Shutdown: 198 * 199 * *Front* *Back* 200 * XenbusStateConnected XenbusStateConnected 201 * | 202 * | 203 * V 204 * XenbusStateClosing 205 * 206 * - Unmap grants 207 * - Unbind evtchns 208 * | 209 * | 210 * V 211 * XenbusStateClosing 212 * 213 * - Unbind evtchns 214 * - Free rings 215 * - Free data structures 216 * | 217 * | 218 * V 219 * XenbusStateClosed 220 * 221 * - Free remaining data structures 222 * | 223 * | 224 * V 225 * XenbusStateClosed 226 * 227 ****************************************************************************** 228 */ 229 230 DEFINE_XEN_FLEX_RING_AND_INTF(xen_9pfs); 231 232 #endif 233 234 /* 235 * Local variables: 236 * mode: C 237 * c-file-style: "BSD" 238 * c-basic-offset: 4 239 * tab-width: 4 240 * indent-tabs-mode: nil 241 * End: 242 */ 243