1-wire. Improved comments

1 files changed, 130 insertions, 34 deletions

diff --git a/os/hal/include/onewire.h b/os/hal/include/onewire.h
index a5ebaa4..290a9b3 100644
--- a/os/hal/include/onewire.h
+++ b/os/hal/include/onewire.h
@@ -27,8 +27,6 @@
 #ifndef _ONEWIRE_H_
 #define _ONEWIRE_H_
 
-#include "hal.h" //FIXME: delete this line when integration done
-
 #if HAL_USE_ONEWIRE || defined(__DOXYGEN__)
 
 /*===========================================================================*/
@@ -36,7 +34,7 @@
 /*===========================================================================*/
 /**
  * @brief   Enable synthetic test for 'search ROM' procedure.
- * @note    Only for debugging/testing.
+ * @note    Only for debugging/testing!
  */
 #define ONEWIRE_SYNTH_SEARCH_TEST         FALSE
 
@@ -58,6 +56,14 @@
 /* Derived constants and error checks.                                       */
 /*===========================================================================*/
 
+#if !HAL_USE_PWM
+#error "1-wire Driver requires HAL_USE_PWM"
+#endif
+
+#if !HAL_USE_PAL
+#error "1-wire Driver requires HAL_USE_PAL"
+#endif
+
 /*===========================================================================*/
 /* Driver data structures and types.                                         */
 /*===========================================================================*/
@@ -83,11 +89,11 @@ typedef uint_fast8_t (*onewire_read_bit_t)(void);
  * @brief   Driver state machine possible states.
  */
 typedef enum {
-  ONEWIRE_UNINIT = 0,
-  ONEWIRE_STOP = 1,
-  ONEWIRE_READY = 2,
+  ONEWIRE_UNINIT = 0,         /**< Not initialized.                         */
+  ONEWIRE_STOP = 1,           /**< Stopped.                                 */
+  ONEWIRE_READY = 2,          /**< Ready.                                   */
 #if ONEWIRE_USE_STRONG_PULLUP
-  ONEWIRE_PULL_UP
+  ONEWIRE_PULL_UP             /**< Pull up asserted.                        */
 #endif
 } onewire_state_t;
 
