A test module to verify implementation of the HAL. More...

Collaboration diagram for HAL Self Test:

Macros
#define	error_log(fmt, ...) print("ERROR: " fmt "\n", ##__VA_ARGS__)

#define	HAL_TEST_VERSION "v1.4"
	Version number of the HAL Self Test.

Functions
static status_t	VerifyHALImplementation (s2pi_slave_t spi_slave)
	Executes a series of tests in order to verify the HAL implementation.

static status_t	TimerPlausibilityTest (void)
	Plausibility Test for Timer HAL Implementation.

static status_t	TimerWraparoundTest (void)
	Wraparound Test for the Timer HAL Implementation.

static status_t	SpiConnectionTest (s2pi_slave_t slave)
	SPI Connection Test for S2PI HAL Implementation.

static status_t	SpiMaxLengthTest (s2pi_slave_t slave)
	Maximum SPI Data Size Test for S2PI HAL Implementation.

static status_t	GpioInterruptTest (s2pi_slave_t slave)
	SPI Interrupt Test for S2PI HAL Implementation.

static status_t	GpioModeTest (s2pi_slave_t slave)
	GPIO Mode Test for S2PI HAL Implementation.

static status_t	TimerTest (s2pi_slave_t slave)
	Test for Timer HAL Implementation by comparing timings to the device.

static status_t	PITTest (void)
	Test for PIT HAL Implementation by comparing timings to the device.

static status_t	SpiTransferFromInterruptTest (s2pi_slave_t slave)
	SPI Transfer from Interrupt Test for S2PI HAL Implementation.

static status_t	CheckTimerCounterValues (uint32_t hct, uint32_t lct)
	Checks the validity of timer counter values.

static status_t	SPITransferSync (s2pi_slave_t slave, uint8_t *data, size_t size)
	Helper function for transfer data to SPI in blocking mode.

static status_t	ConfigureDevice (s2pi_slave_t slave, int8_t rcoTrim)
	Configures the device with a bare minimum setup to run the tests.

static status_t	TriggerMeasurement (s2pi_slave_t slave, uint16_t samples, s2pi_callback_t callback, void *callbackData)
	Triggers a measurement on the device with specified sample count.

static status_t	ReadEEPROM (s2pi_slave_t slave, uint8_t *eeprom)
	Reads the EEPROM byte-wise and applies Hamming weight.

static status_t	ReadRcoTrim (s2pi_slave_t slave, int8_t *rcotrim)
	Reads the RCO_TRIM value from the devices EEPROM.

static status_t	RunMeasurement (s2pi_slave_t slave, uint16_t samples)
	Triggers a measurement on the device and waits for the data ready interrupt.

static status_t	RunPITTest (uint32_t exp_dt_us, uint32_t n)
	Executes a PIT measurement and verifies the callback interval.

static void	PIT_Callback (void *param)
	Callback function invoked by the PIT.

static void	GPIO_Callback (void *param)
	The IRQ callback dedicated to the GpioInterruptTest.

status_t	Argus_VerifyHALImplementation (s2pi_slave_t spi_slave)
	Executes a series of tests in order to verify the HAL implementation.

static status_t	SpiTransferInterruptCallback (status_t status, void *param)
	SPI interrupt callback function for the SPI transfer interrupt test.

static status_t	GPIO_SPI_Callback (status_t status, void *param)
	The SPI transfer callback dedicated to the GpioInterruptTest.

static void	MeasurementCallback (void *param)
	Callback function for the data ready interrupt.

static status_t	SpiTransferFromSpiInterruptCallback (status_t status, void *param)
	SPI interrupt callback function for the SPI transfer from IRQ test.

static status_t	SpiTransferFromSpiInterrupt (s2pi_slave_t slave)
	SPI transfer from SPI interrupt callback test.

static void	SpiTransferFromGpioInterruptCallback (void *param)
	GPIO interrupt callback function for the SPI transfer from IRQ test.

static status_t	SpiTransferFromGpioInterrupt (s2pi_slave_t slave)
	SPI transfer from GPIO interrupt callback test.

static void	SpiTransferFromPitInterruptCallback (void *param)
	PIT interrupt callback function for the SPI transfer from IRQ test.

static status_t	SpiTransferFromPitInterrupt (s2pi_slave_t slave)
	SPI transfer from PIT interrupt callback test.

Detailed Description

A test module to verify implementation of the HAL.

A series of automated tests that can be executed on the target platform in order to verify the implementation of the HAL that are required by the API.

See Argus_VerifyHALImplementation for a detailed documentation.

Macro Definition Documentation

◆ error_log

