Commit 39d3eb1c authored by Michael Quigley's avatar Michael Quigley
Browse files

Added some documentation in headers.

parent 9731fdc3
Pipeline #550 skipped
......@@ -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);
......@@ -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
......@@ -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);
......
......@@ -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;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment