Add testing requirements to HAL CRC header file.

Author: mprse

hal/crc_api.h

@@ -62,9 +62,64 @@ extern "C" {
  * The Hardware CRC HAL API provides a low-level interface to the Hardware CRC
  * module of a target platform.
  *
+ * # Defined behaviour
+ *
+ * * Function hal_crc_is_supported() returns true if platform supports hardware
+ *   CRC for the given polynomial/width - verified by test ::crc_is_supported_test.
+ * * Function hal_crc_is_supported() returns false if platform does not support hardware
+ *   CRC for the given polynomial/width - verified by test ::crc_is_supported_test.
+ * * Function hal_crc_is_supported() returns false if given pointer to configuration
+ *   structure is undefined (NULL) - verified by test ::crc_is_supported_invalid_param_test.
+ * * If CRC module does not support one of the following settings: initial_xor, final_xor
+ *   reflect_in, reflect_out, then these operations should be handled by the driver
+ *   - Verified by test ::crc_calc_single_test.
+ * * Platform which supports hardware CRC must be able to handle at least one of the predefined
+ *   polynomial/width configurations that can be constructed in the MbedCRC class: POLY_8BIT_CCITT,
+ *   POLY_7BIT_SD, POLY_16BIT_CCITT, POLY_16BIT_IBM, POLY_32BIT_ANSI
+ *   - verified by test ::crc_is_supported_test, ::crc_calc_single_test.
+ * * Function hal_crc_compute_partial_start() configures CRC module with the given configuration
+ *   - Verified by test ::crc_calc_single_test.
+ * * Calling hal_crc_compute_partial_start() without finalising the
+ *   CRC calculation overrides the current configuration - Verified by test ::crc_reconfigure_test.
+ * * Function hal_crc_compute_partial() writes data to the CRC module - verified by test ::crc_calc_single_test.
+ * * Function hal_crc_compute_partial() can be call multiple times in succession in order to
+ *   provide additional data to CRC module - verified by test ::crc_calc_multi_test.
+ * * Function hal_crc_compute_partial() does nothing if pointer to buffer is undefined or
+ *   data length is equal to 0 - verified by test ::crc_compute_partial_invalid_param_test.
+ * * Function hal_crc_get_result() returns the checksum result from the CRC module
+ *   - verified by tests ::crc_calc_single_test, ::crc_calc_multi_test, ::crc_reconfigure_test.
+ *
+ * # Undefined behaviour
+ *
+ * * Calling hal_crc_compute_partial_start() function with invalid (unsupported) polynomial.
+ * * Calling hal_crc_compute_partial() or hal_crc_get_result() functions before hal_crc_compute_partial_start().
+ * * Calling hal_crc_get_result() function multiple times.
+ *
+ * # Non-functional requirements
+ *
+ * * CRC configuration provides the following settings:
+ *   * polynomial - CRC Polynomial,
+ *   * width - CRC bit width,
+ *   * initial_xor - seed value for the computation,
+ *   * final_xor - final xor value for the computation,
+ *   * reflect_in - reflect bits on input,
+ *   * reflect_out - reflect bits in final result before returning.
+ *
+ * # Potential bugs
+ *
  * @{
  */
 
+/**
+ * \defgroup hal_crc_tests crc hal tests
+ * The crc HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the crc hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-crc*
+ *
+ */
+
 /** Determine if the current platform supports hardware CRC for given polynomial
  *
  * The purpose of this function is to inform the CRC Platform API whether the