@@ -95,87 +101,177 @@ typedef enum {
  * @brief   Search ROM procedure possible state.
  */
 typedef enum {
-  ONEWIRE_SEARCH_ROM_SUCCESS = 0,
-  ONEWIRE_SEARCH_ROM_LAST,
-  ONEWIRE_SEARCH_ROM_ERROR
+  ONEWIRE_SEARCH_ROM_SUCCESS = 0,   /**< ROM successfully discovered.       */
+  ONEWIRE_SEARCH_ROM_LAST = 1,      /**< Last ROM successfully discovered.  */
+  ONEWIRE_SEARCH_ROM_ERROR = 2      /**< Error happened during search.      */
 } search_rom_result_t;
 
 /**
  * @brief   Search ROM procedure iteration enum.
  */
 typedef enum {
-  ONEWIRE_SEARCH_ROM_FIRST = 0,
-  ONEWIRE_SEARCH_ROM_NEXT
+  ONEWIRE_SEARCH_ROM_FIRST = 0,     /**< First search run.                  */
+  ONEWIRE_SEARCH_ROM_NEXT = 1       /**< Next search run.                   */
 } search_iteration_t;
 
 /**
  * @brief   Driver configuration structure.
  */
 typedef struct {
+  /**
+   * @brief Pointer to @p PWM driver used for communication.
+   */
   PWMDriver                 *pwmd;
+  /**
+   * @brief Number of PWM channel used as master pulse generator.
+   */
   size_t                    master_channel;
+  /**
+   * @brief Number of PWM channel used as sample interrupt generator.
+   */
   size_t                    sample_channel;
+  /**
+   * @brief Pointer to function performing read of single bit.
+   * @note  It must be callable from any context.
+   */
   onewire_read_bit_t        readBitX;
 #if ONEWIRE_USE_STRONG_PULLUP
+  /**
+   * @brief Pointer to function asserting of strong pull up.
+   */
   onewire_pullup_assert_t   pullup_assert;
+  /**
+   * @brief Pointer to function releasing of strong pull up.
+   */
   onewire_pullup_release_t  pullup_release;
 #endif
 } onewireConfig;
 
 /**
- * @brief     Some small variable used in 'search ROM' procedure combined
- *            in single machine word to save RAM.
+ * @brief     Search ROM registry. Contains small variables used
+ *            in 'search ROM' procedure.
  */
 typedef struct {
-  uint32_t      single_device: 1;   /**< @brief Bool flag                   */
-  uint32_t      search_iter: 1;     /**< @brief 0 - first, 1 - next         */
-  uint32_t      result: 2;          /**< @brief 0 - success, 1 - last, 2 - error.*/
-  uint32_t      bit_step: 2;        /**< @brief 0 - direct, 1 - complemented, 2 - generated by master.     */
-  uint32_t      bit_buf: 2;         /**< @brief Acquired bits. 0s - direct, 1st - complement  */
-  uint32_t      rombit: 7;          /**< @brief Currently processing ROM bit. Must be big enough to store number 64.*/
-  uint32_t      devices_found: 8;   /**< @brief Devices count discovered on bus .*/
+  /**
+   * @brief Bool flag. If @p true than only bus has only one slave device.
+   */
+  uint32_t      single_device: 1;
+  /**
+   * @brief Search iteration (@p search_iteration_t enum).
+   */
+  uint32_t      search_iter: 1;
+  /**
+   * @brief Result of discovery procedure (@p search_rom_result_t enum).
+   */
+  uint32_t      result: 2;
+  /**
+   * @brief One of 3 steps of bit discovery.
+   * @details 0 - direct, 1 - complemented, 2 - generated by master.
+   */
+  uint32_t      bit_step: 2;
+  /**
+   * @brief Values acquired during bit discovery.
+   */
+  uint32_t      bit_buf: 2;
+  /**
+   * @brief Currently processing ROM bit.
+   * @note  Must be big enough to store number 64.
+   */
+  uint32_t      rombit: 7;
+  /**
+   * @brief Total device count discovered on bus.
+   * @note  Maximum 256.
+   */
+  uint32_t      devices_found: 8;
 } search_rom_reg_t;
 
 /**
  * @brief     Helper structure for 'search ROM' procedure
  */
 typedef struct {
+  /**
+   * @brief   Search ROM registry.
+   */
   search_rom_reg_t  reg;
-  uint8_t           *retbuf; /* buffer for currently discovering ROM */
+  /**
+   * @brief   Pointer to buffer with currently discovering ROM
+   */
+  uint8_t           *retbuf;
+  /**
+   * @brief   Previously discovered ROM.
+   */
   uint8_t           prev_path[8];
-  int8_t            last_zero_branch; /* negative values uses to point out of tree root */
-  int8_t            prev_zero_branch; /* negative values uses to point out of tree root */
+  /**
+   * @brief   Last zero turn branch.
+   * @note    Negative values use to point out of device tree's root.
+   */
+  int8_t            last_zero_branch;
+  /**
+   * @brief   Previous zero turn branch.
+   * @note    Negative values use to point out of device tree's root.
+   */
+  int8_t            prev_zero_branch;
 } onewire_search_rom_t;
 
 /**
- * @brief     Some small variable used in driver combined
+ * @brief     Onewire registry. Some small variables combined
  *            in single machine word to save RAM.
  */
 typedef struct {
 #if ONEWIRE_USE_STRONG_PULLUP
   /**
-   * @brief     This flag will be asserted by driver to signalize
-   *            ISR part when strong pullup needed.
+   * @brief   This flag will be asserted by driver to signalizes
+   *          ISR part when strong pull up needed.
    */
   uint32_t      need_pullup: 1;
 #endif
-  uint32_t      slave_present: 1;   /**< @brief Bool flag                   */
-  uint32_t      state: 2;           /**< @brief Driver state         */
-  uint32_t      bit: 4;             /**< @brief Bit number in currently receiving byte. Must be big enough to store 8 */
-  uint32_t      final_timeslot: 1;  /**< @brief bool flag for premature timer stop prevention */
-  uint32_t      bytes: 16;          /**< @brief Bytes number to be processing in current transaction.     */
+  /**
+   * @brief   Bool flag. If @p true than at least one device presence on bus.
+   */
+  uint32_t      slave_present: 1;
+  /**
+   * @brief   Driver internal state (@p onewire_state_t enum).
+   */
+  uint32_t      state: 2;
+  /**
+   * @brief   Bit number in currently receiving/sending byte.
+   * @note    Must be big enough to store 8.
+   */
+  uint32_t      bit: 4;
+  /**
+   * @brief   Bool flag for premature timer stop prevention.
+   */
+  uint32_t      final_timeslot: 1;
+  /**
+   * @brief   Bytes number to be processing in current transaction.
+   */
+  uint32_t      bytes: 16;
 } onewire_reg_t;
 
 /**
- * @brief   Structure representing an 1-wire driver.
+ * @brief     Structure representing an 1-wire driver.
  */
 typedef struct {
+  /**
+   * @brief   Onewire registry.
+   */
   onewire_reg_t         reg;
+  /**
+   * @brief   Onewire config.
+   */
   const onewireConfig   *config;
+  /**
+   * @brief   Config for underlying PWM driver.
+   */
   PWMConfig             pwmcfg;
+  /**
+   * @brief   Pointer to I/O data buffer.
+   */
   uint8_t               *buf;
+  /**
+   * @brief   Search ROM helper structure.
+   */
   onewire_search_rom_t  search_rom;
-
   /**
    * @brief   Thread waiting for I/O completion.
    */