ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs: Watchdog: Update code comments 

* capitalize driver class name,
* reword test docs for the driver & HAL,
* capitalize Mbed name,
* reword the comments explaining the SERIAL_FLUSH_TIME_MS macro.
pull/10657/head
Filip Jagodzinski 2018-11-27 10:50:54 +01:00
parent ad295e64ba
commit 16863bb972
13 changed files with 200 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
TESTS/mbed_drivers/reset_reason/ResetReason_tests.h
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*

101
TESTS/mbed_drivers/watchdog/Watchdog_tests.h
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -25,79 +25,84 @@
#if DEVICE_WATCHDOG
/** Test max_timeout is valid
/** Test Watchdog max_timeout validity
*
* Given a device supporting Watchdog driver API
* When @a Watchdog::max_timeout() is called
* Then the returned value is greater than 1
* Given a device supporting Watchdog driver API,
* when @a Watchdog::max_timeout() is called,
* then the returned value is greater than 1.
*/
void test_max_timeout_is_valid();
/** Test watchdog can be stopped
/** Test Watchdog stop
*
* Given a platform with a support for disabling a running watchdog
* When watchdog is not running and @a Watchdog::stop() is called
* Then WATCHDOG_STATUS_OK is returned
* When watchdog is running
* and @a Watchdog::stop() is called before timeout
* Then WATCHDOG_STATUS_OK is returned
* and watchdog does not reset the device
* When watchdog has already been stopped and @a Watchdog::stop() is called
* Then WATCHDOG_STATUS_OK is returned
* Given the Watchdog is *NOT* running,
* when @a Watchdog::stop() is called,
* then WATCHDOG_STATUS_OK is returned.
*
* Given the Watchdog is running,
* when @a Watchdog::stop() is called before the timeout expires,
* then WATCHDOG_STATUS_OK is returned and the device is not restarted.
*
* Given the Watchdog is *NOT* running (it has already been stopped),
* when @a Watchdog::stop() is called,
* then WATCHDOG_STATUS_OK is returned.
*/
void test_stop();
/** Test restart watchdog multiple times
/** Test Watchdog start multiple times
*
* Given @a max_timeout value returned by @a Watchdog::max_timeout()
* and @a Watchdog::start() called multiple times
* When @a timeout is set to max_timeout - delta
* Then return value of @a Watchdog::start() is @a WATCHDOG_STATUS_OK
* and @a Watchdog::reload_value() returns max_timeout - delta
* When @a timeout is set to max_timeout
* Then return value of @a Watchdog::start() is @a WATCHDOG_STATUS_OK
* and @a Watchdog::reload_value() returns max_timeout
* When @a timeout is set to max_timeout + delta
* Then return value of @a Watchdog::start() is @a WATCHDOG_STATUS_INVALID_ARGUMENT
* and @a Watchdog::reload_value() returns previously set value (max_timeout)
* When @a timeout is set to 0
* Then return value of @a Watchdog::start() is @a WATCHDOG_STATUS_INVALID_ARGUMENT
* and @a Watchdog::reload_value() returns previously set value (max_timeout)
* Given @a max_timeout value returned by @a Watchdog::max_timeout(),
*
* when @a Watchdog::start(max_timeout - delta) is called,
* then @a WATCHDOG_STATUS_OK is returned
* and @a Watchdog::reload_value() returns max_timeout - delta;
*
* when @a Watchdog::start(max_timeout) is called,
* then @a WATCHDOG_STATUS_OK is returned
* and @a Watchdog::reload_value() returns max_timeout;
*
* when @a Watchdog::start(max_timeout + delta) is called,
* then @a WATCHDOG_STATUS_INVALID_ARGUMENT is returned
* and @a Watchdog::reload_value() returns previously set value (max_timeout);
*
* when @a Watchdog::start(0) is called,
* then @a WATCHDOG_STATUS_INVALID_ARGUMENT is returned
* and @a Watchdog::reload_value() returns previously set value (max_timeout).
*/
void test_restart();
/** Test start with 0 ms
/** Test Watchdog start with 0 ms timeout
*
* Given a device supporting Watchdog driver API
* When @a timeout is set to 0 ms
* Then return value of Watchdog::start() is @a WATCHDOG_STATUS_INVALID_ARGUMENT
* Given a device supporting Watchdog driver API,
* when @a Watchdog::start() is called with @a timeout set to 0 ms,
* then @a WATCHDOG_STATUS_INVALID_ARGUMENT is returned.
*/
void test_start_zero();
/** Test start with a valid config
/** Test Watchdog start
*
* Given a device supporting Watchdog driver API
* When @a timeout is set to value X within platform's timeout range
* Then return value of Watchdog::start() is @a WATCHDOG_STATUS_OK
* and @a Watchdog::reload_value() returns X
* Given a value of X ms which is within supported Watchdog timeout range,
* when @a Watchdog::start() is called with @a timeout set to X ms,
* then @a WATCHDOG_STATUS_OK is returned
* and @a Watchdog::reload_value() returns X.
*/
template<uint32_t timeout_ms>
void test_start();
/** Test start with a max_timeout
/** Test Watchdog start with max_timeout
*
* Given @a max_timeout value returned by @a Watchdog::max_timeout()
* When @a timeout is set to max_timeout
* Then return value of Watchdog::start() is @a WATCHDOG_STATUS_OK
* and @a Watchdog::reload_value() returns max_timeout
* Given @a max_timeout value returned by @a Watchdog::max_timeout(),
* when @a Watchdog::start() is called with @a timeout set to max_timeout,
* then @a WATCHDOG_STATUS_OK is returned
* and @a Watchdog::reload_value() returns max_timeout.
*/
void test_start_max_timeout();
/** Test start with a timeout value exceeding max_timeout
/** Test Watchdog start with a timeout value greater than max_timeout
*
* Given a device supporting Watchdog driver API
* When @a timeout is set to max_timeout + 1
* Then return value of Watchdog::start() is @a WATCHDOG_STATUS_INVALID_ARGUMENT
* Given @a max_timeout value returned by @a Watchdog::max_timeout(),
* when @a Watchdog::start() is called with @a timeout set to max_timeout + 1,
* then @a WATCHDOG_STATUS_INVALID_ARGUMENT is retuned.
*/
void test_start_max_timeout_exceeded();

