thread.h

Simple Operating Systems （简称SOS）是一个可以运行在X86平台上（包括QEMU

/* Copyright (C) 2004,2005 David Decotigny

   This program is free software; you can redistribute it and/or
   modify it under the terms of the GNU General Public License
   as published by the Free Software Foundation; either version 2
   of the License, or (at your option) any later version.
   
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.
   
   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
   USA. 
*/
#ifndef _SOS_THREAD_H_
#define _SOS_THREAD_H_

/**
 * @file thread.h
 *
 * SOS Thread management API
 */

#include <sos/errno.h>

/* Forward declaration */
struct sos_thread;

#include <hwcore/cpu_context.h>
#include <sos/sched.h>
#include <sos/kwaitq.h>
#include <sos/time.h>

/**
 * The possible states of a valid thread
 */
typedef enum { SOS_THR_CREATED, /**< Thread created, not fully initialized */
	       SOS_THR_READY,   /**< Thread fully initialized or
				     waiting for CPU after having been
				     blocked or preempted */
	       SOS_THR_RUNNING, /**< Thread currently running on CPU */
	       SOS_THR_BLOCKED, /**< Thread waiting for I/O (+ in at LEAST
				     one kwaitq) and/or sleeping (+ in NO
				     kwaitq) */
	       SOS_THR_ZOMBIE,  /**< Thread terminated execution, waiting to
				     be deleted by kernel */
             } sos_thread_state_t;


/**
 * TCB (Thread Control Block): structure describing a thread. Don't
 * access these fields directly: prefer using the accessor functions
 * below.
 */
struct sos_thread
{
#define SOS_THR_MAX_NAMELEN 32
  char name[SOS_THR_MAX_NAMELEN];

  sos_thread_state_t  state;

  /**
   * The hardware context of the thread.
   *
   * It will reflect the CPU state of the thread:
   *  - From an interrupt handler: the state of the thread at the time
   *    of the OUTERMOST irq. An IRQ is not allowed to make context
   *    switches, so this context will remain valid from the begining of
   *    the outermost IRQ handler to the end of it, no matter if there
   *    are other IRQ handlers nesting in one another. You may safely
   *    use it from IRQ handlers to query the state of the interrupted
   *    thread, no matter if there has been other IRQ handlers
   *    executing meanwhile.
   *  - From normal kernel code, exceptions and syscall: the state of
   *    the thread the last time there was a context switch from this
   *    thread to another one. Thus this field WON'T reflect the
   *    current's thread cpu_state in these cases. So, in these cases,
   *    simply DO NOT USE IT outside thread.c ! Note: for syscall and
   *    exception handlers, the VALID state of the interrupted thread is
   *    passed as an argument to the handlers.
   */
  struct sos_cpu_state *cpu_state;

  /* Kernel stack parameters */
  sos_vaddr_t kernel_stack_base_addr;
  sos_size_t  kernel_stack_size;

  /* Data specific to each state */
  union
  {
    struct
    {
      struct sos_thread     *rdy_prev, *rdy_next;
    } ready;
  }; /* Anonymous union (gcc extenion) */


  /*
   * Data used by the kwaitq subsystem: list of kwaitqueues the thread
   * is waiting for.
   *
   * @note: a RUNNING or READY thread might be in one or more
   * waitqueues ! The only property we have is that, among these
   * waitqueues (if any), _at least_ one has woken the thread.
   */
  struct sos_kwaitq_entry *kwaitq_list;


  /**
   * Chaining pointers for global ("gbl") list of threads (debug)
   */
  struct sos_thread *gbl_prev, *gbl_next;
};


/**
 * Definition of the function executed by a kernel thread
 */
typedef void (*sos_kernel_thread_start_routine_t)(void *arg);


/**
 * Initialize the subsystem responsible for thread management
 *
 * Initialize the primary kernel thread so that it can be handled the
 * same way as an ordinary thread created by sos_thread_create().
 */
sos_ret_t sos_thread_subsystem_setup(sos_vaddr_t init_thread_stack_base_addr,
				     sos_size_t init_thread_stack_size);


/**
 * Create a new kernel thread
 */
struct sos_thread *
sos_create_kernel_thread(const char *name,
			 sos_kernel_thread_start_routine_t start_func,
			 void *start_arg);


/**
 * Terminate the execution of the current thread. For kernel threads,
 * it is called by default when the start routine returns.
 */
void sos_thread_exit() __attribute__((noreturn));


/**
 * Get the identifier of the thread currently running on CPU. Trivial
 * function.
 */
struct sos_thread *sos_thread_get_current();


/**
 * If thr == NULL, get the state of the current thread. Trivial
 * function.
 *
 * @note NOT protected against interrupts
 */
sos_thread_state_t sos_thread_get_state(struct sos_thread *thr);


/**
 * Yield CPU to another ready thread.
 *
 * @note This is a BLOCKING FUNCTION
 */
sos_ret_t sos_thread_yield();


/**
 * Release the CPU for (at least) the given delay.
 *
 * @param delay The delay to wait for. If delay == NULL then wait
 * forever that any event occurs.
 *
 * @return SOS_OK when delay expired (and delay is reset to zero),
 * -SOS_EINTR otherwise (and delay contains the amount of time
 * remaining).
 *
 * @note This is a BLOCKING FUNCTION
 */
sos_ret_t sos_thread_sleep(/* in/out */struct sos_time *delay);


/**
 * Mark the given thread as READY (if not already ready) even if it is
 * blocked in a kwaitq or in a sleep ! As a result, the interrupted
 * kwaitq/sleep function call of the thread will return with
 * -SOS_EINTR.
 *
 * @return -SOS_EINVAL if thread does not exist, or -SOS_EFATAL if
 * marked ZOMBIE.
 *
 * @note As a result, the semaphore/mutex/conditions/... functions
 * return values SHOULD ALWAYS be checked ! If they are != SOS_OK,
 * then the caller should consider that the resource is not aquired
 * because somebody woke the thread by some way.
 */
sos_ret_t sos_thread_force_unblock(struct sos_thread *thread);


#endif /* _SOS_THREAD_H_ */