From ad39fc280fcd6ae86659962fa50ade7eb5fbb7f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= <ondra@ondrovo.com>
Date: Sun, 7 Jan 2018 11:22:31 +0100
Subject: [PATCH] added some doc comments

---
 platform/pin_utils.c          | 16 +++++----
 platform/pin_utils.h          | 62 +++++++++++++++++++++++++++++++----
 units/digital_in/unit_din.c   |  1 +
 units/digital_in/unit_din.h   |  9 +++++
 units/digital_out/unit_dout.h | 35 ++++++++++++++++++++
 5 files changed, 109 insertions(+), 14 deletions(-)

diff --git a/platform/pin_utils.c b/platform/pin_utils.c
index 0ef321f..25c5feb 100644
--- a/platform/pin_utils.c
+++ b/platform/pin_utils.c
@@ -261,6 +261,7 @@ uint16_t port_pack(uint16_t spread, uint16_t mask)
     return result;
 }
 
+/** Configure unit pins as analog (part of unit teardown) */
 void deinit_unit_pins(Unit *unit)
 {
     for (uint32_t rsc = R_PA0; rsc <= R_PF15; rsc++) {
@@ -273,8 +274,8 @@ void deinit_unit_pins(Unit *unit)
     }
 }
 
-
-error_t configure_gpio_alternate(char port_name, uint8_t pin_num, uint32_t af)
+/** Configure a pin to alternate function */
+error_t configure_gpio_alternate(char port_name, uint8_t pin_num, uint32_t ll_af)
 {
     bool suc = true;
     GPIO_TypeDef *port = port2periph(port_name, &suc);
@@ -282,16 +283,17 @@ error_t configure_gpio_alternate(char port_name, uint8_t pin_num, uint32_t af)
     if (!suc) return E_BAD_CONFIG;
 
     if (pin_num < 8)
-        LL_GPIO_SetAFPin_0_7(port, ll_pin, af);
+        LL_GPIO_SetAFPin_0_7(port, ll_pin, ll_af);
     else
-        LL_GPIO_SetAFPin_8_15(port, ll_pin, af);
+        LL_GPIO_SetAFPin_8_15(port, ll_pin, ll_af);
 
     LL_GPIO_SetPinMode(port, ll_pin, LL_GPIO_MODE_ALTERNATE);
 
     return E_SUCCESS;
 }
 
