picoos.h

picoos源码。The RTOS and the TCP/IP stack will be built automatically.

/*
 * License:  Modified BSD license, see documentation below.
 *
 * This file is originally from the pico]OS realtime operating system
 * (http://picoos.sourceforge.net).
 *
 * CVS-ID $Id: picoos.h,v 1.25 2006/04/29 16:04:22 dkuschel Exp $
 *
 */

/**
 * @file    picoos.h
 * @brief   pico]OS main include file
 * @author  Dennis Kuschel
 */

/**
 * @mainpage pico]OS - Real Time Operating System
 *
 * <b> Table Of Contents </b>@n@htmlonly<font size="-1">@endhtmlonly
 * <ul><li>@ref overview <ul>
 *   <li> @ref features </li><li> @ref ports     </li>
 *   <li> @ref files    </li><li> @ref license   </li></ul></li></ul>
 * <ul><li> @ref intro <ul>
 *   <li> @ref layer    </li><li> @ref port      </li>
 *   <li> @ref debug    </li><li> @ref make      </li></ul></li></ul>
 * <ul><li><b>Configuration</b><ul>
 *   <li><b>Pico Layer</b><ul>
 *     <li> @ref arch     </li><li> @ref codestyle </li>
 *     <li> @ref lock     </li><li> @ref feature   </li>
 *     <li> @ref findbit  </li><li> @ref portnlcfg </li>
 *     <li> @ref coreset  </li></ul></li></ul><ul>
 *   <li><b>Nano Layer</b><ul>
 *     <li> @ref cfgabstr </li><li> @ref cfgnosbh </li>
 *     <li> @ref cfgnoscio</li><li> @ref cfgcpuu  </li>
 *     <li> @ref cfgnosmem</li><li> @ref cfgnosreg</li></ul></li></ul>
 * </li></ul><ul><li><b>User API Function Reference</b><ul>
 *   <li><b>Pico Layer</b><ul>
 *     <li> @ref atomic   </li><li> @ref errcodes </li>
 *     <li> @ref flag     </li><li> @ref lists    </li>
 *     <li> @ref msg      </li><li> @ref mutex    </li>
 *     <li> @ref sema     </li><li> @ref sint     </li>
 *     <li> @ref task     </li><li> @ref timer    </li></ul></li>
 *   <li><b>Nano Layer</b><ul><li> @ref absfunc <ul>
 *       <li> @ref nanoflag </li><li> @ref nanomsg  </li>
 *       <li> @ref nanomutex</li><li> @ref nanosema </li>
 *       <li> @ref nanotask </li><li> @ref nanotimer</li></ul></li>
 *     <li> @ref bhalf    </li><li> @ref conio    </li>
 *     <li> @ref cpuusage </li><li> @ref nanoinit </li>
 *     <li> @ref mem      </li><li> @ref registry </li></ul></li></ul>
 * </li></ul>@htmlonly</font>@endhtmlonly@n<hr>@n
 * 
 * @section overview Overview
 * pico]OS is a highly configurable and very fast real time operating
 * system. It targets a wide range of architectures, from the small
 * 8 bit processors with very low memory till huge architectures
 * like 32 bit processors with lots of memory.@n@n@n
 *
 * @subsection features Features
 * pico]OS is currently divided into two layer. The <b>pico-layer</b>
 * (the core of the operating system) includes this features:
 *
 * <b>Scheduler:</b>
 *  - two modes: standard priority based or round robin
 *  - preemptive multitasking
 *  - max. 64 tasks on 8 bit processors,
 *    max. 1024 tasks on 32 bit processors
 *  - round robin: max. 8 priority level on 8 bit processors,
 *    max. 32 priority level on 32 bit processors
 *
 * <b>Events:</b>
 *  - the number of events is unlimited
 *  - semaphores
 *  - mutexes
 *  - flag events
 *
 * <b>Message Boxes:</b>
 *  - one built in message box per task
 *  - unlimited box size, messages are collected
 *  - messages can be pointers or huge buffers
 *
 * <b>Timer:</b>
 *  - autonomous running timer, the system timer interrupt is used as timebase
 *  - timer can work in one shot mode or in auto reload mode
 *  - when a timer expires, it triggers a semaphore event
 *
 * <b>Software Interrupts:</b>
 *  - up to 256 simulated software interrupts on 8 bit processors
 *  - can be used to interface fast hardware interrupts outside the scope of
 *    pico]OS to the operating system
 *
 * <b>Miscellaneous:</b>
 *  - atomic variables
 *  - blocking and nonblocking lists
 *  - debugging support allows access to internal structures
 *
 * @n
 * The optional <b>nano-layer</b> supports:
 *
 *  - Bottom Halfs for interrupt service routines
 *  - Multitasking able console I/O
 *  - Multitasking able dynamic memory management
 *  - Standardized API for easier task creation
 *  - Named tasks, semaphores, mutexes and timer
 *  - CPU usage measurement
 *
 * @n@n
 * @subsection ports Available Ports
 *
 * Currently, ports to the following platforms are available:
 *
 *  - Intel 80x86 in real mode, the executable is loadable from DOS
 *  - MS Windows 32bit port, usefull for software development and debugging
 *  - 6502 / 65c02 / 6510 series, port for Commodore 64 available.
 *    Minimum configuration (4 tasks): 4.6kb code, 4.7kb data
 *  - PowerPC: IBM PPC440  (GNU C and MetaWare compiler supported)
 *  - AVR (ATMega, GNU C compiler supported)
 *  - ARM: SAMSUNG S3C2510A CPU (ARM940T core), Philips LPC ARM chips
 *
 * @n@n
 * @subsection files Files
 *
 * The pico]OS Real Time Operating System consists of only
 * a couple of files:
 *
 *  - picoos.h 
 *       - This header is the interface to the operating system.
 *         It is included by the pico]OS core and must also be
 *         included by user applications. 
 *  - poscfg.h
 *       - pico]OS configuration file. Must be supplied by the user.
 *  - noscfg.h
 *       - nano layer configuration file. Must be supplied by the user.
 *  - port.h
 *       - Configuration file for the port.
 *         Must be supplied by the user / port developer.
 *  - picoos.c
 *       - The pico]OS core source file. This is the operating system.
 *  - n_xxxx.c
 *       - The nano layer source files.
 *  - fbit_gen.c 
 *       - This file implements a set of generic "findbit" functions.
 *         The "findbit" function is needed by the operating system.
 *         The user may support its own "findbit" function to
 *         increase performance on a particular architecture.
 *  - arch_c.c
 *       - User supplied file. This is the architecture specific C-code
 *         of the platform port.
 *  - arch_a.asm
 *       - User supplied file (optional). This is the architecture specific
 *         assembler code of the platform port.
 * 
 * @n@n
 * @section license License
 *
 *  Copyright (c) 2004-2006, Dennis Kuschel. @n
 *  All rights reserved. @n
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met: @n
 *
 *   -# Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *   -# 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.
 *   -# 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 ``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. @n
 *
 * @n@n
 * @section cont Contact Information
 * Dennis Kuschel @n
 * Emanuel-Backhaus-Strasse 20 @n
 * 28277 Bremen @n
 * GERMANY @n
 *
 * mail: [e-mail] @n
 * web:  http://picoos.sourceforge.net @n
 *
 * (C) 2004-2006 Dennis Kuschel
 */

