rom400_util.h

这是TCP/IP协议组播的实现代码

/*---------------------------------------------------------------------------
 *  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_util_
#define __rom400_util_

/** \file rom400_util.h
 *  \brief Utility functions in the DS80C400 ROM
 *
 *  This library contains CRC, pseudo-RNG and utility memory functions.
 *  
 *  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>#util_version</i> function.
 * \sa #util_version */
#define ROM400_UTIL_VERSION         5

/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>KernelMalloc</i> method.
 * \sa #util_installhook */
#define REDIRECT_KERNELMALLOC                   1
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>KernelFree</i> method.
 * \sa #util_installhook */
#define REDIRECT_KERNELFREE                     2
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#mem_malloc</i> method.
 * \sa #util_installhook */
#define REDIRECT_MALLOC                         3
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#mem_free</i> method.
 * \sa #util_installhook */
#define REDIRECT_FREE                           4
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#mem_mallocdirty</i> method.
 * \sa #util_installhook */
#define REDIRECT_MALLOCDIRTY                    5
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>MM_Deref</i> method.
 * \sa #util_installhook */
#define REDIRECT_TINIEXPORT_MM_DEREF            6
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#mem_getfreeram</i> method.
 * \sa #util_installhook */
#define REDIRECT_GETFREERAM                     7
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_gettimemillis</i> method.
 * \sa #util_installhook */
#define REDIRECT_GETTIMEMILLIS                  8
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_getthreadid</i> method.
 * \sa #util_installhook */
#define REDIRECT_GETTHREADID                    9
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_threadresume</i> method.
 * \sa #util_installhook */
#define REDIRECT_THREADRESUME                  10
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_threadiosleep</i> method.
 * \sa #util_installhook */
#define REDIRECT_THREADIOSLEEP                 11
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_threadiosleepnc</i> method.
 * \sa #util_installhook */
#define REDIRECT_THREADIOSLEEPNC               12
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_threadsave</i> method.
 * \sa #util_installhook */
#define REDIRECT_THREADSAVE                    13
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_threadrestore</i> method.
 * \sa #util_installhook */
#define REDIRECT_THREADRESTORE                 14
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_sleep</i> method.
 * \sa #util_installhook */
#define REDIRECT_SLEEP                         15
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_gettaskid</i> method.
 * \sa #util_installhook */
#define REDIRECT_GETTASKID                     16
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#util_infosendchar</i> method.
 * \sa #util_installhook */
#define REDIRECT_INFOSENDCHAR                  17
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>IP_ComputeChecksum</i> method.
 * \sa #util_installhook */
#define REDIRECT_IP_COMPUTECHECKSUM_SOFTWARE   18
/** Reserved for future use with the <i>#util_installhook</i> method.
 * \sa #util_installhook */
#define REDIRECT_0                             19
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>DHCPNotify</i> method.
 * \sa #util_installhook */
#define REDIRECT_DHCPNOTIFY                    20
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>TaskCreate</i> method.
 * \sa #util_installhook */
#define REDIRECT_ROM_TASK_CREATE               21
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>TaskDuplicate</i> method.
 * \sa #util_installhook */
#define REDIRECT_ROM_TASK_DUPLICATE            22
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>#task_kill</i> method.
 * \sa #util_installhook */
#define REDIRECT_ROM_TASK_DESTROY              23
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>TaskSwitchIn</i> method.
 * \sa #util_installhook */
#define REDIRECT_ROM_TASK_SWITCH_IN            24
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>TaskSwitchOut</i> method.
 * \sa #util_installhook */
#define REDIRECT_ROM_TASK_SWITCH_OUT           25
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>OWIP_ReadConfig</i> method.
 * \sa #util_installhook */
#define REDIRECT_OWIP_READCONFIG               26
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>SetMACID</i> method.
 * \sa #util_installhook */
#define REDIRECT_SETMACID                      27
/** Value to be used in conjunction with the <i>#util_installhook</i> method to override the <i>M_UnDeref</i> method.
 * \sa #util_installhook */
#define REDIRECT_MM_UNDEREF                    28

/**
 * \brief         Generates a 16-bit CRC given a seed.
 * 
 * Implements the Cyclic-Redundancy Check CRC16.  This CRC is based on the
 * polynomial X^16 + X^15 + X^2 + 1.  It is used extensively in operations
 * with Dallas Semiconductor 1-Wire devices. 
 * 
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param value   single byte input value to the crc function
 * \param seed    16 bit 'previous result' seed
 *
 * \return        16 bit CRC result
 */