#define error_log	(	fmt,
		...
	)	print("ERROR: " fmt "\n", ##__VA_ARGS__)

An error log message via print function.

◆ HAL_TEST_VERSION

#define HAL_TEST_VERSION "v1.4"

Version number of the HAL Self Test.

Changes:

v1.0:
- Initial release.
v1.1:
- Added additional print output.
- Increased tolerance for timer test to 3%.
- Fixed callback issue by disabling it after IRQ test.
v1.2:
- Added PIT test cases.
v1.3:
- Added test case for SPI maximum data transfer size.
- Added tests for SPI transfers invoked from all IRQ callbacks.
- Added verification of first PIT event occurrence.
- Relaxed PIT pass conditions (0.1% -> 0.5%)
v1.4:
- Adopted to new multi-device HAL interface of API v1.4.4 release.
- Added verification of SPI callback invocation.
- Updated GPIO interrupt test to verify if delayed interrupt pending states can be detected via S2PI_ReadIrqPin.

Function Documentation

◆ Argus_VerifyHALImplementation()

status_t Argus_VerifyHALImplementation ( s2pi_slave_t spi_slave )

Executes a series of tests in order to verify the HAL implementation.

A series of automated tests are executed on the target platform in order to verify the implementation of the HAL that are required by the API.

Each test will write an error description via the print (i.e. UART) function that shows what went wrong. Also an corresponding status is returned in case no print functionality is available.

The following tests are executed:

1) Timer Plausibility Test:

Rudimentary tests of the lifetime counter (LTC) implementation. This verifies that the LTC is running by checking if the returned values of two consecutive calls to the Timer_GetCounterValue function are ascending. An artificial delay using the NOP operation is induced such that the timer is not read to fast.

2) Timer Wraparound Test:

The LTC values must wrap from 999999 µs to 0 µs and increase the seconds counter accordingly. This test verifies the correct wrapping by consecutively calling the Timer_GetCounterValue function until at least 2 wraparound events have been occurred.

3) SPI Connection Test:

This test verifies the basic functionality of the SPI interface. The test utilizes the devices laser pattern register, which can be freely programmed by any 128-bit pattern. Thus, it writes a byte sequence and reads back the written values on the consecutive SPI access.

4) SPI Maximum Data Length Test:

This test verifies the maximum data transfer length of the SPI interface. The test sends and receives up to 396 data bytes plus a single address byte over the SPI interface and verifies that no data get lost.

5) SPI Interrupt Test:

This test verifies the correct implementation of the device integration finished interrupt callback. Therefore it configures the device with a minimal setup to run a pseudo measurement that does not emit any laser light.

Note that this test does verify the GPIO interrupt that occurs whenever the device has finished the integration/measurement and new data is waiting to be read from the device. This does not test the interrupt that is triggered when the SPI transfer has finished.

The data ready interrupt implies two S2PI layer functions that are tested in this test: The S2PI_SetIrqCallback function installs a callback function that is invoked whenever the IRQ occurs. The IRQ can be delayed due to higher priority task, e.g. from the user code. It is essential for the laser safety timeout algorithm to determine the device ready signal as fast as possible, another method is implemented to read if the IRQ is pending but the callback has not been reset yet. This is what the S2PI_ReadIrqPin function is for.

6) GPIO Mode Test:

This test verifies the GPIO mode of the S2PI HAL module. This is done by leveraging the EEPROM readout sequence that accesses the devices EEPROM via a software protocol that depends on the GPIO mode.

This the requires several steps, most of them are already verified in previous tests:

Basic device configuration and enable EEPROM.
Read EERPOM via GPIO mode and apply Hamming weight.
Repeat several times (to eliminate random readout issues).
Decode the EEPROM (using EEPROM_Decode in argus_cal_eeprom.c).
Check if Module Number and Chip ID is not 0.

7) Timer Test for Lifetime Counter:

The test verifies the lifetime counter timer HAL implementation by comparing the timings to the AFBR-S50 device as a reference. Therefore several measurement are executed on the device, each with a different averaging sample count. The elapsed time increases linearly with the number of averaging samples. In order to remove the time for software/setup, a linear regression fit is applied to the measurement results and only the slope is considered for the result. A delta of 102.4 microseconds per sample is expected. If the measured delta per sample is within an specified error range, the timer implementation is considered correct.

8) Timer Test for Periodic Interrupt Timer (optional):

The test verifies the correct implementation of the periodic interrupt timer (PIT). It sets different intervals and waits for a certain number of interrupts to happen. Each interrupt event is counted and the time between the first and the last interrupt is measured. Finally, the measured interval is compared to the expectations.

Note that this test is only executed if the PIT is actually implemented. Otherwise, the test is skipped.

9) SPI Transfer from Interrupt Callback Test:

The test verifies that the S2PI_TransferFrame method of the S2PI layer can be invoked from a interrupt callback function too. Thus, it repeats the S2PI Connection Test but this time from different interrupt callback functions:

