uwork.h

Go to the documentation of this file.

#ifndef EVE_UWORK_H_INCLUDED
#define EVE_UWORK_H_INCLUDED

/**********************************************************************/
/*
 * Copyright (c) 2014-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 microsecond-scale work scheduling.
 *
 * \author DT, Jetro AS
 */ /******************************************************************/

#include <stdbool.h>
#include <lib/dlist.h>
#include <core/work.h>

/**
 * \defgroup eve_uwork usec work scheduler
 * \ingroup eve_scheduling
 * \{
 */

/**********************************************************************/
/**
 * Converts a time interval, given in number of microseconds, to the number of microticks.
 *
 * \param us duration of the time interval, microseconds
 * \return number of microticks in the time interval
 */
#define UWORK_USEC(us) (us)

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

/**********************************************************************/
/**
 * Initializes a microwork structure. Typed version of \ref UWORK_INIT
 */
#define UWORK_INIT_TYPED(x, callback)  \
  (struct uwork_t) UWORK_INIT(x, callback)

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

/* Forward declaration */
struct uwork_t;

/**********************************************************************/
/**
 * Microwork time type.
 *
 * MSB is used as a sign bit, so, the max interval for the microwork
 * is 2^(32-1)-1 = 2147483647 us, or ~35 min. Please use OS etimer for
 * longer intervals.
 * Note that system holds high-frequency clock on if a microwork is scheduled.
 */
typedef int32_t uwork_time_t;

/**********************************************************************/
/**
 * Microwork callback type.
 *
 * \param work pointer to the microwork structure
 */
typedef void (*uwork_cb_t)(struct uwork_t *work);

/**********************************************************************/
/**
 * Microwork structure.
 *
 * EVE microsecond-scale work or `microwork` 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 hardware interrupt execution level.
 *
 * The structure represents the microwork instance.
 *
 * The structure must be instantiated in the RAM memory using
 * one of \ref UWORK_INIT() or \ref DECLARE_UWORK().
 */
struct uwork_t {
  struct work_t work;                   /**< Underlaying work structure */
  uwork_time_t at;                      /**< Point in time the microwork is scheduled for */
};

/**********************************************************************/
/**
 * Returns the current timestamp, which can be used as a time reference in struct uwork_t::at
 *
 * Usage:
 * \code
  MyWork.at = uwork_now() + UWORK_USEC(300);
  uwork_schedule(&MyWork);
  // The work is scheduled and will be executed 300 µs later.
 * \endcode
 *
 * \return current timestamp in microsecond-scale `microticks`
 */
uwork_time_t uwork_now(void);

/**********************************************************************/
/**
 * Schedules a microwork.
 *
 * The function schedules a microwork for execution at the specified point in time.
 * The microwork will be executed at the hardware interrupt level. It is allowed to
 * schedule a microwork in the past. In this case it is triggered for execution
 * immediately.
 *
 * If two or more microworks are scheduled for the same tick, they will be executed
 * in the same order as thay were scheduled. As hardware interrupt routines,
 * microworks preempt software interrupts (that implies also works and milliworks)
 * and OS processes. A microwork selv can be preempted by high-priority low-level BLE
 * radio interrupts.
 *
 * If the microwork structure, pointed by the `work` parameter is already scheduled
 * for execution, then it is re-scheduled at the new time.
 *
 * A scheduled microwork holds system at PM_LEVEL_CONSTLAT power level.
 *
 * \param work pointer to the microwork structure
 */
void uwork_schedule(struct uwork_t *work);

/**********************************************************************/
/**
 * Cancels a scheduled microwork.
 *
 * The function cancels a previously scheduled work.
 *
 * \param work pointer to the microwork structure
 */
void uwork_cancel(struct uwork_t *work);

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

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


/**********************************************************************/
/**
 * Initializes the microwork framework
 */
void uwork_init(void);

/** \} eve_uwork */

#endif /* EVE_UWORK_H_INCLUDED */