Added some documentation in headers.

src/common/awe_mapper.c

@@ -35,6 +35,11 @@
  * storage size requirements.
  */
 
+/*
+ * This value is used to determine if a slot is allocated but not yet set in the awe table.
+ */
+static unsigned long initialized_marker = 0xDeadBeef;
+
 
 /*
  * Initilaizes awe mapper.
@@ -92,7 +97,7 @@ awe_mapper_create_id(void)
     } 
     while( is_slot_allocated(awe_map->next_id) );
 
-    (awe_map->awe_list)[awe_map->next_id] = (void*)0xdeadbeef;
+    (awe_map->awe_list)[awe_map->next_id] = (void*)initialized_marker;
 
     awe_map->used_slots++;
 
@@ -101,6 +106,7 @@ awe_mapper_create_id(void)
 EXPORT_SYMBOL(awe_mapper_create_id);
 
 
+
 /*
  * Marks provided id as available
  */
@@ -121,6 +127,7 @@ awe_mapper_remove_id(uint32_t id)
 EXPORT_SYMBOL(awe_mapper_remove_id);
 
 
+
 /*
  * Links awe_ptr with id.
  */
@@ -147,22 +154,3 @@ awe_mapper_get_awe_ptr(uint32_t id)
 
     return (awe_map->awe_list)[id];
 }
-
-
-void 
-LIBASYNC_FUNC_ATTR 
-awe_mapper_print_list(void)
-{
-    int i,j;
-    awe_table_t *awe_map =  get_awe_map();
-    for(i = 0; i < AWE_TABLE_COUNT; i+= 8)
-    {
-        printk(KERN_ERR "\n");
-        for(j = i; j < i + 8; j++)
-        {
-            printk(KERN_ERR "0x%p ", (awe_map->awe_list)[j]);
-        }
-    }
-    printk(KERN_ERR "\n");
-}
-EXPORT_SYMBOL(awe_mapper_print_list);

src/include/awe_mapper.h

@@ -63,13 +63,15 @@ static inline awe_table_t* get_awe_map(void)
     return PTS()->awe_map;
 }
 
+/*
+ * Called in awe_mapper_init.
+ * Sets awe_map struct of the current PTS to a specific awe_table.
+ */
 static inline void set_awe_map(awe_table_t * map_ptr)
 {
     PTS()->awe_map = map_ptr;
 }
 
-void awe_mapper_print_list(void);
-
 #endif /* LINUX_KERNEL */
 
 #endif

src/include/thc_ipc.h

@@ -39,38 +39,137 @@ static inline void thc_set_msg_id(struct fipc_message *msg,
 	fipc_set_flags(msg, flags);
 }
 
+/*
+ * thc_ipc_recv
+ * 
+ * Performs an async receive of a message.
+ * msg_id is used to receive a message with a particular id and must always
+ * be valid. If a message is received but its id does not match the id provided
+ * to this function, then this function will check if the message corresponds
+ * to another pending AWE, and if so, it will yield to that AWE. If there is 
+ * not a message that has been received yet, it will yield to dispatch any
+ * pending work. If a message is received that corresponds to the provided
+ * msg_id, this function will put the message in the *out_msg parameter and return.
+ * This last case is the only time the function will return assuming there are
+ * no error conditions. In the other two cases involving yields, execution will
+ * eventually come back to this function until it receives the message
+ * corresponding to its msg_id. 
+ *  It is the caller's responsibility to mark the message as having completed
+ * the receive. (ex: fipc_recv_msg_end(chnl, msg))
+ *
+ * Returns 0 on success, non-zero otherwise.
+ */
 int thc_ipc_recv(struct fipc_ring_channel *chnl, 
                  unsigned long msg_id, 
                  struct fipc_message** out_msg);
 
+/*
+ * thc_ipc_call
+ * 
+ * Performs both a send and an async receive. 
+ * request is the message to send.
+ * (*response) will have the received message.
+ *
+ * It is the caller's responsibility to mark the message as having completed
+ * the receive. (ex: fipc_recv_msg_end(chnl, msg))
+ *
+ * Returns 0 on success, non-zero otherwise.
+ */
 int thc_ipc_call(struct fipc_ring_channel *chnl, 
 		struct fipc_message *request, 
 		struct fipc_message **response);
 
