    /* SPDX-License-Identifier: MIT */
    /*
     * 9pfs.h -- Xen 9PFS transport
     *
     * Refer to docs/misc/9pfs.markdown for the specification
     *
     * Copyright (C) 2017 Stefano Stabellini <stefano@aporeto.com>
     */

    #ifndef __XEN_PUBLIC_IO_9PFS_H__
    #define __XEN_PUBLIC_IO_9PFS_H__

    #include "../grant_table.h"
    #include "ring.h"

    /*
     * 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.
     *
     *    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.
     *
     *    max-files
     *         Values:        <uint32_t>
     *
     *         The maximum number of files (including directories) allowed for
     *         this device. Backend support of this node is optional. If the node
     *         is not present or the value is zero the number of files is not
     *         limited.
     *
     *    max-open-files
     *         Values:        <uint32_t>
     *
     *         The maximum number of files the guest is allowed to have opened
     *         concurrently. Multiple concurrent opens of the same file are counted
     *         individually. Backend support of this node is optional. If the node
     *         is not present or the value is zero a backend specific default is
     *         applied.
     *
     *    max-space
     *         Values:        <uint32_t>
     *
     *         The maximum file space in MiBs the guest is allowed to use for this
     *         device. Backend support of this node is optional. If the node is
     *         not present or the value is zero the space is not limited.
     *
     *    auto-delete
     *         Values:        <bool>
     *
     *         When set to "1" the backend will delete the file with the oldest
     *         modification date below <path> in case the allowed maximum file
     *         space (see <max-space>) or file number (see <max-files>) is being
     *         exceeded due to guest activity (creation or extension of files).
     *         Files currently opened by the guest won't be deleted. Backend
     *         support of this node is optional.
     *
     ******************************************************************************
     *                            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.
     *
     *    tag
     *         Values:         <string>
     *
     *         Alphanumeric tag that identifies the 9pfs share. The client needs
     *         to know the tag to be able to mount it.
     *
     ******************************************************************************
     *                              State Machine
     ******************************************************************************
     *
     * Initialization:
     *
     *    *Front*                               *Back*
     *    XenbusStateInitialising               XenbusStateInitialising
     *                                          - Query backend device
     *                                            identification data.
     *                                          - Publish backend features
     *                                            and transport parameters.
     *                                                         |
     *                                                         |
     *                                                         V
     *                                                  XenbusStateInitWait
     *
     *    - Query virtual device
     *      properties.
     *    - Query backend features and
     *      transport parameters.
     *    - Setup OS device instance.
     *    - Allocate and initialize the
     *      request ring(s) and
     *      event-channel(s).
     *    - Publish transport parameters
     *      that will be in effect during
     *      this connection.
     *                 |
     *                 |
     *                 V
     *       XenbusStateInitialised
     *
     *                                          - Query frontend transport
     *                                            parameters.
     *                                          - Connect to the request ring(s)
     *                                            and event channel(s).
     *                                                         |
     *                                                         |
     *                                                         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

    /*
     * Local variables:
     * mode: C
     * c-file-style: "BSD"
     * c-basic-offset: 4
     * tab-width: 4
     * indent-tabs-mode: nil
     * End:
     */