thread.h

Go to the documentation of this file.

#ifndef EVE_THREAD_H_INCLUDED
#define EVE_THREAD_H_INCLUDED

/**********************************************************************/
/*
 * Copyright (c) 2016, 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 thread emulation layer.
 *
 * \author DT, Jetro AS
 */ /******************************************************************/

#include <lib/dlist.h>

/**
 * \defgroup thread Thread emulation
 * \ingroup eve_scheduling
 * \{
 *
 * Thread emulation layer provides RTOS-like thread abstraction on top of
 * Contiki protothreads. The threads use a common physical call stack,
 * exactly like the Contiki protothreads do, but the stack content can be
 * saved in an external buffer at thread yield. The stored stack state
 * can be restored later, emulating resuming of the thread.
 * In general it resembles setjmp() / longjmp() semantic, but with addition
 * to stack snapshoting and "return to jump point" functionality.
 */

/**
 * \def EVE_THREAD_EMBEDDED_CSTATE
 * Normally disabled, reduces static RAM usage but increrases dynaamic one
 * and CPU clocks required.
 */
#define EVE_THREAD_EMBEDDED_CSTATE 0

/**
 * \def EVE_THREAD_FPU_SUPPORT
 * Normally enabled, allows FPU usage in the treads
 */
#define EVE_THREAD_FPU_SUPPORT 1

/**
 * \def THREAD_CPU_REGISTERS_COUNT
 * Number of registers stored in the context
 */
#if EVE_THREAD_FPU_SUPPORT != 0
  #define THREAD_CPU_REGISTERS_COUNT    (16 + 9) /* {s16-s31, r4-r11, r15} */
#else /* EVE_THREAD_FPU_SUPPORT */
  #define THREAD_CPU_REGISTERS_COUNT    (9) /* {r4-r11, r15} */
#endif /* EVE_THREAD_FPU_SUPPORT */

#if EVE_THREAD_EMBEDDED_CSTATE != 0
  #define THREAD_CPU_STATE_REGISTER_COUNT 0
#else /* EVE_THREAD_EMBEDDED_CSTATE */
  #define THREAD_CPU_STATE_REGISTER_COUNT THREAD_CPU_REGISTERS_COUNT
#endif /* EVE_THREAD_EMBEDDED_CSTATE */

/**
 * Stack pool state (dynanic)
 */
struct stack_pool_state_t
{
  struct dlist_t Head;                  /**< Linked list of allocated stacks */
  uint32_t Reserved;
};

/**
 * Stack pool instance (constant)
 */
struct stack_pool_t
{
  struct stack_pool_state_t *State;     /**< Pointer to the state of the stack pool */
  uint32_t *Arena;                      /**< Pointer to the memory buffer allocated for the pool */
  uint32_t ArenaSize;                   /**< Size of the stack pool memory buffer */
};

/**
 * Thread state (dynanic)
 */
struct thread_t
{
  struct dlist_t Link;                  /**< Linked list entry */
  uint32_t *Mark;                       /**< Base stack pointer for the thread */
  uint32_t *Sp;                         /**< Stack pointer at ThreadBegin() entry */
  uint32_t Stack;                       /**< Offset in the stack pool to the allocated stack snapshot */
  uint32_t StackSize;                   /**< Amount of bytes used for the thread in the stack pool */
  uint32_t StackReserved;               /**< Amount of bytes allocated for the thread in the stack pool */
  const struct stack_pool_t *Pool;      /**< Pointer to the thread's stack pool */
  uint32_t CpuState[THREAD_CPU_STATE_REGISTER_COUNT]; /**< CPU state at ThreadYield() entry */
  uint32_t BackjumpState[THREAD_CPU_REGISTERS_COUNT]; /**< CPU state at ThreadBegin() entry */
};

/**********************************************************************/
/**
 * Starts or resumes thread execution
 *
 * \param Thread  pointer to the thread instance
 */
uint32_t ThreadBegin(struct thread_t *Thread);

/**********************************************************************/
/**
 * Yields the thread and returns control to the return of ThreadBegin
 *
 * \param Thread  pointer to the thread instance
 * \param Value   value to be passed as the return code of ThreadBegin
 */
void ThreadYield(struct thread_t *Thread, uint32_t Value);

/**********************************************************************/
/**
 * Ends the thread ans deallocates stack from the stack pool
 *
 * \param Thread  pointer to the thread instance
 */
void ThreadEnd(struct thread_t *Thread);

/** @} */ /* thread */

#endif /* EVE_THREAD_H_INCLUDED */