xen-project/xen
1
0 Fork 0
mirror of https://github.com/xen-project/xen.git synced 2026-10-28 02:01:24 +01:00
Code Issues Activity

xen/public: move xenstore related doc into 9pfs.h

Browse Source 
The Xenstore related documentation is currently to be found in
docs/misc/9pfs.pandoc, instead of the related header file
xen/include/public/io/9pfs.h like for most other paravirtualized
device protocols.

There is a comment in the header pointing at the document, but the
given file name is wrong. Additionally such headers are meant to be
copied into consuming projects (Linux kernel, qemu, etc.), so pointing
at a doc file in the Xen git repository isn't really helpful for the
consumers of the header.

This situation is far from ideal, which is already being proved by the
fact that neither qemu nor the Linux kernel are implementing the
device attach/detach protocol correctly.

Change that by moving the Xenstore related 9pfs documentation from
docs/misc/9pfs.pandoc into xen/include/public/io/9pfs.h.

Signed-off-by: Juergen Gross <jgross@suse.com>
Reviewed-by: Julien Grall <jgrall@amazon.com>
This commit is contained in:
Juergen Gross authored and Jan Beulich committed 2023-02-06 08:52:15 +01:00
1 parent 207e584bd6
commit ad58142e73
2 files changed
+169 -150
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/misc/9pfs.pandoc
+4 -149
View File
@@ -59,155 +59,10 @@ This document does not cover the 9pfs client/server design or
implementation, only the transport for it.
## Xenstore
## Configuration
The frontend and the backend connect via xenstore to exchange
information. The toolstack creates front and back nodes with state
[XenbusStateInitialising]. The protocol node name is **9pfs**.
Multiple rings are supported for each frontend and backend connection.
### Backend XenBus Nodes
Backend specific properties, written by the backend, read by the
frontend:
versions
Values: <string>
List of comma separated protocol versions supported by the backend.
For example "1,2,3". Currently the value is just "1", as there is
only one version. N.B.: this is the version of the Xen trasport
protocol, not the version of 9pfs supported by the server.
max-rings
Values: <uint32_t>
The maximum supported number of rings per frontend.
max-ring-page-order
Values: <uint32_t>
The maximum supported size of a memory allocation in units of
log2n(machine pages), e.g. 1 = 2 pages, 2 == 4 pages, etc. It
must be at least 1.
Backend configuration nodes, written by the toolstack, read by the
backend:
path
Values: <string>
Host filesystem path to share.
tag
Values: <string>
Alphanumeric tag that identifies the 9pfs share. The client needs
to know the tag to be able to mount it.
security-model
Values: "none"
*none*: files are stored using the same credentials as they are
created on the guest (no user ownership squash or remap)
Only "none" is supported in this version of the protocol.
### Frontend XenBus Nodes
version
Values: <string>
Protocol version, chosen among the ones supported by the backend
(see **versions** under [Backend XenBus Nodes]). Currently the
value must be "1".
num-rings
Values: <uint32_t>
Number of rings. It needs to be lower or equal to max-rings.
event-channel-<num> (event-channel-0, event-channel-1, etc)
Values: <uint32_t>
The identifier of the Xen event channel used to signal activity
in the ring buffer. One for each ring.
ring-ref<num> (ring-ref0, ring-ref1, etc)
Values: <uint32_t>
The Xen grant reference granting permission for the backend to
map a page with information to setup a share ring. One for each
ring.
### State Machine
Initialization:
*Front* *Back*
XenbusStateInitialising XenbusStateInitialising
- Query virtual device - Query backend device
properties. identification data.
- Setup OS device instance. - Publish backend features
- Allocate and initialize the and transport parameters
request ring. |
- Publish transport parameters |
that will be in effect during V
this connection. XenbusStateInitWait
|
|
V
XenbusStateInitialised
- Query frontend transport parameters.
- Connect to the request ring and
event channel.
|
|
V
XenbusStateConnected
- Query backend device properties.
- Finalize OS virtual device
instance.
|
|
V
XenbusStateConnected
Once frontend and backend are connected, they have a shared page per
ring, which are used to setup the rings, and an event channel per ring,
which are used to send notifications.
Shutdown:
*Front* *Back*
XenbusStateConnected XenbusStateConnected
|
|
V
XenbusStateClosing
- Unmap grants
- Unbind evtchns
|
|
V
XenbusStateClosing
- Unbind evtchns
- Free rings
- Free data structures
|
|
V
XenbusStateClosed
- Free remaining data structures
|
|
V
XenbusStateClosed
The frontend and backend are configured via Xenstore. See [header] for
the detailed Xenstore entries and the connection protocol.
## Ring Setup
@@ -415,5 +270,5 @@ the *size* field of the 9pfs header.
[paper]: https://www.usenix.org/legacy/event/usenix05/tech/freenix/full_papers/hensbergen/hensbergen.pdf
[website]: https://github.com/chaos/diod/blob/master/protocol.md
[XenbusStateInitialising]: https://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,io,xenbus.h.html
[header]: https://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/io/9pfs.h;hb=HEAD
[ring.h]: https://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/io/ring.h;hb=HEAD
xen/include/public/io/9pfs.h
+165 -1
View File
@@ -14,9 +14,173 @@
#include "ring.h"
/*
* See docs/misc/9pfs.markdown in xen.git for the full specification:
* See docs/misc/9pfs.pandoc in xen.git for the full specification:
* https://xenbits.xen.org/docs/unstable/misc/9pfs.html
*/
/*
******************************************************************************
* Xenstore
******************************************************************************
*
* The frontend and the backend connect via xenstore to exchange
* information. The toolstack creates front and back nodes with state
* XenbusStateInitialising. The protocol node name is **9pfs**.
*
* Multiple rings are supported for each frontend and backend connection.
*
******************************************************************************
* Backend XenBus Nodes
******************************************************************************
*
* Backend specific properties, written by the backend, read by the
* frontend:
*
* versions
* Values: <string>
*
* List of comma separated protocol versions supported by the backend.
* For example "1,2,3". Currently the value is just "1", as there is
* only one version. N.B.: this is the version of the Xen transport
* protocol, not the version of 9pfs supported by the server.
*
* max-rings
* Values: <uint32_t>
*
* The maximum supported number of rings per frontend.
*
* max-ring-page-order
* Values: <uint32_t>
*
* The maximum supported size of a memory allocation in units of
* log2n(machine pages), e.g. 1 = 2 pages, 2 == 4 pages, etc. It
* must be at least 1.
*
* Backend configuration nodes, written by the toolstack, read by the
* backend:
*
* path
* Values: <string>
*
* Host filesystem path to share.
*
* tag
* Values: <string>
*
* Alphanumeric tag that identifies the 9pfs share. The client needs
* to know the tag to be able to mount it.
*
* security-model
* Values: "none"
*
* *none*: files are stored using the same credentials as they are
* created on the guest (no user ownership squash or remap)
* Only "none" is supported in this version of the protocol.
*
******************************************************************************
* Frontend XenBus Nodes
******************************************************************************
*
* version
* Values: <string>
*
* Protocol version, chosen among the ones supported by the backend
* (see **versions** under [Backend XenBus Nodes]). Currently the
* value must be "1".
*
* num-rings
* Values: <uint32_t>
*
* Number of rings. It needs to be lower or equal to max-rings.
*
* event-channel-<num> (event-channel-0, event-channel-1, etc)
* Values: <uint32_t>
*
* The identifier of the Xen event channel used to signal activity
* in the ring buffer. One for each ring.
*
* ring-ref<num> (ring-ref0, ring-ref1, etc)
* Values: <uint32_t>
*
* The Xen grant reference granting permission for the backend to
* map a page with information to setup a share ring. One for each
* ring.
*
******************************************************************************
* State Machine
******************************************************************************
*
* Initialization:
*
* *Front* *Back*
* XenbusStateInitialising XenbusStateInitialising
* - Query virtual device - Query backend device
* properties. identification data.
* - Setup OS device instance. - Publish backend features
* - Allocate and initialize the and transport parameters
* request ring. |
* - Publish transport parameters |
* that will be in effect during V
* this connection. XenbusStateInitWait
* |
* |
* V
* XenbusStateInitialised
*
* - Query frontend transport
* parameters.
* - Connect to the request ring and
* event channel.
* |
* |
* V
* XenbusStateConnected
*
* - Query backend device properties.
* - Finalize OS virtual device
* instance.
* |
* |
* V
* XenbusStateConnected
*
* Once frontend and backend are connected, they have a shared page per
* ring, which are used to setup the rings, and an event channel per ring,
* which are used to send notifications.
*
* Shutdown:
*
* *Front* *Back*
* XenbusStateConnected XenbusStateConnected
* |
* |
* V
* XenbusStateClosing
*
* - Unmap grants
* - Unbind evtchns
* |
* |
* V
* XenbusStateClosing
*
* - Unbind evtchns
* - Free rings
* - Free data structures
* |
* |
* V
* XenbusStateClosed
*
* - Free remaining data structures
* |
* |
* V
* XenbusStateClosed
*
******************************************************************************
*/
DEFINE_XEN_FLEX_RING_AND_INTF(xen_9pfs);
#endif
Reference in new issue
xen-project/xen
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.

The note is not visible to the blocked user.