Subversion Repositories HelenOS

Rev

Rev 2927 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed

  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 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 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.
  82.  * Possible race condition can arise, when the client receives messages from new
  83.  * connection before getting response for connect_to_me message. Userspace
  84.  * should implement handshake 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
  92.  *   calls 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
  96.  *   to the calling task. All new calls through this phone
  97.  *   get a EHUNGUP error code, the task is expected to
  98.  *   send an sys_ipc_hangup after cleaning up its internal structures.
  99.  *
  100.  * Call forwarding
  101.  *
  102.  * The call can be forwarded, so that the answer to call is passed directly
  103.  * to the original sender. However, this poses special problems regarding
  104.  * routing of hangup messages.
  105.  *
  106.  * sys_ipc_hangup -> IPC_M_PHONE_HUNGUP
  107.  * - this message CANNOT be forwarded
  108.  *
  109.  * EHANGUP during forward
  110.  * - The *forwarding* phone will be closed, EFORWARD is sent to receiver.
  111.  *
  112.  * EHANGUP, ENOENT during forward
  113.  * - EFORWARD is sent to the receiver, ipc_forward returns error code EFORWARD
  114.  *
  115.  * Cleanup strategy
  116.  *
  117.  * 1) Disconnect all our phones ('ipc_phone_hangup').
  118.  *
  119.  * 2) Disconnect all phones connected to answerbox.
  120.  *
  121.  * 3) Answer all messages in 'calls' and 'dispatched_calls' queues with
  122.  *    appropriate error code (EHANGUP, EFORWARD).
  123.  *
  124.  * 4) Wait for all async answers to arrive and dispose of them.
  125.  *
  126.  */
  127.  
  128. #include <synch/spinlock.h>
  129. #include <ipc/ipc.h>
  130. #include <arch.h>
  131. #include <proc/task.h>
  132. #include <ipc/ipcrsc.h>
  133. #include <debug.h>
  134.  
  135. /** Find call_t * in call table according to callid.
  136.  *
  137.  * @todo Some speedup (hash table?)
  138.  *
  139.  * @param callid    Userspace hash of the call. Currently it is the call
  140.  *          structure kernel address.
  141.  *
  142.  * @return      NULL on not found, otherwise pointer to the call
  143.  *          structure.
  144.  */
  145. call_t *get_call(unative_t callid)
  146. {
  147.     link_t *lst;
  148.     call_t *call, *result = NULL;
  149.  
  150.     spinlock_lock(&TASK->answerbox.lock);
  151.     for (lst = TASK->answerbox.dispatched_calls.next;
  152.         lst != &TASK->answerbox.dispatched_calls; lst = lst->next) {
  153.         call = list_get_instance(lst, call_t, link);
  154.         if ((unative_t) call == callid) {
  155.             result = call;
  156.             break;
  157.         }
  158.     }
  159.     spinlock_unlock(&TASK->answerbox.lock);
  160.     return result;
  161. }
  162.  
  163. /** Allocate new phone slot in the current TASK structure.
  164.  *
  165.  * @return      New phone handle or -1 if the phone handle limit is
  166.  *          exceeded.
  167.  */
  168. int phone_alloc(void)
  169. {
  170.     int i;
  171.  
  172.     spinlock_lock(&TASK->lock);
  173.     for (i = 0; i < IPC_MAX_PHONES; i++) {
  174.         if (TASK->phones[i].state == IPC_PHONE_HUNGUP &&
  175.             atomic_get(&TASK->phones[i].active_calls) == 0)
  176.             TASK->phones[i].state = IPC_PHONE_FREE;
  177.  
  178.         if (TASK->phones[i].state == IPC_PHONE_FREE) {
  179.             TASK->phones[i].state = IPC_PHONE_CONNECTING;
  180.             break;
  181.         }
  182.     }
  183.     spinlock_unlock(&TASK->lock);
  184.  
  185.     if (i == IPC_MAX_PHONES)
  186.         return -1;
  187.  
  188.     return i;
  189. }
  190.  
  191. /** Mark a phone structure free.
  192.  *
  193.  * @param phone     Phone structure to be marked free.
  194.  */
  195. static void phone_deallocp(phone_t *phone)
  196. {
  197.     ASSERT(phone->state == IPC_PHONE_CONNECTING);
  198.    
  199.     /* atomic operation */
  200.     phone->state = IPC_PHONE_FREE;
  201. }
  202.  
  203. /** Free slot from a disconnected phone.
  204.  *
  205.  * All already sent messages will be correctly processed.
  206.  *
  207.  * @param phoneid   Phone handle of the phone to be freed.
  208.  */
  209. void phone_dealloc(int phoneid)
  210. {
  211.     phone_deallocp(&TASK->phones[phoneid]);
  212. }
  213.  
  214. /** Connect phone to a given answerbox.
  215.  *
  216.  * @param phoneid   Phone handle to be connected.
  217.  * @param box       Answerbox to which to connect the phone handle.
  218.  *
  219.  * The procedure _enforces_ that the user first marks the phone
  220.  * busy (e.g. via phone_alloc) and then connects the phone, otherwise
  221.  * race condition may appear.
  222.  */
  223. void phone_connect(int phoneid, answerbox_t *box)
  224. {
  225.     phone_t *phone = &TASK->phones[phoneid];
  226.    
  227.     ASSERT(phone->state == IPC_PHONE_CONNECTING);
  228.     ipc_phone_connect(phone, box);
  229. }
  230.  
  231. /** @}
  232.  */
  233.