-error_t configure_sparse_pins(char port_name, uint16_t mask, GPIO_TypeDef **port_dest, uint32_t mode, uint32_t otype)
+/** Configure pins using sparse map */
+error_t configure_sparse_pins(char port_name, uint16_t mask, GPIO_TypeDef **port_dest, uint32_t ll_mode, uint32_t ll_otype)
 {
     bool suc = true;
     GPIO_TypeDef *port = port2periph(port_name, &suc);
@@ -300,8 +302,8 @@ error_t configure_sparse_pins(char port_name, uint16_t mask, GPIO_TypeDef **port
     for (int i = 0; i < 16; i++) {
         if (mask & (1<<i)) {
             uint32_t ll_pin = pin2ll((uint8_t) i, &suc);
-            LL_GPIO_SetPinMode(port, ll_pin, mode);
-            LL_GPIO_SetPinOutputType(port, ll_pin, otype);
+            LL_GPIO_SetPinMode(port, ll_pin, ll_mode);
+            LL_GPIO_SetPinOutputType(port, ll_pin, ll_otype);
             LL_GPIO_SetPinSpeed(port, ll_pin, LL_GPIO_SPEED_FREQ_HIGH);
         }
     }
diff --git a/platform/pin_utils.h b/platform/pin_utils.h
index 94c83a5..0b2413a 100644
--- a/platform/pin_utils.h
+++ b/platform/pin_utils.h
@@ -38,16 +38,44 @@ Resource pin2resource(char port_name, uint8_t pin_number, bool *suc);
  */
 GPIO_TypeDef *port2periph(char port_name, bool *suc);
 
-/** Parse a pin name PA0 or A0 to port name and pin number */
+/**
+ * Parse a pin name (e.g. PA0 or A0) to port name and pin number
+ *
+ * @param str - source string
+ * @param targetName - output: port name (one character)
+ * @param targetNumber - output: pin number 0-15
+ * @return success
+ */
 bool parse_pin(const char *str, char *targetName, uint8_t *targetNumber);
 
-/** Parse a port name */
+/**
+ * Parse a port name (one character) - validates that it's within range
+ *
+ * @param value - source string
+ * @param targetName - output: port name (one character)
+ * @return success
+ */
 bool parse_port(const char *value, char *targetName);
 
-/** Parse a list of pin numbers with ranges and commans/semicolons to a bitmask */
+/**
+ * Parse a list of pin numbers with ranges and commands/semicolons to a bitmask.
+ * Supported syntax:
+ * - comma separated numbers
+ * - numbers connected by dash or colon form a range (can be in any order)
+ *
+ * @param value - source string
+ * @param suc - set to False if parsing failed
+ * @return the resulting bitmap
+ */
 uint16_t parse_pinmask(const char *value, bool *suc);
 
-/** Convert a pin bitmask to the ASCII format understood by str_parse_pinmask() */
+/**
+ * Convert a pin bitmap to the ASCII format understood by str_parse_pinmask()
+ *
+ * @param pins - sparse pin map
+ * @param buffer - output string buffer
+ * @return the output buffer
+ */
 char * str_pinmask(uint16_t pins, char *buffer);
 
 /**
@@ -69,13 +97,33 @@ uint16_t port_spread(uint16_t packed, uint16_t mask);
 uint16_t port_pack(uint16_t spread, uint16_t mask);
 
 /**
- * Set all GPIO resources held by unit to analog
+ * Set all GPIO resources held by unit to analog.
+ * This is a part of unit teardown.
  *
  * @param unit - holding unit
  */
 void deinit_unit_pins(Unit *unit);
 
-error_t configure_gpio_alternate(char port_name, uint8_t pin_num, uint32_t af);
-error_t configure_sparse_pins(char port_name, uint16_t mask, GPIO_TypeDef **port_dest, uint32_t mode, uint32_t otype);
+/**
+ * Configure a GPIO pin to alternate function.
+ *
+ * @param port_name - Port name A-F
+ * @param pin_num - Pin number 0-15
+ * @param ll_af - LL alternate function constant
+ * @return success
+ */
+error_t configure_gpio_alternate(char port_name, uint8_t pin_num, uint32_t ll_af);
+
+/**
+ * Configure multiple pins using the bitmap pattern
+ *
+ * @param port_name - port name A-F
+ * @param mask - Pins bitmap (0x8002 = pins 1 and 15)
+ * @param port_dest - destination pointer for the parsed GPIO Port struct. Can be NULL if the value is not needed.
+ * @param ll_mode - LL pin mode (in, out, analog...)
+ * @param ll_otype - LL output type (push/pull, opendrain)
+ * @return success
+ */
+error_t configure_sparse_pins(char port_name, uint16_t mask, GPIO_TypeDef **port_dest, uint32_t ll_mode, uint32_t ll_otype);
 
 #endif //GEX_PIN_UTILS_H
diff --git a/units/digital_in/unit_din.c b/units/digital_in/unit_din.c
index 1071e57..049da57 100644
--- a/units/digital_in/unit_din.c
+++ b/units/digital_in/unit_din.c
@@ -173,6 +173,7 @@ static void DI_deInit(Unit *unit)
 
 // ------------------------------------------------------------------------
 
+/** Read request */
 error_t UU_DI_Read(Unit *unit, uint16_t *packed)
 {
     CHECK_TYPE(unit, &UNIT_DIN);
diff --git a/units/digital_in/unit_din.h b/units/digital_in/unit_din.h
index ecb3261..00d5efa 100644
--- a/units/digital_in/unit_din.h
+++ b/units/digital_in/unit_din.h
@@ -9,4 +9,13 @@
 
 extern const UnitDriver UNIT_DIN;
 
+/**
+ * Read pins
+ *
+ * @param unit
+ * @param packed - output; the packed (right aligned) bits representing the pins, highest to lowest, are written here.
+ * @return success
+ */
+error_t UU_DI_Read(Unit *unit, uint16_t *packed);
+
 #endif //U_DIN_H
diff --git a/units/digital_out/unit_dout.h b/units/digital_out/unit_dout.h
index 0f7b3ef..b06a7b5 100644
--- a/units/digital_out/unit_dout.h
+++ b/units/digital_out/unit_dout.h
@@ -9,14 +9,49 @@
 
 extern const UnitDriver UNIT_DOUT;
 
+/**
+ * Write pins (e.g. writing 0b10 if configured pins are PA5 and PA0 sets PA5=1,PA0=0)
+ *
+ * @param unit
+ * @param packed - packed pin states (aligned to right)
+ * @return success
+ */
 error_t UU_DO_Write(Unit *unit, uint16_t packed);
 
+/**
+ * Set pins (clear none)
+ *
+ * @param unit
+ * @param packed - packed pins, 1 if pin should be set
+ * @return success
+ */
 error_t UU_DO_Set(Unit *unit, uint16_t packed);
 
+/**
+ * Clear multiple pins
+ *
+ * @param unit
+ * @param packed - packed pins, 1 if pin should be cleared
+ * @return
+ */
 error_t UU_DO_Clear(Unit *unit, uint16_t packed);
 
+/**
+ * Toggle pins
+ *
+ * @param unit
+ * @param packed - packed pins, 1 if pin should be toggled
+ * @return
+ */
 error_t UU_DO_Toggle(Unit *unit, uint16_t packed);
 
+/**
+ * Get number of configured pins
+ *
+ * @param unit
+ * @param count output, written with 0-16
+ * @return success
+ */
 error_t UU_DO_GetPinCount(Unit *unit, uint8_t *count);
 
 #endif //U_DOUT_H