HAL API requirements updates after review

Author: mprse

hal/analogin_api.h

@@ -37,9 +37,11 @@ typedef struct analogin_s analogin_t;
  * \defgroup hal_analogin Analogin hal functions
  *
  * # Defined behaviour
- * * The function ::analogin_init initializes the analogin peripheral
- * * The function ::analogin_read reads the input voltage, represented as a float in the range [0.0, 1.0]
- * * The function ::analogin_read_u16 reads the value from analogin pin, represented as an unsigned 16bit value
+ * * The function ::analogin_init initializes the analogin_t control structure
+ * * The function ::analogin_read reads the input voltage, represented as a float in the range [0.0 (GND), 1.0 (VCC)]
+ * * The function ::analogin_read_u16 reads the value from analogin pin, represented as an unsigned 16bit value [0.0 (GND), MAX_UINT16 (VCC)]
+ * * The accuracy of the ADC is +/- 10%
+ * * The ADC operations ::analogin_read, ::analogin_read_u16 take less than 20us to complete
  *
  * # Undefined behaviour
  *

hal/analogout_api.h

@@ -37,11 +37,13 @@ typedef struct dac_s dac_t;
  * \defgroup hal_analogout Analogout hal functions
  *
  * # Defined behaviour
- * * The function ::analogout_init initializes the analogin peripheral
- * * The function ::analogout_write sets the output voltage, specified as a percentage (float) in range [0.0, 1.0]
- * * The function ::analogout_write_u16 sets the output voltage, specified as unsigned 16-bit value
- * * The function ::analogout_read reads the current voltage value on the pin and returns a floating-point value representing the current voltage in range [0.0, 1.0]
- * * The function ::analogout_read_u16 reads the current voltage value on the pin and returns the output voltage, specified as unsigned 16-bit value
+ * * The function ::analogout_init initializes the dac_t control structure
+ * * The function ::analogout_write sets the output voltage, specified as a percentage (float) in range [0.0 (GND), 1.0 (VCC)]
+ * * The function ::analogout_write_u16 sets the output voltage, specified as unsigned 16-bit value [0 (GND), MAX_UINT16 (VCC)]
+ * * The function ::analogout_read reads the current voltage value on the pin and returns a floating-point value representing the current voltage in range [0.0 (GND), 1.0 (VCC)]
+ * * The function ::analogout_read_u16 reads the current voltage value on the pin and returns the output voltage, specified as unsigned 16-bit value [0 (GND), MAX_UINT16 (VCC)]
+ * * The accuracy of the DAC is +/- 10%
+ * * The DAC operations ::analogout_write, ::analogout_write_u16, ::analogout_read, ::analogout_read_u16 take less than 20us to complete
  * * The function ::analogout_free releases the analogout object
  *
  * # Undefined behaviour

hal/gpio_api.h

@@ -44,6 +44,7 @@ extern "C" {
  * * ::gpio_init_out inits the pin as an output, with predefined output value 0
  * * ::gpio_init_out_ex inits the pin as an output and sets the output value
  * * ::gpio_init_inout inits the pin to be input/output and set pin mode and value
+ * * The GPIO operations ::gpio_write, ::gpio_read take less than 20us to complete
  *
  * # Undefined behavior
  * * Calling any ::gpio_mode, ::gpio_dir, ::gpio_write or ::gpio_read on a gpio_t object that was initialized

hal/i2c_api.h

@@ -72,8 +72,7 @@ extern "C" {
  * \defgroup hal_GeneralI2C I2C Configuration Functions
  *
  * # Defined behavior
- * * ::i2c_init initialize the I2C peripheral
- * * ::i2c_init sets the default parameters for I2C peripheral
+ * * ::i2c_init initializes i2c_t control structure
  * * ::i2c_init configures the pins used by I2C
  * * ::i2c_frequency configure the I2C frequency
  * * ::i2c_start sends START command

hal/pwmout_api.h

@@ -37,7 +37,7 @@ typedef struct pwmout_s pwmout_t;
  * \defgroup hal_pwmout Pwmout hal functions
  *
  * # Defined behavior
- * * ::pwmout_init initializes the pwm out peripheral and configures the pin
+ * * ::pwmout_init initializes the pwmout_t control structure
  * * ::pwmout_free deinitializes the pwmout object
  * * ::pwmout_write sets the output duty-cycle in range <0.0f, 1.0f>
  * * ::pwmout_read returns the current float-point output duty-cycle in range <0.0f, 1.0f>
@@ -47,6 +47,9 @@ typedef struct pwmout_s pwmout_t;
  * * ::pwmout_pulsewidth sets the PWM pulsewidth specified in seconds, keeping the period the same
  * * ::pwmout_pulsewidth_ms sets the PWM pulsewidth specified in miliseconds, keeping the period the same
  * * ::pwmout_pulsewidth_us sets the PWM pulsewidth specified in microseconds, keeping the period the same
+ * * The accuracy of the PWM is +/- 10%
+ * * The PWM operations ::pwmout_write, ::pwmout_read, ::pwmout_read, ::pwmout_period_ms, ::pwmout_period_us
+ *   ::pwmout_pulsewidth, ::pwmout_pulsewidth_ms, ::pwmout_pulsewidth_us take less than 20us to complete
  *
  * # Undefined behavior
  * * Calling other function before ::pwmout_init

hal/serial_api.h

@@ -143,13 +143,13 @@ extern "C" {
  * otherwise software emulation is used.
  * * ::serial_tx_asynch starts the serial asynchronous transfer.
  * * ::serial_tx_asynch writes `tx_length` bytes from the `tx` to the bus.
- * * ::serial_tx_asynch must support 8 bits words
+ * * ::serial_tx_asynch must support 8 data bits
  * * The callback given to ::serial_tx_asynch is invoked when the transfer completes.
  * * ::serial_tx_asynch specifies the logical OR of events to be registered.
  * * The ::serial_tx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm.
  * * ::serial_rx_asynch starts the serial asynchronous transfer.
  * * ::serial_rx_asynch reads `rx_length` bytes to the `rx` buffer.
- * * ::serial_rx_asynch must support 8 bits words
+ * * ::serial_rx_asynch must support 8 data bits
  * * The callback given to ::serial_rx_asynch is invoked when the transfer completes.
  * * ::serial_rx_asynch specifies the logical OR of events to be registered.
  * * The ::serial_rx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm.

hal/spi_api.h

@@ -61,10 +61,8 @@ extern "C" {
  * \defgroup hal_GeneralSPI SPI Configuration Functions
  *
  * # Defined behavior
- * * ::spi_init initialize the SPI peripheral
+ * * ::spi_init initializes the spi_t control structure
  * * ::spi_init configures the pins used by SPI
- * * ::spi_init sets a default format and frequency
- * * ::spi_init enables the peripheral
  * * ::spi_free returns the pins owned by the SPI object to their reset state
  * * ::spi_format sets the number of bits per frame
  * * ::spi_format configures clock polarity and phase