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     void suspend();
00079 
00080     /**
00081      * Resume wrapper operation and filter interrupts normally
00082      */
00083     void resume();
00084 
00085     /**
00086      * Check if a Timeout object is being used
00087      *
00088      * @return true if Timeout is used for scheduling false otherwise
00089      */
00090     bool timeout_pending();
00091 
00092     /*
00093      * Implementation of ticker_init
00094      */
00095     void init();
00096 
00097     /*
00098      * Implementation of free
00099      */
00100     void free();
00101 
00102     /*
00103      * Implementation of read
00104      */
00105     uint32_t read();
00106 
00107     /*
00108      * Implementation of set_interrupt
00109      */
00110     void set_interrupt(timestamp_t timestamp);
00111 
00112     /*
00113      * Implementation of disable_interrupt
00114      */
00115     void disable_interrupt();
00116 
00117     /*
00118      * Implementation of clear_interrupt
00119      */
00120     void clear_interrupt();
00121 
00122     /*
00123      * Implementation of fire_interrupt
00124      */
00125     void fire_interrupt();
00126 
00127     /*
00128      * Implementation of get_info
00129      */
00130     const ticker_info_t *get_info();
00131 
00132     ticker_data_t data;
00133 
00134 private:
00135     mbed::Timeout _timeout;
00136     const ticker_interface_t *const _intf;
00137 
00138     /*
00139      * The number of low power clock cycles which must pass between subsequent
00140      * calls to intf->set_interrupt
00141      */
00142     const uint32_t _min_count_between_writes;
00143 
00144     /*
00145      * The minimum number of low power clock cycles in the future that
00146      * a match value can be set to and still fire
00147      */
00148     const uint32_t _min_count_until_match;
00149 
00150     /*
00151      * Flag to indicate if the timer is suspended
00152      */
00153     bool _suspended;
00154 
00155     /*
00156      * _cur_match_time is valid and Timeout is scheduled to fire
00157      */
00158     bool _pending_timeout;
00159 
00160     /*
00161      * set_interrupt has been called and _cur_match_time is valid
00162      */
00163     bool _pending_match;
00164 
00165     /*
00166      * The function LowPowerTickerWrapper::fire_interrupt has been called
00167      * and an interrupt is expected.
00168      */
00169     bool _pending_fire_now;
00170 
00171     /*
00172      * It is safe to call intf->set_interrupt
00173      */
00174     bool _set_interrupt_allowed;
00175 
00176     /*
00177      * Last value written by LowPowerTickerWrapper::set_interrupt
00178      */
00179     timestamp_t _cur_match_time;
00180 
00181     /*
00182      * Time of last call to LowPowerTickerWrapper::set_interrupt
00183      */
00184     uint32_t _last_set_interrupt;
00185 
00186     /*
00187      * Time of last call to intf->set_interrupt
00188      */
00189     uint32_t _last_actual_set_interrupt;
00190 
00191     /*
00192      * Mask of valid bits from intf->read()
00193      */
00194     uint32_t _mask;
00195 
00196     /*
00197      * Microsecond per low power tick (rounded up)
00198      */
00199     uint32_t _us_per_tick;
00200 
00201 
00202     void _reset();
00203 
00204     /**
00205      * Set the low power ticker match time when hardware is ready
00206      *
00207      * This event is scheduled to set the lp timer after the previous write
00208      * has taken effect and it is safe to write a new value without blocking.
00209      * If the time has already passed then this function fires and interrupt
00210      * immediately.
00211      */
00212     void _timeout_handler();
00213 
00214     /*
00215      * Check match time has passed
00216      */
00217     bool _match_check(timestamp_t current);
00218 
00219     /*
00220      * Convert low power ticks to approximate microseconds
00221      *
00222      * This value is always larger or equal to exact value.
00223      */
00224     uint32_t _lp_ticks_to_us(uint32_t);
00225 
00226     /*
00227      * Schedule a match interrupt to fire at the correct time
00228      *
00229      * @param current The current low power ticker time
00230      */
00231     void _schedule_match(timestamp_t current);
00232 
00233 };
00234 
00235 #endif
00236 
00237 /** @}*/
00238 
00239