SPI Callback: The first transfer is invoked from thread level, the second transfer is invoke from the SPI interrupt callback function.
GPIO Callback: The device is setup to trigger an GPIO interrupt (see also the SPI Interrupt Test). The corresponding GPIO interrupt callback function will trigger the first transfer while the second one is triggered from the SPI callback function.
PIT Callback (optional): This test is only executed optional if the PIT interface is implemented. The test sequence is the same as for the GPIO callback, but the first transfer is triggered from the PIT callback function.

Note: See HAL_TEST_VERSION for a version history and change log of the HAL self tests.

Parameters

spi_slave The SPI hardware slave, i.e. the specified CS and IRQ lines. This is actually just a number that is passed to the SPI interface to distinct for multiple SPI slave devices. Note that the slave must be not equal to 0, since is reserved for error handling.

Returns: Returns the status (STATUS_OK on success).

Examples: 01_simple_example_with_hal_self_test.c, and 02_advanced_example_with_hal_self_test.c.

◆ CheckTimerCounterValues()

static status_t CheckTimerCounterValues	(	uint32_t	hct,
		uint32_t	lct
	)

static

Checks the validity of timer counter values.

This verifies that the counter values returned from the Timer_GetCounterValue function are valid. This means, the low counter value lct is within 0 and 999999 µs.

Returns

Returns the status:

STATUS_OK on success.
ERROR_FAIL on failure (check the error log for more information).

◆ ConfigureDevice()

static status_t ConfigureDevice	(	s2pi_slave_t	slave,
		int8_t	rcoTrim
	)

static

Configures the device with a bare minimum setup to run the tests.

This function applies a number of configuration values to the device, such that a pseudo measurement w/o laser output can be performed.

A rcoTrim parameter can be passed to adjust the actual clock setup.

Warning: The test utilizes already the timer HAL in order to implement a rudimentary timeout. However, at this time, only some basic plausibility checks are performed on the timer HAL. I.e. if there is an issue in the time HAL, e.g. too fast or too slow time counting, the test may fail with an ERROR_TIMEOUT. In this case, one also needs to verify the timer HAL, especially the Timer_GetCounterValue function.

Parameters

slave	The S2PI slave parameter passed to the S2PI HAL functions.
rcoTrim	The RCO Trimming value added to the nominal RCO register value. Pass 0 if no fine tuning is required.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if the SPI operation did not finished within a specified time (check also timer HAL implementation).
The S2PI layer error code if S2PI_TransferFrame or S2PI_GetStatus return any negative status.

◆ GPIO_Callback()

static void GPIO_Callback ( void * param )

static

The IRQ callback dedicated to the GpioInterruptTest.

The callback is invoked by the API when the device GPIO IRQ is pending after a measurement has been executed and data is ready to be read from the device.

Parameters

param The abstract pointer to the boolean value that determines if the callback is invoked.

◆ GPIO_SPI_Callback()

static status_t GPIO_SPI_Callback	(	status_t	status,
		void *	param
	)

static

The SPI transfer callback dedicated to the GpioInterruptTest.

The callback is invoked by the S2PI layer when the SPI transfer finished IRQ is invoked. The callback is used to simulate a deferred GPIO interrupt by locking the interrupts until the S2PI_ReadIrqPin detects an GPIO interrupt pending state and returns 0.

Parameters

status	The status of the SPI transfer.
param	The abstract pointer to the boolean value that determines if the callback is invoked.

Returns

Returns the status:

STATUS_OK on success.
ERROR_FAIL if the param parameter is NULL.
ERROR_TIMEOUT if the S2PI_ReadIrqPin does not return 0 after a specified time (check also timer HAL implementation).
The S2PI layer error code that may be received from the S2PI module via the status parameter.

◆ GpioInterruptTest()

static status_t GpioInterruptTest ( s2pi_slave_t slave )

static

SPI Interrupt Test for S2PI HAL Implementation.

This test verifies the correct implementation of the device integration finished interrupt callback, a.k.a. the GPIO interrupt. Therefore it configures the device with a minimal setup to run a pseudo measurement that does not emit any laser light but triggers an GPIO interrupt once finished.

The data ready interrupt implies two S2PI layer functions that are tested in this test: The S2PI_SetIrqCallback function installs a callback function that is invoked whenever the IRQ occurs and the S2PI_ReadIrqPin function to obtain the pending interrupt state.

The IRQ can be delayed due to higher priority task, e.g. from the user code. It is essential for the laser safety timeout algorithm to determine the device ready signal as fast as possible. Thus a method is required to obtain if the IRQ is currently pending but the callback has not been invoked yet. This is what the S2PI_ReadIrqPin function is for. Note that the S2PI_ReadIrqPin must return 0 if not interrupt is pending and 1 else. Just like the IRQ pin is active low.

