include/asm-xen/ctrl_if.h

   1 /******************************************************************************
   2  * ctrl_if.h
   3  *
   4  * Management functions for special interface to the domain controller.
   5  *
   6  * Copyright (c) 2004, K A Fraser
   7  *
   8  * This file may be distributed separately from the Linux kernel, or
   9  * incorporated into other software packages, subject to the following license:
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this source file (the "Software"), to deal in the Software without
  13  * restriction, including without limitation the rights to use, copy, modify,
  14  * merge, publish, distribute, sublicense, and/or sell copies of the Software,
  15  * and to permit persons to whom the Software is furnished to do so, subject to
  16  * the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  24  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  26  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  27  * IN THE SOFTWARE.
  28  */
  29
  30 #ifndef __ASM_XEN__CTRL_IF_H__
  31 #define __ASM_XEN__CTRL_IF_H__
  32
  33 #include <asm-xen/hypervisor.h>
  34 #include <asm-xen/queues.h>
  35
  36 typedef control_msg_t ctrl_msg_t;
  37
  38 /*
  39  * Callback function type. Called for asynchronous processing of received
  40  * request messages, and responses to previously-transmitted request messages.
  41  * The parameters are (@msg, @id).
  42  *  @msg: Original request/response message (not a copy). The message can be
  43  *        modified in-place by the handler (e.g., a response callback can
  44  *        turn a request message into a response message in place). The message
  45  *        is no longer accessible after the callback handler returns -- if the
  46  *        message is required to persist for longer then it must be copied.
  47  *  @id:  (Response callbacks only) The 'id' that was specified when the
  48  *        original request message was queued for transmission.
  49  */
  50 typedef void (*ctrl_msg_handler_t)(ctrl_msg_t *, unsigned long);
  51
  52 /*
  53  * Send @msg to the domain controller. Execute @hnd when a response is
  54  * received, passing the response message and the specified @id. This
  55  * operation will not block: it will return -EAGAIN if there is no space.
  56  * Notes:
  57  *  1. The @msg is copied if it is transmitted and so can be freed after this
  58  *     function returns.
  59  *  2. If @hnd is NULL then no callback is executed.
  60  */
  61 int
  62 ctrl_if_send_message_noblock(
  63     ctrl_msg_t *msg,
  64     ctrl_msg_handler_t hnd,
  65     unsigned long id);
  66
  67 /*
  68  * Send @msg to the domain controller. Execute @hnd when a response is
  69  * received, passing the response message and the specified @id. This
  70  * operation will block until the message is sent, or a signal is received
  71  * for the calling process (unless @wait_state is TASK_UNINTERRUPTIBLE).
  72  * Notes:
  73  *  1. The @msg is copied if it is transmitted and so can be freed after this
  74  *     function returns.
  75  *  2. If @hnd is NULL then no callback is executed.
  76  */
  77 int
  78 ctrl_if_send_message_block(
  79     ctrl_msg_t *msg,
  80     ctrl_msg_handler_t hnd,
  81     unsigned long id,
  82     long wait_state);
  83
  84 /*
  85  * Send @msg to the domain controller. Block until the response is received,
  86  * and then copy it into the provided buffer, @rmsg.
  87  */
  88 int
  89 ctrl_if_send_message_and_get_response(
  90     ctrl_msg_t *msg,
  91     ctrl_msg_t *rmsg,
  92     long wait_state);
  93
  94 /*
  95  * Request a callback when there is /possibly/ space to immediately send a
  96  * message to the domain controller. This function returns 0 if there is
  97  * already space to trasnmit a message --- in this case the callback task /may/
  98  * still be executed. If this function returns 1 then the callback /will/ be
  99  * executed when space becomes available.
 100  */
 101 int
 102 ctrl_if_enqueue_space_callback(
 103     struct tq_struct *task);
 104
 105 /*
 106  * Send a response (@msg) to a message from the domain controller. This will
 107  * never block.
 108  * Notes:
 109  *  1. The @msg is copied and so can be freed after this function returns.
 110  *  2. The @msg may be the original request message, modified in-place.
 111  */
 112 void
 113 ctrl_if_send_response(
 114     ctrl_msg_t *msg);
 115
 116 /*
 117  * Register a receiver for typed messages from the domain controller. The
 118  * handler (@hnd) is called for every received message of specified @type.
 119  * Returns TRUE (non-zero) if the handler was successfully registered.
 120  * If CALLBACK_IN_BLOCKING CONTEXT is specified in @flags then callbacks will
 121  * occur in a context in which it is safe to yield (i.e., process context).
 122  */
 123 #define CALLBACK_IN_BLOCKING_CONTEXT 1
 124 int ctrl_if_register_receiver(
 125     u8 type,
 126     ctrl_msg_handler_t hnd,
 127     unsigned int flags);
 128
 129 /*
 130  * Unregister a receiver for typed messages from the domain controller. The
 131  * handler (@hnd) will not be executed after this function returns.
 132  */
 133 void
 134 ctrl_if_unregister_receiver(
 135     u8 type, ctrl_msg_handler_t hnd);
 136
 137 /* Suspend/resume notifications. */
 138 void ctrl_if_suspend(void);
 139 void ctrl_if_resume(void);
 140
 141 /* Start-of-day setup. */
 142 void ctrl_if_init(void);
 143
 144 /*
 145  * Returns TRUE if there are no outstanding message requests at the domain
 146  * controller. This can be used to ensure that messages have really flushed
 147  * through when it is not possible to use the response-callback interface.
 148  * WARNING: If other subsystems are using the control interface then this
 149  * function might never return TRUE!
 150  */
 151 int ctrl_if_transmitter_empty(void);  /* !! DANGEROUS FUNCTION !! */
 152
 153 /*
 154  * Manually discard response messages from the domain controller.
 155  * WARNING: This is usually done automatically -- this function should only
 156  * be called when normal interrupt mechanisms are disabled!
 157  */
 158 void ctrl_if_discard_responses(void); /* !! DANGEROUS FUNCTION !! */
 159
 160 #endif /* __ASM_XEN__CONTROL_IF_H__ */