work.h

Go to the documentation of this file.

#ifndef EVE_WORK_H_INCLUDED
#define EVE_WORK_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 work scheduling.
 *
 * \author DT, Jetro AS
 */ /******************************************************************/

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

/**
 * \defgroup eve_work Generic work scheduler
 * \ingroup eve_scheduling
 * \{
 */

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

/**********************************************************************/
/**
 * Initializes a work structure. Typed version of \ref WORK_INIT
 */
#define WORK_INIT_TYPED(work, callback)  \
  (struct work_t) WORK_INIT(work, callback)

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

/**********************************************************************/
/**
 * Declares an anonymous software interrupt lock, which disables
 * software interrupts in scope of the the auto variable visibility block
 *
 * Usage:
 * \code
  {
    SWINT_AUTO_LOCK();
    // Do something protected by the lock
  }
  // The lock is released here
 * \endcode
 *
 * Note: taking in mind lazy nature of releasing the clock locks, use of auto clock locks is negligible. 
 */
#define SWINT_AUTO_LOCK() \
  swint_state_t swint_auto_lock_state __attribute__((cleanup(swint_enable_indirect_adapter))); \
  do { swint_auto_lock_state = swint_disable(); } while (0)

/* Forward declaration */
struct work_t;

/**********************************************************************/
/**
 * Work callback type.
 *
 * \param work pointer to the work structure
 */
typedef void (*work_cb_t)(struct work_t *work);

/**********************************************************************/
/**
 * Work structure.
 *
 * EVE `work item` is a function with an associated data structure,
 * which can be executed at the software interrupt execution level.
 *
 * The structure represents the work item instance.
 *
 * The structure must be instantiated in the RAM memory using
 * one of \ref WORK_INIT() or \ref DECLARE_WORK().
 */
struct work_t {
  struct dlist_t link;                  /**< Linked list of all scheduled work items */
  work_cb_t cb;                         /**< Callback function to be called for the work */
};

/**********************************************************************/
/**
 * Software interrupt state.
 *
 * The structure holds state if the software interrupts are enabled.
 */
typedef struct {
  bool disabled;                        /**< true if software interrupt processing is disabled */
} swint_state_t;

/**********************************************************************/
/**
 * Schedules a work.
 *
 * The function schedules a work item for execution at the software interrupt level.
 * Depending on the current interrupt level and the software interrupt enable status,
 * the work item callback may be called immediately or be queued until the software
 * interrupt level is available.
 *
 * Framework keeps order of execution of the scheduled work items. First scheduled work
 * is executed first.
 *
 * Is the work structure, pointed by the `work` parameter is already scheduled for execution,
 * then it is re-scheduled at the tail of the work queue.
 *
 * \param work pointer to the work structure
 */
void work_schedule(struct work_t *work);

/**********************************************************************/
/**
 * Removes a work from the work queue.
 *
 * The function removes a previously scheduled work from the work queue.
 *
 * \param work pointer to the work structure
 */
void work_cancel(struct work_t *work);

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

/**********************************************************************/
/**
 * Disables software interrupt processing
 *
 * The function disables software interrupt processing
 *
 * Usage:
 * \code
  swint_state_t swint_state = swint_disable();
  // Do something atomically
  swint_enable(swint_state);
 * \endcode
 *
 * \return previous software interrupt status
 */
swint_state_t swint_disable(void);

/**********************************************************************/
/**
 * Restores software interrupt processing
 *
 * The function conditionally enables software interrupt processing
 *
 * Usage:
 * \code
  swint_state_t swint_state = swint_disable();
  // Do something atomically
  swint_enable(swint_state);
 * \endcode
 *
 * \param state state, obtained by corresponding swint_disable() call
 */
void swint_enable(swint_state_t state);

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


/**********************************************************************/
/**
 * Cleanup adapter for SWINT_AUTO_LOCK()
 */
__attribute__((always_inline))
static inline void swint_enable_indirect_adapter(swint_state_t *state)
{
  swint_enable(*state);
}

/** \} eve_work */

#endif /* EVE_WORK_H_INCLUDED */