The test simulate a delayed GPIO interrupt by locking the interrupts until the S2PI_ReadIrqPin detects an GPIO interrupt pending state and returns 0. This is done by the GPIO_SPI_Callback function.

Note that this test does verify the GPIO interrupt that occurs whenever the device has finished the integration/measurement and new data is waiting to be read from the device. This does not test the interrupt that is triggered when the SPI transfer has finished.

Warning: The test assumes the device is in a fresh power on state and no additional reset is required. If the test fail, one may want to power cycle the device and try again.; The test locks the interrupts for a quite long period of time in order to simulate a delayed GPIO interrupt. This is not a good practice in production code. However, it is required to test the S2PI_ReadIrqPin function. Please be aware of that when you run this test.; The test utilizes already the timer HAL in order to implement a rudimentary timeout. However, at this time, only some basic plausibility checks are performed on the timer HAL. I.e. if there is an issue in the time HAL, e.g. too fast or too slow time counting, the test may fail with an ERROR_TIMEOUT. In this case, one also needs to verify the timer HAL, especially the Timer_GetCounterValue function.

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if either the SPI operation did not finished or the IRQ was not detected within a specified time (check also timer HAL implementation).
ERROR_FAIL if the IRQ pin readout failed and the no or invalid interrupt was detected.
The S2PI layer error code if S2PI_TransferFrame, S2PI_GetStatus or S2PI_SetIrqCallback return any negative status.

◆ GpioModeTest()

static status_t GpioModeTest ( s2pi_slave_t slave )

static

GPIO Mode Test for S2PI HAL Implementation.

This test verifies the GPIO mode of the S2PI HAL module. This is done by leveraging the EEPROM readout sequence that accesses the devices EEPROM via a software protocol that depends on the GPIO mode.

This the requires several steps, most of them are already verified in previous tests:

Basic device configuration and enable EEPROM.
Read EEPROM via GPIO mode and apply Hamming weight
Repeat several times (to eliminate random readout issues).
Decode the EEPROM (using EEPROM_Decode in argus_cal_eeprom.c)
Check if Module Number and Chip ID is not 0

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_FAIL if the GPIO test fails.
STATUS_ARGUS_EEPROM_BIT_ERROR if the Hamming weight fails.
The S2PI layer error code if S2PI_CaptureGpioControl, S2PI_ReleaseGpioControl, S2PI_WriteGpioPin or S2PI_ReadGpioPin return any negative status.

◆ MeasurementCallback()

static void MeasurementCallback ( void * param )

static

Callback function for the data ready interrupt.

The function is called by the S2PI layer when the data ready interrupt is pending. The function sets the param to STATUS_IDLE.

Parameters

param The parameter passed to the S2PI_SetIrqCallback function as an abstract pointer to an status_t type.

◆ PIT_Callback()

static void PIT_Callback ( void * param )

static

Callback function invoked by the PIT.

The function that is invoked every time a specified interval elapses. An abstract parameter is passed to the function whenever it is called.

This implementation collects callback time stamps and counts the number of callback events using the abstract parameter.

Parameters

param An abstract parameter to be passed to the callback. This is also the identifier of the given interval.

◆ PITTest()

static status_t PITTest ( void )

static

Test for PIT HAL Implementation by comparing timings to the device.

The test verifies the timer HAL implementation by comparing the period between the interrupts with the lifetime timer values that has been already verified in a previous test (see TimerTest).

Returns

Returns the status:

STATUS_OK on success.
ERROR_NOT_IMPLEMENTED if the PIT functionality is not implemented and the test is skipped.
ERROR_FAIL if the measured interval does not match the expectations or the PIT was not disabled properly.
ERROR_TIMEOUT if either the PIT events do not occur within the expected time.
The PIT layer error code if Timer_SetInterval or Timer_SetCallback return any negative status.

◆ ReadEEPROM()

static status_t ReadEEPROM	(	s2pi_slave_t	slave,
		uint8_t *	eeprom
	)

static

Reads the EEPROM byte-wise and applies Hamming weight.

The EEPROM bytes are consecutively read from the device via GPIO mode. The EEPROM_Read function is an internal API function that enables the GPIO mode from the S2PI module and reads the data via a software bit-banging protocol. Finally it disables the GPIO mode and returns to SPI mode.

The calls to S2PI HAL module is as follows:

S2PI_CaptureGpioControl
multiple calls to S2PI_WriteGpioPin and S2PI_ReadGpioPin
S2PI_ReleaseGpioControl

Parameters

slave	The S2PI slave parameter passed to the S2PI HAL functions.
eeprom	The 16 byte array to be filled with EEPROM data.

Returns

Returns the status:

