pbio/os: Clarify use of pbio_os_process_init.

Author: laurensvalk

lib/pbio/include/pbio/os.h

@@ -208,7 +208,7 @@ struct _pbio_os_process_t {
 
 /**
  * Awaits two protothreads until one of them completes successfully or returns
- * an error.
+ * an error. There is no cleanup of the other protothread.
  *
  * @param [in]  host_state             State of the host protothread in which this macro is used.
  * @param [in]  sub_state_1            State of the first sub protothread.
@@ -250,6 +250,13 @@ struct _pbio_os_process_t {
         }                                       \
     } while (0)
 
+/**
+ * Yields the protothread until the specified timer expires.
+ * 
+ * @param [in]  state     Protothread state.
+ * @param [in]  timer     The timer to check.
+ * @param [in]  duration  The duration to wait for in milliseconds.
+ */
 #define PBIO_OS_AWAIT_MS(state, timer, duration)      \
     do {                                              \
         pbio_os_timer_set(timer, duration);           \
@@ -269,7 +276,7 @@ pbio_error_t pbio_port_process_none_thread(pbio_os_state_t *state, void *context
 
 void pbio_os_process_start(pbio_os_process_t *process, pbio_os_process_func_t func, void *context);
 
-void pbio_os_process_reset(pbio_os_process_t *process, pbio_os_process_func_t func);
+void pbio_os_process_init(pbio_os_process_t *process, pbio_os_process_func_t func);
 
 /**
  * Disables interrupts and returns the previous interrupt state.

lib/pbio/src/os.c

@@ -80,16 +80,20 @@ void pbio_os_process_start(pbio_os_process_t *process, pbio_os_process_func_t fu
     process->next = NULL;
     process->context = context;
 
-    pbio_os_process_reset(process, func);
+    pbio_os_process_init(process, func);
 }
 
 /**
- * Resets an existing process to the initial state with a new function and context.
+ * Initializes a process to the initial state with a protothread function to run.
+ *
+ * Can also be used to reset a process to the initial state or to change the
+ * protothread function. Doing so should be done with caution, but can be useful
+ * to make a process behave in distinct operation modes.
  *
  * @param process   The process to start.
  * @param func      The process thread function. Choose NULL if it does not need changing.
  */
-void pbio_os_process_reset(pbio_os_process_t *process, pbio_os_process_func_t func) {
+void pbio_os_process_init(pbio_os_process_t *process, pbio_os_process_func_t func) {
     process->err = PBIO_ERROR_AGAIN;
     process->state = 0;
     if (func) {

lib/pbio/src/port.c

@@ -500,7 +500,7 @@ pbio_error_t pbio_port_set_mode(pbio_port_t *port, pbio_port_mode_t mode) {
     }
 
     // Disable thread activity by attaching a thread that does nothing.
-    pbio_os_process_reset(&port->process, pbio_port_process_none_thread);
+    pbio_os_process_init(&port->process, pbio_port_process_none_thread);
     port->mode = mode;
 
     switch (mode) {
@@ -511,7 +511,7 @@ pbio_error_t pbio_port_set_mode(pbio_port_t *port, pbio_port_mode_t mode) {
         case PBIO_PORT_MODE_LEGO_DCM:
             // Physical modes for this mode will be set by the process so this
             // is all we need to do here.
-            pbio_os_process_reset(&port->process, pbio_port_process_pup_thread);
+            pbio_os_process_init(&port->process, pbio_port_process_pup_thread);
             // Returning e-again allows user module to wait for the port to be
             // ready after first entering LEGO mode, avoiding NODEV errors when
             // switching from direct access modes back to LEGO mode.