LowPowerTickerWrapper.h

00001 
00002 /** \addtogroup hal */
00003 /** @{*/
00004 /* mbed Microcontroller Library
00005  * Copyright (c) 2018 ARM Limited
00006  *
00007  * Licensed under the Apache License, Version 2.0 (the "License");
00008  * you may not use this file except in compliance with the License.
00009  * You may obtain a copy of the License at
00010  *
00011  *     http://www.apache.org/licenses/LICENSE-2.0
00012  *
00013  * Unless required by applicable law or agreed to in writing, software
00014  * distributed under the License is distributed on an "AS IS" BASIS,
00015  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016  * See the License for the specific language governing permissions and
00017  * limitations under the License.
00018  */
00019 #ifndef MBED_LOW_POWER_TICKER_WRAPPER_H
00020 #define MBED_LOW_POWER_TICKER_WRAPPER_H
00021 
00022 #include "device.h"
00023 
00024 #include "hal/ticker_api.h"
00025 #include "hal/us_ticker_api.h"
00026 #include "drivers/Timeout.h"
00027 
00028 
00029 class LowPowerTickerWrapper {
00030 public:
00031 
00032 
00033     /**
00034      * Create a new wrapped low power ticker object
00035      *
00036      * @param data Low power ticker data to wrap
00037      * @param interface new ticker interface functions
00038      * @param min_cycles_between_writes The number of whole low power clock periods
00039      * which must complete before subsequent calls to set_interrupt
00040      * @param min_cycles_until_match The minimum number of whole low power clock periods
00041      * from the current time for which the match timestamp passed to set_interrupt is
00042      * guaranteed to fire.
00043      *
00044      *  N = min_cycles_between_writes
00045      *
00046      *       0       1             N - 1     N     N + 1   N + 2   N + 3
00047      *       |-------|------...------|-------|-------|-------|-------|
00048      *           ^                                    ^
00049      *           |                                    |
00050      *       set_interrupt                   Next set_interrupt allowed
00051      *
00052      * N = min_cycles_until_match
00053      *
00054      *      0       1             N - 1     N     N + 1   N + 2   N + 3
00055      *      |-------|------...------|-------|-------|-------|-------|
00056      *          ^                                   ^
00057      *          |                                   |
00058      *      set_interrupt              Earliest match timestamp allowed
00059      *
00060      *
00061      */
00062 
00063     LowPowerTickerWrapper(const ticker_data_t *data, const ticker_interface_t *interface, uint32_t min_cycles_between_writes, uint32_t min_cycles_until_match);
00064 
00065     /**
00066      * Interrupt handler called by the underlying driver/hardware
00067      *
00068      * @param handler The callback which would normally be called by the underlying driver/hardware
00069      */
00070     void irq_handler(ticker_irq_handler_type handler);
00071 
00072     /**
00073      * Suspend wrapper operation and pass through interrupts.
00074      *
00075      * This stops to wrapper layer from using the microsecond ticker.
00076      * This should be called before using the low power ticker APIs directly.
00077      *
00078      * @warning: Make sure to suspend the LP ticker first (call ticker_suspend()),
00079      * otherwise the behavior is undefined.
00080      */
00081     void suspend();
00082 
00083     /**
00084      * Resume wrapper operation and filter interrupts normally
00085      */
00086     void resume();
00087 
00088     /**
00089      * Check if a Timeout object is being used
00090      *
00091      * @return true if Timeout is used for scheduling false otherwise
00092      */
00093     bool timeout_pending();
00094 
00095     /*
00096      * Implementation of ticker_init
00097      */
00098     void init();
00099 
00100     /*
00101      * Implementation of free
00102      */
00103     void free();
00104 
00105     /*
00106      * Implementation of read
00107      */
00108     uint32_t read();
00109 
00110     /*
00111      * Implementation of set_interrupt
00112      */
00113     void set_interrupt(timestamp_t timestamp);
00114 
00115     /*
00116      * Implementation of disable_interrupt
00117      */
00118     void disable_interrupt();
00119 
00120     /*
00121      * Implementation of clear_interrupt
00122      */
00123     void clear_interrupt();
00124 
00125     /*
00126      * Implementation of fire_interrupt
00127      */
00128     void fire_interrupt();
00129 
00130     /*
00131      * Implementation of get_info
00132      */
00133     const ticker_info_t *get_info();
00134 
00135     ticker_data_t data;
00136 
00137 private:
00138     mbed::Timeout _timeout;
00139     const ticker_interface_t *const _intf;
00140 
00141     /*
00142      * The number of low power clock cycles which must pass between subsequent
00143      * calls to intf->set_interrupt
00144      */
00145     const uint32_t _min_count_between_writes;
00146 
00147     /*
00148      * The minimum number of low power clock cycles in the future that
00149      * a match value can be set to and still fire
00150      */
00151     const uint32_t _min_count_until_match;
00152 
00153     /*
00154      * Flag to indicate if the timer is suspended
00155      */
00156     bool _suspended;
00157 
00158     /*
00159      * _cur_match_time is valid and Timeout is scheduled to fire
00160      */
00161     bool _pending_timeout;
00162 
00163     /*
00164      * set_interrupt has been called and _cur_match_time is valid
00165      */
00166     bool _pending_match;
00167 
00168     /*
00169      * The function LowPowerTickerWrapper::fire_interrupt has been called
00170      * and an interrupt is expected.
00171      */
00172     bool _pending_fire_now;
00173 
00174     /*
00175      * It is safe to call intf->set_interrupt
00176      */
00177     bool _set_interrupt_allowed;
00178 
00179     /*
00180      * Last value written by LowPowerTickerWrapper::set_interrupt
00181      */
00182     timestamp_t _cur_match_time;
00183 
00184     /*
00185      * Time of last call to LowPowerTickerWrapper::set_interrupt
00186      */
00187     uint32_t _last_set_interrupt;
00188 
00189     /*
00190      * Time of last call to intf->set_interrupt
00191      */
00192     uint32_t _last_actual_set_interrupt;
00193 
00194     /*
00195      * Mask of valid bits from intf->read()
00196      */
00197     uint32_t _mask;
00198 
00199     /*
00200      * Microsecond per low power tick (rounded up)
00201      */
00202     uint32_t _us_per_tick;
00203 
00204 
00205     void _reset();
00206 
00207     /**
00208      * Set the low power ticker match time when hardware is ready
00209      *
00210      * This event is scheduled to set the lp timer after the previous write
00211      * has taken effect and it is safe to write a new value without blocking.
00212      * If the time has already passed then this function fires and interrupt
00213      * immediately.
00214      */
00215     void _timeout_handler();
00216 
00217     /*
00218      * Check match time has passed
00219      */
00220     bool _match_check(timestamp_t current);
00221 
00222     /*
00223      * Convert low power ticks to approximate microseconds
00224      *
00225      * This value is always larger or equal to exact value.
00226      */
00227     uint32_t _lp_ticks_to_us(uint32_t);
00228 
00229     /*
00230      * Schedule a match interrupt to fire at the correct time
00231      *
00232      * @param current The current low power ticker time
00233      */
00234     void _schedule_match(timestamp_t current);
00235 
00236 };
00237 
00238 #endif
00239 
00240 /** @}*/
00241 
00242