STATUS_OK on success.
STATUS_ARGUS_EEPROM_BIT_ERROR if the Hamming weight fails. interrupt was detected.
The S2PI layer error code if S2PI_CaptureGpioControl, S2PI_ReleaseGpioControl, S2PI_WriteGpioPin or S2PI_ReadGpioPin return any negative status.

◆ ReadRcoTrim()

static status_t ReadRcoTrim	(	s2pi_slave_t	slave,
		int8_t *	rcotrim
	)

static

Reads the RCO_TRIM value from the devices EEPROM.

The function reads the devices EEPROM via GPIO mode and extracts the RCO_TRIM value from the EEPROM map.

Parameters

slave	The S2PI slave parameter passed to the S2PI HAL functions.
rcotrim	The read RCO_TRIM value will be returned via this pointer.

Returns

Returns the status:

STATUS_OK on success.
STATUS_ARGUS_EEPROM_BIT_ERROR if the Hamming weight fails.
ERROR_ARGUS_UNKNOWN_MODULE if the EEPROM module number is invalid.
The S2PI layer error code if S2PI_CaptureGpioControl, S2PI_ReleaseGpioControl, S2PI_WriteGpioPin or S2PI_ReadGpioPin return any negative status.

◆ RunMeasurement()

static status_t RunMeasurement	(	s2pi_slave_t	slave,
		uint16_t	samples
	)

static

Triggers a measurement on the device and waits for the data ready interrupt.

The function triggers a measurement cycle on the device and waits until the measurement has been finished. A sample count can be specified to setup individual number of digital averaging.

Warning: The test utilizes already the timer HAL in order to implement a rudimentary timeout. However, at this time, only some basic plausibility checks are performed on the timer HAL. I.e. if there is an issue in the time HAL, e.g. too fast or too slow time counting, the test may fail with an ERROR_TIMEOUT. In this case, one also needs to verify the timer HAL, especially the Timer_GetCounterValue function.

Parameters

slave	The S2PI slave parameter passed to the S2PI HAL functions.
samples	The specified number of averaging samples for the measurement.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if either the SPI operation did not finished or the IRQ was not detected within a specified time (check also timer HAL implementation).
The S2PI layer error code if S2PI_TransferFrame, S2PI_GetStatus or S2PI_SetIrqCallback return any negative status.

◆ RunPITTest()

static status_t RunPITTest	(	uint32_t	exp_dt_us,
		uint32_t	n
	)

static

Executes a PIT measurement and verifies the callback interval.

The function configures the PIT with a given interval and waits several callback events to happen. In each callback event, the elapsed time is measured and the number of calls are counted. Finally, the average interrupt period is compared with the lifetime timer that has been already verified in a previous test (see TimerTest). The time until the first interrupt event is also verified.

Parameters

exp_dt_us	The expected timer interval in microseconds.
n	The number of PIT events to await.

Returns

Returns the status:

STATUS_OK on success.
ERROR_FAIL if the measured interval does not match the expectations or the PIT was not disabled properly.
ERROR_TIMEOUT if either the PIT events do not occur within the expected time.
The PIT layer error code if Timer_SetInterval return any negative status.

◆ SpiConnectionTest()

static status_t SpiConnectionTest ( s2pi_slave_t slave )

static

SPI Connection Test for S2PI HAL Implementation.

This test verifies the basic functionality of the SPI interface.

     The test utilizes the devices laser pattern register, which can
     be freely programmed by any 128-bit pattern. Thus, it writes a byte
     sequence and reads back the written values on the consecutive SPI
     access.

     Note: The test verifies the SPI interface transfer functionality
     in blocking mode and also verifies the interrupt callback.
     In order to wait for the transfer to finish, it reads the S2PI
     status in a loop. If the status does not change to #STATUS_IDLE,
     the test will fail with an #ERROR_TIMEOUT. Finally, the test will
     verify the SPI transfer callback status.

Warning: The test utilizes already the timer HAL in order to implement a rudimentary timeout. However, at this time, only some basic plausibility checks are performed on the timer HAL. I.e. if there is an issue in the time HAL, e.g. too fast or too slow time counting, the test may fail with an ERROR_TIMEOUT. In this case, one also needs to verify the timer HAL, especially the Timer_GetCounterValue function.

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if the operation did not finished within a specified time (check also timer HAL implementation).
ERROR_FAIL if the device access failed and the read data did not match the expected values.
The S2PI layer error code if S2PI_TransferFrame, S2PI_GetStatus or the SPI callback yield any negative status.

◆ SpiMaxLengthTest()

static status_t SpiMaxLengthTest ( s2pi_slave_t slave )

static

Maximum SPI Data Size Test for S2PI HAL Implementation.

This test verifies the maximum data transfer length of the SPI interface. The test sends and receives up to 396 data bytes plus a single address byte over the SPI interface and verifies that no data get lost.

