WebSVN – HelenOS – Diff – /trunk/uspace/libc/generic/ipc.c

 #include <futex.h>
 #include <kernel/synch/synch.h>
 #include <async.h>
 #include <psthread.h>
-/** Structure used for keeping track of sent async msgs
+/** Structure used for keeping track of sent asynchronous calls and queing
- * and queing unsent msgs
+ * unsent calls.
- *
  */
 typedef struct {
     link_t list;
     ipc_async_callback_t callback;
         ipc_callid_t callid;
         struct {
             ipc_call_t data;
             int phoneid;
         } msg;
-    }u;
+    } u;
-    pstid_t ptid;   /**< Thread waiting for sending this msg */
+    pstid_t ptid;   /**< Pseudothread waiting for sending this call. */
 } async_call_t;
 LIST_INITIALIZE(dispatched_calls);
-/* queued_calls is protcted by async_futex, because if the
+/** List of asynchronous calls that were not accepted by kernel.
+ *
- * call cannot be sent into kernel, async framework is used
+ * It is protected by async_futex, because if the call cannot be sent into the
- * automatically
+ * kernel, the async framework is used automatically.
  */
-LIST_INITIALIZE(queued_calls); /**< List of async calls that were not accepted
+LIST_INITIALIZE(queued_calls);
-                *   by kernel */
 static atomic_t ipc_futex = FUTEX_INITIALIZER;
+/** Make a fast synchronous call.
+ *
+ * Only one payload argument can be passed using this function. However, this
-int ipc_call_sync(int phoneid, ipcarg_t method, ipcarg_t arg1,
+ * function is faster than the generic ipc_call_sync_3().
+ *
+ * @param phoneid   Phone handle for the call.
-          ipcarg_t *result)
+ * @param method    Requested method.
+ * @param arg1      Service-defined payload argument.
+ * @param result    If non-NULL, the return ARG1 will be stored there.
+ *
+ * @return      Negative values represent errors returned by IPC.
+ *          Otherwise the RETVAL of the answer is returned.
+ */
+int ipc_call_sync(int phoneid, ipcarg_t method, ipcarg_t arg1, ipcarg_t *result)
+{
     ipc_call_t resdata;
     int callres;
     callres = __SYSCALL4(SYS_IPC_CALL_SYNC_FAST, phoneid, method, arg1,
-                 (sysarg_t)&resdata);
+        (sysarg_t) &resdata);
     if (callres)
         return callres;
     if (result)
         *result = IPC_GET_ARG1(resdata);
     return IPC_GET_RETVAL(resdata);