/** @defgroup intro     Introduction */
/** @defgroup configp   Configuration: Pico Layer */
/** @defgroup confign   Configuration: Nano Layer */
/** @defgroup userapip  User API: Pico Layer */
/** @defgroup userapin  User API: Nano Layer */

/** @defgroup layer The Layer Scheme
 * @ingroup intro
 * @{
 *
 * pico]OS is currently split into two layers:
 *
 *   - The pico layer contains the RTOS core. It covers:
 *      - Tasks
 *      - Semaphores
 *      - Mutexes
 *      - Flag Events
 *      - Message Boxes
 *      - Software Interrupts
 *      - Timers
 *      - Lists
 *      - Atomic Variables
 *
 *   - The nano layer contains features that are based on the pico layer:
 *      - Bottom Halfs
 *      - Multitasking able console I/O
 *      - Multitasking able dynamic memory management
 *      - Standardized API for easier task creation
 *      - Named tasks, semaphores, mutexes and timer
 *      - CPU usage measurement
 *      - etc. (more will follow)
 *
 * Below is a diagram showing the layer scheme. Note that the nano layer
 * is disabled by default to lower the memory usage for small devices.
 * There are two ways to enable the nano layer: First, if you run your
 * makefile, you can add the parameter @c NANO=1 to the make command line.
 * Second, you can set this parameter in your application makefile. @n
 * If the parameter @c NANO is set to 1, the makesystem will automatically
 * compile and link the nano layer source files. Also the global define
 * @c POSCFG_ENABLE_NANO is set, so you can test from within your sources
 * if the nano layer is enabled or not. @n@n
 *
 * <p><img src="../pic/layer.png" align="middle" border=0></p>@n@n@n
 *
 * @}
 */