The test utilizes the channel select register which is 3 bytes plus address. This register can be repeatedly written with any pattern using the DMA mode. The register is written 100 times in a row to verify that long data frames with up to 400 bytes can be transmitted.

Note that this test was motivated by an invalid implementation that used uint8_t type for the frame length in the S2PI_TransferFrame function instead of an uint16_t value. This resulted in a maximum data length of 141 bytes (367 & 0xFF = 141) when reading the data value register.

Warning: The test utilizes already the timer HAL in order to implement a rudimentary timeout. However, at this time, only some basic plausibility checks are performed on the timer HAL. I.e. if there is an issue in the time HAL, e.g. too fast or too slow time counting, the test may fail with an ERROR_TIMEOUT. In this case, one also needs to verify the timer HAL, especially the Timer_GetCounterValue function.

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if the operation did not finished within a specified time (check also timer HAL implementation).
ERROR_FAIL if the device access failed and the read data did not match the expected values.
The S2PI layer error code if S2PI_TransferFrame or S2PI_GetStatus return any negative status.

◆ SpiTransferFromGpioInterrupt()

static status_t SpiTransferFromGpioInterrupt ( s2pi_slave_t slave )

static

SPI transfer from GPIO interrupt callback test.

This test verifies the interrupt functionality of the SPI interface. The test verifies that an SPI transfer can be triggered from the GPIO interrupt service routine context.

The test basically repeats the SpiTransferFromSpiInterrupt but this time it invokes the first SPI transfer from the GPIO callback function. In order to trigger a GPIO interrupt, the device is configured and a measurement is started (see GpioInterruptTest).

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if the test did not finish within a specified time.
ERROR_FAIL if the device access failed and the read data did not match the expected values.
The S2PI layer error code if S2PI_TransferFrame or the GPIO or SPI callback yield in any non-OK status.

◆ SpiTransferFromGpioInterruptCallback()

static void SpiTransferFromGpioInterruptCallback ( void * param )

static

GPIO interrupt callback function for the SPI transfer from IRQ test.

The interrupt callback is invoked from the S2PI module upon receiving an GPIO interrupt from the devices IRQ pin. The callback is used by the SpiTransferFromGpioInterrupt test to trigger the first SPI transfer from the interrupt callback context.

Note: The callback also utilizes the print functionality. This requires a correct implementation of the corresponding function such that it can be invoked from the given interrupt context. This usually requires the underlying send (e.g. UART or USB send functions) to have higher priority that this interrupt in order to finished the print statement asynchronously.

Parameters

param The abstract interrupt callback parameter.

◆ SpiTransferFromInterruptTest()

static status_t SpiTransferFromInterruptTest ( s2pi_slave_t slave )

static

SPI Transfer from Interrupt Test for S2PI HAL Implementation.

This test verifies the interrupt functionality of the SPI interface. The test verifies that an SPI transfer can be triggered from the interrupt service routine context. I.e. the S2PI_TransferFrame function is called from the following interrupts:

SPI interrupt
GPIO interrupt
PIT interrupt (optional, if PIT is implemented)

Warning: The test utilizes already the timer HAL in order to implement a rudimentary timeout. However, at this time, only some basic plausibility checks are performed on the timer HAL. I.e. if there is an issue in the time HAL, e.g. too fast or too slow time counting, the test may fail with an ERROR_TIMEOUT. In this case, one also needs to verify the timer HAL, especially the Timer_GetCounterValue function.

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if the operation did not finished within a specified time (check also timer HAL implementation).
ERROR_FAIL if the device access failed and the read data did not match the expected values.
The S2PI layer error code if S2PI_TransferFrame or S2PI_GetStatus return any negative status.

◆ SpiTransferFromPitInterrupt()

static status_t SpiTransferFromPitInterrupt ( s2pi_slave_t slave )

static

SPI transfer from PIT interrupt callback test.

This test verifies the interrupt functionality of the SPI interface. The test verifies that an SPI transfer can be triggered from the PIT interrupt service routine context.

The test basically repeats the SpiTransferFromSpiInterrupt but this time it invokes the first SPI transfer from the PIT callback function. In order to trigger a PIT interrupt, the timer is configured with a small interval and immediately disabled upon the first event.

Note that this test is only executed if the PIT module is actually implemented.

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_NOT_IMPLEMENTED if the PIT functionality is not implemented and the test is skipped.
ERROR_TIMEOUT if the test did not finish within a specified time.
ERROR_FAIL if the device access failed and the read data did not match the expected values.
The S2PI layer error code if S2PI_TransferFrame or the SPI callback yield in any non-OK status.
The PIT layer error code if Timer_SetCallback or the PIT callback yield in any non-OK status.

◆ SpiTransferFromPitInterruptCallback()

static void SpiTransferFromPitInterruptCallback ( void * param )

