Changeset 8b243f2 in mainline for kernel/generic/src/ipc/ipcrsc.c

Timestamp:

2007-06-17T19:34:36Z (18 years ago)

Author:

Jakub Jermar <jakub@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

bd72c3e9

Parents:

4680ef5

Message:

Greatly improve comments in the IPC layer.
Now I think I finally start to understand our IPC internals

File:

• kernel/generic/src/ipc/ipcrsc.c (modified) (7 diffs)

kernel/generic/src/ipc/ipcrsc.c

@@ -133 +133 @@
 #include <debug.h>
 
-/** Find call_t * in call table according to callid
- *
- * TODO: Some speedup (hash table?)
- * @return NULL on not found, otherwise pointer to call structure
- */
-call_t * get_call(unative_t callid)
+/** Find call_t * in call table according to callid.
+ *
+ * @todo Some speedup (hash table?)
+ *
+ * @param callid        Userspace hash of the call. Currently it is the call
+ *                      structure kernel address.
+ *
+ * @return              NULL on not found, otherwise pointer to the call
+ *                      structure.
+ */
+call_t *get_call(unative_t callid)
 {
         link_t *lst;
@@ -145 +150 @@
         spinlock_lock(&TASK->answerbox.lock);
         for (lst = TASK->answerbox.dispatched_calls.next;
-             lst != &TASK->answerbox.dispatched_calls; lst = lst->next) {
+            lst != &TASK->answerbox.dispatched_calls; lst = lst->next) {
                 call = list_get_instance(lst, call_t, link);
-                if ((unative_t)call == callid) {
+                if ((unative_t) call == callid) {
                         result = call;
                         break;
@@ -156 +161 @@
 }
 
-/** Allocate new phone slot in current TASK structure */
+/** Allocate new phone slot in the current TASK structure.
+ *
+ * @return              New phone handle or -1 if the phone handle limit is
+ *                      exceeded.
+ */
 int phone_alloc(void)
 {
@@ -163 +172 @@
         spinlock_lock(&TASK->lock);
         
-        for (i=0; i < IPC_MAX_PHONES; i++) {
-                if (TASK->phones[i].state == IPC_PHONE_HUNGUP && \
+        for (i = 0; i < IPC_MAX_PHONES; i++) {
+                if (TASK->phones[i].state == IPC_PHONE_HUNGUP &&
                     atomic_get(&TASK->phones[i].active_calls) == 0)
                         TASK->phones[i].state = IPC_PHONE_FREE;
@@ -180 +189 @@
 }
 
+/** Mark a phone structure free.
+ *
+ * @param phone         Phone structure to be marked free.
+ */
 static void phone_deallocp(phone_t *phone)
 {
@@ -188 +201 @@
 }
 
-/** Free slot from a disconnected phone
- *
- * All already sent messages will be correctly processed
+/** Free slot from a disconnected phone.
+ *
+ * All already sent messages will be correctly processed.
+ *
+ * @param phoneid       Phone handle of the phone to be freed.
  */
 void phone_dealloc(int phoneid)
@@ -197 +212 @@
 }
 
-/** Connect phone to a given answerbox
- *
- * @param phoneid The slot that will be connected
+/** Connect phone to a given answerbox.
+ *
+ * @param phoneid       Phone handle to be connected.
+ * @param box           Answerbox to which to connect the phone handle.
  *
  * The procedure _enforces_ that the user first marks the phone