rom400_task.h

tini的http-slientC程序

/*---------------------------------------------------------------------------
 *  Copyright (C) 2003 Dallas Semiconductor Corporation, All Rights Reserved.
 * 
 *  Permission is hereby granted, free of charge, to any person obtaining a
 *  copy of this software and associated documentation files (the "Software"),
 *  to deal in the Software without restriction, including without limitation
 *  the rights to use, copy, modify, merge, publish, distribute, sublicense,
 *  and/or sell copies of the Software, and to permit persons to whom the
 *  Software is furnished to do so, subject to the following conditions:
 * 
 *  The above copyright notice and this permission notice shall be included
 *  in all copies or substantial portions of the Software.
 * 
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 *  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *  MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *  IN NO EVENT SHALL DALLAS SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, DAMAGES
 *  OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *  ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *  OTHER DEALINGS IN THE SOFTWARE.
 * 
 *  Except as contained in this notice, the name of Dallas Semiconductor
 *  shall not be used except as stated in the Dallas Semiconductor
 *  Branding Policy.
 * ---------------------------------------------------------------------------
 *
 * This file contains function definitions for the built-in ROM functions 
 * of the Dallas Semiconductor 400 processor.  This file is intended for use 
 * with the Keil MicroVision (uVision) C compiler.
 *
 * ---------------------------------------------------------------------------
 */
#ifndef __rom400_task_
#define __rom400_task_

/** \file rom400_task.h
 *  \brief Process scheduler functions in the DS80C400 ROM
 *
 *  This library contains functions for starting, suspending, 
 *  killing, and managing tasks using the ROM's process scheduler.
 *  
 *  For detailed information on the DS80C400 please see the
 *  <a href="http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf">
 *  High-Speed Microcontroller User's Guide: DS80C400 Supplement</a>.
 *
 *  \warning  Some functions in this library are <b>NOT</b> multi-process 
 *            safe--that is, if you call the same method from two different 
 *            processes at the same time, the parameters to the function 
 *            may be destroyed, yielding unpredictable results.  Consult
 *            each individual funtion's documentation for details on which
 *            functions are multi-process safe.
 */

/** Version number associated with this header file.  Should be the same as
 * the version number returned by the <i>#task_version</i> function.
 * \sa #task_version */
#define ROM400_TASK_VERSION         8

/// Included for legacy reasons.  Please use #ROM400_TASK_VERSION instead.
#define ROM400_SCHED_VERSION         ROM400_TASK_VERSION

/** Timer reload value for 14.746 MHz crystal.
 * \sa #task_settickreload
 * \sa #task_gettickreload */
#define RELOAD_14_746 0xfb33

/** Timer reload value for 18.432 MHz crystal.
 * \sa #task_settickreload
 * \sa #task_gettickreload */
#define RELOAD_18_432 0xfa00

/** Timer reload value for 29.491 MHz crystal.
 * \sa #task_settickreload
 * \sa #task_gettickreload */
#define RELOAD_29_491 0xfd99

/** Timer reload value for 36.864 MHz crystal.
 * \sa #task_settickreload
 * \sa #task_gettickreload */
#define RELOAD_36_864 0xfd00

/** Timer reload value for 58.982 MHz crystal.
 * \sa #task_settickreload
 * \sa #task_gettickreload */
#define RELOAD_58_982 0xfecc

/** Timer reload value for 73.728 MHz crystal.
 * \sa #task_settickreload
 * \sa #task_gettickreload */
#define RELOAD_73_728 0xfe80


/** Minimum priority level assignable to a task.
 * \sa #task_setpriority
 * \sa #task_getpriority */
#define MIN_PRIORITY    1
/** Normal priority for a task.  This is the default priority for the default task.
 * \sa #task_setpriority
 * \sa #task_getpriority */
#define NORM_PRIORITY   128
/** Maximum priority level assignable to a task.
 * \sa #task_setpriority
 * \sa #task_getpriority */
#define MAX_PRIORITY    255

