Home | History | Annotate | Download | only in Protocol
      1 
      2 /** @file
      3   XenBus protocol to be used between the XenBus bus driver and Xen PV devices.
      4 
      5   DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
      6   should not be used outside of the EDK II tree.
      7 
      8   This protocol provide the necessary for a Xen PV driver frontend to
      9   communicate with the bus driver, and perform several task to
     10   initialize/shutdown a PV device and perform IO with a PV backend.
     11 
     12   Copyright (C) 2014, Citrix Ltd.
     13 
     14   This program and the accompanying materials
     15   are licensed and made available under the terms and conditions of the BSD License
     16   which accompanies this distribution.  The full text of the license may be found at
     17   http://opensource.org/licenses/bsd-license.php
     18 
     19   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
     20   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
     21 
     22 **/
     23 
     24 #ifndef __PROTOCOL_XENBUS_H__
     25 #define __PROTOCOL_XENBUS_H__
     26 
     27 #define XENBUS_PROTOCOL_GUID \
     28   {0x3d3ca290, 0xb9a5, 0x11e3, {0xb7, 0x5d, 0xb8, 0xac, 0x6f, 0x7d, 0x65, 0xe6}}
     29 
     30 ///
     31 /// Forward declaration
     32 ///
     33 typedef struct _XENBUS_PROTOCOL XENBUS_PROTOCOL;
     34 
     35 typedef enum xenbus_state XenBusState;
     36 
     37 typedef struct
     38 {
     39   UINT32 Id;
     40 } XENSTORE_TRANSACTION;
     41 
     42 #define XST_NIL ((XENSTORE_TRANSACTION *) NULL)
     43 
     44 typedef enum {
     45   XENSTORE_STATUS_SUCCESS = 0,
     46   XENSTORE_STATUS_FAIL,
     47   XENSTORE_STATUS_EINVAL,
     48   XENSTORE_STATUS_EACCES,
     49   XENSTORE_STATUS_EEXIST,
     50   XENSTORE_STATUS_EISDIR,
     51   XENSTORE_STATUS_ENOENT,
     52   XENSTORE_STATUS_ENOMEM,
     53   XENSTORE_STATUS_ENOSPC,
     54   XENSTORE_STATUS_EIO,
     55   XENSTORE_STATUS_ENOTEMPTY,
     56   XENSTORE_STATUS_ENOSYS,
     57   XENSTORE_STATUS_EROFS,
     58   XENSTORE_STATUS_EBUSY,
     59   XENSTORE_STATUS_EAGAIN,
     60   XENSTORE_STATUS_EISCONN,
     61   XENSTORE_STATUS_E2BIG
     62 } XENSTORE_STATUS;
     63 
     64 
     65 #include <IndustryStandard/Xen/grant_table.h>
     66 #include <IndustryStandard/Xen/event_channel.h>
     67 
     68 ///
     69 /// Function prototypes
     70 ///
     71 
     72 /**
     73   Get the contents of the node Node of the PV device. Returns the contents in
     74   *Result which should be freed after use.
     75 
     76   @param This           A pointer to XENBUS_PROTOCOL instance.
     77   @param Transaction    The XenStore transaction covering this request.
     78   @param Node           The basename of the file to read.
     79   @param Result         The returned contents from this file.
     80 
     81   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
     82            indicating the type of failure.
     83 
     84   @note The results buffer is malloced and should be free'd by the
     85         caller.
     86 **/
     87 typedef
     88 XENSTORE_STATUS
     89 (EFIAPI *XENBUS_XS_READ)(
     90   IN  XENBUS_PROTOCOL       *This,
     91   IN  CONST XENSTORE_TRANSACTION *Transaction,
     92   IN  CONST CHAR8           *Node,
     93   OUT VOID                  **Result
     94   );
     95 
     96 /**
     97   Get the contents of the node Node of the PV device's backend. Returns the
     98   contents in *Result which should be freed after use.
     99 
    100   @param This           A pointer to XENBUS_PROTOCOL instance.
    101   @param Transaction    The XenStore transaction covering this request.
    102   @param Node           The basename of the file to read.
    103   @param Result         The returned contents from this file.
    104 
    105   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    106            indicating the type of failure.
    107 
    108   @note The results buffer is malloced and should be free'd by the
    109         caller.
    110 **/
    111 typedef
    112 XENSTORE_STATUS
    113 (EFIAPI *XENBUS_XS_BACKEND_READ)(
    114   IN  XENBUS_PROTOCOL       *This,
    115   IN  CONST XENSTORE_TRANSACTION *Transaction,
    116   IN  CONST CHAR8           *Node,
    117   OUT VOID                  **Result
    118   );
    119 
    120 /**
    121   Print formatted write to a XenStore node.
    122 
    123   @param This             A pointer to XENBUS_PROTOCOL instance.
    124   @param Transaction      The XenStore transaction covering this request.
    125   @param Directory        The dirname of the path to read.
    126   @param Node             The basename of the path to read.
    127   @param Format           AsciiSPrint format string followed by a variable number
    128                           of arguments.
    129 
    130   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    131            indicating the type of write failure.
    132 **/
    133 typedef
    134 XENSTORE_STATUS
    135 (EFIAPI *XENBUS_XS_PRINTF) (
    136   IN XENBUS_PROTOCOL        *This,
    137   IN CONST XENSTORE_TRANSACTION *Transaction,
    138   IN CONST CHAR8            *Directory,
    139   IN CONST CHAR8            *Node,
    140   IN CONST CHAR8            *Format,
    141   ...
    142   );
    143 
    144 /**
    145   Remove a node or directory (directories must be empty) of the PV driver's
    146   subdirectory.
    147 
    148   @param This           A pointer to XENBUS_PROTOCOL instance.
    149   @param Transaction    The XenStore transaction covering this request.
    150   @param Node           The basename of the node to remove.
    151 
    152   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    153            indicating the type of failure.
    154 **/
    155 typedef
    156 XENSTORE_STATUS
    157 (EFIAPI *XENBUS_XS_REMOVE) (
    158   IN XENBUS_PROTOCOL        *This,
    159   IN CONST XENSTORE_TRANSACTION *Transaction,
    160   IN CONST CHAR8            *Node
    161   );
    162 
    163 /**
    164   Start a transaction.
    165 
    166   Changes by others will not be seen during the lifetime of this
    167   transaction, and changes will not be visible to others until it
    168   is committed (XsTransactionEnd).
    169 
    170   @param This         A pointer to XENBUS_PROTOCOL instance.
    171   @param Transaction  The returned transaction.
    172 
    173   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    174            indicating the type of failure.
    175 **/
    176 typedef
    177 XENSTORE_STATUS
    178 (EFIAPI *XENBUS_XS_TRANSACTION_START)(
    179   IN  XENBUS_PROTOCOL       *This,
    180   OUT XENSTORE_TRANSACTION  *Transaction
    181   );
    182 
    183 /**
    184   End a transaction.
    185 
    186   @param This         A pointer to XENBUS_PROTOCOL instance.
    187   @param Transaction  The transaction to end/commit.
    188   @param Abort        If TRUE, the transaction is discarded
    189                       instead of committed.
    190 
    191   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    192            indicating the type of failure.
    193 **/
    194 typedef
    195 XENSTORE_STATUS
    196 (EFIAPI *XENBUS_XS_TRANSACTION_END) (
    197   IN XENBUS_PROTOCOL        *This,
    198   IN CONST XENSTORE_TRANSACTION *Transaction,
    199   IN BOOLEAN                Abort
    200   );
    201 
    202 /**
    203   Set a new state for the frontend of the PV driver.
    204 
    205   @param This         A pointer to XENBUS_PROTOCOL instance.
    206   @param Transaction  The transaction to end/commit.
    207   @param State        The new state to apply.
    208 
    209   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    210            indicating the type of failure.
    211 **/
    212 typedef
    213 XENSTORE_STATUS
    214 (EFIAPI *XENBUS_SET_STATE)(
    215   IN XENBUS_PROTOCOL        *This,
    216   IN CONST XENSTORE_TRANSACTION *Transaction,
    217   IN XenBusState            State
    218   );
    219 
    220 /**
    221   Grant access to the page Frame to the domain DomainId.
    222 
    223   @param This       A pointer to XENBUS_PROTOCOL instance.
    224   @param DomainId   ID of the domain to grant acces to.
    225   @param Frame      Frame Number of the page to grant access to.
    226   @param ReadOnly   Provide read-only or read-write access.
    227   @param RefPtr     Reference number of the grant will be writen to this pointer.
    228 **/
    229 typedef
    230 EFI_STATUS
    231 (EFIAPI *XENBUS_GRANT_ACCESS)(
    232   IN  XENBUS_PROTOCOL *This,
    233   IN  domid_t         DomainId,
    234   IN  UINTN           Frame,
    235   IN  BOOLEAN         ReadOnly,
    236   OUT grant_ref_t     *refp
    237   );
    238 
    239 /**
    240   End access to grant Ref, previously return by XenBusGrantAccess.
    241 
    242   @param This       A pointer to XENBUS_PROTOCOL instance.
    243   @param Ref        Reference numeber of a grant previously returned by
    244                     XenBusGrantAccess.
    245 **/
    246 typedef
    247 EFI_STATUS
    248 (EFIAPI *XENBUS_GRANT_END_ACCESS)(
    249   IN XENBUS_PROTOCOL  *This,
    250   IN grant_ref_t      Ref
    251   );
    252 
    253 /**
    254   Allocate a port that can be bind from domain DomainId.
    255 
    256   @param This       A pointer to the XENBUS_PROTOCOL.
    257   @param DomainId   The domain ID that can bind the newly allocated port.
    258   @param Port       A pointer to a evtchn_port_t that will contain the newly
    259                     allocated port.
    260 
    261   @retval UINT32    The return value from the hypercall, 0 if success.
    262 **/
    263 typedef
    264 UINT32
    265 (EFIAPI *XENBUS_EVENT_CHANNEL_ALLOCATE) (
    266   IN  XENBUS_PROTOCOL *This,
    267   IN  domid_t         DomainId,
    268   OUT evtchn_port_t   *Port
    269   );
    270 
    271 /**
    272   Send an event to the remote end of the channel whose local endpoint is Port.
    273 
    274   @param This       A pointer to the XENBUS_PROTOCOL.
    275   @param Port       Local port to the the event from.
    276 
    277   @retval UINT32    The return value from the hypercall, 0 if success.
    278 **/
    279 typedef
    280 UINT32
    281 (EFIAPI *XENBUS_EVENT_CHANNEL_NOTIFY) (
    282   IN XENBUS_PROTOCOL  *This,
    283   IN evtchn_port_t    Port
    284   );
    285 
    286 /**
    287   Close a local event channel Port.
    288 
    289   @param This       A pointer to the XENBUS_PROTOCOL.
    290   @param Port       The event channel to close.
    291 
    292   @retval UINT32    The return value from the hypercall, 0 if success.
    293 **/
    294 typedef
    295 UINT32
    296 (EFIAPI *XENBUS_EVENT_CHANNEL_CLOSE) (
    297   IN XENBUS_PROTOCOL  *This,
    298   IN evtchn_port_t    Port
    299   );
    300 
    301 /**
    302   Register a XenStore watch.
    303 
    304   XenStore watches allow a client to wait for changes to an object in the
    305   XenStore.
    306 
    307   @param This       A pointer to the XENBUS_PROTOCOL.
    308   @param Node       The basename of the path to watch.
    309   @param Token      A token.
    310 
    311   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    312            indicating the type of write failure.  EEXIST errors from the
    313            XenStore are supressed, allowing multiple, physically different,
    314            xenbus_watch objects, to watch the same path in the XenStore.
    315 **/
    316 typedef
    317 XENSTORE_STATUS
    318 (EFIAPI *XENBUS_REGISTER_WATCH) (
    319   IN  XENBUS_PROTOCOL *This,
    320   IN  CONST CHAR8     *Node,
    321   OUT VOID            **Token
    322   );
    323 
    324 /**
    325   Register a XenStore watch on a backend's node.
    326 
    327   XenStore watches allow a client to wait for changes to an object in the
    328   XenStore.
    329 
    330   @param This       A pointer to the XENBUS_PROTOCOL.
    331   @param Node       The basename of the path to watch.
    332   @param Token      A token.
    333 
    334   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    335            indicating the type of write failure.  EEXIST errors from the
    336            XenStore are supressed, allowing multiple, physically different,
    337            xenbus_watch objects, to watch the same path in the XenStore.
    338 **/
    339 typedef
    340 XENSTORE_STATUS
    341 (EFIAPI *XENBUS_REGISTER_WATCH_BACKEND) (
    342   IN  XENBUS_PROTOCOL *This,
    343   IN  CONST CHAR8     *Node,
    344   OUT VOID            **Token
    345   );
    346 
    347 /**
    348   Unregister a XenStore watch.
    349 
    350   @param This   A pointer to the XENBUS_PROTOCOL.
    351   @param Token  An token previously returned by a successful
    352                 call to RegisterWatch ().
    353 **/
    354 typedef
    355 VOID
    356 (EFIAPI *XENBUS_UNREGISTER_WATCH) (
    357   IN XENBUS_PROTOCOL  *This,
    358   IN VOID             *Token
    359   );
    360 
    361 /**
    362   Block until the node watch by Token change.
    363 
    364   @param This   A pointer to the XENBUS_PROTOCOL.
    365   @param Token  An token previously returned by a successful
    366                 call to RegisterWatch or RegisterWatchBackend.
    367 
    368   @return  On success, XENSTORE_STATUS_SUCCESS. Otherwise an errno value
    369            indicating the type of failure.
    370 **/
    371 typedef
    372 XENSTORE_STATUS
    373 (EFIAPI *XENBUS_WAIT_FOR_WATCH) (
    374   IN XENBUS_PROTOCOL  *This,
    375   IN VOID             *Token
    376   );
    377 
    378 
    379 ///
    380 /// Protocol structure
    381 ///
    382 /// DISCLAIMER: the XENBUS_PROTOCOL introduced here is a work in progress, and
    383 /// should not be used outside of the EDK II tree.
    384 ///
    385 struct _XENBUS_PROTOCOL {
    386   XENBUS_XS_READ                XsRead;
    387   XENBUS_XS_BACKEND_READ        XsBackendRead;
    388   XENBUS_XS_PRINTF              XsPrintf;
    389   XENBUS_XS_REMOVE              XsRemove;
    390   XENBUS_XS_TRANSACTION_START   XsTransactionStart;
    391   XENBUS_XS_TRANSACTION_END     XsTransactionEnd;
    392   XENBUS_SET_STATE              SetState;
    393 
    394   XENBUS_GRANT_ACCESS           GrantAccess;
    395   XENBUS_GRANT_END_ACCESS       GrantEndAccess;
    396 
    397   XENBUS_EVENT_CHANNEL_ALLOCATE EventChannelAllocate;
    398   XENBUS_EVENT_CHANNEL_NOTIFY   EventChannelNotify;
    399   XENBUS_EVENT_CHANNEL_CLOSE    EventChannelClose;
    400 
    401   XENBUS_REGISTER_WATCH         RegisterWatch;
    402   XENBUS_REGISTER_WATCH_BACKEND RegisterWatchBackend;
    403   XENBUS_UNREGISTER_WATCH       UnregisterWatch;
    404   XENBUS_WAIT_FOR_WATCH         WaitForWatch;
    405   //
    406   // Protocol data fields
    407   //
    408   CONST CHAR8                   *Type;
    409   UINT16                        DeviceId;
    410   CONST CHAR8                   *Node;
    411   CONST CHAR8                   *Backend;
    412 };
    413 
    414 extern EFI_GUID gXenBusProtocolGuid;
    415 
    416 #endif
    417