+}
+/** Make a synchronous call transmitting 3 arguments of payload.
+ *
+ * @param phoneid   Phone handle for the call.
+ * @param method    Requested method.
+ * @param arg1      Service-defined payload argument.
+ * @param arg2      Service-defined payload argument.
+ * @param arg3      Service-defined payload argument.
+ * @param result1   If non-NULL, storage for the first return argument.
+ * @param result2   If non-NULL, storage for the second return argument.
-int ipc_call_sync_3(int phoneid, ipcarg_t method, ipcarg_t arg1,
+ * @param result3   If non-NULL, storage for the third return argument.
+ *
+ * @return      Negative value means IPC error.
+ *          Otherwise the RETVAL of the answer.
+ */
-            ipcarg_t arg2, ipcarg_t arg3,
+int ipc_call_sync_3(int phoneid, ipcarg_t method, ipcarg_t arg1, ipcarg_t arg2,
-            ipcarg_t *result1, ipcarg_t *result2, ipcarg_t *result3)
+    ipcarg_t arg3, ipcarg_t *result1, ipcarg_t *result2, ipcarg_t *result3)
+{
     ipc_call_t data;
     int callres;
     IPC_SET_METHOD(data, method);
     IPC_SET_ARG1(data, arg1);
     IPC_SET_ARG2(data, arg2);
     IPC_SET_ARG3(data, arg3);
-    callres = __SYSCALL3(SYS_IPC_CALL_SYNC, phoneid, (sysarg_t)&data,
+    callres = __SYSCALL3(SYS_IPC_CALL_SYNC, phoneid, (sysarg_t) &data,
-                 (sysarg_t)&data);
+        (sysarg_t) &data);
     if (callres)
         return callres;
     if (result1)
         *result1 = IPC_GET_ARG1(data);
     if (result3)
         *result3 = IPC_GET_ARG3(data);
     return IPC_GET_RETVAL(data);
+}
-/** Syscall to send asynchronous message */
+/** Syscall to send asynchronous message.
+ *
+ * @param phoneid   Phone handle for the call.
+ * @param data      Call data with the request.
+ *
+ * @return      Hash of the call or an error code.
+ */
-static  ipc_callid_t _ipc_call_async(int phoneid, ipc_call_t *data)
+static ipc_callid_t _ipc_call_async(int phoneid, ipc_call_t *data)
+{
-    return __SYSCALL2(SYS_IPC_CALL_ASYNC, phoneid, (sysarg_t)data);
+    return __SYSCALL2(SYS_IPC_CALL_ASYNC, phoneid, (sysarg_t) data);
+}
-/** Prolog to ipc_async_send functions */
+/** Prolog to ipc_call_async_*() functions.
+ *
+ * @param private   Argument for the answer/error callback.
+ * @param callback  Answer/error callback.
+ *
+ * @return      New, partially initialized async_call structure or NULL.
+ */
-static inline async_call_t *ipc_prepare_async(void *private, ipc_async_callback_t callback)
+static inline async_call_t *ipc_prepare_async(void *private,
+    ipc_async_callback_t callback)
+{
     async_call_t *call;
     call = malloc(sizeof(*call));
     if (!call) {
     call->private = private;
     return call;
+}
-/** Epilogue of ipc_async_send functions */
+/** Epilogue of ipc_call_async_*() functions.
+ *
+ * @param callid    Value returned by the SYS_IPC_CALL_ASYNC_* syscall.
+ * @param phoneid   Phone handle through which the call was made.
+ * @param call      async_call structure returned by ipc_prepare_async().
+ * @param can_preempt   If non-zero, the current pseudo thread can be preempted
+ *          in this call.
+ */
 static inline void ipc_finish_async(ipc_callid_t callid, int phoneid,
-                    async_call_t *call, int can_preempt)
+    async_call_t *call, int can_preempt)
+{
     if (!call) { /* Nothing to do regardless if failed or not */
         futex_up(&ipc_futex);
         return;
+    }
             futex_up(&async_futex);
+        }
         return;
+    }
     call->u.callid = callid;
-    /* Add call to list of dispatched calls */
+    /* Add call to the list of dispatched calls */
     list_append(&call->list, &dispatched_calls);
     futex_up(&ipc_futex);