/** Flag for putting a task to sleep.
 * \sa #task_wait */
#define FLAG_SLEEPING   1
/** Flag for putting a task to sleep.
 * \sa #task_wait */
#define FLAG_IO_WAIT    2
/** Flag for putting a task to sleep.
 * \sa #task_wait */
#define FLAG_DHCP_WAIT  4

/** Default size for task switching buffer.
 * \sa #task_genesis */
#define ROM_SAVESIZE    384

/** Structure to be used when handling the DS80C400's 5 byte time values.
 * \sa #task_gettimemillis
 */
struct TIME
{
    /// Most significatnt byte of the time stamp.  The Keil compiler does not have data types longer than 4 bytes.
    unsigned char msb;
    /// The lower 4 bytes of a DS80C400 time stamp (in milliseconds).  This will cover up to 49.7 days.
    unsigned long millis;
};

/**
 * Task control buffer.
 */
struct TCB
{
    unsigned char Priority;     ///< Priority of the task
    unsigned char ID;           ///< ID of the task
    void*         Next;         ///< Next task in the queue
    unsigned char Flags;        ///< Flags for the task
    struct TIME   WakeupTime;   ///< Time that the task is scheduled to wake from a sleep
    unsigned int  StateSize;    ///< Size of the saved state for the task
    void*         StatePtr;     ///< Pointer to the saved state for the task
};

/**
 * \brief     Initializes the process scheduler.
 *
 * Note that calling the function <i>#init_rom</i> from the initialization
 * library is the preferred way of initializing the ROM.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     savesize Size of the task buffer for saving information on task switches.
 */
//---------------------------------------------------------------------------
void           task_genesis(unsigned int savesize);

/**
 * \brief     Gets the process ID for the current task.
 *
 * Returns the process ID for the current task, which can be used to manage that
 * task.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \return    PID for the current task.
 *
 * \sa        #task_kill
 * \sa        #task_setpriority
 * \sa        #task_getpriority
 */
//---------------------------------------------------------------------------
unsigned char  task_getcurrent(void);

/**
 * \brief     Gets the priority level for the given task.
 *
 * Given the process ID of a task, return the priority level
 * for that task.  Use a <i>task_id</i> of 0 for the current 
 * task.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     task_id Task PID to get the priority for.  A task PID of zero 
 *                    means the current task.
 *
 * \return    Priority level of the task.
 *
 * \sa        #MIN_PRIORITY
 * \sa        #NORM_PRIORITY
 * \sa        #MAX_PRIORITY
 */
//---------------------------------------------------------------------------
unsigned char  task_getpriority(unsigned char task_id);

/**
 * \brief     Sets the priority level for a given task.
 *
 * Given the process ID of a task, set the priority level
 * for that task.  Use a <i>task_id</i> of 0 for the current
 * task.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     task_id    Task PID to set the priority for.  A task PID of zero 
 *                       means the current task.
 * \param     priority   Priority setting for PID <i>task_id</i>.  Can be any 
 *                       value between #MIN_PRIORITY and #MAX_PRIORITY
 *
 * \return    0 for Success, non-zero for failure
 *
 * \sa        #MIN_PRIORITY
 * \sa        #NORM_PRIORITY
 * \sa        #MAX_PRIORITY
 */
//---------------------------------------------------------------------------
unsigned char  task_setpriority(unsigned char task_id, unsigned char priority);

/**
 * \brief     Attempts to create a new task
 *
 * Spawns a new task, returning the process ID of the new task to the parent
 * task.  Note that because of the way the Keil compiler assigns variables,
 * calls to task_fork should be wrapped inside a critical section.  Make sure 
 * the child's process ID is stored in a secure location before exiting the 
 * critical section.  Note that only the parent need leave the critical 
 * section, the child will not run until the parent has left it.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     priority  priority level for the new task.
 * \param     savesize  size of the task state buffer for the new task
 *
 * \return    0x0FFFF for failure, else 0 if this is the child task, or the 
 *            child's PID if this is the parent.
 *
 * \sa        #MIN_PRIORITY
 * \sa        #NORM_PRIORITY
 * \sa        #MAX_PRIORITY
 * \sa        #ROM_SAVESIZE
 * \sa        #task_kill
 */
