Mistake on this page?
Report an issue in GitHub or email us

Microsecond ticker

Implementing the microsecond ticker enables Mbed OS to perform operations that require precise timing. You can use this API to schedule events, record elapsed time and perform submillisecond delays.

Assumptions

Defined behavior

  • Has a reported frequency between 250KHz and 8MHz.
  • Has a counter that is at least 16 bits wide.
  • The function ticker_init is safe to call repeatedly.
  • The function ticker_init allows the ticker to keep counting and disables the ticker interrupt.
  • Ticker frequency is nonzero, and the counter is at least 8 bits.
  • The ticker rolls over at (1 << bits) and continues counting starting from 0.
  • The ticker counts at the specified frequency plus or minus 10%.
  • The ticker increments by 1 each tick.
  • The ticker interrupt fires only when the ticker time increments to or past the value set by ticker_set_interrupt.
  • It is safe to call ticker_set_interrupt repeatedly before the handler is called.
  • The function ticker_fire_interrupt causes ticker_irq_handler to be called immediately from interrupt context.
  • The ticker operations ticker_read, ticker_clear_interrupt, ticker_set_interrupt and ticker_fire_interrupt take less than 20us to complete.

Undefined behavior

  • Calling any function other than ticker_init before the initialization of the ticker.
  • Whether ticker_irq_handler is called a second time if the time wraps and matches the value set by ticker_set_interrupt again.
  • Calling ticker_set_interrupt with a value that has more than the supported number of bits.
  • Calling any function other than us_ticker_init after calling us_ticker_free.

Notes

Be careful around these common trouble areas when implementing this API:

  • The ticker cannot drift when rescheduled repeatedly
  • The ticker keeps counting when it rolls over
  • The ticker interrupt fires when the compare value is set to 0 and overflow occurs

Dependencies

To implement this API, the device must have a hardware counter that has a count value at least 16 bits wide and can operate between 250KHz and 8MHz.

Implementing the microsecond ticker API

You can find the API and specification for the microsecond ticker API in the following header file:

To enable microsecond ticker support in Mbed OS, add the USTICKER label in the device_has option of the target's section in the targets.json file.

Testing

The Mbed OS HAL provides a set of conformance tests for the microsecond ticker. You can use these tests to validate the correctness of your implementation. To run the microsecond ticker HAL tests, use the following command:

mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker*,tests-mbed_hal-us_ticker*

You can read more about the test cases:

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.