+}
-/** Send asynchronous message
+/** Make a fast asynchronous call.
+ *
+ * This function can only handle two arguments of payload. It is, however,
+ * faster than the more generic ipc_call_async_3().
+ *
+ * Note that this function is a void function.
+ * During normal opertation, answering this call will trigger the callback.
- * - if fatal error, call callback handler with proper error code
+ * In case of fatal error, call the callback handler with the proper error code.
- * - if message cannot be temporarily sent, add to queue
+ * If the call cannot be temporarily made, queue it.
+ *
+ * @param phoneid   Phone handle for the call.
+ * @param method    Requested method.
+ * @param arg1      Service-defined payload argument.
+ * @param arg2      Service-defined payload argument.
+ * @param private   Argument to be passed to the answer/error callback.
+ * @param callback  Answer or error callback.
+ * @param can_preempt   If non-zero, the current pseudo thread will be preempted
+ *          in case the kernel temporarily refuses to accept more
+ *          asynchronous calls.
  */
 void ipc_call_async_2(int phoneid, ipcarg_t method, ipcarg_t arg1,
-              ipcarg_t arg2, void *private,
+    ipcarg_t arg2, void *private, ipc_async_callback_t callback,
-              ipc_async_callback_t callback, int can_preempt)
+    int can_preempt)
+{
     async_call_t *call = NULL;
     ipc_callid_t callid;
     if (callback) {
         call = ipc_prepare_async(private, callback);
         if (!call)
             return;
+    }
+    /*
-    /* We need to make sure that we get callid before
+     * We need to make sure that we get callid before another thread
-     * another thread accesses the queue again */
+     * accesses the queue again.
+     */
     futex_down(&ipc_futex);
-    callid = __SYSCALL4(SYS_IPC_CALL_ASYNC_FAST, phoneid, method, arg1, arg2);
+    callid = __SYSCALL4(SYS_IPC_CALL_ASYNC_FAST, phoneid, method, arg1,
+        arg2);
     if (callid == IPC_CALLRET_TEMPORARY) {
         if (!call) {
             call = ipc_prepare_async(private, callback);
             if (!call)
         IPC_SET_ARG2(call->u.msg.data, arg2);
+    }
     ipc_finish_async(callid, phoneid, call, can_preempt);
+}
+/** Make an asynchronous call transmitting the entire payload.
+ *
+ * Note that this function is a void function.
+ * During normal opertation, answering this call will trigger the callback.
+ * In case of fatal error, call the callback handler with the proper error code.
+ * If the call cannot be temporarily made, queue it.
+ *
+ * @param phoneid   Phone handle for the call.
+ * @param method    Requested method.
+ * @param arg1      Service-defined payload argument.
+ * @param arg2      Service-defined payload argument.
+ * @param arg3      Service-defined payload argument.
+ * @param private   Argument to be passed to the answer/error callback.
+ * @param callback  Answer or error callback.
+ * @param can_preempt   If non-zero, the current pseudo thread will be preempted
+ *          in case the kernel temporarily refuses to accept more
-/** Send asynchronous message
+ *          asynchronous calls.
+ *
- * - if fatal error, call callback handler with proper error code
- * - if message cannot be temporarily sent, add to queue
  */
 void ipc_call_async_3(int phoneid, ipcarg_t method, ipcarg_t arg1,
-              ipcarg_t arg2, ipcarg_t arg3, void *private,
+    ipcarg_t arg2, ipcarg_t arg3, void *private, ipc_async_callback_t callback,
-              ipc_async_callback_t callback, int can_preempt)
+    int can_preempt)
+{
     async_call_t *call;
     ipc_callid_t callid;
     call = ipc_prepare_async(private, callback);
     IPC_SET_METHOD(call->u.msg.data, method);
     IPC_SET_ARG1(call->u.msg.data, arg1);
     IPC_SET_ARG2(call->u.msg.data, arg2);
     IPC_SET_ARG3(call->u.msg.data, arg3);
+    /*
-    /* We need to make sure that we get callid before
+     * We need to make sure that we get callid before another thread accesses
-     * another thread accesses the queue again */
+     * the queue again.
+     */
     futex_down(&ipc_futex);
     callid = _ipc_call_async(phoneid, &call->u.msg.data);
     ipc_finish_async(callid, phoneid, call, can_preempt);
+}
-/** Send a fast answer to a received call.
+/** Answer a received call - fast version.
+ *
- * The fast answer makes use of passing retval and first two arguments in registers.
+ * The fast answer makes use of passing retval and first two arguments in
- * If you need to return more, use the ipc_answer() instead.
+ * registers. If you need to return more, use the ipc_answer() instead.
+ *
- * @param callid ID of the call being answered.
+ * @param callid    Hash of the call being answered.
- * @param retval Return value.
+ * @param retval    Return value.
- * @param arg1 First return argument.
+ * @param arg1      First return argument.
- * @param arg2 Second return argument.
+ * @param arg2      Second return argument.
+ *
- * @return Zero on success or a value from @ref errno.h on failure.
+ * @return      Zero on success or a value from @ref errno.h on failure.
  */
 ipcarg_t ipc_answer_fast(ipc_callid_t callid, ipcarg_t retval, ipcarg_t arg1,
-        ipcarg_t arg2)
+    ipcarg_t arg2)
+{
     return __SYSCALL4(SYS_IPC_ANSWER_FAST, callid, retval, arg1, arg2);
+}
-/** Send a full answer to a received call.
+/** Answer a received call - full version.
+ *
- * @param callid ID of the call being answered.
+ * @param callid    Hash of the call being answered.
+ * @param call      Call structure with the answer.
- * @param call Call data. Must be already initialized by the responder.
+ *          Must be already initialized by the responder.
+ *
- * @return Zero on success or a value from @ref errno.h on failure.
+ * @return      Zero on success or a value from @ref errno.h on failure.
  */
 ipcarg_t ipc_answer(ipc_callid_t callid, ipc_call_t *call)
+{
     return __SYSCALL2(SYS_IPC_ANSWER, callid, (sysarg_t) call);
+}
-/** Try to dispatch queed calls from async queue */
+/** Try to dispatch queued calls from the async queue. */
 static void try_dispatch_queued_calls(void)