2
TESTS/mbed_drivers/watchdog/main.cpp
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*

51
TESTS/mbed_drivers/watchdog_reset/Watchdog_reset_tests.h
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -25,48 +25,47 @@
#if DEVICE_WATCHDOG
/** Test watchdog reset
/** Test Watchdog reset
*
* Given a device with a watchdog started
* When a watchdog timeout expires
* Then the device is restarted
* Given a device with a Watchdog started,
* when the Watchdog timeout expires,
* then the device is restarted.
*/
void test_simple_reset();
/** Test watchdog reset in sleep mode
/** Test Watchdog reset in sleep mode
*
* Given a device supporting sleep mode, with a watchdog started
* When the device is in sleep mode and watchdog timeout expires
* Then the device is restarted
* Given a device with a Watchdog started,
* when the Watchdog timeout expires while the device is in sleep mode,
* then the device is restarted.
*/
void test_sleep_reset();
/** Test watchdog reset in deepsleep mode
/** Test Watchdog reset in deepsleep mode
*
* Given a device supporting deepsleep mode, with watchdog started
* When the device is in deepsleep mode and watchdog timeout expires
* Then the device is restarted
* Given a device with a Watchdog started,
* when the Watchdog timeout expires while the device is in deepsleep mode,
* then the device is restarted.
*/
void test_deepsleep_reset();
/** Test stopped watchdog can be started again and reset the device
/** Test Watchdog reset after Watchdog restart
*
* Given a device supporting 'disable_watchdog' feature, with watchdog started
* When the watchdog is stopped before timeout expires
* Then the device is not restarted
* When the watchdog is started again and it's timeout expires
* Then the device is restarted
* Given a device with a Watchdog started,
* when the Watchdog is stopped before its timeout expires,
* then the device is not restarted.
* When the Watchdog is started again and its timeout expires,
* then the device is restarted.
*/
void test_restart_reset();
/** Test kicking the watchdog prevents reset
*
* Given a device with watchdog started
* When the watchdog is kicked before timeout expires
* Then the device restart is prevented
* When the watchdog is *NOT* kicked again before next timeout expires
* Then the device is restarted
/** Test Watchdog kick
*
* Given a device with a Watchdog started,
* when the Watchdog is kicked before its timeout expires,
* then the device restart is prevented.
* When the Watchdog is *NOT* kicked again before next timeout expires,
* then the device is restarted.
*/
void test_kick_reset();

2
TESTS/mbed_drivers/watchdog_reset/main.cpp
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*

