Subversion Repositories HelenOS

Rev

Rev 3362 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
1072 palkovsky 1
/*
2071 jermar 2
 * Copyright (c) 2006 Ondrej Palkovsky
1072 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
 
1757 jermar 29
/** @addtogroup genericipc
1702 cejka 30
 * @{
31
 */
32
/** @file
33
 */
34
 
1072 palkovsky 35
/* IPC resources management
36
 *
2359 jermar 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.
1072 palkovsky 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
1086 palkovsky 45
 * - hangup phone (the caller has hung up)
46
 * - hangup phone (the answerbox is exiting)
1072 palkovsky 47
 *
1084 palkovsky 48
 * Locking strategy
49
 *
2359 jermar 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)
1084 palkovsky 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.
2359 jermar 58
 *   It is perfectly correct to pass unconnected phone to these functions and
59
 *   proper reply will be generated.
1084 palkovsky 60
 *
61
 * Locking order
62
 *
63
 * - first phone, then answerbox
64
 *   + Easy locking on calls
2359 jermar 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.
1084 palkovsky 68
 *
1086 palkovsky 69
 * Destroying is less frequent, this approach is taken.
1084 palkovsky 70
 *
1090 palkovsky 71
 * Phone call
72
 *
73
 * *** Connect_me_to ***
2359 jermar 74
 * The caller sends IPC_M_CONNECT_ME_TO to an answerbox. The server receives
2637 cejka 75
 * 'phoneid' of the connecting phone as an ARG5. If it answers with RETVAL=0,
2359 jermar 76
 * the phonecall is accepted, otherwise it is refused.
1090 palkovsky 77
 *
78
 * *** Connect_to_me ***
2359 jermar 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.
1090 palkovsky 85
 *
1086 palkovsky 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),
2359 jermar 90
 *   all in-progress messages are correctly handled. The answerbox receives
1086 palkovsky 91
 *   IPC_M_PHONE_HUNGUP call from the phone that hung up. When all async
92
 *   calls are answered, the phone is deallocated.
1084 palkovsky 93
 *
1088 palkovsky 94
 * *** The answerbox hangs up (ipc_answer(EHANGUP))
95
 * - The phone is disconnected. EHANGUP response code is sent
1698 jermar 96
 *   to the calling task. All new calls through this phone
1088 palkovsky 97
 *   get a EHUNGUP error code, the task is expected to
1888 jermar 98
 *   send an sys_ipc_hangup after cleaning up its internal structures.
1086 palkovsky 99
 *
1088 palkovsky 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
 *
1084 palkovsky 115
 * Cleanup strategy
1072 palkovsky 116
 *
1088 palkovsky 117
 * 1) Disconnect all our phones ('ipc_phone_hangup').
1086 palkovsky 118
 *
119
 * 2) Disconnect all phones connected to answerbox.
1084 palkovsky 120
 *
1086 palkovsky 121
 * 3) Answer all messages in 'calls' and 'dispatched_calls' queues with
1088 palkovsky 122
 *    appropriate error code (EHANGUP, EFORWARD).
1084 palkovsky 123
 *
1090 palkovsky 124
 * 4) Wait for all async answers to arrive and dispose of them.
1084 palkovsky 125
 *
1072 palkovsky 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
 
2471 jermar 135
/** Find call_t * in call table according to callid.
1072 palkovsky 136
 *
2471 jermar 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.
1072 palkovsky 144
 */
2471 jermar 145
call_t *get_call(unative_t callid)
1072 palkovsky 146
{
1141 palkovsky 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;
2471 jermar 152
        lst != &TASK->answerbox.dispatched_calls; lst = lst->next) {
1573 palkovsky 153
        call = list_get_instance(lst, call_t, link);
2471 jermar 154
        if ((unative_t) call == callid) {
1141 palkovsky 155
            result = call;
156
            break;
157
        }
158
    }
159
    spinlock_unlock(&TASK->answerbox.lock);
160
    return result;
1072 palkovsky 161
}
162
 
4407 jermar 163
/** Allocate new phone slot in the specified task.
2471 jermar 164
 *
4407 jermar 165
 * @param t     Task for which to allocate a new phone.
166
 *
2471 jermar 167
 * @return      New phone handle or -1 if the phone handle limit is
168
 *          exceeded.
169
 */
4407 jermar 170
int phone_alloc(task_t *t)
1072 palkovsky 171
{
172
    int i;
173
 
4407 jermar 174
    spinlock_lock(&t->lock);
2471 jermar 175
    for (i = 0; i < IPC_MAX_PHONES; i++) {
4407 jermar 176
        if (t->phones[i].state == IPC_PHONE_HUNGUP &&
177
            atomic_get(&t->phones[i].active_calls) == 0)
178
            t->phones[i].state = IPC_PHONE_FREE;
1568 palkovsky 179
 
4407 jermar 180
        if (t->phones[i].state == IPC_PHONE_FREE) {
181
            t->phones[i].state = IPC_PHONE_CONNECTING;
1072 palkovsky 182
            break;
183
        }
184
    }
4407 jermar 185
    spinlock_unlock(&t->lock);
1072 palkovsky 186
 
3362 jermar 187
    if (i == IPC_MAX_PHONES)
1072 palkovsky 188
        return -1;
3362 jermar 189
 
1072 palkovsky 190
    return i;
191
}
192
 
2471 jermar 193
/** Mark a phone structure free.
194
 *
195
 * @param phone     Phone structure to be marked free.
196
 */
1090 palkovsky 197
static void phone_deallocp(phone_t *phone)
198
{
1568 palkovsky 199
    ASSERT(phone->state == IPC_PHONE_CONNECTING);
1090 palkovsky 200
 
201
    /* atomic operation */
1568 palkovsky 202
    phone->state = IPC_PHONE_FREE;
1090 palkovsky 203
}
204
 
2471 jermar 205
/** Free slot from a disconnected phone.
1086 palkovsky 206
 *
2471 jermar 207
 * All already sent messages will be correctly processed.
208
 *
209
 * @param phoneid   Phone handle of the phone to be freed.
1086 palkovsky 210
 */
1072 palkovsky 211
void phone_dealloc(int phoneid)
212
{
1090 palkovsky 213
    phone_deallocp(&TASK->phones[phoneid]);
1072 palkovsky 214
}
215
 
2471 jermar 216
/** Connect phone to a given answerbox.
1084 palkovsky 217
 *
2471 jermar 218
 * @param phoneid   Phone handle to be connected.
219
 * @param box       Answerbox to which to connect the phone handle.
1084 palkovsky 220
 *
221
 * The procedure _enforces_ that the user first marks the phone
222
 * busy (e.g. via phone_alloc) and then connects the phone, otherwise
223
 * race condition may appear.
224
 */
1072 palkovsky 225
void phone_connect(int phoneid, answerbox_t *box)
226
{
227
    phone_t *phone = &TASK->phones[phoneid];
228
 
1568 palkovsky 229
    ASSERT(phone->state == IPC_PHONE_CONNECTING);
1072 palkovsky 230
    ipc_phone_connect(phone, box);
231
}
1702 cejka 232
 
1757 jermar 233
/** @}
1702 cejka 234
 */