Contiki 2.6

platform-common.h

Go to the documentation of this file.
00001 /** @file hal/micro/generic/compiler/platform-common.h
00002  * See @ref platform_common for detailed documentation.
00003  *
00004  * <!--(C) COPYRIGHT 2010 STMicroelectronics. All rights reserved.        -->
00005  */
00006 
00007 /** @addtogroup platform_common
00008  * @brief Compiler and Platform specific definitions and typedefs common to
00009  * all platforms.  
00010  *
00011  * platform-common.h provides PLATFORM_HEADER defaults and common definitions.
00012  * This head should never be included directly, it should only be included
00013  * by the specific PLATFORM_HEADER used by your platform.
00014  *
00015  * See platform-common.h for source code.
00016  *@{
00017  */
00018  
00019 #ifndef PLATCOMMONOKTOINCLUDE
00020   //  This header should only be included by a PLATFORM_HEADER
00021   #error  platform-common.h should not be included directly
00022 #endif
00023 
00024 #ifndef __PLATFORMCOMMON_H__
00025 #define __PLATFORMCOMMON_H__
00026 ////////////////////////////////////////////////////////////////////////////////
00027 // Many of the common definitions must be explicitly enabled by the 
00028 //  particular PLATFORM_HEADER being used
00029 ////////////////////////////////////////////////////////////////////////////////
00030 
00031 
00032 ////////////////////////////////////////////////////////////////////////////////
00033 #ifdef _HAL_USE_COMMON_PGM_
00034   /** \name Master Program Memory Declarations
00035    * These are a set of defines for simple declarations of program memory.
00036    */
00037   //@{
00038   /**
00039    * @brief Standard program memory delcaration.
00040    */
00041   #define PGM     const
00042 
00043   /**
00044    * @brief Char pointer to program memory declaration.
00045    */
00046   #define PGM_P   const char *
00047 
00048   /**
00049    * @brief Unsigned char pointer to program memory declaration.
00050    */
00051   #define PGM_PU  const unsigned char *
00052 
00053 
00054   /**
00055    * @brief Sometimes a second PGM is needed in a declaration.  Having two
00056    * 'const' declarations generates a warning so we have a second PGM that turns
00057    * into nothing under gcc.
00058    */
00059   #define PGM_NO_CONST
00060   //@} \\END MASTER PROGRAM MEMORY DECLARATIONS
00061 #endif //_HAL_USE_COMMON_PGM_
00062 
00063 
00064 ////////////////////////////////////////////////////////////////////////////////
00065 #ifdef _HAL_USE_COMMON_DIVMOD_
00066   /** \name Divide and Modulus Operations
00067    * Some platforms can perform divide and modulus operations on 32 bit 
00068    * quantities more efficiently when the divisor is only a 16 bit quantity.
00069    * C compilers will always promote the divisor to 32 bits before performing the
00070    * operation, so the following utility functions are instead required to take 
00071    * advantage of this optimisation.
00072    */
00073   //@{
00074   /**
00075    * @brief Provide a portable name for the int32u by int16u division
00076    * library function (which can perform the division with only a single 
00077    * assembly instruction on some platforms)
00078    */
00079   #define halCommonUDiv32By16(x, y) ((int16u) (((int32u) (x)) / ((int16u) (y))))
00080 
00081   /**
00082    * @brief Provide a portable name for the int32s by int16s division
00083    * library function (which can perform the division with only a single
00084    * assembly instruction on some platforms)
00085    */
00086   #define halCommonSDiv32By16(x, y) ((int16s) (((int32s) (x)) / ((int16s) (y))))
00087 
00088   /**
00089    * @brief Provide a portable name for the int32u by int16u modulo
00090    * library function (which can perform the division with only a single
00091    * assembly instruction on some platforms)
00092    */
00093   #define halCommonUMod32By16(x, y) ((int16u) (((int32u) (x)) % ((int16u) (y))))
00094 
00095   /**
00096    * @brief Provide a portable name for the int32s by int16s modulo
00097    * library function (which can perform the division with only a single
00098    * assembly instruction on some platforms)
00099    */
00100   #define halCommonSMod32By16(x, y) ((int16s) (((int32s) (x)) % ((int16s) (y))))
00101   //@} \\END DIVIDE and MODULUS OPERATIONS
00102 #endif //_HAL_USE_COMMON_DIVMOD_
00103 
00104 
00105 ////////////////////////////////////////////////////////////////////////////////
00106 #ifdef _HAL_USE_COMMON_MEMUTILS_
00107   /** \name C Standard Library Memory Utilities
00108    * These should be used in place of the standard library functions.
00109    * 
00110    * These functions have the same parameters and expected results as their C
00111    * Standard Library equivalents but may take advantage of certain implementation
00112    * optimizations.
00113    * 
00114    * Unless otherwise noted, these functions are utilized by the StStack and are 
00115    * therefore required to be implemented in the HAL. Additionally, unless otherwise
00116    * noted, applications that find these functions useful may utilze them.
00117    */
00118   //@{
00119 
00120   /**
00121    * @brief Refer to the C stdlib memcpy().
00122    */
00123   void halCommonMemCopy(void *dest, const void *src, int8u bytes);
00124 
00125 
00126   /**
00127    * @brief Refer to the C stdlib memset().
00128    */
00129   void halCommonMemSet(void *dest, int8u val, int16u bytes);
00130 
00131 
00132   /**
00133    * @brief Refer to the C stdlib memcmp().
00134    */
00135   int8s halCommonMemCompare(const void *source0, const void *source1, int8u bytes);
00136 
00137 
00138   /**
00139    * @brief Friendly convenience macro pointing to the full HAL function.
00140    */
00141   #define MEMSET(d,v,l)  halCommonMemSet(d,v,l)
00142   #define MEMCOPY(d,s,l) halCommonMemCopy(d,s,l)
00143   #define MEMCOMPARE(s0,s1,l) halCommonMemCompare(s0, s1, l)
00144   #define MEMPGMCOMPARE(s0,s1,l) halCommonMemPGMCompare(s0, s1, l)
00145 
00146   //@}  // end of C Standard Library Memory Utilities
00147 #endif //_HAL_USE_COMMON_MEMUTILS_
00148 
00149 
00150 
00151 
00152 
00153 
00154 
00155 
00156 
00157 ////////////////////////////////////////////////////////////////////////////////
00158 //  The following sections are common on all platforms
00159 ////////////////////////////////////////////////////////////////////////////////
00160 
00161 ////////////////////////////////////////////////////////////////////////////////
00162 /**
00163  * @name Generic Types
00164  *@{
00165  */
00166 
00167 /**
00168  * @brief An alias for one, used for clarity.
00169  */
00170 #define TRUE  1
00171 
00172 /**
00173  * @brief An alias for zero, used for clarity.
00174  */
00175 #define FALSE 0
00176 
00177 #ifndef NULL
00178 /**
00179  * @brief The null pointer.
00180  */
00181 #define NULL ((void *)0)
00182 #endif
00183 
00184 //@} \\END Generic Types
00185 
00186 
00187 /**
00188  * @name  Bit Manipulation Macros
00189  */
00190 //@{
00191 
00192 /**
00193  * @brief Useful to reference a single bit of a byte.
00194  */
00195 #define BIT(x) (1U << (x))  // Unsigned avoids compiler warnings re BIT(15)
00196 
00197 /**
00198  * @brief Useful to reference a single bit of an int32u type.
00199  */
00200 #define BIT32(x) (((int32u) 1) << (x))
00201 
00202 /**
00203  * @brief Sets \c bit in the \c reg register or byte.
00204  * @note Assuming \c reg is an IO register, some platforms
00205  * can implement this in a single atomic operation.
00206 */
00207 #define SETBIT(reg, bit)      reg |= BIT(bit)
00208 
00209 /**
00210  * @brief Sets the bits in the \c reg register or the byte 
00211  * as specified in the bitmask \c bits. 
00212  * @note This is never a single atomic operation.
00213  */
00214 #define SETBITS(reg, bits)    reg |= (bits)
00215 
00216 /**
00217  * @brief Clears a bit in the \c reg register or byte. 
00218  * @note Assuming \c reg is an IO register, some platforms (such as the AVR) 
00219  * can implement this in a single atomic operation.
00220  */
00221 #define CLEARBIT(reg, bit)    reg &= ~(BIT(bit))
00222 
00223 /**
00224  * @brief Clears the bits in the \c reg register or byte 
00225  * as specified in the bitmask \c bits. 
00226  * @note This is never a single atomic operation.
00227  */
00228 #define CLEARBITS(reg, bits)  reg &= ~(bits)
00229 
00230 /**
00231  * @brief Returns the value of \c bit within the register or byte \c reg.
00232 */
00233 #define READBIT(reg, bit)     (reg & (BIT(bit)))
00234 
00235 /**
00236  * @brief Returns the value of the bitmask \c bits within 
00237  * the register or byte \c reg.
00238  */
00239 #define READBITS(reg, bits)   (reg & (bits))
00240 
00241 //@} \\END Bit Manipulation Macros
00242 
00243 
00244 ////////////////////////////////////////////////////////////////////////////////
00245 /**
00246  * @name  Byte Manipulation Macros
00247  */
00248 //@{
00249 
00250 /**
00251  * @brief Returns the low byte of the 16-bit value \c n as an \c int8u.
00252  */
00253 #define LOW_BYTE(n)                     ((int8u)((n) & 0xFF))
00254 
00255 /**
00256  * @brief Returns the high byte of the 16-bit value \c n as an \c int8u.
00257  */
00258 #define HIGH_BYTE(n)                    ((int8u)(LOW_BYTE((n) >> 8)))
00259 
00260 /**
00261  * @brief Returns the value built from the two \c int8u 
00262  * values \c high and \c low.
00263  */
00264 #define HIGH_LOW_TO_INT(high, low) (                              \
00265                                     (( (int16u) (high) ) << 8) +  \
00266                                     (  (int16u) ( (low) & 0xFF))  \
00267                                    )                                
00268 
00269 /**
00270  * @brief Returns the low byte of the 32-bit value \c n as an \c int8u.
00271  */
00272 #define BYTE_0(n)                    ((int8u)((n) & 0xFF))
00273 
00274 /**
00275  * @brief Returns the second byte of the 32-bit value \c n as an \c int8u.
00276  */
00277 #define BYTE_1(n)                    ((int8u)(BYTE_0((n) >> 8)))
00278 
00279 /**
00280  * @brief Returns the third byte of the 32-bit value \c n as an \c int8u.
00281  */
00282 #define BYTE_2(n)                    ((int8u)(BYTE_0((n) >> 16)))
00283 
00284 /**
00285  * @brief Returns the high byte of the 32-bit value \c n as an \c int8u.
00286  */
00287 #define BYTE_3(n)                    ((int8u)(BYTE_0((n) >> 24)))
00288 
00289 //@} \\END Byte manipulation macros
00290 
00291 
00292 ////////////////////////////////////////////////////////////////////////////////
00293 /**
00294  * @name  Time Manipulation Macros
00295  */
00296 //@{
00297 
00298 /**
00299  * @brief Returns the elapsed time between two 8 bit values.  
00300  *        Result may not be valid if the time samples differ by more than 127
00301  */
00302 #define elapsedTimeInt8u(oldTime, newTime)       \
00303   ((int8u) ((int8u)(newTime) - (int8u)(oldTime)))
00304 
00305 /**
00306  * @brief Returns the elapsed time between two 16 bit values.  
00307  *        Result may not be valid if the time samples differ by more than 32767
00308  */
00309 #define elapsedTimeInt16u(oldTime, newTime)      \
00310   ((int16u) ((int16u)(newTime) - (int16u)(oldTime)))
00311 
00312 /**
00313  * @brief Returns the elapsed time between two 32 bit values.  
00314  *   Result may not be valid if the time samples differ by more than 2147483647
00315  */
00316 #define elapsedTimeInt32u(oldTime, newTime)      \
00317   ((int32u) ((int32u)(newTime) - (int32u)(oldTime)))
00318 
00319 /**
00320  * @brief Returns TRUE if t1 is greater than t2.  Can only account for 1 wrap
00321  * around of the variable before it is wrong.
00322  */
00323 #define MAX_INT8U_VALUE 0xFF
00324 #define timeGTorEqualInt8u(t1, t2)           \
00325   (elapsedTimeInt8u(t2, t1) <= ((MAX_INT8U_VALUE + 1) / 2))
00326 
00327 /**
00328  * @brief Returns TRUE if t1 is greater than t2.  Can only account for 1 wrap
00329  * around of the variable before it is wrong.
00330  */
00331 #define MAX_INT16U_VALUE 0xFFFF
00332 #define timeGTorEqualInt16u(t1, t2)           \
00333   (elapsedTimeInt16u(t2, t1) <= ((MAX_INT16U_VALUE + 1) / 2))
00334 
00335 /**
00336  * @brief Returns TRUE if t1 is greater than t2.  Can only account for 1 wrap
00337  * around of the variable before it is wrong.
00338  */
00339 #define MAX_INT32U_VALUE 0xFFFFFFFF
00340 #define timeGTorEqualInt32u(t1, t2)           \
00341   (elapsedTimeInt32u(t2, t1) <= ((MAX_INT32U_VALUE + 1) / 2))
00342 
00343 //@} \\END Time manipulation macros
00344 
00345 
00346 
00347 #endif //__PLATFORMCOMMON_H__
00348 
00349 /** @}  END addtogroup */
00350