Diff: mbos.h

Revision:

2:af930cdf7cce

Parent:

1:b453bba9c5c0

Child:

3:6cb5413f143f

--- a/mbos.h	Sun Dec 05 10:34:48 2010 +0000
+++ b/mbos.h	Sun Dec 05 13:21:15 2010 +0000
@@ -95,39 +95,40 @@
 
 class mbos {
 public:
-    /** Create an mbos object. Instantiate mbos and define the number of tasks, timers and resources. 
+    /** Create an mbos object. Instantiate mbos and define the number of tasks, timers 
+     * and resources. 
      *
-     * @param ntasks The number of user tasks (1 .. 99) in the application. 
-     * @param ntimers Optional number of timers (0 ..  100) in the application.
-     * @param nresources Optional number of resources (0 .. 100) in the application.
+     * @param ntasks The number of user tasks (1 .. 99). 
+     * @param ntimers Optional number of timers (0 ..  100).
+     * @param nresources Optional number of resources (0 .. 100).
      */
     mbos(uint ntasks, uint ntimers = 0, uint nresources = 0);
 
-    /** Start mbos. Optionally specify the size of the stack for a user-written idle task. All tasks, 
-     * timers and resources must be created before calling Start. 
+    /** Start mbos. Optionally specify the size of the stack for a user-written idle task. 
+     * All tasks, timers and resources must be created before calling Start. 
      *
-     * @param idlestacksize Size in words (≥32) of the user-written idle stack, if present. 
+     * @param idlestacksize Size in words (>= 32) of the user-written idle task if present. 
      * @returns Never returns
      */
     void Start(uint idlestacksize = 0);
 
-    /** Create a mboss task. Allocates and initialises the Task Control Block and task's private stack.
+    /** Create an mbos task. Allocates and initialises data structures for the task.
      *
-     * @param taskid Unique ID (1 .. number specified in the constructor) for the task.
+     * @param taskid Unique ID for the task. (1 .. ntasks).
      * @param priority Priority (0 .. 99) of the task. Tasks may share the same priority.
-     * @param stacksize Size in words (>= 32) of the task'sstack.
-     * @param fun Pointer to the task function. Function must be static, of type void, returning  void.
+     * @param stacksize Size in words (>= 32) of the task's stack.
+     * @param fun Pointer to the task function. Function must be of type static void, 
+     * and must return nothing.
      */
     void CreateTask(uint taskid, uint priority, uint stacksz, void (*fun)(void));
 
-    /** Get the ID of the current task
-     * Returns the ID of the calling task
+    /** Get the ID of the current task.
      *
-     * @returns The ID (0 .. 99) of the calling task
+     * @returns The ID (0 .. 99) of the calling task.
      */
     uint GetTask(void);
 
-    /** Set the priority of the current task. Does not force a context switch. Does nothing if called from the idle task.
+    /** Set the priority of the current task.  Does nothing if called from the idle task.
      *
      * @param priority Priority (0 .. 99) to apply to the calling task.
      */
@@ -135,86 +136,95 @@
 
     /** Get the priority of the current task.
      *
-     * @returns The priority (0 .. 99) of the calling task
+     * @returns The priority (0 .. 99) of the calling task.
      */
     uint GetPriority(void);
 
-    /** Wait for an event or events. Causes the current task to block, waiting for the specified event. Does nothing if called from the idle task, or if event is NULL.
+    /** Wait for an event or events. Causes the current task to block, waiting for the 
+     * specified event. Does nothing if called from the idle task, or if the event is NULL.
      *
      * @param event Event flag(s) to wait for.
      */
     void WaitEvent(uint event);
 
     /** Post an event or events to a soecified task.
-     * Posts the nominated event(s) to the specified task. Forces a context switch if the events are posted successfully. Does nothing if the task is not waiting, or is not waiting for the posted event.
+     * Posts the nominated event(s) to the specified task. Forces a context switch if the events
+     * are posted successfully. Does nothing if the task is not waiting, or is not waiting for 
+     * the posted event.
      *
      * @param event Event flag(s) to post. 
      * @param task The ID of the task to which to post the event(s). May not be idle task.
      */
     void SetEvent(uint event, uint task);
 
-    /** Get the event flags
-     * Returns the event flag(s) which caused the task to unblock the most recent time.
+    /** Returns the event flag(s) which last caused the task to unblock.
      *
      * @returns The event flags.
      */
     uint GetEvent(void);
 
-    /** Create a mbos timer
-     * Allocates and initialises the Timer Control Block.
+    /** Create a mbos timer. Allocates and initialises the data structures for the timer.
      *
-     * @param timerid Unique ID (0 .. the number specified in the constructor - 1) of the timer . 
-     * @param taskid The ID of the  task to which the timer will post events. May not be idle task.
+     * @param timerid Unique ID for the timer (0 .. ntimers - 1). 
+     * @param taskid The ID of the task to which the timer will post events. May not be 
+     * the idle task.
      * @param event The event flag(s) that the timer should post on timeout. May not be NULL.
      */
     void CreateTimer(uint timerid, uint taskid, uint event);
 
-    /** Set a timer
-     * Starts an mbos timer. If the reload time is zero or omitted, the timer will be reset once it has posted a single event, after time milliseconds. If the reload time is non-zero, this value will be loaded into the timer on time-out, and the timer will continue indefinitely. In this case the interval to the first event will be time, and the interval between subsequent events will be reloadtime.
+    /** Starts an mbos timer. If the reload time is zero or omitted, the timer will be reset 
+     * once it has posted a single event, after time milliseconds. If the reload time is
+     * non-zero, this value will be loaded into the timer on time-out, and the timer will 
+     * continue indefinitely. In this case the interval to the first event will be time, 
+     * and the interval between subsequent events will be reloadtime.
      *
-     * @param timerid Unique ID (0 .. the number specified in the constructor - 1) of the timer . 
+     * @param timerid The ID of the timer. 
      * @param time The period in milliseconds before the timer times out.
      * @param reload The optional time to reload into the timer when it times out.
      */
     void SetTimer(uint timerid, uint time, uint reload = 0);
 
-    /** Clear a timer
-     * Stops and clears an mbos timer.
+    /** Stops and clears an mbos timer.
      *
-     * @param timerid Unique ID (0 .. the number specified in the constructor - 1) of the timer. 
+     * @param timerid The ID of the timer to clear. 
      */
     void ClearTimer(uint timerid);
 
-    /** Create a mbos resource
-     * Creates a mbos resource. Allocates and initialises the Resource Control Block.
+    /** Creates an mbos resource. Allocates and initialises the data structures for the Resource.
      *
-     * @param resourceid Unique ID (0 .. the number specified in the constructor - 1) of the resource. 
-     * @param priority Priority of the resource (should be > than that of any task using the resource).
+     * @param resourceid Unique ID for the resource (0 .. nresource).
+     * @param priority Priority of the resource (normally > than that of any task using the 
+     * resource).
      */
     void CreateResource(uint resourceid, uint priority);
 
-    /** Lock a resource
-     *Locks a mbos resource by temporarily allocating the resource's priority to the calling task. This priority should be higher than that of any other task potentially accessing the resource. Does nothing if the resource is already locked, or if called from the idle task.
+    /** Locks an mbos resource and temporarily allocates the resource's priority to the calling 
+     * task. 
+     * Does nothing if the resource is already locked, or if called from the idle task.
      *
-     * @param resourceid Unique ID (0 .. the number specified in the constructor - 1) of the resource. 
-     * @returns Zero, if the resource was locked successfully or the id of the task locking the resource, if not.
+     * @param resourceid The ID of the resource to lock. 
+     * @returns Zero if the resource was locked successfully, or the ID of the task that is
+     * currently locking the resource, if not.
      */
     uint LockResource(uint resourceid);
 
-    /** Test a resource
-     * Checks whether a resource is locked or free, without changing its state.
+    /** Tests whether a resource is locked or free, without changing its state.
      *
-     * @param resourceid Unique ID (0 .. the number specified in the constructor - 1) of the resource. 
-     * @returns The ID of the task which has locked the resource, or zero if the resource is free.
+     * @param resourceid The ID of the resouce to test.
+     * @returns Zero if the resource is free, or the ID of the task that is currently
+     * locking the resouce , if not.
 
      */
     uint TestResource(uint resourceid);
 
     /** Frees a resource
-     * Frees an mbos resource and restores the calling task's original priority. Does nothing if the resource is already free, if called from the idle task, or the resource was locked by a different task..
+     * Frees an mbos resource and restores the calling task's original priority. Does nothing 
+     * if the resource is already free, if called from the idle task, or the resource was 
+     * locked by a different task.
      *
-     * @param resourceid Unique ID (0 .. the number specified in the constructor - 1) of the resource. 
-     * @returns Zero, if the resource was freed successfully or the id of the task locking the resource if not.
+     * @param resourceid The ID of the resource t free. 
+     * @returns Zero if the resource was freed successfully, or the ID of the task that is
+     * locking the resource, if not.
      */
     uint FreeResource(uint resource);