+{
     async_call_t *call;
     ipc_callid_t callid;
+    /** @todo
-    /* TODO: integrate intelligently ipc_futex, so that it
+     * Integrate intelligently ipc_futex, so that it is locked during
-     * is locked during ipc_call_async, until it is added
+     * ipc_call_async_*(), until it is added to dispatched_calls.
-     * to dispatched_calls
      */
     futex_down(&async_futex);
     while (!list_empty(&queued_calls)) {
-        call = list_get_instance(queued_calls.next, async_call_t,
+        call = list_get_instance(queued_calls.next, async_call_t, list);
-                     list);
-        callid = _ipc_call_async(call->u.msg.phoneid,
+        callid = _ipc_call_async(call->u.msg.phoneid, &call->u.msg.data);
-                     &call->u.msg.data);
         if (callid == IPC_CALLRET_TEMPORARY) {
             break;
+        }
         list_remove(&call->list);
         futex_down(&async_futex);
+    }
     futex_up(&async_futex);
+}
-/** Handle received answer
+/** Handle a received answer.
+ *
+ * Find the hash of the answer and call the answer callback.
+ *
- * TODO: Make it use hash table
+ * @todo Make it use hash table.
+ *
- * @param callid Callid (with first bit set) of the answered call
+ * @param callid    Hash of the received answer.
+ *          The answer has the same hash as the request OR'ed with
+ *          the IPC_CALLID_ANSWERED bit.
+ * @param data      Call data of the answer.
  */
 static void handle_answer(ipc_callid_t callid, ipc_call_t *data)
+{
     link_t *item;
     async_call_t *call;
     callid &= ~IPC_CALLID_ANSWERED;
     futex_down(&ipc_futex);
     for (item = dispatched_calls.next; item != &dispatched_calls;
-         item = item->next) {
+        item = item->next) {
         call = list_get_instance(item, async_call_t, list);
         if (call->u.callid == callid) {
             list_remove(&call->list);
             futex_up(&ipc_futex);
             if (call->callback)
                 call->callback(call->private,
-                           IPC_GET_RETVAL(*data),
+                    IPC_GET_RETVAL(*data), data);
-                           data);
             free(call);
             return;
+        }
+    }
     futex_up(&ipc_futex);
-    /* We may get here after async_msg, which doesn't register any callback */
+}
-/** One cycle of ipc wait for call call
+/** Wait for a first call to come.
+ *
- * - dispatch ASYNC reoutines in the background
- * @param call Space where the message is stored
+ * @param call      Storage where the incoming call data will be stored.
- * @param usec Timeout in microseconds
+ * @param usec      Timeout in microseconds
- * @param flags Flags passed to SYS_IPC_WAIT (blocking, nonblocking)
+ * @param flags     Flags passed to SYS_IPC_WAIT (blocking, nonblocking).
+ *
- * @return Callid of the answer.
+ * @return      Hash of the call. Note that certain bits have special
+ *          meaning. IPC_CALLID_ANSWERED will be set in an answer
+ *          and IPC_CALLID_NOTIFICATION is used for notifications.
+ *
  */
 ipc_callid_t ipc_wait_cycle(ipc_call_t *call, uint32_t usec, int flags)
+{
     ipc_callid_t callid;
     return callid;
+}
 /** Wait some time for an IPC call.
+ *
- * - dispatch ASYNC reoutines in the background
+ * The call will return after an answer is received.
+ *
- * @param call Space where the message is stored
+ * @param call      Storage where the incoming call data will be stored.
- * @param usec Timeout in microseconds.
+ * @param usec      Timeout in microseconds.
+ *
- * @return Callid of the answer.
+ * @return      Hash of the answer.
  */
 ipc_callid_t ipc_wait_for_call_timeout(ipc_call_t *call, uint32_t usec)
+{
     ipc_callid_t callid;
     return callid;
+}
 /** Check if there is an IPC call waiting to be picked up.
+ *
- * - dispatch ASYNC reoutines in the background
- *
- * @param call Space where the message is stored
+ * @param call      Storage where the incoming call will be stored.
- * @return Callid of the answer.
+ * @return      Hash of the answer.
  */
 ipc_callid_t ipc_trywait_for_call(ipc_call_t *call)