21
TESTS/mbed_hal/reset_reason/main.cpp
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -50,19 +50,18 @@
#define MSG_KEY_RESET_REASON "reason"
#define MSG_KEY_DEVICE_RESET "reset"
/* Flush serial buffer before deep sleep/reset
/* To prevent a loss of Greentea data, the serial buffers have to be flushed
* before the UART peripheral shutdown. The UART shutdown happens when the
* device is entering the deepsleep mode or performing a reset.
*
* Since deepsleep()/reset would shut down the UART peripheral, we wait for some time
* to allow for hardware serial buffers to completely flush.
* With the current API, it is not possible to check if the hardware buffers
* are empty. However, it is possible to determine the time required for the
* buffers to flush.
*
* Take NUMAKER_PFM_NUC472 as an example:
* Its UART peripheral has 16-byte Tx FIFO. With baud rate set to 9600, flush
* Tx FIFO would take: 16 * 8 * 1000 / 9600 = 13.3 (ms). So set wait time to
* 20ms here for safe.
*
* This should be replaced with a better function that checks if the
* hardware buffers are empty. However, such an API does not exist now,
* so we'll use the wait_ms() function for now.
* The UART peripheral has 16-byte Tx FIFO. With a baud rate set to 9600,
* flushing the Tx FIFO would take: 16 * 8 * 1000 / 9600 = 13.3 ms.
* To be on the safe side, set the wait time to 20 ms.
*/
#define SERIAL_FLUSH_TIME_MS 20

