Add proposition of requirements for the HAL APIs tested by FPGA test shield.

Author: mprse

hal/analogin_api.h

@@ -35,9 +35,29 @@ 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
+ *
+ * # Undefined behaviour
+ *
+ * * ::analogin_init is called with invalid pin (which does not support analog input function)
+ * * Calling ::analogin_read, ::analogin_read_u16 before ::analogin_init
  * @{
  */
 
+/**
+ * \defgroup hal_analogin_tests Analogin hal tests
+ * The Analogin HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the Analogin hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-analogin
+ *
+ */
+
 /** Initialize the analogin peripheral
  *
  * Configures the pin used by analogin.

hal/analogout_api.h

@@ -35,9 +35,32 @@ 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_free releases the analogout object
+ *
+ * # Undefined behaviour
+ *
+ * * ::analogout_init is called with invalid pin (which does not support analog output function)
+ * * Calling other functions before ::analogout_init
  * @{
  */
 
+/**
+ * \defgroup hal_analogin_tests Analogout hal tests
+ * The Analogout HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the Analogout hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-analogout
+ *
+ */
+
 /** Initialize the analogout peripheral
  *
  * Configures the pin used by analogout.

hal/gpio_api.h

@@ -33,6 +33,16 @@ extern "C" {
  * # Defined behavior
  * * ::gpio_init and other init functions can be called with NC or a valid PinName for the target - Verified by ::gpio_nc_test
  * * ::gpio_is_connected can be used to test whether a gpio_t object was initialized with NC - Verified by ::gpio_nc_test
+ * * ::gpio_init initializes the GPIO pin
+ * * ::gpio_mode sets the mode of the given pin
+ * * ::gpio_dir sets the direction of the given pin
+ * * ::gpio_write sets the gpio output value
+ * * ::gpio_read reads the input value
+ * * ::gpio_init_in inits the input pin and sets mode to PullDefault
+ * * ::gpio_init_in_ex inits the input pin and sets the mode
+ * * ::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
  *
  * # Undefined behavior
  * * Calling any ::gpio_mode, ::gpio_dir, ::gpio_write or ::gpio_read on a gpio_t object that was initialized
@@ -42,6 +52,16 @@ extern "C" {
  * @{
  */
 
+/**
+ * \defgroup hal_gpio_tests GPIO HAL tests
+ * The GPIO HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the GPIO hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-gpio,tests-mbed_hal-gpio
+ *
+ */
+
 /** Set the given pin as GPIO
  *
  * @param pin The pin to be set as GPIO

hal/gpio_irq_api.h

@@ -44,9 +44,31 @@ typedef void (*gpio_irq_handler)(uint32_t id, gpio_irq_event event);
 
 /**
  * \defgroup hal_gpioirq GPIO IRQ HAL functions
+ *
+ * # Defined behavior
+ * * ::gpio_irq_init initializes the GPIO IRQ pin
+ * * ::gpio_irq_init attaches the interrupt handler
+ * * ::gpio_irq_free releases the GPIO IRQ pin
+ * * ::gpio_irq_set enables/disables pin IRQ event
+ * * ::gpio_irq_enable enables GPIO IRQ
+ * * ::gpio_irq_disable disables GPIO IRQ
+ *
+ * # Undefined behavior
+ * * Calling other function before ::gpio_irq_init
+ *
  * @{
  */
 
+/**
+ * \defgroup hal_gpioirq_tests GPIO IRQ HAL tests
+ * The GPIO IRQ HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the GPIO IRQ hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-gpio_irq
+ *
+ */
+
 /** Initialize the GPIO IRQ pin
  *
  * @param obj     The GPIO object to initialize

hal/i2c_api.h

@@ -70,9 +70,72 @@ 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 configures the pins used by I2C
+ * * ::i2c_frequency configure the I2C frequency
+ * * ::i2c_start sends START command
+ * * ::i2c_read reads `length` bytes from the I2C slave specified by `address` to the `data` buffer
+ * * ::i2c_read reads generates a stop condition on the bus at the end of the transfer if `stop` parameter is non-zero
+ * * ::i2c_read reads returns the number of symbols received from the bus
+ * * ::i2c_write writes `length` bytes to the I2C slave specified by `address` from the `data` buffer
+ * * ::i2c_write generates a stop condition on the bus at the end of the transfer if `stop` parameter is non-zero
+ * * ::i2c_write returns zero on success, error code otherwise
+ * * ::i2c_reset resets the I2C peripheral
+ * * ::i2c_byte_read reads and return one byte from the specfied I2C slave
+ * * ::i2c_byte_read uses `last` parameter to inform the slave that all bytes have been read
+ * * ::i2c_byte_write writes one byte to the specified I2C slave
+ * * ::i2c_byte_write returns 0 if NAK was received, 1 if ACK was received, 2 for timeout
+ * * ::i2c_slave_mode enables/disables I2S slave mode
+ * * ::i2c_slave_receive returns: 1 - read addresses, 2 - write to all slaves, 3 write addressed, 0 - the slave has not been addressed
+ * * ::i2c_slave_read reads `length` bytes from the I2C master to the `data` buffer
+ * * ::i2c_slave_read returns non-zero if a value is available, 0 otherwise
+ * * ::i2c_slave_write writes `length` bytes to the I2C master from the `data` buffer
+ * * ::i2c_slave_write returns non-zero if a value is available, 0 otherwise
+ * * ::i2c_slave_address configures I2C slave address
+ * * ::i2c_transfer_asynch starts I2C asynchronous transfer
+ * * ::i2c_transfer_asynch writes `tx_length` bytes to the I2C slave specified by `address` from the `tx` buffer
+ * * ::i2c_transfer_asynch reads `rx_length` bytes from the I2C slave specified by `address` to the `rx` buffer
+ * * ::i2c_transfer_asynch generates a stop condition on the bus at the end of the transfer if `stop` parameter is non-zero
+ * * The callback given to ::i2c_transfer_asynch is invoked when the transfer completes
+ * * ::i2c_transfer_asynch specifies the logical OR of events to be registered
+ * * The ::i2c_transfer_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm
+ * * ::i2c_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise returns 0.
+ * * ::i2c_active returns non-zero if the I2C module is active or 0 if it is not
+ * * ::i2c_abort_asynch aborts an on-going async transfer
+ *
+ * # Undefined behavior
+ * * Calling ::i2c_init multiple times on the same `i2c_t`
+ * * Calling any function other than ::i2c_init on a non-initialized `i2c_t`
+ * * Initialising the `I2C` peripheral with invalid `SDA` and `SCL` pins.
+ * * Passing pins that cannot be on the same peripheral
+ * * Passing an invalid pointer as `obj` to any function
+ * * Use of a `null` pointer as an argument to any function.
+ * * Initialising the peripheral in slave mode if slave mode is not supported
+ * * Operating the peripheral in slave mode without first specifying and address using ::i2c_slave_address
+ * * Setting an address using i2c_slave_address after initialising the peripheral in master mode
+ * * Setting an address to an `I2C` reserved value
+ * * Specifying an invalid address when calling any `read` or `write` functions
+ * * Setting the length of the transfer or receive buffers to larger than the buffers are
+ * * Passing an invalid pointer as `handler`
+ * * Calling ::i2c_abort_async when no transfer is currently in progress
+ *
+ *
  * @{
  */
 
+/**
+ * \defgroup hal_GeneralI2C_tests I2C hal tests
+ * The I2C HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the I2C hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-i2c
+ *
+ */
+
 /** Initialize the I2C peripheral. It sets the default parameters for I2C
  *  peripheral, and configures its specifieds pins.
  *

hal/pwmout_api.h

@@ -35,9 +35,36 @@ 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_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>
+ * * ::pwmout_period sets the PWM period specified in seconds, keeping the duty cycle the same
+ * * ::pwmout_period_ms sets the PWM period specified in miliseconds, keeping the duty cycle the same
+ * * ::pwmout_period_us sets the PWM period specified in microseconds, keeping the duty cycle the same
+ * * ::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
+ *
+ * # Undefined behavior
+ * * Calling other function before ::pwmout_init
+ * * Calling ::pwmout_init with NC as pwmout pin
+ *
  * @{
  */
 
+/**
+ * \defgroup hal_pwmout_tests GPIO IRQ HAL tests
+ * The Pwmout HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the Pwmout hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-pwm
+ *
+ */
+
 /** Initialize the pwm out peripheral and configure the pin
  *
  * @param obj The pwmout object to initialize

hal/serial_api.h

@@ -108,9 +108,69 @@ extern "C" {
 
 /**
  * \defgroup hal_GeneralSerial Serial Configuration Functions
+ *
+ * # Defined behaviour
+ * * ::serial_init initializes the serial peripheral
+ * * ::serial_init sets the default parameters for serial peripheral
+ * * ::serial_init configures its specified pins
+ * * ::serial_free releases the serial peripheral
+ * * ::serial_baud configures the baud rate
+ * * ::serial_format configures the transmission format (number of bits, parity and the number of stop bits)
+ * * ::serial_irq_handler registers the interrupt handler which will be invoked when the interrupt fires
+ * * ::serial_irq_set enables or disables serial irq (RX or TX)
+ * * ::serial_getc returns the character from serial buffer
+ * * ::serial_getc is a blocking call (waits for the character)
+ * * ::serial_putc sends a character
+ * * ::serial_putc is a blocking call (waits for a peripheral to be available)
+ * * ::serial_readable returns non-zero value if a character can be read, 0 if nothing to read
+ * * ::serial_writable returns non-zero value if a character can be written, 0 otherwise
+ * * ::serial_clear clears the serial peripheral
+ * * ::serial_break_set sets the break signal
+ * * ::serial_pinout_tx configures the TX pin for UART function
+ * * ::serial_set_flow_control configures serial flow control
+ * * ::serial_set_flow_control sets flow control in the hardware if a serial peripheral supports it, 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
+ * * 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
+ * * The callback given to ::serial_rx_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_tx_asynch specifies the character in range 0-254 to be matched
+ * * ::serial_tx_active returns non-zero if the TX transaction is ongoing, 0 otherwise
+ * * ::serial_rx_active returns non-zero if the RX transaction is ongoing, 0 otherwise
+ * * ::serial_irq_handler_asynch returns event flags if an RX transfer termination condition was met, otherwise returns 0
+ * * ::serial_tx_abort_asynch aborts the ongoing TX transaction
+ * * ::serial_tx_abort_asynch disables the enabled interupt for TX
+ * * ::serial_tx_abort_asynch flushes the TX hardware buffer if TX FIFO is used
+ * * ::serial_rx_abort_asynch aborts the ongoing RX transaction
+ * * ::serial_rx_abort_asynch disables the enabled interupt for RX
+ * * ::serial_rx_abort_asynch flushes the TX hardware buffer if RX FIFO is used
+ *
+ * # Undefined behaviour
+ *
+ * * Calling ::serial_init multiple times on the same `serial_t` without ::serial_free
+ * * Passing invalid pin to ::serial_init, ::serial_pinout_tx
+ * * Calling any function other than ::serial_init on a non-initialized or freed `serial_t`
+ * * Passing an invalid pointer as `obj` to any function
+ * * Passing an invalid pointer as `handler` to ::serial_irq_handler, ::serial_tx_asynch, ::serial_rx_asynch
+ * * Calling ::spi_abort while no async transfer is being processed (no transfer or a synchronous transfer)
  * @{
  */
 
+/**
+ * \defgroup hal_GeneralSerial_tests Serial hal tests
+ * The Serial HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the Serial hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-uart
+ *
+ */
+
 /** Initialize the serial peripheral. It sets the default parameters for serial
  *  peripheral, and configures its specifieds pins.
  *

hal/spi_api.h

@@ -59,9 +59,63 @@ extern "C" {
 
 /**
  * \defgroup hal_GeneralSPI SPI Configuration Functions
+ *
+ * # Defined behavior
+ * * ::spi_init initialize the SPI peripheral
+ * * ::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
+ * * ::spi_format configures master/slave mode
+ * * ::spi_frequency sets the SPI baud rate
+ * * ::spi_master_write writes a symbol out in master mode and receives a symbol
+ * * ::spi_master_block_write writes `tx_length` words to the bus
+ * * ::spi_master_block_write reads `rx_length` words from the bus
+ * * ::spi_master_block_write returns the maximum of tx_length and rx_length
+ * * ::spi_master_block_write specifies the write_fill which is default data transmitted while performing a read
+ * * ::spi_get_module returns non-zero if a value is available to read from SPI channel, 0 otherwise
+ * * ::spi_slave_read returns a received value out of the SPI receive buffer in slave mode
+ * * ::spi_slave_read blocks until a value is available
+ * * ::spi_slave_write writes a value to the SPI peripheral in slave mode
+ * * ::spi_slave_write blocks until the SPI peripheral can be written to
+ * * ::spi_busy returns non-zero if the peripheral is currently transmitting, 0 otherwise
+ * * ::spi_master_transfer starts the SPI asynchronous transfer
+ * * ::spi_master_transfer writes `tx_len` words to the bus
+ * * ::spi_master_transfer reads `rx_len` words from the bus
+ * * ::spi_master_transfer specifies the bit width of buffer words
+ * * The callback given to ::spi_master_transfer is invoked when the transfer completes (with a success or an error)
+ * * ::spi_master_transfer specifies the logical OR of events to be registered
+ * * The ::spi_master_transfer function may use the `DMAUsage` hint to select the appropriate async algorithm
+ * * ::spi_irq_handler_asynch reads the received values out of the RX FIFO
+ * * ::spi_irq_handler_asynch writes values into the TX FIFO
+ * * ::spi_irq_handler_asynch checks for transfer termination conditions, such as buffer overflows or transfer complete
+ * * ::spi_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise 0
+ * * ::spi_abort_asynch aborts an on-going async transfer
+ * * ::spi_active returns non-zero if the SPI port is active or zero if it is not
+ *
+ * # Undefined behavior
+ * * Calling ::spi_init multiple times on the same `spi_t` without ::spi_free
+ * * Calling any function other than ::spi_init on a non-initialized or freed `spi_t`
+ * * Passing pins that cannot be on the same peripheral
+ * * Passing an invalid pointer as `obj` to any function
+ * * Passing an invalid pointer as `handler` to ::spi_master_transfer
+ * * Calling ::spi_abort while no async transfer is being processed (no transfer or a synchronous transfer)
+ *
  * @{
  */
 
+/**
+ * \defgroup hal_GeneralSPI_tests SPI hal tests
+ * The SPI HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the SPI hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-spi
+ *
+ */
+
 #ifdef DEVICE_SPI_COUNT
 /**
  * Returns a variant of the SPIName enum uniquely identifying a SPI peripheral of the device.