Changeset a783ca4 in mainline

Timestamp:

2005-10-11T20:25:46Z (19 years ago)

Author:

Jakub Jermar <jakub@…>

Branches:

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

Children:

26f9943

Parents:

a016b63

Message:

Fix doxygen comments.

Location:

src

Files:

• debug/symtab.c (modified) (1 diff)
• proc/the.c (modified) (2 diffs)
• synch/condvar.c (modified) (3 diffs)
• synch/mutex.c (modified) (1 diff)
• synch/waitq.c (modified) (1 diff)
• time/delay.c (modified) (2 diffs)
• time/timeout.c (modified) (1 diff)

src/debug/symtab.c

@@ -32 +32 @@
 #include <arch/byteorder.h>
 
-/** Return entry that seems most likely to correspond to the @addr
+/** Return entry that seems most likely to correspond to address
  *
+ * Return entry that seems most likely to correspond
+ * to address passed in the argument.
+ *
+ * @param addr Address.
+ *
+ * @return Pointer to respective symbol string on success, NULL otherwise.
  */
 char * get_symtab_entry(__native addr)

src/proc/the.c

@@ -35 +35 @@
  * Initialize THE structure passed as argument.
  *
- * @the THE structure to be initialized.
- *
+ * @param the THE structure to be initialized.
  */
 void the_initialize(the_t *the)
@@ -51 +50 @@
  * Copy the source THE structure to the destination THE structure.
  *
- * @src The source THE structure.
- * @dst The destination THE structure.
+ * @param src The source THE structure.
+ * @param dst The destination THE structure.
  */
 void the_copy(the_t *src, the_t *dst)

src/synch/condvar.c

@@ -48 +48 @@
  * to the first waiting thread by waking it up.
  *
- * @param Condition variable.
+ * @param cv Condition variable.
  */
 void condvar_signal(condvar_t *cv)
@@ -60 +60 @@
  * to all waiting threads by waking them up.
  *
- * @param Condition variable.
+ * @param cv Condition variable.
  */
 void condvar_broadcast(condvar_t *cv)
@@ -71 +71 @@
  * Wait for the condition becoming true.
  *
- * @param Condition variable.
+ * @param cv Condition variable.
+ * @param mtx Mutex.
+ * @param usec Timeout value in microseconds.
+ * @param trywait Blocking versus non-blocking operation mode switch.
+ *
+ * For exact description of possible combinations of
+ * 'usec' and 'trywait', see comment for waitq_sleep_timeout().
+ *
+ * @return See comment for waitq_sleep_timeout().
  */
 int _condvar_wait_timeout(condvar_t *cv, mutex_t *mtx, __u32 usec, int trywait)

src/synch/mutex.c

@@ -47 +47 @@
  * Timeout mode and non-blocking mode can be requested.
  *
- * @param mxt Mutex.
+ * @param mtx Mutex.
  * @param usec Timeout in microseconds.
  * @param trylock Switches between blocking and non-blocking mode.

src/synch/waitq.c

@@ -109 +109 @@
  *
  * @param wq Pointer to wait queue.
- * @param usec Timeout value in microseconds.
- * @param nonblocking Controls whether only a conditional sleep
- *        (non-blocking sleep) is called for when the usec argument is 0.
- *
- * Relation between 'usec' and 'nonblocking' is described by this table:
- *
- * usec | nonblocking | what happens if there is no missed_wakeup
- * -----+-------------+--------------------------------------------
- *  0   | 0           | blocks without timeout until wakeup
- *  0   | <> 0        | immediately returns ESYNCH_WOULD_BLOCK
- *  > 0 | x           | blocks with timeout until timeout or wakeup
+ * @param usec Timeout in microseconds.
+ * @param nonblocking Blocking vs. non-blocking operation mode switch.
+ *
+ * If usec is greater than zero, regardless of the value of @nonblocking,
+ * the call will not return until either timeout or wakeup comes.
+ *
+ * If usec is zero and nonblocking is zero (false), the call
+ * will not return until wakeup comes.
+ *
+ * If usec is zero and nonblocking is non-zero (true), the call will
+ * immediately return, reporting either success or failure.
  *
  * @return Returns one of: ESYNCH_WOULD_BLOCK, ESYNCH_TIMEOUT,
  *         ESYNCH_OK_ATOMIC, ESYNCH_OK_BLOCKED.
  *
- * Meaning of the return values is described by the following chart:
- *
- * ESYNCH_WOULD_BLOCK   Sleep failed because at the time of the call,
- *                      there was no pending wakeup.
- * ESYNCH_TIMEOUT       Sleep timed out.
- * ESYNCH_OK_ATOMIC     Sleep succeeded; at the time of the call,
- *                      where was a pending wakeup.
- * ESYNCH_OK_BLOCKED    Sleep succeeded; the full sleep was attempted.
+ * ESYNCH_WOULD_BLOCK means that the sleep failed because at the time
+ * of the call there was no pending wakeup.
+ *
+ * ESYNCH_TIMEOUT means that the sleep timed out.
+ *
+ * ESYNCH_OK_ATOMIC means that the sleep succeeded and that there was
+ * a pending wakeup at the time of the call. The caller was not put
+ * asleep at all.
+ * 
+ * ESYNCH_OK_BLOCKED means that the sleep succeeded; the full sleep was 
+ * attempted.
  */
 int waitq_sleep_timeout(waitq_t *wq, __u32 usec, int nonblocking)

src/time/delay.c

@@ -39 +39 @@
  * is implemented as CPU calibrated active loop.
  *
- * @param microseconds Number of usec to sleep.
- *
+ * @param usec Number of microseconds to sleep.
  */
-void delay(__u32 microseconds)
+void delay(__u32 usec)
 {
         pri_t pri;
@@ -50 +49 @@
            cpu_priority_high() before calling the asm_delay_loop(). */
         pri = cpu_priority_high();
-        asm_delay_loop(microseconds * CPU->delay_loop_const);
+        asm_delay_loop(usec * CPU->delay_loop_const);
         cpu_priority_restore(pri);
 }

src/time/timeout.c

@@ -91 +91 @@
  *
  * @param t    Timeout list.
- * @patam time Number of usec in the future to execute
+ * @param time Number of usec in the future to execute
  *             the handler.
  * @param f    Timeout handler function.