#ifndef _PICOOS_H
#define _PICOOS_H


#define POS_VER_N           0x0100
#define POS_VER_S           "1.0.0"
#define POS_COPYRIGHT       "(c) 2004-2006, D.Kuschel"
#define POS_STARTUPSTRING   "pico]OS " POS_VER_S "  " POS_COPYRIGHT

#ifndef NULL
#define NULL ((void*)0)
#endif

#ifndef DOX
#define DOX  0
#endif
#if DOX==0

#include <port.h>
#include <poscfg.h>



/*---------------------------------------------------------------------------
 *  CONFIGURATION
 *-------------------------------------------------------------------------*/

/* test if all needed parameters are set */
#ifndef MVAR_t
#error  MVAR_t not defined
#endif
#ifndef MVAR_BITS
#error  MVAR_BITS not defined
#endif
#ifndef POSCFG_ALIGNMENT
#error  POSCFG_ALIGNMENT not defined
#endif
#ifndef POSCFG_MAX_PRIO_LEVEL
#error  POSCFG_MAX_PRIO_LEVEL not defined
#endif
#ifndef POSCFG_MAX_TASKS
#error  POSCFG_MAX_TASKS not defined
#endif
#ifndef POSCFG_MAX_EVENTS
#error  POSCFG_MAX_EVENTS not defined
#endif
#ifndef POSCFG_MAX_MESSAGES
#error  POSCFG_MAX_MESSAGES not defined
#endif
#ifndef POSCFG_MAX_TIMER
#error  POSCFG_MAX_TIMER not defined
#endif
#ifndef POSCFG_SOFT_MTASK
#error  POSCFG_SOFT_MTASK not defined
#endif
#ifndef POSCFG_CTXSW_COMBINE
#error  POSCFG_CTXSW_COMBINE not defined
#endif
#ifndef POSCFG_REALTIME_PRIO
#error  POSCFG_REALTIME_PRIO not defined
#endif
#ifndef POSCFG_ISR_INTERRUPTABLE
#error  POSCFG_ISR_INTERRUPTABLE not defined
#endif
#ifndef POSCFG_ROUNDROBIN
#error  POSCFG_ROUNDROBIN not defined
#endif
#ifndef POSCFG_TASKS_PER_PRIO
#error  POSCFG_TASKS_PER_PRIO not defined
#endif
#ifndef POSCFG_FASTCODE
#error  POSCFG_FASTCODE not defined
#endif
#ifndef POSCFG_SMALLCODE
#error  POSCFG_SMALLCODE not defined
#endif
#ifndef POSCFG_ARGCHECK
#error  POSCFG_ARGCHECK not defined
#endif
#ifndef POSCFG_MSG_MEMORY
#error  POSCFG_MSG_MEMORY not defined
#endif
#ifndef POSCFG_MSG_BUFSIZE
#error  POSCFG_MSG_BUFSIZE not defined
#endif
#ifndef POSCFG_DYNAMIC_MEMORY
#error  POSCFG_DYNAMIC_MEMORY not defined
#endif
#ifndef POSCFG_DYNAMIC_REFILL
#error  POSCFG_DYNAMIC_REFILL
#endif
#if POSCFG_DYNAMIC_MEMORY != 0
#ifndef POS_MEM_ALLOC
#error  POS_MEM_ALLOC not defined
#endif
#ifndef POS_MEM_ALLOC
#error  POS_MEM_ALLOC not defined
#endif
#endif
#ifndef POSCFG_CALLINITARCH
#error  POSCFG_CALLINITARCH not defined
#endif
#ifndef POSCFG_LOCK_USEFLAGS
#error  POSCFG_LOCK_USEFLAGS not defined
#endif
#if POSCFG_LOCK_USEFLAGS != 0