Changeset 374 for asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/can_api.h

r352	r374
59	59
60	60	void can_init (can_t *obj, PinName rd, PinName td);
	61	void can_init_freq(can_t *obj, PinName rd, PinName td, int hz);
61	62	void can_free (can_t *obj);
62	63	int can_frequency(can_t *obj, int hz);

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/can_helper.h

-              r352
+              r374
 #endif
+/**
+ *
+ * \enum    CANFormat
+ *
+ * \brief   Values that represent CAN Format
+**/
 enum CANFormat {
     CANStandard = 0,
 …
 typedef enum CANFormat CANFormat;
+/**
+ *
+ * \enum    CANType
+ *
+ * \brief   Values that represent CAN Type
+**/
 enum CANType {
     CANData   = 0,
 …
 typedef enum CANType CANType;
+/**
+ *
+ * \struct  CAN_Message
+ *
+ * \brief   Holder for single CAN message.
+ *
+**/
 struct CAN_Message {
     unsigned int   id;                 // 29 bit identifier
     unsigned char  data[8];            // Data field
     unsigned char  len;                // Length of data field in bytes
     CANFormat      format;             // 0 - STANDARD, 1- EXTENDED IDENTIFIER
     CANType        type;               // 0 - DATA FRAME, 1 - REMOTE FRAME
+    CANFormat      format;             // Format ::CANFormat
+    CANType        type;               // Type ::CANType
 };
 typedef struct CAN_Message CAN_Message;

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/ethernet_api.h

r352	r374
45	45	int ethernet_send(void);
46	46
47		// recieve from ethernet buffer, returning packet size, or 0 if no packet
	47	// receive from ethernet buffer, returning packet size, or 0 if no packet
48	48	int ethernet_receive(void);
49	49

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/gpio_api.h

-              r352
+              r374
 /** Init the input pin and set mode to PullDefault
+ *
  * @param obj The GPIO object
+ * @param gpio The GPIO object
  * @param pin The pin name
  */
 …
 /** Init the input pin and set the mode
+ *
  * @param obj  The GPIO object
+ * @param gpio  The GPIO object
  * @param pin  The pin name
  * @param mode The pin mode to be set
 …
 /** Init the output pin as an output, with predefined output value 0
+ *
  * @param obj The GPIO object
+ * @param gpio The GPIO object
  * @param pin The pin name
  * @return An integer value 1 or 0
 …
 /** Init the pin as an output and set the output value
+ *
  * @param obj   The GPIO object
+ * @param gpio  The GPIO object
  * @param pin   The pin name
  * @param value The value to be set
 …
 /** Init the pin to be in/out
+ *
  * @param obj       The GPIO object
+ * @param gpio      The GPIO object
  * @param pin       The pin name
  * @param direction The pin direction to be set

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/i2c_api.h

-              r352
+              r374
 /** Configure I2C as slave or master.
  *  @param obj The I2C object
+ *  @param enable_slave Enable i2c hardware so you can receive events with ::i2c_slave_receive
  *  @return non-zero if a value is available
  */
 …
 /** Configure I2C as slave or master.
  *  @param obj The I2C object
+ *  @param data    The buffer for receiving
+ *  @param length  Number of bytes to read
  *  @return non-zero if a value is available
  */
 …
 /** Configure I2C as slave or master.
  *  @param obj The I2C object
+ *  @param data    The buffer for sending
+ *  @param length  Number of bytes to write
  *  @return non-zero if a value is available
  */
 …
  *  @param stop      If true, stop will be generated after the transfer is done
  *  @param handler   The I2C IRQ handler to be set
+ *  @param event     Event mask for the transfer. See \ref hal_I2CEvents
  *  @param hint      DMA hint usage
  */

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/lp_ticker_api.h

-              r352
+              r374
 #include "device.h"
 #if DEVICE_LOWPOWERTIMER
+#if DEVICE_LPTICKER
 #include "hal/ticker_api.h"
 …
 /**
+ * \defgroup hal_LpTicker Low Power Ticker Functions
+ * \defgroup hal_lp_ticker Low Power Ticker
+ * Low level interface to the low power ticker of a target
+ *
+ * # Defined behavior
+ * * Has a reported frequency between 4KHz and 64KHz - verified by ::lp_ticker_info_test
+ * * Has a counter that is at least 12 bits wide - verified by ::lp_ticker_info_test
+ * * Continues operating in deep sleep mode - verified by ::lp_ticker_deepsleep_test
+ * * All behavior defined by the @ref hal_ticker_shared "ticker specification"
+ *
+ * # Undefined behavior
+ * * See the @ref hal_ticker_shared "ticker specification"
+ * * Calling any function other than lp_ticker_init after calling lp_ticker_free
+ *
+ * # Potential bugs
+ * * Glitches due to ripple counter - Verified by ::lp_ticker_glitch_test
+ *
+ * @see hal_lp_ticker_tests
+ *
  * @{
  */
+/**
+ * \defgroup hal_lp_ticker_tests Low Power Ticker tests
+ * Tests to validate the proper implementation of the low power ticker
+ *
+ * To run the low power ticker hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker*,tests-mbed_hal-lp_ticker*
+ *
+ */
+typedef void (*ticker_irq_handler_type)(const ticker_data_t *const);
+/** Set low power ticker IRQ handler
+ *
+ * @param ticker_irq_handler IRQ handler to be connected
+ *
+ * @return previous ticker IRQ handler
+ *
+ * @note by default IRQ handler is set to ::ticker_irq_handler
+ * @note this function is primarily for testing purposes and it's not required part of HAL implementation
+ *
+ */
+ticker_irq_handler_type set_lp_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler);
 /** Get low power ticker's data
+ *
  * @return The low power ticker data
  */
 const ticker_data_t* get_lp_ticker_data(void);
+const ticker_data_t *get_lp_ticker_data(void);
 /** The wrapper for ticker_irq_handler, to pass lp ticker's data
 …
 /** Initialize the low power ticker
+ *
+ * Initialize or re-initialize the ticker. This resets all the
+ * clocking and prescaler registers, along with disabling
+ * the compare interrupt.
+ *
+ * Pseudo Code:
+ * @code
+ * void lp_ticker_init()
+ * {
+ *     // Enable clock gate so processor can read LPTMR registers
+ *     POWER_CTRL |= POWER_CTRL_LPTMR_Msk;
+ *
+ *     // Disable the timer and ensure it is powered down
+ *     LPTMR_CTRL &= ~(LPTMR_CTRL_ENABLE_Msk | LPTMR_CTRL_COMPARE_ENABLE_Msk);
+ *
+ *     // Configure divisors - no division necessary
+ *     LPTMR_PRESCALE = 0;
+ *     LPTMR_CTRL |= LPTMR_CTRL_ENABLE_Msk;
+ *
+ *     // Install the interrupt handler
+ *     NVIC_SetVector(LPTMR_IRQn, (uint32_t)lp_ticker_irq_handler);
+ *     NVIC_EnableIRQ(LPTMR_IRQn);
+ * }
+ * @endcode
  */
 void lp_ticker_init(void);
+/** Read the current counter
+ *
+ * @return The current timer's counter value in microseconds
+/** Deinitialize the lower power ticker
+ *
+ * Powerdown the lp ticker in preparation for sleep, powerdown, or reset.
+ *
+ * After calling this function no other ticker functions should be called except
+ * lp_ticker_init(). Calling any function other than init after freeing is
+ * undefined.
+ *
+ * @note This function stops the ticker from counting.
+ */
+void lp_ticker_free(void);
+/** Read the current tick
+ *
+ * If no rollover has occurred, the seconds passed since lp_ticker_init()
+ * was called can be found by dividing the ticks returned by this function
+ * by the frequency returned by ::lp_ticker_get_info.
+ *
+ * @return The current timer's counter value in ticks
+ *
+ * Pseudo Code:
+ * @code
+ * uint32_t lp_ticker_read()
+ * {
+ *     uint16_t count;
+ *     uint16_t last_count;
+ *
+ *     // Loop until the same tick is read twice since this
+ *     // is ripple counter on a different clock domain.
+ *     count = LPTMR_COUNT;
+ *     do {
+ *         last_count = count;
+ *         count = LPTMR_COUNT;
+ *     } while (last_count != count);
+ *
+ *     return count;
+ * }
+ * @endcode
  */
 uint32_t lp_ticker_read(void);
 …
 /** Set interrupt for specified timestamp
+ *
+ * @param timestamp The time in microseconds to be set
+ * @param timestamp The time in ticks to be set
+ *
+ * @note no special handling needs to be done for times in the past
+ * as the common timer code will detect this and call
+ * lp_ticker_fire_interrupt() if this is the case
+ *
+ * @note calling this function with timestamp of more than the supported
+ * number of bits returned by ::lp_ticker_get_info results in undefined
+ * behavior.
+ *
+ * Pseudo Code:
+ * @code
+ * void lp_ticker_set_interrupt(timestamp_t timestamp)
+ * {
+ *     LPTMR_COMPARE = timestamp;
+ *     LPTMR_CTRL |= LPTMR_CTRL_COMPARE_ENABLE_Msk;
+ * }
+ * @endcode
  */
 void lp_ticker_set_interrupt(timestamp_t timestamp);
 …
 /** Disable low power ticker interrupt
+ *
+ * Pseudo Code:
+ * @code
+ * void lp_ticker_disable_interrupt(void)
+ * {
+ *     // Disable the compare interrupt
+ *     LPTMR_CTRL &= ~LPTMR_CTRL_COMPARE_ENABLE_Msk;
+ * }
+ * @endcode
  */
 void lp_ticker_disable_interrupt(void);
 …
 /** Clear the low power ticker interrupt
+ *
+ * Pseudo Code:
+ * @code
+ * void lp_ticker_clear_interrupt(void)
+ * {
+ *     // Write to the ICR (interrupt clear register) of the LPTMR
+ *     LPTMR_ICR = LPTMR_ICR_COMPARE_Msk;
+ * }
+ * @endcode
  */
 void lp_ticker_clear_interrupt(void);
+/** Set pending interrupt that should be fired right away.
+ *
+ * Pseudo Code:
+ * @code
+ * void lp_ticker_fire_interrupt(void)
+ * {
+ *     NVIC_SetPendingIRQ(LPTMR_IRQn);
+ * }
+ * @endcode
+ */
+void lp_ticker_fire_interrupt(void);
+/** Get frequency and counter bits of this ticker.
+ *
+ * Pseudo Code:
+ * @code
+ * const ticker_info_t* lp_ticker_get_info()
+ * {
+ *     static const ticker_info_t info = {
+ *         32768,      // 32KHz
+ *         16          // 16 bit counter
+ *     };
+ *     return &info;
+ * }
+ * @endcode
+ */
+const ticker_info_t *lp_ticker_get_info(void);
 /**@}*/

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_gpio.c

-              r352
+              r374
+}
+void gpio_init_in(gpio_t* gpio, PinName pin) {
+void gpio_init_in(gpio_t *gpio, PinName pin)
+{
     gpio_init_in_ex(gpio, pin, PullDefault);
+}
+void gpio_init_in_ex(gpio_t* gpio, PinName pin, PinMode mode) {
+void gpio_init_in_ex(gpio_t *gpio, PinName pin, PinMode mode)
+{
     _gpio_init_in(gpio, pin, mode);
+}
+void gpio_init_out(gpio_t* gpio, PinName pin) {
+void gpio_init_out(gpio_t *gpio, PinName pin)
+{
     gpio_init_out_ex(gpio, pin, 0);
+}
+void gpio_init_out_ex(gpio_t* gpio, PinName pin, int value) {
+void gpio_init_out_ex(gpio_t *gpio, PinName pin, int value)
+{
     _gpio_init_out(gpio, pin, PullNone, value);
+}
+void gpio_init_inout(gpio_t* gpio, PinName pin, PinDirection direction, PinMode mode, int value) {
+void gpio_init_inout(gpio_t *gpio, PinName pin, PinDirection direction, PinMode mode, int value)
+{
     if (direction == PIN_INPUT) {
         _gpio_init_in(gpio, pin, mode);
         if (pin != NC)
+        if (pin != NC) {
             gpio_write(gpio, value); // we prepare the value in case it is switched later
+        }
     } else {
         _gpio_init_out(gpio, pin, mode, value);

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_lp_ticker_api.c

-              r352
+              r374
  */
 #include "hal/lp_ticker_api.h"
+#include "hal/mbed_lp_ticker_wrapper.h"
 #if DEVICE_LOWPOWERTIMER
+#if DEVICE_LPTICKER
+static ticker_event_queue_t events;
+static ticker_event_queue_t events = { 0 };
+static ticker_irq_handler_type irq_handler = ticker_irq_handler;
 static const ticker_interface_t lp_interface = {
 …
     .clear_interrupt = lp_ticker_clear_interrupt,
     .set_interrupt = lp_ticker_set_interrupt,
+    .fire_interrupt = lp_ticker_fire_interrupt,
+    .get_info = lp_ticker_get_info,
+    .free = lp_ticker_free,
 };
 …
 };
 const ticker_data_t* get_lp_ticker_data(void)
+const ticker_data_t *get_lp_ticker_data(void)
+{
+#if LPTICKER_DELAY_TICKS > 0
+    return get_lp_ticker_wrapper_data(&lp_data);
+#else
     return &lp_data;
+#endif
+}
+ticker_irq_handler_type set_lp_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler)
+{
+    ticker_irq_handler_type prev_irq_handler = irq_handler;
+    irq_handler = ticker_irq_handler;
+    return prev_irq_handler;
+}
 void lp_ticker_irq_handler(void)
+{
+    ticker_irq_handler(&lp_data);
+#if LPTICKER_DELAY_TICKS > 0
+    lp_ticker_wrapper_irq_handler(irq_handler);
+#else
+    if (irq_handler) {
+        irq_handler(&lp_data);
+    }
+#endif
+}

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_pinmap_common.c

-              r352
+              r374
 #include "platform/mbed_error.h"
+void pinmap_pinout(PinName pin, const PinMap *map) {
+    if (pin == NC)
+void pinmap_pinout(PinName pin, const PinMap *map)
+{
+    if (pin == NC) {
         return;
+    }
     while (map->pin != NC) {
 …
         map++;
+    }
     error("could not pinout");
+    MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_PLATFORM, MBED_ERROR_CODE_PINMAP_INVALID), "could not pinout", pin);
+}
+uint32_t pinmap_merge(uint32_t a, uint32_t b) {
+uint32_t pinmap_merge(uint32_t a, uint32_t b)
+{
     // both are the same (inc both NC)
     if (a == b)
+    if (a == b) {
         return a;
+    }
     // one (or both) is not connected
     if (a == (uint32_t)NC)
+    if (a == (uint32_t)NC) {
         return b;
+    if (b == (uint32_t)NC)
+    }
+    if (b == (uint32_t)NC) {
         return a;
+    }
     // mis-match error case
     error("pinmap mis-match");
+    MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_PLATFORM, MBED_ERROR_CODE_PINMAP_INVALID), "pinmap mis-match", a);
     return (uint32_t)NC;
+}
+uint32_t pinmap_find_peripheral(PinName pin, const PinMap* map) {
+uint32_t pinmap_find_peripheral(PinName pin, const PinMap *map)
+{
     while (map->pin != NC) {
         if (map->pin == pin)
+        if (map->pin == pin) {
             return map->peripheral;
+        }
         map++;
+    }
 …
+}
+uint32_t pinmap_peripheral(PinName pin, const PinMap* map) {
+uint32_t pinmap_peripheral(PinName pin, const PinMap *map)
+{
     uint32_t peripheral = (uint32_t)NC;
     if (pin == (PinName)NC)
+    if (pin == (PinName)NC) {
         return (uint32_t)NC;
+    }
     peripheral = pinmap_find_peripheral(pin, map);
+    if ((uint32_t)NC == peripheral) // no mapping available
+        error("pinmap not found for peripheral");
+    if ((uint32_t)NC == peripheral) { // no mapping available
+        MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_PLATFORM, MBED_ERROR_CODE_PINMAP_INVALID), "pinmap not found for peripheral", peripheral);
+    }
     return peripheral;
+}
+uint32_t pinmap_find_function(PinName pin, const PinMap* map) {
+uint32_t pinmap_find_function(PinName pin, const PinMap *map)
+{
     while (map->pin != NC) {
         if (map->pin == pin)
+        if (map->pin == pin) {
             return map->function;
+        }
         map++;
+    }
 …
+}
+uint32_t pinmap_function(PinName pin, const PinMap* map) {
+uint32_t pinmap_function(PinName pin, const PinMap *map)
+{
     uint32_t function = (uint32_t)NC;
     if (pin == (PinName)NC)
+    if (pin == (PinName)NC) {
         return (uint32_t)NC;
+    }
     function = pinmap_find_function(pin, map);
+    if ((uint32_t)NC == function) // no mapping available
+        error("pinmap not found for function");
+    if ((uint32_t)NC == function) { // no mapping available
+        MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_PLATFORM, MBED_ERROR_CODE_PINMAP_INVALID), "pinmap not found for function", function);
+    }
     return function;
+}

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_ticker_api.c

-              r352
+              r374
  * limitations under the License.
  */
+#include <stdio.h>
 #include <stddef.h>
 #include "hal/ticker_api.h"
 #include "platform/mbed_critical.h"
+void ticker_set_handler(const ticker_data_t *const data, ticker_event_handler handler) {
+    data->interface->init();
+    data->queue->event_handler = handler;
+}
+void ticker_irq_handler(const ticker_data_t *const data) {
+    data->interface->clear_interrupt();
+#include "platform/mbed_assert.h"
+static void schedule_interrupt(const ticker_data_t *const ticker);
+static void update_present_time(const ticker_data_t *const ticker);
+/*
+ * Initialize a ticker instance.
+ */
+static void initialize(const ticker_data_t *ticker)
+{
+    // return if the queue has already been initialized, in that case the
+    // interface used by the queue is already initialized.
+    if (ticker->queue->initialized) {
+        return;
+    }
+    if (ticker->queue->suspended) {
+        return;
+    }
+    ticker->interface->init();
+    const ticker_info_t *info = ticker->interface->get_info();
+    uint32_t frequency = info->frequency;
+    if (info->frequency == 0) {
+        MBED_ASSERT(0);
+        frequency = 1000000;
+    }
+    uint8_t frequency_shifts = 0;
+    for (uint8_t i = 31; i > 0; --i) {
+        if ((1 << i) == frequency) {
+            frequency_shifts = i;
+            break;
+        }
+    }
+    uint32_t bits = info->bits;
+    if ((info->bits > 32) || (info->bits < 4)) {
+        MBED_ASSERT(0);
+        bits = 32;
+    }
+    uint32_t max_delta = 0x7 << (bits - 4); // 7/16th
+    uint64_t max_delta_us =
+        ((uint64_t)max_delta * 1000000 + frequency - 1) / frequency;
+    ticker->queue->event_handler = NULL;
+    ticker->queue->head = NULL;
+    ticker->queue->tick_last_read = ticker->interface->read();
+    ticker->queue->tick_remainder = 0;
+    ticker->queue->frequency = frequency;
+    ticker->queue->frequency_shifts = frequency_shifts;
+    ticker->queue->bitmask = ((uint64_t)1 << bits) - 1;
+    ticker->queue->max_delta = max_delta;
+    ticker->queue->max_delta_us = max_delta_us;
+    ticker->queue->present_time = 0;
+    ticker->queue->dispatching = false;
+    ticker->queue->suspended = false;
+    ticker->queue->initialized = true;
+    update_present_time(ticker);
+    schedule_interrupt(ticker);
+}
+/**
+ * Set the event handler function of a ticker instance.
+ */
+static void set_handler(const ticker_data_t *const ticker, ticker_event_handler handler)
+{
+    ticker->queue->event_handler = handler;
+}
+/*
+ * Convert a 32 bit timestamp into a 64 bit timestamp.
+ *
+ * A 64 bit timestamp is used as the point of time of reference while the
+ * timestamp to convert is relative to this point of time.
+ *
+ * The lower 32 bits of the timestamp returned will be equal to the timestamp to
+ * convert.
+ *
+ * If the timestamp to convert is less than the lower 32 bits of the time
+ * reference then the timestamp to convert is seen as an overflowed value and
+ * the upper 32 bit of the timestamp returned will be equal to the upper 32 bit
+ * of the reference point + 1.
+ * Otherwise, the upper 32 bit returned will be equal to the upper 32 bit of the
+ * reference point.
+ *
+ * @param ref: The 64 bit timestamp of reference.
+ * @param timestamp: The timestamp to convert.
+ */
+static us_timestamp_t convert_timestamp(us_timestamp_t ref, timestamp_t timestamp)
+{
+    bool overflow = timestamp < ((timestamp_t) ref) ? true : false;
+    us_timestamp_t result = (ref & ~((us_timestamp_t)UINT32_MAX)) | timestamp;
+    if (overflow) {
+        result += (1ULL << 32);
+    }
+    return result;
+}
+/**
+ * Update the present timestamp value of a ticker.
+ */
+static void update_present_time(const ticker_data_t *const ticker)
+{
+    ticker_event_queue_t *queue = ticker->queue;
+    if (queue->suspended) {
+        return;
+    }
+    uint32_t ticker_time = ticker->interface->read();
+    if (ticker_time == ticker->queue->tick_last_read) {
+        // No work to do
+        return;
+    }
+    uint64_t elapsed_ticks = (ticker_time - queue->tick_last_read) & queue->bitmask;
+    queue->tick_last_read = ticker_time;
+    uint64_t elapsed_us;
+    if (1000000 == queue->frequency) {
+        // Optimized for 1MHz
+        elapsed_us = elapsed_ticks;
+    } else if (0 != queue->frequency_shifts) {
+        // Optimized for frequencies divisible by 2
+        uint64_t us_x_ticks = elapsed_ticks * 1000000;
+        elapsed_us = us_x_ticks >> queue->frequency_shifts;
+        // Update remainder
+        queue->tick_remainder += us_x_ticks - (elapsed_us << queue->frequency_shifts);
+        if (queue->tick_remainder >= queue->frequency) {
+            elapsed_us += 1;
+            queue->tick_remainder -= queue->frequency;
+        }
+    } else {
+        // General case
+        uint64_t us_x_ticks = elapsed_ticks * 1000000;
+        elapsed_us = us_x_ticks / queue->frequency;
+        // Update remainder
+        queue->tick_remainder += us_x_ticks - elapsed_us * queue->frequency;
+        if (queue->tick_remainder >= queue->frequency) {
+            elapsed_us += 1;
+            queue->tick_remainder -= queue->frequency;
+        }
+    }
+    // Update current time
+    queue->present_time += elapsed_us;
+}
+/**
+ * Given the absolute timestamp compute the hal tick timestamp rounded up.
+ */
+static timestamp_t compute_tick_round_up(const ticker_data_t *const ticker, us_timestamp_t timestamp)
+{
+    ticker_event_queue_t *queue = ticker->queue;
+    us_timestamp_t delta_us = timestamp - queue->present_time;
+    timestamp_t delta = ticker->queue->max_delta;
+    if (delta_us <=  ticker->queue->max_delta_us) {
+        // Checking max_delta_us ensures the operation will not overflow
+        if (1000000 == queue->frequency) {
+            // Optimized for 1MHz
+            delta = delta_us;
+            if (delta > ticker->queue->max_delta) {
+                delta = ticker->queue->max_delta;
+            }
+        } else if (0 != queue->frequency_shifts) {
+            // Optimized frequencies divisible by 2
+            delta = ((delta_us << ticker->queue->frequency_shifts) + 1000000 - 1) / 1000000;
+            if (delta > ticker->queue->max_delta) {
+                delta = ticker->queue->max_delta;
+            }
+        } else {
+            // General case
+            delta = (delta_us * queue->frequency + 1000000 - 1) / 1000000;
+            if (delta > ticker->queue->max_delta) {
+                delta = ticker->queue->max_delta;
+            }
+        }
+    }
+    return (queue->tick_last_read + delta) & queue->bitmask;
+}
+/**
+ * Return 1 if the tick has incremented to or past match_tick, otherwise 0.
+ */
+int _ticker_match_interval_passed(timestamp_t prev_tick, timestamp_t cur_tick, timestamp_t match_tick)
+{
+    if (match_tick > prev_tick) {
+        return (cur_tick >= match_tick) || (cur_tick < prev_tick);
+    } else {
+        return (cur_tick < prev_tick) && (cur_tick >= match_tick);
+    }
+}
+/**
+ * Compute the time when the interrupt has to be triggered and schedule it.
+ *
+ * If there is no event in the queue or the next event to execute is in more
+ * than ticker.queue.max_delta ticks from now then the ticker irq will be
+ * scheduled in ticker.queue.max_delta ticks. Otherwise the irq will be
+ * scheduled to happen when the running counter reach the timestamp of the
+ * first event in the queue.
+ *
+ * @note If there is no event in the queue then the interrupt is scheduled to
+ * in ticker.queue.max_delta. This is necessary to keep track
+ * of the timer overflow.
+ */
+static void schedule_interrupt(const ticker_data_t *const ticker)
+{
+    ticker_event_queue_t *queue = ticker->queue;
+    if (queue->suspended || ticker->queue->dispatching) {
+        // Don't schedule the next interrupt until dispatching is
+        // finished. This prevents repeated calls to interface->set_interrupt
+        return;
+    }
+    update_present_time(ticker);
+    if (ticker->queue->head) {
+        us_timestamp_t present = ticker->queue->present_time;
+        us_timestamp_t match_time = ticker->queue->head->timestamp;
+        // if the event at the head of the queue is in the past then schedule
+        // it immediately.
+        if (match_time <= present) {
+            ticker->interface->fire_interrupt();
+            return;
+        }
+        timestamp_t match_tick = compute_tick_round_up(ticker, match_time);
+        // The same tick should never occur since match_tick is rounded up.
+        // If the same tick is returned scheduling will not work correctly.
+        MBED_ASSERT(match_tick != queue->tick_last_read);
+        ticker->interface->set_interrupt(match_tick);
+        timestamp_t cur_tick = ticker->interface->read();
+        if (_ticker_match_interval_passed(queue->tick_last_read, cur_tick, match_tick)) {
+            ticker->interface->fire_interrupt();
+        }
+    } else {
+        uint32_t match_tick =
+            (queue->tick_last_read + queue->max_delta) & queue->bitmask;
+        ticker->interface->set_interrupt(match_tick);
+    }
+}
+void ticker_set_handler(const ticker_data_t *const ticker, ticker_event_handler handler)
+{
+    initialize(ticker);
+    core_util_critical_section_enter();
+    set_handler(ticker, handler);
+    core_util_critical_section_exit();
+}
+void ticker_irq_handler(const ticker_data_t *const ticker)
+{
+    core_util_critical_section_enter();
+    ticker->interface->clear_interrupt();
+    if (ticker->queue->suspended) {
+        core_util_critical_section_exit();
+        return;
+    }
     /* Go through all the pending TimerEvents */
+    ticker->queue->dispatching = true;
     while (1) {
+        if (data->queue->head == NULL) {
+            // There are no more TimerEvents left, so disable matches.
+            data->interface->disable_interrupt();
+            return;
+        }
+        if ((int)(data->queue->head->timestamp - data->interface->read()) <= 0) {
+        if (ticker->queue->head == NULL) {
+            break;
+        }
+        // update the current timestamp used by the queue
+        update_present_time(ticker);
+        if (ticker->queue->head->timestamp <= ticker->queue->present_time) {
             // This event was in the past:
             //      point to the following one and execute its handler
             ticker_event_t *p = data->queue->head;
             data->queue->head = data->queue->head->next;
             if (data->queue->event_handler != NULL) {
                 (*data->queue->event_handler)(p->id); // NOTE: the handler can set new events
+            ticker_event_t *p = ticker->queue->head;
+            ticker->queue->head = ticker->queue->head->next;
+            if (ticker->queue->event_handler != NULL) {
+                (*ticker->queue->event_handler)(p->id); // NOTE: the handler can set new events
+            }
             /* Note: We continue back to examining the head because calling the
              * event handler may have altered the chain of pending events. */
         } else {
+            // This event and the following ones in the list are in the future:
+            //      set it as next interrupt and return
+            data->interface->set_interrupt(data->queue->head->timestamp);
+            return;
+        }
+    }
+}
+void ticker_insert_event(const ticker_data_t *const data, ticker_event_t *obj, timestamp_t timestamp, uint32_t id) {
+    /* disable interrupts for the duration of the function */
+    core_util_critical_section_enter();
+            break;
+        }
+    }
+    ticker->queue->dispatching = false;
+    schedule_interrupt(ticker);
+    core_util_critical_section_exit();
+}
+void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj, timestamp_t timestamp, uint32_t id)
+{
+    core_util_critical_section_enter();
+    // update the current timestamp
+    update_present_time(ticker);
+    us_timestamp_t absolute_timestamp = convert_timestamp(
+                                            ticker->queue->present_time,
+                                            timestamp
+                                        );
+    // defer to ticker_insert_event_us
+    ticker_insert_event_us(
+        ticker,
+        obj, absolute_timestamp, id
+    );
+    core_util_critical_section_exit();
+}
+void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *obj, us_timestamp_t timestamp, uint32_t id)
+{
+    core_util_critical_section_enter();
+    // update the current timestamp
+    update_present_time(ticker);
     // initialise our data
 …
        an element this should come before (which is possibly the
        head). */
     ticker_event_t *prev = NULL, *p = data->queue->head;
+    ticker_event_t *prev = NULL, *p = ticker->queue->head;
     while (p != NULL) {
         /* check if we come before p */
         if ((int)(timestamp - p->timestamp) < 0) {
+        if (timestamp < p->timestamp) {
             break;
+        }
 …
         p = p->next;
+    }
     /* if we're at the end p will be NULL, which is correct */
     obj->next = p;
 …
     /* if prev is NULL we're at the head */
     if (prev == NULL) {
         data->queue->head = obj;
         data->interface->set_interrupt(timestamp);
+        ticker->queue->head = obj;
+        schedule_interrupt(ticker);
     } else {
         prev->next = obj;
 …
+}
+void ticker_remove_event(const ticker_data_t *const data, ticker_event_t *obj) {
+void ticker_remove_event(const ticker_data_t *const ticker, ticker_event_t *obj)
+{
     core_util_critical_section_enter();
     // remove this object from the list
     if (data->queue->head == obj) {
+    if (ticker->queue->head == obj) {
         // first in the list, so just drop me
+        data->queue->head = obj->next;
+        if (data->queue->head == NULL) {
+            data->interface->disable_interrupt();
+        } else {
+            data->interface->set_interrupt(data->queue->head->timestamp);
+        }
+        ticker->queue->head = obj->next;
+        schedule_interrupt(ticker);
     } else {
         // find the object before me, then drop me
         ticker_event_t* p = data->queue->head;
+        ticker_event_t *p = ticker->queue->head;
         while (p != NULL) {
             if (p->next == obj) {
 …
+}
+timestamp_t ticker_read(const ticker_data_t *const data)
+{
+    return data->interface->read();
+timestamp_t ticker_read(const ticker_data_t *const ticker)
+{
+    return ticker_read_us(ticker);
+}
+us_timestamp_t ticker_read_us(const ticker_data_t *const ticker)
+{
+    initialize(ticker);
+    core_util_critical_section_enter();
+    update_present_time(ticker);
+    core_util_critical_section_exit();
+    return ticker->queue->present_time;
+}
 …
     return ret;
+}
+void ticker_suspend(const ticker_data_t *const ticker)
+{
+    core_util_critical_section_enter();
+    ticker->queue->suspended = true;
+    core_util_critical_section_exit();
+}
+void ticker_resume(const ticker_data_t *const ticker)
+{
+    core_util_critical_section_enter();
+    ticker->queue->suspended = false;
+    if (ticker->queue->initialized) {
+        ticker->queue->tick_last_read = ticker->interface->read();
+        update_present_time(ticker);
+        schedule_interrupt(ticker);
+    } else {
+        initialize(ticker);
+    }
+    core_util_critical_section_exit();
+}

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_us_ticker_api.c

-              r352
+              r374
 #include "hal/us_ticker_api.h"
+static ticker_event_queue_t events;
+static ticker_event_queue_t events = { 0 };
+static ticker_irq_handler_type irq_handler = ticker_irq_handler;
 static const ticker_interface_t us_interface = {
 …
     .clear_interrupt = us_ticker_clear_interrupt,
     .set_interrupt = us_ticker_set_interrupt,
+    .fire_interrupt = us_ticker_fire_interrupt,
+    .get_info = us_ticker_get_info,
+    .free = us_ticker_free,
 };
 static const ticker_data_t us_data = {
     .interface = &us_interface,
     .queue = &events,
+    .queue = &events
 };
 const ticker_data_t* get_us_ticker_data(void)
+const ticker_data_t *get_us_ticker_data(void)
+{
     return &us_data;
+}
+ticker_irq_handler_type set_us_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler)
+{
+    ticker_irq_handler_type prev_irq_handler = irq_handler;
+    irq_handler = ticker_irq_handler;
+    return prev_irq_handler;
+}
 void us_ticker_irq_handler(void)
+{
+    ticker_irq_handler(&us_data);
+    if (irq_handler) {
+        irq_handler(&us_data);
+    }
+}

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/rtc_api.h

-              r352
+              r374
-/** \addtogroup hal */
-/** @{*/
 /* mbed Microcontroller Library
  * Copyright (c) 2006-2013 ARM Limited
 …
  * limitations under the License.
  */
+/** \addtogroup hal */
+/** @{*/
 #ifndef MBED_RTC_API_H
 #define MBED_RTC_API_H
 #include "device.h"
-#if DEVICE_RTC
 #include <time.h>
 …
 /**
+ * \defgroup hal_rtc RTC hal functions
+ * \defgroup hal_rtc RTC hal
+ *
+ * The RTC hal provides a low level interface to the Real Time Counter (RTC) of a
+ * target.
+ *
+ * # Defined behaviour
+ * * The function ::rtc_init is safe to call repeatedly - Verified by test ::rtc_init_test.
+ * * RTC accuracy is at least 10% - Verified by test ::rtc_accuracy_test.
+ * * Init/free doesn't stop RTC from counting - Verified by test ::rtc_persist_test.
+ * * Software reset doesn't stop RTC from counting - Verified by test ::rtc_reset_test.
+ * * Sleep modes don't stop RTC from counting - Verified by test ::rtc_sleep_test.
+ * * Shutdown mode doesn't stop RTC from counting - Not verified.
+ * * The functions ::rtc_write/::rtc_read provides availability to set/get RTC time
+ * - Verified by test ::rtc_write_read_test.
+ * * The functions ::rtc_isenabled returns 1 if the RTC is counting and the time has been set,
+ * 0 otherwise - Verified by test ::rtc_enabled_test.
+ *
+ * # Undefined behaviour
+ * * Calling any function other than ::rtc_init before the initialisation of the RTC
+ *
+ * # Potential bugs
+ * * Incorrect overflow handling - Verified by ::rtc_range_test
+ * * Glitches due to ripple counter - Verified by ::rtc_glitch_test
+ *
+ * @see hal_rtc_tests
+ *
  * @{
  */
+/**
+ * \defgroup hal_rtc_tests RTC hal tests
+ * The RTC test validate proper implementation of the RTC hal.
+ *
+ * To run the RTC hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-rtc*
+ */
 /** Initialize the RTC peripheral
+ *
+ * Powerup the RTC in perpetration for access. This function must be called
+ * before any other RTC functions ares called. This does not change the state
+ * of the RTC. It just enables access to it.
+ *
+ * @note This function is safe to call repeatedly - Tested by ::rtc_init_test
+ *
+ * Example Implementation Pseudo Code:
+ * @code
+ * void rtc_init()
+ * {
+ *     // Enable clock gate so processor can read RTC registers
+ *     POWER_CTRL |= POWER_CTRL_RTC_Msk;
+ *
+ *     // See if the RTC is already setup
+ *     if (!(RTC_STATUS & RTC_STATUS_COUNTING_Msk)) {
+ *
+ *         // Setup the RTC clock source
+ *         RTC_CTRL |= RTC_CTRL_CLK32_Msk;
+ *     }
+ * }
+ * @endcode
  */
 void rtc_init(void);
 …
 /** Deinitialize RTC
+ *
+ * TODO: The function is not used by rtc api in mbed-drivers.
+ * Powerdown the RTC in preparation for sleep, powerdown or reset. That should only
+ * affect the CPU domain and not the time keeping logic.
+ * After this function is called no other RTC functions should be called
+ * except for ::rtc_init.
+ *
+ * @note This function does not stop the RTC from counting - Tested by ::rtc_persist_test
+ *
+ * Example Implementation Pseudo Code:
+ * @code
+ * void rtc_free()
+ * {
+ *     // Disable clock gate since processor no longer needs to read RTC registers
+ *     POWER_CTRL &= ~POWER_CTRL_RTC_Msk;
+ * }
+ * @endcode
  */
 void rtc_free(void);
 /** Get the RTC enable status
+/** Check if the RTC has the time set and is counting
+ *
+ * @retval 0 disabled
+ * @retval 1 enabled
+ * @retval 0 The time reported by the RTC is not valid
+ * @retval 1 The time has been set the RTC is counting
+ *
+ * Example Implementation Pseudo Code:
+ * @code
+ * int rtc_isenabled()
+ * {
+ *     if (RTC_STATUS & RTC_STATUS_COUNTING_Msk) {
+ *         return 1;
+ *     } else {
+ *         return 0;
+ *     }
+ * }
+ * @endcode
  */
 int rtc_isenabled(void);
 …
 /** Get the current time from the RTC peripheral
+ *
+ * @return The current time
+ * @return The current time in seconds
+ *
+ * @note Some RTCs are not synchronized with the main clock. If
+ * this is the case with your RTC then you must read the RTC time
+ * in a loop to prevent reading the wrong time due to a glitch.
+ * The test ::rtc_glitch_test is intended to catch this bug.
+ *
+ * Example implementation for an unsynchronized ripple counter:
+ * @code
+ * time_t rtc_read()
+ * {
+ *     uint32_t val;
+ *     uint32_t last_val;
+ *
+ *     // Loop until the same value is read twice
+ *     val = RTC_SECONDS;
+ *     do {
+ *         last_val = val;
+ *         val = RTC_SECONDS;
+ *     } while (last_val != val);
+ *
+ *     return (time_t)val;
+ * }
+ * @endcode
  */
 time_t rtc_read(void);
 /** Set the current time to the RTC peripheral
+/** Write the current time in seconds to the RTC peripheral
+ *
+ * @param t The current time to be set
+ * @param t The current time to be set in seconds.
+ *
+ * Example Implementation Pseudo Code:
+ * @code
+ * void rtc_write(time_t t)
+ * {
+ *     RTC_SECONDS = t;
+ * }
+ * @endcode
  */
 void rtc_write(time_t t);
 …
 #endif
-#endif
 /** @}*/

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/sleep_api.h

-              r352
+              r374
 #endif
+/**
+ * \defgroup hal_sleep sleep hal requirements
+ * Low level interface to the sleep mode of a target.
+ *
+ * # Defined behaviour
+ *
+ * * Sleep mode
+ *   * wake-up time should be less than 10 us - Verified by sleep_usticker_test().
+ *   * the processor can be woken up by any internal peripheral interrupt  - Verified by sleep_usticker_test().
+ *   * all peripherals operate as in run mode - not verified.
+ *   * the processor can be woken up by external pin interrupt - not verified.
+ * * Deep sleep
+ *   * the wake-up time should be less than 10 ms - Verified by deepsleep_lpticker_test().
+ *   * lp ticker should wake up a target from this mode - Verified by deepsleep_lpticker_test().
+ *   * RTC should wake up a target from this mode - not verified.
+ *   * an external interrupt on a pin should wake up a target from this mode - not verified.
+ *   * a watchdog timer should wake up a target from this mode - not verified.
+ *   * High-speed clocks are turned off - Verified by deepsleep_high_speed_clocks_turned_off_test().
+ *   * RTC keeps time - Verified by rtc_sleep_test().
+ *
+ * # Undefined behaviour
+ *
+ * * peripherals aside from RTC, GPIO and lp ticker result in undefined behaviour in deep sleep.
+ * @{
+ */
+/**
+ * \defgroup hal_sleep_tests sleep hal tests
+ * The sleep HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the sleep hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-sleep*
+ *
+ */
 /** Send the microcontroller to sleep
+ *
  * The processor is setup ready for sleep, and sent to sleep using __WFI(). In this mode, the
+ * The processor is setup ready for sleep, and sent to sleep. In this mode, the
  * system clock to the core is stopped until a reset or an interrupt occurs. This eliminates
  * dynamic power used by the processor, memory systems and buses. The processor, peripheral and
 …
  * The processor can be woken up by any internal peripheral interrupt or external pin interrupt.
+ *
+ * @note
+ *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
+ * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
+ * able to access the LocalFileSystem
+ * The wake-up time shall be less than 10 us.
+ *
  */
 void hal_sleep(void);
 …
+ *
  * This processor is setup ready for deep sleep, and sent to sleep using __WFI(). This mode
  * has the same sleep features as sleep plus it powers down peripherals and clocks. All state
  * is still maintained.
+ * has the same sleep features as sleep plus it powers down peripherals and high frequency clocks.
+ * All state is still maintained.
+ *
  * The processor can only be woken up by an external interrupt on a pin or a watchdog timer.
+ * The processor can only be woken up by low power ticker, RTC, an external interrupt on a pin or a watchdog timer.
+ *
+ * @note
+ *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
+ * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
+ * able to access the LocalFileSystem
+ * The wake-up time shall be less than 10 ms.
  */
 void hal_deepsleep(void);
+/**@}*/
 #ifdef __cplusplus

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/spi_api.h

r364	r374
34	34
35	35	#define SPI_FILL_WORD (0xFFFF)
	36	#define SPI_FILL_CHAR (0xFF)
36	37
37	38	#if DEVICE_SPI_ASYNCH

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/ticker_api.h

-              r352
+              r374
 #include <stdint.h>
+#include <stdbool.h>
 #include "device.h"
+/**
+ * Legacy format representing a timestamp in us.
+ * Given it is modeled as a 32 bit integer, this type can represent timestamp
+ * up to 4294 seconds (71 minutes).
+ * Prefer using us_timestamp_t which store timestamp as 64 bits integer.
+ */
 typedef uint32_t timestamp_t;
+/**
+ * A us timestamp stored in a 64 bit integer.
+ * Can store timestamp up to 584810 years.
+ */
+typedef uint64_t us_timestamp_t;
 /** Ticker's event structure
  */
 typedef struct ticker_event_s {
     timestamp_t            timestamp; /**< Event's timestamp */
+    us_timestamp_t         timestamp; /**< Event's timestamp */
     uint32_t               id;        /**< TimerEvent object */
     struct ticker_event_s *next;      /**< Next event in the queue */
 …
 typedef void (*ticker_event_handler)(uint32_t id);
+/** Information about the ticker implementation
+ */
+typedef struct {
+    uint32_t frequency;                           /**< Frequency in Hz this ticker runs at */
+    uint32_t bits;                                /**< Number of bits this ticker supports */
+} ticker_info_t;
 /** Ticker's interface structure - required API for a ticker
 …
     void (*clear_interrupt)(void);                /**< Clear interrupt function */
     void (*set_interrupt)(timestamp_t timestamp); /**< Set interrupt function */
+    void (*fire_interrupt)(void);                 /**< Fire interrupt right-away */
+    void (*free)(void);                           /**< Disable function */
+    const ticker_info_t *(*get_info)(void);       /**< Return info about this ticker's implementation */
 } ticker_interface_t;
 …
     ticker_event_handler event_handler; /**< Event handler */
     ticker_event_t *head;               /**< A pointer to head */
+    uint32_t frequency;                 /**< Frequency of the timer in Hz */
+    uint32_t bitmask;                   /**< Mask to be applied to time values read */
+    uint32_t max_delta;                 /**< Largest delta in ticks that can be used when scheduling */
+    uint64_t max_delta_us;              /**< Largest delta in us that can be used when scheduling */
+    uint32_t tick_last_read;            /**< Last tick read */
+    uint64_t tick_remainder;            /**< Ticks that have not been added to base_time */
+    us_timestamp_t present_time;        /**< Store the timestamp used for present time */
+    bool initialized;                   /**< Indicate if the instance is initialized */
+    bool dispatching;                   /**< The function ticker_irq_handler is dispatching */
+    bool suspended;                     /**< Indicate if the instance is suspended */
+    uint8_t frequency_shifts;           /**< If frequency is a value of 2^n, this is n, otherwise 0 */
 } ticker_event_queue_t;
 …
 /** Initialize a ticker and set the event handler
+ *
  * @param data    The ticker's data
+ * @param ticker The ticker object.
  * @param handler A handler to be set
  */
 void ticker_set_handler(const ticker_data_t *const data, ticker_event_handler handler);
+void ticker_set_handler(const ticker_data_t *const ticker, ticker_event_handler handler);
 /** IRQ handler that goes through the events to trigger overdue events.
+ *
  * @param data    The ticker's data
  */
 void ticker_irq_handler(const ticker_data_t *const data);
+ * @param ticker The ticker object.
+ */
+void ticker_irq_handler(const ticker_data_t *const ticker);
 /** Remove an event from the queue
+ *
  * @param data The ticker's data
+ * @param ticker The ticker object.
  * @param obj  The event object to be removed from the queue
  */
 void ticker_remove_event(const ticker_data_t *const data, ticker_event_t *obj);
+void ticker_remove_event(const ticker_data_t *const ticker, ticker_event_t *obj);
 /** Insert an event to the queue
+ *
+ * @param data      The ticker's data
+ * The event will be executed in timestamp - ticker_read().
+ *
+ * @warning This function does not consider timestamp in the past. If an event
+ * is inserted with a timestamp less than the current timestamp then the event
+ * will be executed in timestamp - ticker_read() us.
+ * The internal counter wrap very quickly it is hard to decide weither an
+ * event is in the past or in 1 hour.
+ *
+ * @note prefer the use of ticker_insert_event_us which allows registration of
+ * absolute timestamp.
+ *
+ * @param ticker    The ticker object.
  * @param obj       The event object to be inserted to the queue
  * @param timestamp The event's timestamp
  * @param id        The event object
  */
+void ticker_insert_event(const ticker_data_t *const data, ticker_event_t *obj, timestamp_t timestamp, uint32_t id);
+/** Read the current ticker's timestamp
+ *
+ * @param data The ticker's data
+void ticker_insert_event(const ticker_data_t *const ticker, ticker_event_t *obj, timestamp_t timestamp, uint32_t id);
+/** Insert an event to the queue
+ *
+ * The event will be executed in timestamp - ticker_read_us() us.
+ *
+ * @note If an event is inserted with a timestamp less than the current
+ * timestamp then the event will be scheduled immediately resulting in
+ * an instant call to event handler.
+ *
+ * @param ticker    The ticker object.
+ * @param obj       The event object to be inserted to the queue
+ * @param timestamp The event's timestamp
+ * @param id        The event object
+ */
+void ticker_insert_event_us(const ticker_data_t *const ticker, ticker_event_t *obj, us_timestamp_t timestamp, uint32_t id);
+/** Read the current (relative) ticker's timestamp
+ *
+ * @warning Return a relative timestamp because the counter wrap every 4294
+ * seconds.
+ *
+ * @param ticker The ticker object.
  * @return The current timestamp
  */
+timestamp_t ticker_read(const ticker_data_t *const data);
+timestamp_t ticker_read(const ticker_data_t *const ticker);
+/** Read the current (absolute) ticker's timestamp
+ *
+ * @warning Return an absolute timestamp counting from the initialization of the
+ * ticker.
+ *
+ * @param ticker The ticker object.
+ * @return The current timestamp
+ */
+us_timestamp_t ticker_read_us(const ticker_data_t *const ticker);
 /** Read the next event's timestamp
+ *
+ * @param data The ticker's data
+ * @param ticker        The ticker object.
+ * @param timestamp     The timestamp object.
  * @return 1 if timestamp is pending event, 0 if there's no event pending
  */
+int ticker_get_next_timestamp(const ticker_data_t *const data, timestamp_t *timestamp);
+int ticker_get_next_timestamp(const ticker_data_t *const ticker, timestamp_t *timestamp);
+/** Suspend this ticker
+ *
+ * When suspended reads will always return the same time and no
+ * events will be dispatched. When suspended the common layer
+ * will only ever call the interface function clear_interrupt()
+ * and that is only if ticker_irq_handler is called.
+ *
+ *
+ * @param ticker        The ticker object.
+ */
+void ticker_suspend(const ticker_data_t *const ticker);
+/** Resume this ticker
+ *
+ * When resumed the ticker will ignore any time that has passed
+ * and continue counting up where it left off.
+ *
+ * @param ticker        The ticker object.
+ */
+void ticker_resume(const ticker_data_t *const ticker);
+/* Private functions
+ *
+ * @cond PRIVATE
+ *
+ */
+int _ticker_match_interval_passed(timestamp_t prev_tick, timestamp_t cur_tick, timestamp_t match_tick);
+/*
+ * @endcond PRIVATE
+ *
+ */
 /**@}*/

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/us_ticker_api.h

-              r352
+              r374
 /**
+ * \defgroup hal_UsTicker Microseconds Ticker Functions
+ * \defgroup hal_us_ticker Microsecond Ticker
+ * Low level interface to the microsecond ticker of a target
+ *
+ * # Defined behavior
+ * * Has a reported frequency between 250KHz and 8MHz - Verified by test ::us_ticker_info_test
+ * * Has a counter that is at least 16 bits wide - Verified by test ::us_ticker_info_test
+ * * All behavior defined by the @ref hal_ticker_shared "ticker specification"
+ *
+ * # Undefined behavior
+ * * See the @ref hal_ticker_shared "ticker specification"
+ *
+ * @see hal_us_ticker_tests
+ *
  * @{
  */
+/**
+ * \defgroup hal_us_ticker_tests Microsecond Ticker tests
+ * Tests to validate the proper implementation of the microsecond ticker
+ *
+ * To run the microsecond ticker hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker*,tests-mbed_hal-us_ticker*
+ *
+ * @see hal_ticker_tests
+ *
+ */
+/**
+ * \defgroup hal_ticker_shared Ticker Hal
+ * Low level interface to the ticker of a target
+ *
+ * # Defined behavior
+ * * The function ticker_init is safe to call repeatedly - Verified by test ::ticker_init_test
+ * * The function ticker_init allows the ticker to keep counting and disables the ticker interrupt - Verified by test ::ticker_init_test
+ * * Ticker frequency is non-zero and counter is at least 8 bits - Verified by ::ticker_info_test
+ * * The ticker rolls over at (1 << bits) and continues counting starting from 0 - Verified by ::ticker_overflow_test
+ * * The ticker counts at the specified frequency +- 10% - Verified by ::ticker_frequency_test
+ * * The ticker increments by 1 each tick - Verified by ::ticker_increment_test
+ * * The ticker interrupt fires only when the ticker times increments to or past the value set by ticker_set_interrupt.
+ * Verified by ::ticker_interrupt_test and ::ticker_past_test
+ * * It is safe to call ticker_set_interrupt repeatedly before the handler is called - Verified by ::ticker_repeat_reschedule_test
+ * * The function ticker_fire_interrupt causes ticker_irq_handler to be called immediately from interrupt context -
+ * Verified by ::ticker_fire_now_test
+ * * The ticker operations ticker_read, ticker_clear_interrupt, ticker_set_interrupt and ticker_fire_interrupt
+ * take less than 20us to complete - Verified by ::ticker_speed_test
+ *
+ * # 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
+ *
+ * # Potential bugs
+ * * Drift due to reschedule - Verified by ::ticker_repeat_reschedule_test
+ * * Incorrect overflow handling of timers - Verified by ::ticker_overflow_test
+ * * Interrupting at a time of 0 - Verified by ::ticker_overflow_test
+ * * Interrupt triggered more than once - Verified by ::ticker_interrupt_test
+ *
+ * @ingroup hal_us_ticker
+ * @ingroup hal_lp_ticker
+ */
+/**
+ * \defgroup hal_ticker_tests Ticker Tests
+ * Tests to validate the proper implementation of a ticker
+ *
+ * To run the ticker hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker*
+ *
+ * @ingroup hal_us_ticker
+ * @ingroup hal_lp_ticker
+ */
+typedef void (*ticker_irq_handler_type)(const ticker_data_t *const);
+/** Set ticker IRQ handler
+ *
+ * @param ticker_irq_handler IRQ handler to be connected
+ *
+ * @return previous ticker IRQ handler
+ *
+ * @note by default IRQ handler is set to ::ticker_irq_handler
+ * @note this function is primarily for testing purposes and it's not required part of HAL implementation
+ *
+ */
+ticker_irq_handler_type set_us_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler);
 /** Get ticker's data
+ *
  * @return The low power ticker data
  */
 const ticker_data_t* get_us_ticker_data(void);
+ * @return The microsecond ticker data
+ */
+const ticker_data_t *get_us_ticker_data(void);
 …
 /** Initialize the ticker
+ *
+ * Initialize or re-initialize the ticker. This resets all the
+ * clocking and prescaler registers, along with disabling
+ * the compare interrupt.
+ *
+ * @note Initialization properties tested by ::ticker_init_test
+ *
+ * Pseudo Code:
+ * @code
+ * void us_ticker_init()
+ * {
+ *     // Enable clock gate so processor can read TIMER registers
+ *     POWER_CTRL |= POWER_CTRL_TIMER_Msk;
+ *
+ *     // Disable the timer and ensure it is powered down
+ *     TIMER_CTRL &= ~(TIMER_CTRL_ENABLE_Msk | TIMER_CTRL_COMPARE_ENABLE_Msk);
+ *
+ *     // Configure divisors
+ *     uint32_t prescale = SystemCoreClock / 1000000;
+ *     TIMER_PRESCALE = prescale - 1;
+ *     TIMER_CTRL |= TIMER_CTRL_ENABLE_Msk;
+ *
+ *     // Install the interrupt handler
+ *     NVIC_SetVector(TIMER_IRQn, (uint32_t)us_ticker_irq_handler);
+ *     NVIC_EnableIRQ(TIMER_IRQn);
+ * }
+ * @endcode
  */
 void us_ticker_init(void);
+/** Deinitialize the us ticker
+ *
+ * Powerdown the us ticker in preparation for sleep, powerdown, or reset.
+ *
+ * After this function is called, no other ticker functions should be called
+ * except us_ticker_init(), calling any function other than init is undefined.
+ *
+ * @note This function stops the ticker from counting.
+ *
+ * Pseudo Code:
+ * @code
+ * uint32_t us_ticker_free()
+ * {
+ *     // Disable timer
+ *     TIMER_CTRL &= ~TIMER_CTRL_ENABLE_Msk;
+ *
+ *     // Disable the compare interrupt
+ *     TIMER_CTRL &= ~TIMER_CTRL_COMPARE_ENABLE_Msk;
+ *
+ *     // Disable timer interrupt
+ *     NVIC_DisableIRQ(TIMER_IRQn);
+ *
+ *     // Disable clock gate so processor cannot read TIMER registers
+ *     POWER_CTRL &= ~POWER_CTRL_TIMER_Msk;
+ * }
+ * @endcode
+ *
+ */
+void us_ticker_free(void);
 /** Read the current counter
+ *
+ * @return The current timer's counter value in microseconds
+ * Read the current counter value without performing frequency conversions.
+ * If no rollover has occurred, the seconds passed since us_ticker_init()
+ * was called can be found by dividing the ticks returned by this function
+ * by the frequency returned by ::us_ticker_get_info.
+ *
+ * @return The current timer's counter value in ticks
+ *
+ * Pseudo Code:
+ * @code
+ * uint32_t us_ticker_read()
+ * {
+ *     return TIMER_COUNT;
+ * }
+ * @endcode
  */
 uint32_t us_ticker_read(void);
 …
 /** Set interrupt for specified timestamp
+ *
+ * @param timestamp The time in microseconds to be set
+ * @param timestamp The time in ticks to be set
+ *
+ * @note no special handling needs to be done for times in the past
+ * as the common timer code will detect this and call
+ * us_ticker_fire_interrupt() if this is the case
+ *
+ * @note calling this function with timestamp of more than the supported
+ * number of bits returned by ::us_ticker_get_info results in undefined
+ * behavior.
+ *
+ * Pseudo Code:
+ * @code
+ * void us_ticker_set_interrupt(timestamp_t timestamp)
+ * {
+ *     TIMER_COMPARE = timestamp;
+ *     TIMER_CTRL |= TIMER_CTRL_COMPARE_ENABLE_Msk;
+ * }
+ * @endcode
  */
 void us_ticker_set_interrupt(timestamp_t timestamp);
 …
 /** Disable us ticker interrupt
+ *
+ * Pseudo Code:
+ * @code
+ * void us_ticker_disable_interrupt(void)
+ * {
+ *     // Disable the compare interrupt
+ *     TIMER_CTRL &= ~TIMER_CTRL_COMPARE_ENABLE_Msk;
+ * }
+ * @endcode
  */
 void us_ticker_disable_interrupt(void);
 …
 /** Clear us ticker interrupt
+ *
+ * Pseudo Code:
+ * @code
+ * void us_ticker_clear_interrupt(void)
+ * {
+ *     // Write to the ICR (interrupt clear register) of the TIMER
+ *     TIMER_ICR = TIMER_ICR_COMPARE_Msk;
+ * }
+ * @endcode
  */
 void us_ticker_clear_interrupt(void);
+/** Set pending interrupt that should be fired right away.
+ *
+ * The ticker should be initialized prior calling this function.
+ *
+ * Pseudo Code:
+ * @code
+ * void us_ticker_fire_interrupt(void)
+ * {
+ *     NVIC_SetPendingIRQ(TIMER_IRQn);
+ * }
+ * @endcode
+ */
+void us_ticker_fire_interrupt(void);
+/** Get frequency and counter bits of this ticker.
+ *
+ * Pseudo Code:
+ * @code
+ * const ticker_info_t* us_ticker_get_info()
+ * {
+ *     static const ticker_info_t info = {
+ *         1000000,    // 1 MHz
+ *         32          // 32 bit counter
+ *     };
+ *     return &info;
+ * }
+ * @endcode
+ */
+const ticker_info_t *us_ticker_get_info(void);
 /**@}*/

Context Navigation

Legend:

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/can_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/can_helper.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/ethernet_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/gpio_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/i2c_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/lp_ticker_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_gpio.c

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_lp_ticker_api.c

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_pinmap_common.c

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_ticker_api.c

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/mbed_us_ticker_api.c

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/rtc_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/sleep_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/spi_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/ticker_api.h

asp3_tinet_ecnl_arm/trunk/asp3_dcre/mbed/hal/us_ticker_api.h

Download in other formats: