abi/include/ipc/methods.h

   1 /*
   2  * Copyright (c) 2006 Ondrej Palkovsky
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * - Redistributions of source code must retain the above copyright
  10  *   notice, this list of conditions and the following disclaimer.
  11  * - Redistributions in binary form must reproduce the above copyright
  12  *   notice, this list of conditions and the following disclaimer in the
  13  *   documentation and/or other materials provided with the distribution.
  14  * - The name of the author may not be used to endorse or promote products
  15  *   derived from this software without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /** @addtogroup genericipc
  30  * @{
  31  */
  32 /** @file
  33  */
  34
  35 #ifndef ABI_IPC_METHODS_H_
  36 #define ABI_IPC_METHODS_H_
  37
  38 /* Well known phone descriptors */
  39 #define PHONE_NS  0
  40
  41 /** Kernel IPC interfaces
  42  *
  43  */
  44 #define IPC_IF_KERNEL  0
  45
  46 /** System-specific IPC methods
  47  *
  48  * These methods have special behaviour. These methods also
  49  * have the implicit kernel interface zero (0).
  50  *
  51  */
  52
  53 /** This message is sent to answerbox when the phone is hung up
  54  *
  55  * The numerical value zero (0) of this method is important,
  56  * so as the value can be easily tested in conditions.
  57  *
  58  */
  59 #define IPC_M_PHONE_HUNGUP  0
  60
  61 /** Clone connection.
  62  *
  63  * The calling task clones one of its phones for the callee.
  64  *
  65  * - ARG1 - The caller sets ARG1 to the phone of the cloned connection.
  66  *        - The callee gets the new phone from ARG1.
  67  *
  68  * - on answer, the callee acknowledges the new connection by sending EOK back
  69  *   or the kernel closes it
  70  *
  71  */
  72 #define IPC_M_CONNECTION_CLONE  1
  73
  74 /** Protocol for establishing a cloned connection.
  75  *
  76  * Through this call, the recipient learns about the new cloned connection.
  77  *
  78  * - ARG5 - the kernel sets ARG5 to contain the hash of the used phone
  79  * - on answer, the callee acknowledges the new connection by sending EOK back
  80  *   or the kernel closes it
  81  *
  82  */
  83 #define IPC_M_CLONE_ESTABLISH  2
  84
  85 /** Protocol for initializing callback connections.
  86  *
  87  * Calling process asks the callee to create a callback connection,
  88  * so that it can start initiating new messages.
  89  *
  90  * The protocol for negotiating is:
  91  * - sys_connect_to_me - sends a message IPC_M_CONNECT_TO_ME
  92  * - recipient         - upon receipt tries to allocate new phone
  93  *                       - if it fails, responds with ELIMIT
  94  *                     - passes call to userspace. If userspace
  95  *                       responds with error, phone is deallocated and
  96  *                       error is sent back to caller. Otherwise
  97  *                       the call is accepted and the response is sent back.
  98  *                     - the hash of the allocated phone is passed to userspace
  99  *                       (on the receiving side) as ARG5 of the call.
 100  *
 101  */
 102 #define IPC_M_CONNECT_TO_ME  3
 103
 104 /** Protocol for initializing new foward connections.
 105  *
 106  * Calling process asks the callee to create for him a new connection.
 107  * E.g. the caller wants a name server to connect him to print server.
 108  *
 109  * The protocol for negotiating is:
 110  * - sys_connect_me_to - send a synchronous message to name server
 111  *                       indicating that it wants to be connected to some
 112  *                       service
 113  *                     - arg1/2/3 are user specified, arg5 contains
 114  *                       address of the phone that should be connected
 115  *                       (TODO: it leaks to userspace)
 116  *  - recipient        -  if ipc_answer == 0, then accept connection
 117  *                     -  otherwise connection refused
 118  *                     -  recepient may forward message.
 119  *
 120  */
 121 #define IPC_M_CONNECT_ME_TO  4
 122
 123 /** Send as_area over IPC.
 124  * - ARG1 - source as_area base address
 125  * - ARG2 - size of source as_area (filled automatically by kernel)
 126  * - ARG3 - flags of the as_area being sent
 127  *
 128  * on answer, the recipient must set:
 129  *
 130  * - ARG1 - dst as_area lower bound
 131  * - ARG2 - dst as_area base adress pointer
 132  *          (filled automatically by the kernel)
 133  *
 134  */
 135 #define IPC_M_SHARE_OUT  5
 136
 137 /** Receive as_area over IPC.
 138  * - ARG1 - destination as_area size
 139  * - ARG2 - user defined argument
 140  *
 141  * on answer, the recipient must set:
 142  *
 143  * - ARG1 - source as_area base address
 144  * - ARG2 - flags that will be used for sharing
 145  * - ARG3 - dst as_area lower bound
 146  * - ARG4 - dst as_area base address (filled automatically by kernel)
 147  *
 148  */
 149 #define IPC_M_SHARE_IN  6
 150
 151 /** Send data to another address space over IPC.
 152  * - ARG1 - source address space virtual address
 153  * - ARG2 - size of data to be copied, may be overriden by the recipient
 154  *
 155  * on answer, the recipient must set:
 156  *
 157  * - ARG1 - final destination address space virtual address
 158  * - ARG2 - final size of data to be copied
 159  *
 160  */
 161 #define IPC_M_DATA_WRITE  7
 162
 163 /** Receive data from another address space over IPC.
 164  * - ARG1 - destination virtual address in the source address space
 165  * - ARG2 - size of data to be received, may be cropped by the recipient
 166  *
 167  * on answer, the recipient must set:
 168  *
 169  * - ARG1 - source virtual address in the destination address space
 170  * - ARG2 - final size of data to be copied
 171  *
 172  */
 173 #define IPC_M_DATA_READ  8
 174
 175 /** Authorize change of recipient's state in a third party task.
 176  * - ARG1 - user protocol defined data
 177  * - ARG2 - user protocol defined data
 178  * - ARG3 - user protocol defined data
 179  * - ARG5 - sender's phone to the third party task
 180  *
 181  * on EOK answer, the recipient must set:
 182  *
 183  * - ARG1 - recipient's phone to the third party task
 184  */
 185 #define IPC_M_STATE_CHANGE_AUTHORIZE  9
 186
 187 /** Debug the recipient.
 188  * - ARG1 - specifies the debug method (from udebug_method_t)
 189  * - other arguments are specific to the debug method
 190  *
 191  */
 192 #define IPC_M_DEBUG  10
 193
 194 /** Last system IPC method */
 195 #define IPC_M_LAST_SYSTEM  511
 196
 197 #endif
 198
 199 /** @}
 200  */