+/*
+ * thc_ipc_reply
+ *
+ * Sets the msg_id of response to the msg_id of request
+ * and marks the response message as having a response message type.
+ * Sends response message on the provided ring channel. 
+ *
+ * Returns 0 on success, non-zero otherwise.
+ */
 int thc_ipc_reply(struct fipc_ring_channel *chnl,
 		struct fipc_message *request,
 		struct fipc_message *response);
 
-
+/*
+ * thc_ipc_reply_with_id 
+ *
+ * Same as thc_ipc_reply except it sets response's msg_id
+ * to the message id provided instead of extracting it
+ * from a request.
+ *
+ * Returns 0 on success, non-zero otherwise.
+ */
 int thc_ipc_reply_with_id(struct fipc_ring_channel *chnl,
 	uint32_t msg_id,
 	struct fipc_message *response);
 
-int thc_poll_recv_group(struct thc_channel_group* chan_group, 
-                        struct thc_channel_group_item** chan_group_item, 
-                        struct fipc_message** out_msg);
-
+/* thc_poll_recv
+ *
+ * Same as thc_ipc_recv except that if no message is present, it
+ * returns -EWOULDBLOCK instead of yielding.
+ * Additionally, the channel inside the thc_channel_group_item is what
+ * is used instead of a channel directly.
+ * There is also no msg_id passed in because poll_recv should not expect a
+ * specific message.
+ *
+ * Returns 0 on success, non-zero otherwise.
+ */
 int thc_poll_recv(struct thc_channel_group_item* item,
                  struct fipc_message** out_msg);
 
+/*
+ * thc_poll_recv_group
+ *
+ * Calls thc_poll_recv on a list of thc_channel_group_items represented
+ * by thc_channel_group. If there is a message available that does not
+ * correspond to a pending AWE, the thc_channel_group_item that corresponds
+ * to the received message is set to the out param (*chan_group_item),
+ * and the received message is set to the out param (*out_msg).
+ * If there is no message available in any of the thc_channel_group_items,
+ * then this function returns -EWOULDBLOCK.
+ *
+ * Returns 0 on success, non-zero otherwise.
+ */
+int thc_poll_recv_group(struct thc_channel_group* chan_group, 
+                        struct thc_channel_group_item** chan_group_item, 
+                        struct fipc_message** out_msg);
+/*
+ * thc_channel_group_init
+ *
+ * Initializes thc_channel_group structure after it has been allocated.
+ *
+ * Returns 0 on success, non-zero otherwise.
+ */
 int thc_channel_group_init(struct thc_channel_group* channel_group);
 
+/*
+ * thc_channel_group_item_add
+ *
+ * Adds a thc_channel_group_item to a thc_channel_group.
+ *
+ * Returns 0 on success, non-zero otherwise.
+ */
 int thc_channel_group_item_add(struct thc_channel_group* channel_group,
                           struct thc_channel_group_item* item);
 
+/*
+ * thc_channel_group_item_add
+ *
+ * Removes a thc_channel_group_item from a thc_channel_group.
+ */
 void thc_channel_group_item_remove(struct thc_channel_group* channel_group, 
 				struct thc_channel_group_item* item);
 
+/*
+ * thc_channel_group_item_get
+ *
+ * Gets a thc_channel_group_item at a particular index in a channel_group.
+ * Puts the thc_channel_group_item in the out parameter (*out_item) on success.
+ *
+ * Returns 0 on success. Returns 1 if index is out of range.
+ */
 int thc_channel_group_item_get(struct thc_channel_group* channel_group, 
                                int index, 
                                struct thc_channel_group_item **out_item);

src/include/thc_ipc_types.h

@@ -19,6 +19,12 @@ struct predicate_payload
     msg_type_t msg_type;
 };
 
+/*
+ * struct thc_channel_group_item
+ *
+ * Contains a channel and a function that should get called when a message
+ * is received on the channel.
+ */
 struct thc_channel_group_item
 {
     struct list_head list;
@@ -26,6 +32,11 @@ struct thc_channel_group_item
     int (*dispatch_fn)(struct fipc_ring_channel*, struct fipc_message*);
 };
 
+/*
+ * struct thc_channel_group
+ *
+ * Represents a linked list of thc_channel_group_items.
+ */
 struct thc_channel_group
 {
     struct list_head head;