// ---------------------------------------------------------------------------
unsigned int util_crc16(unsigned char value, unsigned int seed);

/**
 * \brief         Gets a pseudo-random byte.
 *
 * Returns a pseudo-random byte generated with the help of the CRC function.
 * This is not a true random byte, as there is no real source of entropy.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \return        One pseudorandom byte.
 */
// ---------------------------------------------------------------------------
unsigned char util_getpseudorandom(void);

/**
 * \brief         Sets the seed of the random number generator.
 *
 * Changes the current value of the random seed to the random number 
 * generator, allowing for additional randomness to be inserted into the
 * generation.  Note that additional randomness is also generated by the
 * timer bytes and the millisecond counter, so this seed is not the only
 * source.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param seed    new random seed
 */
//---------------------------------------------------------------------------
void util_setrandomseed(unsigned int seed);

/**
 * \brief         Clears a block of memory.
 *
 * Sets <i>length</i> bytes to zero starting at address <i>target</i>.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param target  beginning address of memory to clear
 * \param length  number of bytes to clear
 */
//---------------------------------------------------------------------------
void util_memclear(void* target, unsigned int length);

/**
 * \brief         Copies a block of memory
 *
 * Copies <i>length</i> bytes of data from the <i>source</i> pointer to the
 * <i>dest</i> pointer.  The copy operation starts from the beginning of
 * the <i>source</i> pointer, placing bytes from the beginning of the <i>
 * dest</i> buffer.  Therefore, f the buffers referenced by <i>source</i>
 * and <i>dest</i> overlap, some bytes from <i>source</i> bytes will be
 * overwritten prior to being copied to the target.
 *
 * \warning       This function is not multi-process safe.  If two processes
 *                try to call this function at the same time, its parameters
 *                may be destroyed, yielding unpredictable results.
 * 
 * \param source  pointer to bytes that will be the source of the copy
 * \param dest    pointer to the bytes that will to copied to
 * \param length  number of bytes to copy from <i>source</i> to <i>dest</i>
 */
//---------------------------------------------------------------------------
void util_memcopy(void* source, void* dest, unsigned int length);

/**
 * \brief         Compares the values in 2 blocks of memory
 *
 * Compares <i>length</i> bytes from <i>block0</i> to <i>length</i> bytes from 
 * <i>block1</i> for equality.  If the two memory blocks are identical,
 * the function returns 0.
 *
 * \warning       This function is not multi-process safe.  If two processes
 *                try to call this function at the same time, its parameters
 *                may be destroyed, yielding unpredictable results.
 * 
 * \param block0  first input block to compare
 * \param block1  second input block to compare
 * \param length  maximum number of bytes to compare
 *
 * \return        0 if the blocks are identical, non-zero otherwise
 */
//---------------------------------------------------------------------------
unsigned char util_memcompare(void* block0, void* block1, unsigned int length);

/**
 * \brief         Sends a character to serial port 0.
 *
 * This is a redirected function.  The DS80C400 silicon software version of
 * this function accesses the serial loader pin (P1.7) and does nothing if
 * this pin is in the logic low state.  The DS80C400 silicon software does 
 * not use interrupt driver I/O to the serial port.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param ch      character to send to the debug port
 */
//---------------------------------------------------------------------------
void util_infosendchar(unsigned char ch);

/**
 * \brief         Installs a new function pointer into the ROM redirect table
 *
 * This function alters the redirect table, which allows functions in the
 * ROM to be overridden by intredpid users.  The function that is 
 * redirected will now call the code at address <i>fncptr</i>.  It is not
 * advised that <i>fncptr</i> point to a C function unless no arguments
 * are expected (there is no way without writing an assembler wrapper
 * to get the arguments to the C function in the Keil compiler).
 *
 * See the DS80C400 User's Guide Supplement for more on the meaning of
 * <i>redirected functions</i>.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param fncptr address of the function that will be inserted into the 
 *               redirect table
 * \param fncindex  number of the redirected function that will be altered
 *                       (i.e. #REDIRECT_KERNELMALLOC)
 */
//---------------------------------------------------------------------------
void util_installhook(void* fncptr, unsigned int fncindex);

/**
 * \brief        Returns the version number of this utility library.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \return       Version number of this UTIL library.
 */
//---------------------------------------------------------------------------
unsigned int util_version(void);

#endif