8
TESTS/mbed_hal/reset_reason/reset_reason_api_tests.h
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -31,9 +31,9 @@ extern "C" {
/** Test the Reset Reason HAL API
*
* Given a device supporting a Reset Reason API
* When the device is restarted using various methods
* Then the device returns a correct reset reason for every restart
* Given a device supporting a Reset Reason API,
* when the device is restarted,
* then the device returns a correct reset reason for every restart.
*/
void test_reset_reason();

21
TESTS/mbed_hal/watchdog/main.cpp
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -45,19 +45,18 @@
#define MSG_KEY_START_CASE "start_case"
#define MSG_KEY_DEVICE_RESET "reset_on_case_teardown"
/* Flush serial buffer before deep sleep/reset
/* To prevent a loss of Greentea data, the serial buffers have to be flushed
* before the UART peripheral shutdown. The UART shutdown happens when the
* device is entering the deepsleep mode or performing a reset.
*
* Since deepsleep()/reset would shut down the UART peripheral, we wait for some time
* to allow for hardware serial buffers to completely flush.
* With the current API, it is not possible to check if the hardware buffers
* are empty. However, it is possible to determine the time required for the
* buffers to flush.
*
* Take NUMAKER_PFM_NUC472 as an example:
* Its UART peripheral has 16-byte Tx FIFO. With baud rate set to 9600, flush
* Tx FIFO would take: 16 * 8 * 1000 / 9600 = 13.3 (ms). So set wait time to
* 20ms here for safe.
*
* This should be replaced with a better function that checks if the
* hardware buffers are empty. However, such an API does not exist now,
* so we'll use the wait_ms() function for now.
* The UART peripheral has 16-byte Tx FIFO. With a baud rate set to 9600,
* flushing the Tx FIFO would take: 16 * 8 * 1000 / 9600 = 13.3 ms.
* To be on the safe side, set the wait time to 20 ms.
*/
#define SERIAL_FLUSH_TIME_MS 20

99
TESTS/mbed_hal/watchdog/watchdog_api_tests.h
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -25,72 +25,83 @@
#if DEVICE_WATCHDOG
/** Test max_timeout is valid
/** Test max_timeout validity
*
* Given a device supporting watchdog HAL API
* When @a hal_watchdog_get_platform_features() is called
* Then max_timeout member of returned watchdog_features_t struct is greater than 1
* Given a device supporting watchdog HAL API,
* when @a hal_watchdog_get_platform_features() is called,
* then max_timeout member of returned watchdog_features_t struct is greater than 1.
*/
void test_max_timeout_is_valid();
/** Test stopped watchdog can be started again
/** Test watchdog features if a stopped watchdog can be started again
*
* Given a device supporting watchdog HAL API
* When the device supports the @a disable_watchdog feature
* Then the device also supports @a update_config feature
* Given a device supporting watchdog HAL API,
* when the device supports the @a disable_watchdog feature,
* then the device also supports @a update_config feature.
*/
void test_restart_is_possible();
/** Test watchdog can be stopped
/** Test watchdog stop
*
* Given a device without a support for the @a disable_watchdog feature
* When @a hal_watchdog_stop() is called
* Then WATCHDOG_STATUS_NOT_SUPPORTED is returned
* Given a device without a support for the @a disable_watchdog feature,
* when @a hal_watchdog_stop() is called,
* then WATCHDOG_STATUS_NOT_SUPPORTED is returned.
*
* Given a device supporting @a disable_watchdog feature
* When watchdog is not running and @a hal_watchdog_stop() is called
* Then WATCHDOG_STATUS_OK is returned
* When watchdog is running
* and @a hal_watchdog_stop() is called before timeout
* Then WATCHDOG_STATUS_OK is returned
* and watchdog does not reset the device
* When watchdog has already been stopped and @a hal_watchdog_stop() is called
* Then WATCHDOG_STATUS_OK is returned
* Otherwise, given the device with @a disable_watchdog feature support:
*
* Given the watchdog is *NOT* running,
* when @a hal_watchdog_stop() is called,
* then WATCHDOG_STATUS_OK is returned.
*
* Given the watchdog is running,
* when @a hal_watchdog_stop() is called before the timeout expires,
* then WATCHDOG_STATUS_OK is returned and the device is not restarted.
*
* Given the watchdog is *NOT* running (it has already been stopped),
* when @a hal_watchdog_stop() is called,
* then WATCHDOG_STATUS_OK is returned.
*/
void test_stop();
/** Test update config with multiple init calls
/** Test watchdog init multiple times
*
* Given @a max_timeout value returned by @a hal_watchdog_get_platform_features()
* and @a hal_watchdog_init() called multiple times with same @a config
* When @a config.timeout_ms is set to WDG_CONFIG_DEFAULT
* Then return value of hal_watchdog_init() is @a WATCHDOG_STATUS_OK
* and @a hal_watchdog_get_reload_value() returns WDG_CONFIG_DEFAULT
* When @a config.timeout_ms is set to max_timeout-delta
* Then return value of hal_watchdog_init() is @a WATCHDOG_STATUS_OK
* and @a hal_watchdog_get_reload_value() returns max_timeout-delta
* When @a config.timeout_ms is set to max_timeout
* Then return value of hal_watchdog_init() is @a WATCHDOG_STATUS_OK
* and @a hal_watchdog_get_reload_value() returns max_timeout
* Given @a max_timeout value returned by @a hal_watchdog_get_platform_features():
*
* Given @a config.timeout_ms is set to WDG_TIMEOUT_MS,
* when @a hal_watchdog_init() is called,
* then @a WATCHDOG_STATUS_OK is returned
* and @a hal_watchdog_get_reload_value() returns WDG_TIMEOUT_MS.
*
* Given @a config.timeout_ms is set to max_timeout-delta,
* when @a hal_watchdog_init() is called,
* then @a WATCHDOG_STATUS_OK is returned
* and @a hal_watchdog_get_reload_value() returns max_timeout-delta.
*
* Given @a config.timeout_ms is set to max_timeout,
* when @a hal_watchdog_init() is called,
* then @a WATCHDOG_STATUS_OK is returned
* and @a hal_watchdog_get_reload_value() returns max_timeout.
*/
void test_update_config();
/** Test init with a valid config
/** Test watchdog init with a valid config
*
* Given a device supporting watchdog HAL API
* When @a config.timeout_ms is set to value X within platform's timeout range
* Then return value of hal_watchdog_init() is @a WATCHDOG_STATUS_OK
* and @a hal_watchdog_get_reload_value() returns X
* Given @a config.timeout_ms is set to X ms,
* which is within supported watchdog timeout range,
* when @a hal_watchdog_init() is called,
* then @a WATCHDOG_STATUS_OK is returned
* and @a hal_watchdog_get_reload_value() returns X.
*/
template<uint32_t timeout_ms>
void test_init();
/** Test init with a max_timeout
/** Test watchdog init with a max_timeout
*
* Given @a max_timeout value returned by @a hal_watchdog_get_platform_features()
* When @a config.timeout_ms is set to max_timeout
* Then return value of hal_watchdog_init() is @a WATCHDOG_STATUS_OK
* and @a hal_watchdog_get_reload_value() returns max_timeout
* Given @a config.timeout_ms is set to max_timeout,
* which is a value returned by @a hal_watchdog_get_platform_features(),
* when @a hal_watchdog_init() is called,
* then @a WATCHDOG_STATUS_OK is returned
* and @a hal_watchdog_get_reload_value() returns max_timeout.
*/
void test_init_max_timeout();

21
TESTS/mbed_hal/watchdog_reset/main.cpp
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -45,19 +45,18 @@
#define MSG_KEY_START_CASE "start_case"
#define MSG_KEY_DEVICE_RESET "dev_reset"
/* Flush serial buffer before deep sleep/reset
/* To prevent a loss of Greentea data, the serial buffers have to be flushed
* before the UART peripheral shutdown. The UART shutdown happens when the
* device is entering the deepsleep mode or performing a reset.
*
* Since deepsleep()/reset would shut down the UART peripheral, we wait for some time
* to allow for hardware serial buffers to completely flush.
* With the current API, it is not possible to check if the hardware buffers
* are empty. However, it is possible to determine the time required for the
* buffers to flush.
*
* Take NUMAKER_PFM_NUC472 as an example:
* Its UART peripheral has 16-byte Tx FIFO. With baud rate set to 9600, flush
* Tx FIFO would take: 16 * 8 * 1000 / 9600 = 13.3 (ms). So set wait time to
* 20ms here for safe.
*
* This should be replaced with a better function that checks if the
* hardware buffers are empty. However, such an API does not exist now,
* so we'll use the wait_ms() function for now.
* The UART peripheral has 16-byte Tx FIFO. With a baud rate set to 9600,
* flushing the Tx FIFO would take: 16 * 8 * 1000 / 9600 = 13.3 ms.
* To be on the safe side, set the wait time to 20 ms.
*/
#define SERIAL_FLUSH_TIME_MS 20

45
TESTS/mbed_hal/watchdog_reset/watchdog_reset_tests.h
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -27,46 +27,45 @@
/** Test watchdog reset
*
* Given a device with a watchdog started
* When a watchdog timeout expires
* Then the device is restarted
* Given a device with a watchdog started,
* when a watchdog timeout expires,
* then the device is restarted.
*/
void test_simple_reset();
/** Test watchdog reset in sleep mode
*
* Given a device supporting sleep mode, with a watchdog started
* When the device is in sleep mode and watchdog timeout expires
* Then the device is restarted
* Given a device with a watchdog started,
* when the watchdog timeout expires while the device is in sleep mode,
* then the device is restarted.
*/
void test_sleep_reset();
/** Test watchdog reset in deepsleep mode
*
* Given a device supporting deepsleep mode, with watchdog started
* When the device is in deepsleep mode and watchdog timeout expires
* Then the device is restarted
* Given a device with a watchdog started,
* when the watchdog timeout expires while the device is in deepsleep mode,
* then the device is restarted.
*/
void test_deepsleep_reset();
/** Test stopped watchdog can be started again and reset the device
/** Test watchdog reset after watchdog restart
*
* Given a device supporting 'disable_watchdog' feature, with watchdog started
* When the watchdog is stopped before timeout expires
* Then the device is not restarted
* When the watchdog is started again and it's timeout expires
* Then the device is restarted
* Given a device with a watchdog started,
* when the watchdog is stopped before its timeout expires,
* then the device is not restarted.
* When the watchdog is started again and its timeout expires,
* then the device is restarted.
*/
void test_restart_reset();
/** Test kicking the watchdog prevents reset
*
* Given a device with watchdog started
* When the watchdog is kicked before timeout expires
* Then the device restart is prevented
* When the watchdog is *NOT* kicked again before next timeout expires
* Then the device is restarted
/** Test watchdog kick
*
* Given a device with a watchdog started,
* when the watchdog is kicked before its timeout expires,
* then the device restart is prevented.
* When the watchdog is *NOT* kicked again before next timeout expires,
* then the device is restarted.
*/
void test_kick_reset();

2
TESTS/mbed_hal/watchdog_timing/main.cpp
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*

14
TESTS/mbed_hal/watchdog_timing/watchdog_timing_tests.h
View File

@ -1,4 +1,4 @@
/* mbed Microcontroller Library
/* Mbed Microcontroller Library
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
@ -28,14 +28,14 @@
/** Test watchdog timing accuracy
*
* Phase 1.
* Given a watchdog timer started with a timeout value of X ms
* When given time of X ms elapses
* Then the device is restarted by the watchdog
* Given a watchdog timer started with a timeout value of X ms,
* when the time of X ms elapses,
* then the device is restarted by the watchdog.
*
* Phase 2.
* Given a device restarted by the watchdog timer
* When the device receives time measurement from the host
* Then time measured by host equals X ms
* Given a device restarted by the watchdog timer,
* when the device receives time measurement from the host,
* then time measured by host equals X ms.
*/
template<uint32_t timeout_ms, uint32_t delta_ms>
void test_timing();