//---------------------------------------------------------------------------
unsigned int   task_fork(unsigned char priority, unsigned int savesize);

/**
 * \brief     Kills the specified task.
 *
 * Kill the specified task.  Use a <i>task_id</i> of 0 to indicate the current
 * task.  This function does not close or clean up any sockets.  Use the socket
 * library function <i>#cleanup</i> to clean any sockets owned by the task
 * before any more processes are created.
 * 
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     task_id  Task PID to kill.
 *
 * \return    0 for Success, non-zero for failure
 *
 * \sa        #task_fork
 */
//---------------------------------------------------------------------------
unsigned char  task_kill(unsigned char task_id);

/**
 * \brief     Suspends the specified task.
 *
 * Suspends the execution of the specified task until a set of events
 * have occurred.  Use the function <i>#task_signal</i> to wake the task
 * up.
 * 
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     task_id     Task PID to suspend.  A task PID of zero 
 *                        means suspend the current task.
 * \param     event_mask  Bitmap of events to wait for before wakeup
 *
 * \return    0 for Success, non-zero for failure
 *
 * \sa        #task_signal
 * \sa        #task_sleep
 */
//---------------------------------------------------------------------------
unsigned char  task_suspend(unsigned char task_id, unsigned char event_mask);

/**
 * \brief     Puts the specified task to sleep.
 *
 * Suspends the execution of the specified task until a set of events
 * have occurred, or until a set amount of time has elapsed.  Use the function 
 * <i>#task_signal</i> to wake the task up.
 * 
 * This "function" is now multi-process safe.  If two processes try to call 
 * this function at the same time, its parameters will not be destroyed.
 * This "function" is now a macro that actually calls <i>#task_synch_wait</i>.
 * 
 * \param     task_id     Task PID to put to sleep.  A task PID of zero 
 *                        means put the current task to sleep.
 * \param     event_mask  Bitmap of events to wait for before wakeup
 * \param     millis      Maximum number of milliseconds to sleep for
 *
 * \return    0 for Success, non-zero for failure
 * 
 * \sa        #task_signal
 * \sa        #task_synch_wait
 * \sa        #task_sleep
 * \sa        #task_synch_sleep
 * \sa        #task_suspend
 */
//---------------------------------------------------------------------------
#define task_wait(task_id,event_mask,millis) task_synch_wait(((long)(millis))>>16,(millis), (task_id) | ((event_mask) << 8))

/**
 * \brief     Puts the specified task to sleep.
 *
 * Suspends the execution of the specified task until a set of events
 * have occurred, or until a set amount of time has elapsed.  Use the function 
 * <i>#task_signal</i> to wake the task up.
 * 
 * This function <b>IS</b> multi-process safe.  Two processes may safely 
 * call this function at the same time.
 * 
 * \param     millis_h    high 16 bits of amount of time to put 'task' to sleep for
 * \param     millis_l    low 16 bits of amount of time to put 'task' to sleep for
 * \param     task_event  Most significant byte contains bitmap of events to 
 *                        wait for before wakeup.  Least significant byte 
 *                        contains task PID to put to sleep.  A task PID of zero 
 *                        means put the current task to sleep.
 *
 * \return    0 for Success, non-zero for failure
 * 
 * \sa        #task_signal
 * \sa        #task_wait
 * \sa        #task_sleep
 * \sa        #task_synch_sleep
 * \sa        #task_suspend
 */
//---------------------------------------------------------------------------
unsigned char  task_synch_wait(unsigned int millis_h, unsigned int millis_l, unsigned int task_event);

/**
 * \brief     Posts events to the specified task.
 *
 * Sends the event(s) in <i>event_mask</i> to process <i>task_id</i>.  If the
 * task is waiting for no other events, it will wake up and be 
 * electable to run by the task scheduler.  
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *