mwork.h

Go to the documentation of this file.

#ifndef EVE_MWORK_H_INCLUDED
#define EVE_MWORK_H_INCLUDED

/**********************************************************************/
/*
 * Copyright (c) 2013-2015, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

 /**
 * \file
 * \brief Header file for the EVE millisecond-scale work scheduling.
 *
 * \author DT, Jetro AS
 */ /******************************************************************/

#include <stdbool.h>
#include <stdint.h>
#include <lib/dlist.h>
#include <core/work.h>
#include <nrf52.h>
#include <hal/nrf_rtc.h>

/**
 * \defgroup eve_mwork msec work scheduler
 * \ingroup eve_scheduling
 * \{
 */

/**********************************************************************/
/**
 * Counter register width, bits.
 */
#define MWORK_COUNTER_WIDTH     (24)

/**********************************************************************/
/**
 * Amount of counter register LSB bits, reserved as synchronization quard
 */
#define MWORK_GUARD_WIDTH       (2)

/**********************************************************************/
/**
 * Effective width if counter register width, bits.
 */
#define MWORK_EFFECTIVE_WIDTH   (MWORK_COUNTER_WIDTH - MWORK_GUARD_WIDTH)

/**********************************************************************/
/**
 * Effective time mask.
 */
#define MWORK_TIME_MASK         ((1 << MWORK_EFFECTIVE_WIDTH) - 1)

/**********************************************************************/
/**
 * Round time by the effective width of the counter register.
 */
#define MWORK_ROUND_TIME(tick)  ((tick) & MWORK_TIME_MASK)

/**********************************************************************/
/**
 * Checks if mwork time span is negative.
 */
#define MWORK_TIME_SPAN_IS_NEGATIVE(span) \
                                (((span) & (1 << (MWORK_EFFECTIVE_WIDTH - 1))) != 0)

/**********************************************************************/
/**
 * Converts a time interval, given in number of milliseconds, to the number of ticks.
 *
 * \param ms duration of the time interval, milliseconds
 * \return number of ticks in the time interval
 */
#define MWORK_MSEC(ms)          MS_TO_TICKS(ms)

/**********************************************************************/
/**
 * Initializes a milliwork structure.
 *
 * The macro is used to initialize a millisecond-scale work (milliwork) structure instance.
 *
 * \param x milliwork structure
 * \param callback milliwork callback
 *
 * Usage:
 * \code
  static void MyWorkCallback(struct mwork_t *Work);
  struct mwork_t MyWork = MWORK_INIT(MyWork, MyWorkCallback);
 * \endcode
 */
#define MWORK_INIT(x, callback)  \
  {                                     \
    .work.link.next = &(x).work.link,   \
    .work.link.prev = &(x).work.link,   \
    .work.cb = (work_cb_t) (callback),  \
  }

/**********************************************************************/
/**
 * Initializes a milliwork structure. Typed version of \ref MWORK_INIT
 */
#define MWORK_INIT_TYPED(x, callback)  \
  (struct mwork_t) MWORK_INIT(x, callback)

/**********************************************************************/
/**
 * Instantiates a milliwork structure.
 *
 * The macro is used to instantiate a work structure.
 *
 * \param x name of the milliwork structure
 * \param callback the milliwork callback
 *
 * Usage:
 * \code
  static void MyWorkCallback(struct mwork_t *Work);
  DECLARE_MWORK(MyWork, MyWorkCallback);
 * \endcode
 */
#define DECLARE_MWORK(x, callback) \
  struct mwork_t x = MWORK_INIT(x, callback)

/* Forward declaration */
struct mwork_t;

/**********************************************************************/
/**
 * Milliwork time type.
 *
 * Only \ref MWORK_EFFECTIVE_WIDTH LSB bits are used, while MSB of them becomes
 * a sign bit, and the rest of the uint32_t is ignored by the framework.
 * So, the max interval for the milliwork is 2^(24-2-1)-1 = 2097151 ticks,
 * or ~34 min. Please use OS etimer for longer intervals.
 */
typedef uint32_t mwork_time_t;

/**********************************************************************/
/**
 * Milliwork callback type.
 *
 * \param work pointer to the milliwork structure
 */
typedef void (*mwork_cb_t)(struct mwork_t *work);

/**********************************************************************/
/**
 * Milliwork structure.
 *
 * EVE millisecond-scale work or `milliwork` is a function with an associated data structure,
 * which can be scheduled for execution at specified time in future. The function is executed
 * at the software interrupt execution level.
 *
 * The structure represents the milliwork instance.
 *
 * The structure must be instantiated in the RAM memory using
 * one of \ref MWORK_INIT() or \ref DECLARE_MWORK().
 */
struct mwork_t {
  struct work_t work;                   /**< Underlaying work structure */
  mwork_time_t at;                      /**< Point in time the milliwork is scheduled for */
};

/**********************************************************************/
/**
 * Returns the current timestamp, which can be used as a time reference in struct mwork_t::at
 *
 * Usage:
 * \code
  MyWork.at = mwork_now() + MWORK_MSEC(100);
  mwork_schedule(&MyWork);
  // The work is scheduled and will be executed 100 ms later.
 * \endcode
 *
 * \return current timestamp in system ticks
 */
static inline mwork_time_t mwork_now()
{
  return nrf_rtc_counter_get(NRF_RTC1) >> MWORK_GUARD_WIDTH;
}

/**********************************************************************/
/**
 * Schedules a milliwork.
 *
 * The function schedules a milliwork for execution at the specified point in time.
 * The milliwork will be executed at the software interrupt level, like a work item.
 * It is allowed to schedule a milliwork in the past. In this case it is triggered
 * for execution immediately.
 *
 * If two or more milliworks are scheduled for the same tick, they will be executed
 * in the same order as thay were scheduled. Due to non-preemptive execution of work
 * items and milliworks at the software interrupt level, the actual time when the
 * milliwork execution starts can vary.
 *
 * If the milliwork structure, pointed by the `work` parameter is already scheduled
 * for execution, then it is re-scheduled at the new time.
 *
 * A scheduled milliwork holds system at PM_LEVEL_LOWPWR power level.
 *
 * \param work pointer to the milliwork structure
 */
void mwork_schedule(struct mwork_t *work);

/**********************************************************************/
/**
 * Cancels a scheduled milliwork.
 *
 * The function cancels a previously scheduled work.
 *
 * \param work pointer to the milliwork structure
 */
void mwork_cancel(struct mwork_t *work);

/**********************************************************************/
/**
 * Checks if the milliwork is scheduled and pending execution.
 *
 * The function checks if the milliwork is scheduled for execution.
 *
 * \param work pointer to the milliwork structure
 * \return true if the milliwork is scheduled for execution
 * \return false if the milliwork is not scheduled
 * \return false if the milliwork is being executed
 */
static inline bool mwork_pending(struct mwork_t *work)
{
  return !dlist_is_empty(&work->work.link);
}

/**********************************************************************/
/**
 * \internal
 *
 */ /******************************************************************/

/**********************************************************************/
/**
 * Milliwork timer
 */
void mwork_timer(void);

/** @} eve_mwork */

#endif /* EVE_MWORK_H_INCLUDED */