LCOV - code coverage report
Current view: top level - zephyr/xen/public - event_channel.h Coverage Total Hit
Test: new.info Lines: 0.0 % 60 0
Test Date: 2025-09-05 20:47:19

            Line data    Source code
       1            0 : /* SPDX-License-Identifier: MIT */
       2              : 
       3              : /******************************************************************************
       4              :  * event_channel.h
       5              :  *
       6              :  * Event channels between domains.
       7              :  *
       8              :  * Permission is hereby granted, free of charge, to any person obtaining a copy
       9              :  * of this software and associated documentation files (the "Software"), to
      10              :  * deal in the Software without restriction, including without limitation the
      11              :  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
      12              :  * sell copies of the Software, and to permit persons to whom the Software is
      13              :  * furnished to do so, subject to the following conditions:
      14              :  *
      15              :  * The above copyright notice and this permission notice shall be included in
      16              :  * all copies or substantial portions of the Software.
      17              :  *
      18              :  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
      19              :  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      20              :  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
      21              :  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      22              :  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
      23              :  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
      24              :  * DEALINGS IN THE SOFTWARE.
      25              :  *
      26              :  * Copyright (c) 2003-2004, K A Fraser.
      27              :  */
      28              : 
      29              : #ifndef __XEN_PUBLIC_EVENT_CHANNEL_H__
      30              : #define __XEN_PUBLIC_EVENT_CHANNEL_H__
      31              : 
      32              : #include "xen.h"
      33              : 
      34              : /*
      35              :  * `incontents 150 evtchn Event Channels
      36              :  *
      37              :  * Event channels are the basic primitive provided by Xen for event
      38              :  * notifications. An event is the Xen equivalent of a hardware
      39              :  * interrupt. They essentially store one bit of information, the event
      40              :  * of interest is signalled by transitioning this bit from 0 to 1.
      41              :  *
      42              :  * Notifications are received by a guest via an upcall from Xen,
      43              :  * indicating when an event arrives (setting the bit). Further
      44              :  * notifications are masked until the bit is cleared again (therefore,
      45              :  * guests must check the value of the bit after re-enabling event
      46              :  * delivery to ensure no missed notifications).
      47              :  *
      48              :  * Event notifications can be masked by setting a flag; this is
      49              :  * equivalent to disabling interrupts and can be used to ensure
      50              :  * atomicity of certain operations in the guest kernel.
      51              :  *
      52              :  * Event channels are represented by the evtchn_* fields in
      53              :  * struct shared_info and struct vcpu_info.
      54              :  */
      55              : 
      56            0 : #define EVTCHNOP_bind_interdomain       0
      57            0 : #define EVTCHNOP_bind_virq              1
      58            0 : #define EVTCHNOP_bind_pirq              2
      59            0 : #define EVTCHNOP_close                  3
      60            0 : #define EVTCHNOP_send                   4
      61            0 : #define EVTCHNOP_status                 5
      62            0 : #define EVTCHNOP_alloc_unbound          6
      63            0 : #define EVTCHNOP_bind_ipi               7
      64            0 : #define EVTCHNOP_bind_vcpu              8
      65            0 : #define EVTCHNOP_unmask                 9
      66            0 : #define EVTCHNOP_reset                  10
      67            0 : #define EVTCHNOP_init_control           11
      68            0 : #define EVTCHNOP_expand_array           12
      69            0 : #define EVTCHNOP_set_priority           13
      70              : #ifdef __XEN__
      71              : #define EVTCHNOP_reset_cont             14
      72              : #endif
      73              : 
      74            0 : typedef uint32_t evtchn_port_t;
      75            0 : DEFINE_XEN_GUEST_HANDLE(evtchn_port_t);
      76              : 
      77              : /*
      78              :  * EVTCHNOP_alloc_unbound: Allocate a port in domain <dom> and mark as
      79              :  * accepting interdomain bindings from domain <remote_dom>. A fresh port
      80              :  * is allocated in <dom> and returned as <port>.
      81              :  * NOTES:
      82              :  *  1. If the caller is unprivileged then <dom> must be DOMID_SELF.
      83              :  *  2. <remote_dom> may be DOMID_SELF, allowing loopback connections.
      84              :  */
      85            0 : struct evtchn_alloc_unbound {
      86              :         /* IN parameters */
      87            0 :         domid_t dom, remote_dom;
      88              :         /* OUT parameters */
      89            0 :         evtchn_port_t port;
      90              : };
      91            0 : typedef struct evtchn_alloc_unbound evtchn_alloc_unbound_t;
      92              : 
      93              : /*
      94              :  * EVTCHNOP_bind_interdomain: Construct an interdomain event channel between
      95              :  * the calling domain and <remote_dom>. <remote_dom,remote_port> must identify
      96              :  * a port that is unbound and marked as accepting bindings from the calling
      97              :  * domain. A fresh port is allocated in the calling domain and returned as
      98              :  * <local_port>.
      99              :  *
     100              :  * In case the peer domain has already tried to set our event channel
     101              :  * pending, before it was bound, EVTCHNOP_bind_interdomain always sets
     102              :  * the local event channel pending.
     103              :  *
     104              :  * The usual pattern of use, in the guest's upcall (or subsequent
     105              :  * handler) is as follows: (Re-enable the event channel for subsequent
     106              :  * signalling and then) check for the existence of whatever condition
     107              :  * is being waited for by other means, and take whatever action is
     108              :  * needed (if any).
     109              :  *
     110              :  * NOTES:
     111              :  *  1. <remote_dom> may be DOMID_SELF, allowing loopback connections.
     112              :  */
     113            0 : struct evtchn_bind_interdomain {
     114              :         /* IN parameters. */
     115            0 :         domid_t remote_dom;
     116            0 :         evtchn_port_t remote_port;
     117              :         /* OUT parameters. */
     118            0 :         evtchn_port_t local_port;
     119              : };
     120            0 : typedef struct evtchn_bind_interdomain evtchn_bind_interdomain_t;
     121              : 
     122              : /*
     123              :  * EVTCHNOP_close: Close a local event channel <port>. If the channel is
     124              :  * interdomain then the remote end is placed in the unbound state
     125              :  * (EVTCHNSTAT_unbound), awaiting a new connection.
     126              :  */
     127            0 : struct evtchn_close {
     128              :         /* IN parameters. */
     129            0 :         evtchn_port_t port;
     130              : };
     131            0 : typedef struct evtchn_close evtchn_close_t;
     132              : 
     133              : /*
     134              :  * EVTCHNOP_send: Send an event to the remote end of the channel whose local
     135              :  * endpoint is <port>.
     136              :  */
     137            0 : struct evtchn_send {
     138              :         /* IN parameters. */
     139            0 :         evtchn_port_t port;
     140              : };
     141            0 : typedef struct evtchn_send evtchn_send_t;
     142              : 
     143              : /*
     144              :  * EVTCHNOP_status: Get the current status of the communication channel which
     145              :  * has an endpoint at <dom, port>.
     146              :  * NOTES:
     147              :  *  1. <dom> may be specified as DOMID_SELF.
     148              :  *  2. Only a sufficiently-privileged domain may obtain the status of an event
     149              :  *     channel for which <dom> is not DOMID_SELF.
     150              :  */
     151            0 : struct evtchn_status {
     152              :         /* IN parameters */
     153            0 :         domid_t  dom;
     154            0 :         evtchn_port_t port;
     155              :         /* OUT parameters */
     156            0 : #define EVTCHNSTAT_closed       0 /* Channel is not in use.                 */
     157            0 : #define EVTCHNSTAT_unbound      1 /* Channel is waiting interdom connection.*/
     158            0 : #define EVTCHNSTAT_interdomain  2 /* Channel is connected to remote domain. */
     159            0 : #define EVTCHNSTAT_pirq         3 /* Channel is bound to a phys IRQ line.   */
     160            0 : #define EVTCHNSTAT_virq         4 /* Channel is bound to a virtual IRQ line */
     161            0 : #define EVTCHNSTAT_ipi          5 /* Channel is bound to a virtual IPI line */
     162            0 :         uint32_t status;
     163            0 :         uint32_t vcpu;                  /* VCPU to which this channel is bound.   */
     164              :         union {
     165              :                 struct {
     166              :                         domid_t dom;
     167            0 :                 } unbound;                      /* EVTCHNSTAT_unbound */
     168              :                 struct {
     169              :                         domid_t dom;
     170              :                         evtchn_port_t port;
     171            0 :                 } interdomain;                  /* EVTCHNSTAT_interdomain */
     172            0 :                 uint32_t pirq;                  /* EVTCHNSTAT_pirq */
     173            0 :                 uint32_t virq;                  /* EVTCHNSTAT_virq */
     174            0 :         } u;
     175              : };
     176            0 : typedef struct evtchn_status evtchn_status_t;
     177              : 
     178              : /*
     179              :  * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver
     180              :  * a notification to the appropriate VCPU if an event is pending.
     181              :  */
     182            0 : struct evtchn_unmask {
     183              :         /* IN parameters. */
     184            0 :         evtchn_port_t port;
     185              : };
     186            0 : typedef struct evtchn_unmask evtchn_unmask_t;
     187              : 
     188              : /*
     189              :  * EVTCHNOP_reset: Close all event channels associated with specified domain.
     190              :  * NOTES:
     191              :  *  1. <dom> may be specified as DOMID_SELF.
     192              :  *  2. Only a sufficiently-privileged domain may specify other than DOMID_SELF.
     193              :  *  3. Destroys all control blocks and event array, resets event channel
     194              :  *     operations to 2-level ABI if called with <dom> == DOMID_SELF and FIFO
     195              :  *     ABI was used. Guests should not bind events during EVTCHNOP_reset call
     196              :  *     as these events are likely to be lost.
     197              :  */
     198            0 : struct evtchn_reset {
     199              :         /* IN parameters. */
     200            0 :         domid_t dom;
     201              : };
     202            0 : typedef struct evtchn_reset evtchn_reset_t;
     203              : 
     204              : /*
     205              :  * EVTCHNOP_set_priority: set the priority for an event channel.
     206              :  */
     207            0 : struct evtchn_set_priority {
     208              :         /* IN parameters. */
     209            0 :         evtchn_port_t port;
     210            0 :         uint32_t priority;
     211              : };
     212            0 : typedef struct evtchn_set_priority evtchn_set_priority_t;
     213              : 
     214            0 : #define EVTCHN_2L_NR_CHANNELS (sizeof(xen_ulong_t) * sizeof(xen_ulong_t) * 64)
     215              : 
     216              : #endif /* __XEN_PUBLIC_EVENT_CHANNEL_H__ */
        

Generated by: LCOV version 2.0-1