static

PIT interrupt callback function for the SPI transfer from IRQ test.

The interrupt callback is invoked from the PIT module upon periodic timeout event. The callback is used by the SpiTransferFromPitInterrupt test to trigger the first SPI transfer from the interrupt callback context.

Note: The callback also utilizes the print functionality. This requires a correct implementation of the corresponding function such that it can be invoked from the given interrupt context. This usually requires the underlying send (e.g. UART or USB send functions) to have higher priority that this interrupt in order to finished the print statement asynchronously.

Parameters

param The abstract interrupt callback parameter.

◆ SpiTransferFromSpiInterrupt()

static status_t SpiTransferFromSpiInterrupt ( s2pi_slave_t slave )

static

SPI transfer from SPI interrupt callback test.

This test verifies the interrupt functionality of the SPI interface. The test verifies that an SPI transfer can be triggered from the SPI interrupt service routine context.

The test basically repeats the SpiConnectionTest but this time it invokes the second SPI transfer from the SPI callback function. A very common error is that the callback is invoked while the SPI module is still busy which does not allow to invoke another SPI transfer from the callback.

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if the test did not finish within a specified time.
ERROR_FAIL if the device access failed and the read data did not match the expected values.
The S2PI layer error code if S2PI_TransferFrame or the SPI callback yield in any non-OK status.

◆ SpiTransferFromSpiInterruptCallback()

static status_t SpiTransferFromSpiInterruptCallback	(	status_t	status,
		void *	param
	)

static

SPI interrupt callback function for the SPI transfer from IRQ test.

The interrupt callback is invoked from the S2PI module upon finishing the SPI transfer. The callback is used by the SpiTransferFromSpiInterrupt test to trigger the second SPI transfer from the interrupt callback context.

Note: The callback also utilizes the print functionality. This requires a correct implementation of the corresponding function such that it can be invoked from the given interrupt context. This usually requires the underlying send (e.g. UART or USB send functions) to have higher priority that this interrupt in order to finished the print statement asynchronously.

Parameters

status	The S2PI module status passed to the callback.
param	The abstract interrupt callback parameter.

Returns

Returns the status:

STATUS_OK on success.
ERROR_INVALID_ARGUMENT if the param is NULL.
The S2PI layer error code if any is passed to the callback function.
The S2PI layer error code if S2PI_TransferFrame return any.

◆ SpiTransferInterruptCallback()

static status_t SpiTransferInterruptCallback	(	status_t	status,
		void *	param
	)

static

SPI interrupt callback function for the SPI transfer interrupt test.

The interrupt callback is invoked from the S2PI module upon finishing the SPI transfer. The callback is used by the SPITransferSync helper function to retrieve the status of the SPI transfer.

Parameters

status	The S2PI module status passed to the callback.
param	The abstract interrupt callback parameter.

Returns: Returns STATUS_OK.

◆ SPITransferSync()

static status_t SPITransferSync	(	s2pi_slave_t	slave,
		uint8_t *	data,
		size_t	size
	)

static

Helper function for transfer data to SPI in blocking mode.

Calls the S2PI_TransferFrame function and waits until the transfer has been finished by checking the S2PI_GetStatus return code to become STATUS_IDLE (or STATUS_OK).

Warning: The test utilizes already the timer HAL in order to implement a rudimentary timeout. However, at this time, only some basic plausibility checks are performed on the timer HAL. I.e. if there is an issue in the time HAL, e.g. too fast or too slow time counting, the test may fail with an ERROR_TIMEOUT. In this case, one also needs to verify the timer HAL, especially the Timer_GetCounterValue function.

Parameters

slave	The S2PI slave parameter passed to the S2PI HAL functions.
data	The data array to be transferred.
size	The size of the data array to be transferred.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if the operation did not finished within a specified time (check also timer HAL implementation).
The S2PI layer error code if S2PI_TransferFrame or S2PI_GetStatus return any negative status.

◆ TimerPlausibilityTest()

static status_t TimerPlausibilityTest ( void )

static

Plausibility Test for Timer HAL Implementation.

Rudimentary tests the lifetime counter (LTC) implementation. This verifies that the LTC is running by checking if the returned values of two consecutive calls to the Timer_GetCounterValue function are ascending. An artificial delay using the NOP operation is induced such that the timer is not read to fast.

Warning: If using an ultra-fast processor with a rather low timer granularity, the test may fail! In this case, it could help to increase the delay by increasing the for-loop exit criteria.; This test does not test yet verify if the timing is correct at all! This it done in later test...

Returns

Returns the status:

STATUS_OK on success.
ERROR_FAIL on failure (check the error log for more information).

◆ TimerTest()

static status_t TimerTest ( s2pi_slave_t slave )

static

Test for Timer HAL Implementation by comparing timings to the device.

