Very confusing and wrong description for the watchdog_reboot/watchdog_enable #1505

New issue

Closed

opened 2023-09-11 09:32:34 -05:00 by nicolas-Philips · 3 comments

nicolas-Philips commented

2023-09-11 09:32:34 -05:00

(Migrated from github.com)

The documentation of the watchdog_reboot function is as follows: pico sdk online docs

Or in the source code:

/*! \brief Define actions to perform at watchdog timeout
 *  \ingroup hardware_watchdog
 *
 * \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms
 * parameter will not be in microseconds. See the datasheet for more details.
 *
 * By default the SDK assumes a 12MHz XOSC and sets the \ref watchdog_start_tick appropriately.
 *
 * \param pc If Zero, a standard boot will be performed, if non-zero this is the program counter to jump to on reset.
 * \param sp If \p pc is non-zero, this will be the stack pointer used.
 * \param delay_ms Initial load value. Maximum value 0x7fffff, approximately 8.3s.
 */
void watchdog_reboot(uint32_t pc, uint32_t sp, uint32_t delay_ms);

If the delay is indeed in ms, then the maximum value of 0x7fffff=8.388607e6 would be in microseconds instead of ms.
this cannot be correct.

If watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms parameter will not be in microseconds. Well I think you can see how this is confusing?

What it should probably be:

/*! \brief Define actions to perform at watchdog timeout
 *  \ingroup hardware_watchdog
 *
 * \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms
 * parameter will not be in milliseconds. See the datasheet for more details.
 * The maximum amount of ticks is 0xffffffu and the watchdog count increases every two ticks. This means that the maximum timeout 
 * will occur at 0xffffffu / 2 = 0x7fffff
 * The timeout is loaded as delay_ms * 1000 * 2
 *
 * By default the SDK assumes a 12MHz XOSC and sets the \ref watchdog_start_tick appropriately.
 *
 * \param pc If Zero, a standard boot will be performed, if non-zero this is the program counter to jump to on reset.
 * \param sp If \p pc is non-zero, this will be the stack pointer used.
 * \param delay_ms Initial load value. Maximum value is approx 8388 ms
 */
void watchdog_reboot(uint32_t pc, uint32_t sp, uint32_t delay_ms);

The documentation of the watchdog_reboot function is as follows: [pico sdk online docs](https://cec-code-lab.aps.edu/robotics/resources/pico-c-api/group__hardware__watchdog.html#gaa73ccd43d6d755817e71bc3d7eb1fda6) Or in the source code: ``` /*! \brief Define actions to perform at watchdog timeout * \ingroup hardware_watchdog * * \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms * parameter will not be in microseconds. See the datasheet for more details. * * By default the SDK assumes a 12MHz XOSC and sets the \ref watchdog_start_tick appropriately. * * \param pc If Zero, a standard boot will be performed, if non-zero this is the program counter to jump to on reset. * \param sp If \p pc is non-zero, this will be the stack pointer used. * \param delay_ms Initial load value. Maximum value 0x7fffff, approximately 8.3s. */ void watchdog_reboot(uint32_t pc, uint32_t sp, uint32_t delay_ms); ``` If the delay is indeed in ms, then the maximum value of 0x7fffff=8.388607e6 would be in microseconds instead of ms. this cannot be correct. If watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms parameter will not be in microseconds. Well I think you can see how this is confusing? What it should probably be: ``` /*! \brief Define actions to perform at watchdog timeout * \ingroup hardware_watchdog * * \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms * parameter will not be in milliseconds. See the datasheet for more details. * The maximum amount of ticks is 0xffffffu and the watchdog count increases every two ticks. This means that the maximum timeout * will occur at 0xffffffu / 2 = 0x7fffff * The timeout is loaded as delay_ms * 1000 * 2 * * By default the SDK assumes a 12MHz XOSC and sets the \ref watchdog_start_tick appropriately. * * \param pc If Zero, a standard boot will be performed, if non-zero this is the program counter to jump to on reset. * \param sp If \p pc is non-zero, this will be the stack pointer used. * \param delay_ms Initial load value. Maximum value is approx 8388 ms */ void watchdog_reboot(uint32_t pc, uint32_t sp, uint32_t delay_ms); ```

Rows
Columns