kernel/generic/src/ipc/ipcrsc.c

   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 /* IPC resources management
  36  *
  37  * The goal of this source code is to properly manage IPC resources and allow
  38  * straight and clean clean-up procedure upon task termination.
  39  *
  40  * The pattern of usage of the resources is:
  41  * - allocate empty phone capability slot, connect | deallocate slot
  42  * - disconnect connected phone (some messages might be on the fly)
  43  * - find phone in slot and send a message using phone
  44  * - answer message to phone
  45  * - hangup phone (the caller has hung up)
  46  * - hangup phone (the answerbox is exiting)
  47  *
  48  * Locking strategy
  49  *
  50  * - To use a phone, disconnect a phone etc., the phone must be first locked and
  51  *   then checked that it is connected
  52  * - To connect an allocated phone it need not be locked (assigning pointer is
  53  *   atomic on all platforms)
  54  *
  55  * - To find an empty phone capability slot, the TASK must be locked
  56  * - To answer a message, the answerbox must be locked
  57  * - The locking of phone and answerbox is done at the ipc_ level.
  58  *   It is perfectly correct to pass unconnected phone to these functions and
  59  *   proper reply will be generated.
  60  *
  61  * Locking order
  62  *
  63  * - first phone, then answerbox
  64  *   + Easy locking on calls
  65  *   - Very hard traversing list of phones when disconnecting because the phones
  66  *     may disconnect during traversal of list of connected phones. The only
  67  *     possibility is try_lock with restart of list traversal.
  68  *
  69  * Destroying is less frequent, this approach is taken.
  70  *
  71  * Phone call
  72  *
  73  * *** Connect_me_to ***
  74  * The caller sends IPC_M_CONNECT_ME_TO to an answerbox. The server receives
  75  * 'phoneid' of the connecting phone as an ARG5. If it answers with RETVAL=0,
  76  * the phonecall is accepted, otherwise it is refused.
  77  *
  78  * *** Connect_to_me ***
  79  * The caller sends IPC_M_CONNECT_TO_ME.
  80  * The server receives an automatically opened phoneid. If it accepts
  81  * (RETVAL=0), it can use the phoneid immediately.  Possible race condition can
  82  * arise, when the client receives messages from new connection before getting
  83  * response for connect_to_me message. Userspace should implement handshake
  84  * protocol that would control it.
  85  *
  86  * Phone hangup
  87  *
  88  * *** The caller hangs up (sys_ipc_hangup) ***
  89  * - The phone is disconnected (no more messages can be sent over this phone),
  90  *   all in-progress messages are correctly handled. The answerbox receives
  91  *   IPC_M_PHONE_HUNGUP call from the phone that hung up. When all async calls
  92  *   are answered, the phone is deallocated.
  93  *
  94  * *** The answerbox hangs up (ipc_answer(EHANGUP))
  95  * - The phone is disconnected. EHANGUP response code is sent to the calling
  96  *   task. All new calls through this phone get a EHUNGUP error code, the task
  97  *   is expected to send an sys_ipc_hangup after cleaning up its internal
  98  *   structures.
  99  *
 100  *
 101  * Call forwarding
 102  *
 103  * The call can be forwarded, so that the answer to call is passed directly to
 104  * the original sender. However, this poses special problems regarding routing
 105  * of hangup messages.
 106  *
 107  * sys_ipc_hangup -> IPC_M_PHONE_HUNGUP
 108  * - this message CANNOT be forwarded
 109  *
 110  * EHANGUP during forward
 111  * - The *forwarding* phone will be closed, EFORWARD is sent to receiver.
 112  *
 113  * EHANGUP, ENOENT during forward
 114  * - EFORWARD is sent to the receiver, ipc_forward returns error code EFORWARD
 115  *
 116  * Cleanup strategy
 117  *
 118  * 1) Disconnect all our phones ('ipc_phone_hangup').
 119  *
 120  * 2) Disconnect all phones connected to answerbox.
 121  *
 122  * 3) Answer all messages in 'calls' and 'dispatched_calls' queues with
 123  *    appropriate error code (EHANGUP, EFORWARD).
 124  *
 125  * 4) Wait for all async answers to arrive and dispose of them.
 126  *
 127  */
 128
 129 #include <synch/spinlock.h>
 130 #include <ipc/ipc.h>
 131 #include <arch.h>
 132 #include <proc/task.h>
 133 #include <ipc/ipcrsc.h>
 134 #include <assert.h>
 135 #include <abi/errno.h>
 136 #include <cap/cap.h>
 137 #include <mm/slab.h>
 138
 139 /** Find call_t * in call table according to callid.
 140  *
 141  * @todo Some speedup (hash table?)
 142  *
 143  * @param callid Userspace hash of the call. Currently it is the call structure
 144  *               kernel address.
 145  *
 146  * @return NULL on not found, otherwise pointer to the call structure.
 147  *
 148  */
 149 call_t *get_call(sysarg_t callid)
 150 {
 151         call_t *result = NULL;
 152
 153         irq_spinlock_lock(&TASK->answerbox.lock, true);
 154
 155         list_foreach(TASK->answerbox.dispatched_calls, ab_link, call_t, call) {
 156                 if ((sysarg_t) call == callid) {
 157                         result = call;
 158                         break;
 159                 }
 160         }
 161
 162         irq_spinlock_unlock(&TASK->answerbox.lock, true);
 163         return result;
 164 }
 165
 166 /** Get phone from the current task by capability handle.
 167  *
 168  * @param handle  Phone capability handle.
 169  * @param phone   Place to store pointer to phone.
 170  *
 171  * @return  Address of the phone kernel object.
 172  * @return  NULL if the capability is invalid.
 173  *
 174  */
 175 phone_t *phone_get(task_t *task, int handle)
 176 {
 177         phone_t *phone;
 178
 179         caps_lock(task);
 180         cap_t *cap = cap_get(task, handle, CAP_TYPE_PHONE);
 181         phone = (phone_t *) cap->kobject;
 182         caps_unlock(task);
 183         if (!cap)
 184                 return NULL;
 185
 186         return phone;
 187 }
 188
 189 phone_t *phone_get_current(int handle)
 190 {
 191         return phone_get(TASK, handle);
 192 }
 193
 194 static bool phone_can_reclaim(cap_t *cap)
 195 {
 196         assert(cap->type == CAP_TYPE_PHONE);
 197
 198         phone_t *phone = (phone_t *) cap->kobject;
 199
 200         return (phone->state == IPC_PHONE_HUNGUP) &&
 201             (atomic_get(&phone->active_calls) == 0);
 202 }
 203
 204 /** Allocate new phone in the specified task.
 205  *
 206  * @param task  Task for which to allocate a new phone.
 207  *
 208  * @return  New phone capability handle.
 209  * @return  Negative error code if a new capability cannot be allocated.
 210  */
 211 int phone_alloc(task_t *task)
 212 {
 213         int handle = cap_alloc(task);
 214         if (handle >= 0) {
 215                 phone_t *phone = slab_alloc(phone_slab, FRAME_ATOMIC);
 216                 if (!phone) {
 217                         cap_free(TASK, handle);
 218                         return ENOMEM;
 219                 }
 220
 221                 ipc_phone_init(phone, task);
 222                 phone->state = IPC_PHONE_CONNECTING;
 223
 224                 // FIXME: phase this out eventually
 225                 mutex_lock(&task->cap_info->lock);
 226                 cap_t *cap = cap_get(task, handle, CAP_TYPE_ALLOCATED);
 227                 cap->can_reclaim = phone_can_reclaim;
 228                 mutex_unlock(&task->cap_info->lock);
 229
 230                 cap_publish(task, handle, CAP_TYPE_PHONE, phone);
 231         }
 232
 233         return handle;
 234 }
 235
 236 /** Free slot from a disconnected phone.
 237  *
 238  * All already sent messages will be correctly processed.
 239  *
 240  * @param handle Phone capability handle of the phone to be freed.
 241  *
 242  */
 243 void phone_dealloc(int handle)
 244 {
 245         cap_t *cap = cap_unpublish(TASK, handle, CAP_TYPE_PHONE);
 246         assert(cap);
 247
 248         phone_t *phone = (phone_t *) cap->kobject;
 249
 250         assert(phone);
 251         assert(phone->state == IPC_PHONE_CONNECTING);
 252
 253         slab_free(phone_slab, phone);
 254         cap_free(TASK, handle);
 255 }
 256
 257 /** Connect phone to a given answerbox.
 258  *
 259  * @param handle  Capability handle of the phone to be connected.
 260  * @param box     Answerbox to which to connect the phone.
 261  * @return        True if the phone was connected, false otherwise.
 262  *
 263  * The procedure _enforces_ that the user first marks the phone busy (e.g. via
 264  * phone_alloc) and then connects the phone, otherwise race condition may
 265  * appear.
 266  *
 267  */
 268 bool phone_connect(int handle, answerbox_t *box)
 269 {
 270         phone_t *phone = phone_get_current(handle);
 271
 272         assert(phone);
 273         assert(phone->state == IPC_PHONE_CONNECTING);
 274
 275         return ipc_phone_connect(phone, box);
 276 }
 277
 278 /** @}
 279  */