+{
     ipc_callid_t callid;
     do {
-        callid = ipc_wait_cycle(call, SYNCH_NO_TIMEOUT, SYNCH_FLAGS_NON_BLOCKING);
+        callid = ipc_wait_cycle(call, SYNCH_NO_TIMEOUT,
+            SYNCH_FLAGS_NON_BLOCKING);
     } while (callid & IPC_CALLID_ANSWERED);
     return callid;
+}
 /** Ask destination to do a callback connection.
+ *
- * @param phoneid   Phone ID used for contacting the other side.
+ * @param phoneid   Phone handle used for contacting the other side.
- * @param arg1      User defined argument.
+ * @param arg1      Service-defined argument.
- * @param arg2      User defined argument.
+ * @param arg2      Service-defined argument.
- * @param phonehash Pointer to a place where the library will store an opaque
+ * @param phonehash Storage where the library will store an opaque
  *          identifier of the phone that will be used for incoming
+ *          calls. This identifier can be used for connection
- *          calls.
+ *          tracking.
+ *
- * @return Zero on success or a negative error code.
+ * @return      Zero on success or a negative error code.
  */
 int ipc_connect_to_me(int phoneid, int arg1, int arg2, ipcarg_t *phonehash)
+{
     return ipc_call_sync_3(phoneid, IPC_M_CONNECT_TO_ME, arg1, arg2, 0, 0, 0,
         phonehash);
+}
 /** Ask through phone for a new connection to some service.
+ *
- * @param phoneid   Phone ID used for contacting the other side.
+ * @param phoneid   Phone handle used for contacting the other side.
  * @param arg1      User defined argument.
  * @param arg2      User defined argument.
+ *
- * @return New phone ID on success or a negative error code.
+ * @return      New phone handle on success or a negative error code.
  */
 int ipc_connect_me_to(int phoneid, int arg1, int arg2)
+{
     ipcarg_t newphid;
     int res;
     if (res)
         return res;
     return newphid;
+}
-/* Hang up specified phone */
+/** Hang up a phone.
+ *
+ * @param phoneid   Handle of the phone to be hung up.
+ *
+ * @return      Zero on success or a negative error code.
+ */
 int ipc_hangup(int phoneid)
+{
     return __SYSCALL1(SYS_IPC_HANGUP, phoneid);
+}
 /** Register IRQ notification.
+ *
- * @param inr IRQ number.
+ * @param inr       IRQ number.
- * @param devno Device number of the device generating inr.
+ * @param devno     Device number of the device generating inr.
- * @param method Use this method for notifying me.
+ * @param method    Use this method for notifying me.
- * @param ucode Top-half pseudocode handler.
+ * @param ucode     Top-half pseudocode handler.
+ *
- * @return Value returned by the kernel.
+ * @return      Value returned by the kernel.
  */
 int ipc_register_irq(int inr, int devno, int method, irq_code_t *ucode)
+{
-    return __SYSCALL4(SYS_IPC_REGISTER_IRQ, inr, devno, method, (sysarg_t) ucode);
+    return __SYSCALL4(SYS_IPC_REGISTER_IRQ, inr, devno, method,
+        (sysarg_t) ucode);
+}
 /** Unregister IRQ notification.
+ *
- * @param inr IRQ number.
+ * @param inr       IRQ number.
- * @param devno Device number of the device generating inr.
+ * @param devno     Device number of the device generating inr.
+ *
- * @return Value returned by the kernel.
+ * @return      Value returned by the kernel.
  */
 int ipc_unregister_irq(int inr, int devno)
+{
     return __SYSCALL2(SYS_IPC_UNREGISTER_IRQ, inr, devno);
+}
+/** Forward a received call to another destination.
+ *
+ * @param callid    Hash of the call to forward.
+ * @param phoneid   Phone handle to use for forwarding.
+ * @param method    New method for the forwarded call.
+ * @param arg1      New value of the first argument for the forwarded call.
+ *
+ * @return      Zero on success or an error code.
+ *
+ * For non-system methods, the old method and arg1 are rewritten by the new
+ * values. For system methods, the new method and arg1 are written to the old
+ * arg1 and arg2, respectivelly.
+ */
 int ipc_forward_fast(ipc_callid_t callid, int phoneid, int method, ipcarg_t arg1)
+{
     return __SYSCALL4(SYS_IPC_FORWARD_FAST, callid, phoneid, method, arg1);
+}

Subversion Repositories HelenOS

(root)/trunk/uspace/libc/generic/ipc.c – Rev 2359 → 2471