LowPowerTickerWrapper.h

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