The test verifies the timer HAL implementation by comparing the timings to the AFBR-S50 device as a reference. Therefore several measurement are executed on the device, each with a different averaging sample count. The elapsed time increases linearly with the number of averaging samples. In order to remove the time for software/setup, a linear regression fit is applied to the measurement results and only the slope is considered for the result. A delta of 102.4 microseconds per sample is expected. If the measured delta per sample is within an specified error range, the timer implementation is considered correct.

Parameters

slave The S2PI slave parameter passed to the S2PI HAL functions.

Returns

Returns the status:

STATUS_OK on success.
ERROR_FAIL if the timer test fails.
STATUS_ARGUS_EEPROM_BIT_ERROR if the EEPROM Hamming weight fails.
ERROR_ARGUS_UNKNOWN_MODULE if the EEPROM module number is invalid.
ERROR_TIMEOUT if either the SPI operation did not finished or the IRQ was not detected within a specified time (check also timer HAL implementation).
The S2PI layer error code if S2PI_TransferFrame, S2PI_GetStatus, S2PI_SetIrqCallback, S2PI_CaptureGpioControl, S2PI_ReleaseGpioControl, S2PI_WriteGpioPin or S2PI_ReadGpioPin return any negative status.

◆ TimerWraparoundTest()

static status_t TimerWraparoundTest ( void )

static

Wraparound Test for the Timer HAL Implementation.

The LTC values must wrap from 999999 µs to 0 µs and increase the seconds counter accordingly. This test verifies the correct wrapping by consecutively calling the Timer_GetCounterValue function until at least 2 wraparound events have been occurred.

Note: This test requires the timer to basically run and return ascending values. Also, if the timer is too slow, this may take very long! Usually, the test takes 2 seconds, since 2 wraparound events are verified.

Warning: This test does not test yet verify if the timing is correct at all! This it done in later test...

Returns

Returns the status:

STATUS_OK on success.
ERROR_FAIL on failure (check the error log for more information).

◆ TriggerMeasurement()

static status_t TriggerMeasurement	(	s2pi_slave_t	slave,
		uint16_t	samples,
		s2pi_callback_t	callback,
		void *	callbackData
	)

static

Triggers a measurement on the device with specified sample count.

The function triggers a measurement cycle on the device. A sample count can be specified to setup individual number of digital averaging.

The measurement in triggered asynchronously without waiting for any event to finish.

Warning: The test utilizes already the timer HAL in order to implement a rudimentary timeout. However, at this time, only some basic plausibility checks are performed on the timer HAL. I.e. if there is an issue in the time HAL, e.g. too fast or too slow time counting, the test may fail with an ERROR_TIMEOUT. In this case, one also needs to verify the timer HAL, especially the Timer_GetCounterValue function.

Parameters

slave	The S2PI slave parameter passed to the S2PI HAL functions.
samples	The specified number of averaging samples for the measurement.
callback	An optional SPI callback.
callbackData	The optional callback data parameter.

Returns

Returns the status:

STATUS_OK on success.
ERROR_TIMEOUT if the operation did not finished within a specified time (check also timer HAL implementation).
The S2PI layer error code if S2PI_TransferFrame or S2PI_GetStatus return any negative status.

◆ VerifyHALImplementation()

static status_t VerifyHALImplementation ( s2pi_slave_t spi_slave )

static

Executes a series of tests in order to verify the HAL implementation.

See Argus_VerifyHALImplementation for details.

Parameters

spi_slave The SPI hardware slave.

Returns: Returns the status (STATUS_OK on success).

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ error_log

◆ HAL_TEST_VERSION

Function Documentation

◆ Argus_VerifyHALImplementation()

◆ CheckTimerCounterValues()

◆ ConfigureDevice()

◆ GPIO_Callback()

◆ GPIO_SPI_Callback()

◆ GpioInterruptTest()

◆ GpioModeTest()

◆ MeasurementCallback()

◆ PIT_Callback()

◆ PITTest()

◆ ReadEEPROM()

◆ ReadRcoTrim()

◆ RunMeasurement()

◆ RunPITTest()

◆ SpiConnectionTest()

◆ SpiMaxLengthTest()

◆ SpiTransferFromGpioInterrupt()

◆ SpiTransferFromGpioInterruptCallback()

◆ SpiTransferFromInterruptTest()

◆ SpiTransferFromPitInterrupt()

◆ SpiTransferFromPitInterruptCallback()

◆ SpiTransferFromSpiInterrupt()

◆ SpiTransferFromSpiInterruptCallback()

◆ SpiTransferInterruptCallback()

◆ SPITransferSync()

◆ TimerPlausibilityTest()

◆ TimerTest()

◆ TimerWraparoundTest()

◆ TriggerMeasurement()

◆ VerifyHALImplementation()