diff options
Diffstat (limited to 'libmaple/timers.h')
| -rw-r--r-- | libmaple/timers.h | 224 |
1 files changed, 206 insertions, 18 deletions
diff --git a/libmaple/timers.h b/libmaple/timers.h index 1d929db..7589283 100644 --- a/libmaple/timers.h +++ b/libmaple/timers.h @@ -144,7 +144,7 @@ typedef enum TimerMode { TIMER_PWM, /**< This is the default mode for pins after initialization. */ TIMER_OUTPUTCOMPARE, /**< In this mode, the timer counts from 0 to - the overflow value repeatedly; every time + its reload value repeatedly; every time the counter value reaches one of the channel compare values, the corresponding interrupt is fired. */ @@ -225,51 +225,239 @@ struct timer_dev { extern struct timer_dev timer_dev_table[]; -/* Turn on timer with prescale as the divisor - * void timer_init(uint32 timer, uint16 prescale) - * timer -> {1-4} - * prescale -> {1-65535} +/** + * Initializes timer with prescale as the clock divisor. + * + * @param timer Timer number. Valid values are TIMER1, TIMER2, + * TIMER3, TIMER4, and (on high-density devices) TIMER5, TIMER8. + * + * @param prescale value in the range 1--65535 to use as a prescaler + * for timer counter increment frequency. + * + * @see timer_set_prescaler() + * @see timer_set_mode() */ void timer_init(timer_dev_num, uint16); + +/** + * Quickly disable all timers. Calling this function is faster than, + * e.g., calling timer_set_mode() for all available timers/channels. + */ void timer_disable_all(void); +/** + * Returns the timer's counter value. Due to function call overhead, + * this value is likely to be inaccurate if the counter is running + * with a low prescaler. + * + * @param timer the timer whose counter to return. + * + * @pre Timer has been initialized. + */ uint16 timer_get_count(timer_dev_num); + +/** + * Sets the counter value for the given timer. + * + * @param timer the timer whose counter to set. + * + * @param value the new counter value. + * + * @pre Timer has been initialized. + */ void timer_set_count(timer_dev_num,uint16); +/** + * Stops the timer's counter from incrementing. Does not modify the + * timer's mode or settings. + * + * @param timer the timer to pause. + * + * @see timer_resume() + * + * @pre Timer has been initialized. + */ void timer_pause(timer_dev_num); + +/** + * Starts the counter for the given timer. Does not modify the + * timer's mode or settings. The timer will begin counting on the + * first rising clock cycle after it has been re-enabled using this + * function. + * + * @param timer the timer to resume. + * + * @see timer_pause() + * + * @pre Timer has been initialized. + */ void timer_resume(timer_dev_num); +/** + * Returns the prescaler for the given timer. + * + * @see timer_set_prescaler() + * + * @pre Timer has been initialized. + */ uint16 timer_get_prescaler(timer_dev_num timer_num); + +/** + * Sets the prescaler for the given timer. This value goes into the + * PSC register, so it's 0-based (i.e., a prescale of 0 counts 1 tick + * per clock cycle). This prescale does not take effect until the + * next update event. + * + * @param timer the timer whose prescaler to set. + * + * @param prescale the new prescaler. + * + * @pre Timer has been initialized. + */ void timer_set_prescaler(timer_dev_num timer_num, uint16 prescale); +/** + * Gets the reload value for the timer. + * + * @see timer_set_reload() + * + * @pre Timer has been initialized. + */ uint16 timer_get_reload(timer_dev_num timer_num); + +/** + * Sets the reload value for the timer. + * + * After this function returns, the timer's counter will reset to 0 + * after it has reached the value max_reload. + * + * @param timer the timer whose reload to set. + * + * @param max_reload the new reload value. + * + * @pre Timer has been initialized. + */ void timer_set_reload(timer_dev_num timer_num, uint16 max_reload); /* TODO: timer_get_mode */ + +/** + * Set the mode of an individual timer channel. + * + * @param timer the timer whose channel mode to set. + * + * @param channel the channel whose mode to set (1 <= channel <= 4). + * + * @param mode the new mode value. Currently acceptable values + * include TIMER_DISABLED, TIMER_PWM, and TIMER_OUTPUTCOMPARE. Note + * that timer_disable_all() will disable all timers and all channels + * much more quickly than repeated calls to this function with mode + * TIMER_DISABLED. + * + * @see TimerMode + * + * @see timer_disable_all() + * + * @pre Timer has been initialized. + */ void timer_set_mode(timer_dev_num timer_num, uint8 channel_num, uint8 mode); +/** + * Get the compare value for the given timer channel. + * @see timer_set_compare_value() + * + * @pre Timer has been initialized. + */ uint16 timer_get_compare_value(timer_dev_num timer_num, uint8 channel_num); -void timer_set_compare_value(timer_dev_num timer_num, uint8 channel_num, uint16 value); +/** + * Sets the compare value for a given timer channel. Useful for + * scheduling when interrupt handlers will be called. + * + * @param timer the timer whose channel compare to set. + * + * @param channel the channel whose compare to set (1 <= channel <= 4). + * + * @param compare the new compare value. This new value must be less + * than or equal to the timer's reload value. + * + * @see timer_attach_interrupt() + * + * @see timer_detach_interrupt() + * + * @see timer_set_reload() + * + * @pre Timer has been initialized. + */ +void timer_set_compare_value(timer_dev_num timer_num, uint8 channel_num, + uint16 value); + +/** + * Detach the interrupt handler for the given timer channel, if any. + * After this function returns, any handler attached to the given + * channel will no longer be called. + * + * @param timer the timer whose channel to detach the interrupt + * handler from. + * + * @param channel the channel from which to detach the interrupt handler. + * + * @see timer_attach_interrupt() + * + * @pre Timer has been initialized. + */ +void timer_detach_interrupt(timer_dev_num timer_num, uint8 channel_num); + +/** + * Attach an interrupt handler for the given timer and channel. The + * handler will be called whenever the timer's counter reaches the + * compare value for the given timer and channel. + * + * @param timer the timer whose channel to register with an interrupt handler. + * + * @param channel the channel with which the new handler will be + * associated. timer_set_compare_value() can be used to set the value + * which the timer's counter must reach before handler is called (1 <= + * channel <= 4). + * + * @param handler the interrupt handler to call once the timer reaches + * the given channel's compare value. + * + * @pre The channel's mode must be set to TIMER_OUTPUTCOMPARE, or the + * interrupt handler will not get called. + * + * @see timer_set_compare_value() + * + * @see timer_detach_interrupt() + * + * @see timer_set_mode() + * + * @pre Timer has been initialized. + */ void timer_attach_interrupt(timer_dev_num timer_num, uint8 channel_num, voidFuncPtr handler); -void timer_detach_interrupt(timer_dev_num timer_num, uint8 channel_num); -/* generate UEV */ +/** + * Programmatically generate an update event on the given timer. This + * updates the prescaler, reloads the compare value (in upcounting + * mode, etc.). + * + * @pre Timer has been initialized. + */ void timer_generate_update(timer_dev_num timer_num); -/* Turn on PWM with duty_cycle on the specified channel in timer. - * This function takes in a pointer to the corresponding CCR - * register for the pin cause it saves pwmWrite() a couple of - * cycles. +/** + * Turn on PWM with duty_cycle. + * + * @param channel TIMERx_CHn_CCR, where x goes from 1 to NR_TIMERS, + * and n goes from 1 to 4. + * + * @param duty_cycle 0--65535. duty_cycle=0 means always off; + * duty_cycle=65535 means always on. * - * void timer_pwm(uint8 channel, uint8 duty_cycle); - * channel -> {TIMERx_CHn_CCR} - * duty_cycle -> {0-65535} + * @pre Pin has been set to alternate function output. * - * PRECONDITIONS: - * pin has been set to alternate function output - * timer has been initialized + * @pre Timer has been initialized. */ static inline void timer_pwm_write_ccr(TimerCCR CCR, uint16 duty_cycle) { *CCR = duty_cycle; |