sys/contrib/ncsw/inc/ncsw_ext.h

   1 /* Copyright (c) 2008-2011 Freescale Semiconductor, Inc.
   2  * All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *     * Redistributions of source code must retain the above copyright
   7  *       notice, this list of conditions and the following disclaimer.
   8  *     * Redistributions in binary form must reproduce the above copyright
   9  *       notice, this list of conditions and the following disclaimer in the
  10  *       documentation and/or other materials provided with the distribution.
  11  *     * Neither the name of Freescale Semiconductor nor the
  12  *       names of its contributors may be used to endorse or promote products
  13  *       derived from this software without specific prior written permission.
  14  *
  15  *
  16  * ALTERNATIVELY, this software may be distributed under the terms of the
  17  * GNU General Public License ("GPL") as published by the Free Software
  18  * Foundation, either version 2 of that License or (at your option) any
  19  * later version.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
  22  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  23  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  24  * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
  25  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  26  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  28  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33  /**************************************************************************//**
  34  @File          ncsw_ext.h
  35
  36  @Description   General NetCommSw Standard Definitions
  37 *//***************************************************************************/
  38
  39 #ifndef __NCSW_EXT_H
  40 #define __NCSW_EXT_H
  41
  42 #include "memcpy_ext.h"
  43
  44
  45 #define WRITE_BLOCK                 IOMemSet32
  46 #define COPY_BLOCK                  Mem2IOCpy32
  47
  48 #define PTR_TO_UINT(_ptr)           ((uintptr_t)(_ptr))
  49 #define UINT_TO_PTR(_val)           ((void*)(uintptr_t)(_val))
  50
  51 #define PTR_MOVE(_ptr, _offset)     (void*)((uint8_t*)(_ptr) + (_offset))
  52
  53
  54 #define WRITE_UINT8_UINT24(arg, data08, data24) WRITE_UINT32(arg,((uint32_t)(data08)<<24)|((uint32_t)(data24)&0x00FFFFFF))
  55 #define WRITE_UINT24_UINT8(arg, data24, data08) WRITE_UINT32(arg,((uint32_t)(data24)<< 8)|((uint32_t)(data08)&0x000000FF))
  56
  57 /* Little-Endian access macros */
  58
  59 #define WRITE_UINT16_LE(arg, data) \
  60         WRITE_UINT16((arg), SwapUint16(data))
  61
  62 #define WRITE_UINT32_LE(arg, data) \
  63         WRITE_UINT32((arg), SwapUint32(data))
  64
  65 #define WRITE_UINT64_LE(arg, data) \
  66         WRITE_UINT64((arg), SwapUint64(data))
  67
  68 #define GET_UINT16_LE(arg) \
  69         SwapUint16(GET_UINT16(arg))
  70
  71 #define GET_UINT32_LE(arg) \
  72         SwapUint32(GET_UINT32(arg))
  73
  74 #define GET_UINT64_LE(arg) \
  75         SwapUint64(GET_UINT64(arg))
  76
  77 /* Write and Read again macros */
  78 #define WRITE_UINT_SYNC(size, arg, data)    \
  79     do {                                    \
  80         WRITE_UINT##size((arg), (data));    \
  81         CORE_MemoryBarrier();               \
  82     } while (0)
  83
  84 #define WRITE_UINT8_SYNC(arg, data)     WRITE_UINT_SYNC(8, (arg), (data))
  85
  86 #define WRITE_UINT16_SYNC(arg, data)    WRITE_UINT_SYNC(16, (arg), (data))
  87 #define WRITE_UINT32_SYNC(arg, data)    WRITE_UINT_SYNC(32, (arg), (data))
  88
  89 #define MAKE_UINT64(high32, low32)      (((uint64_t)high32 << 32) | (low32))
  90
  91
  92 /*----------------------*/
  93 /* Miscellaneous macros */
  94 /*----------------------*/
  95
  96 #define UNUSED(X) (X=X)
  97
  98 #define KILOBYTE            0x400UL                 /* 1024 */
  99 #define MEGABYTE            (KILOBYTE * KILOBYTE)   /* 1024*1024 */
 100 #define GIGABYTE            (KILOBYTE * MEGABYTE)   /* 1024*1024*1024 */
 101
 102 #undef  NO_IRQ
 103 #define NO_IRQ              (-1)
 104 #define NCSW_MASTER_ID      (0)
 105
 106 /* Macro for checking if a number is a power of 2 */
 107 #define POWER_OF_2(n)   (!((n) & ((n)-1)))
 108
 109 /* Macro for calculating log of base 2 */
 110 #define LOG2(num, log2Num)      \
 111     do                          \
 112     {                           \
 113         uint64_t tmp = (num);   \
 114         log2Num = 0;            \
 115         while (tmp > 1)         \
 116         {                       \
 117             log2Num++;          \
 118             tmp >>= 1;          \
 119         }                       \
 120     } while (0)
 121
 122 #define NEXT_POWER_OF_2(_num, _nextPow) \
 123 do                                      \
 124 {                                       \
 125     if (POWER_OF_2(_num))               \
 126         _nextPow = (_num);              \
 127     else                                \
 128     {                                   \
 129         uint64_t tmp = (_num);          \
 130         _nextPow = 1;                   \
 131         while (tmp)                     \
 132         {                               \
 133             _nextPow <<= 1;             \
 134             tmp >>= 1;                  \
 135         }                               \
 136     }                                   \
 137 } while (0)
 138
 139 /* Ceiling division - not the fastest way, but safer in terms of overflow */
 140 #define DIV_CEIL(x,y)   (((x)/(y)) + ((((((x)/(y)))*(y)) == (x)) ? 0 : 1))
 141
 142 /* Round up a number to be a multiple of a second number */
 143 #define ROUND_UP(x,y)   ((((x) + (y) - 1) / (y)) * (y))
 144
 145 /* Timing macro for converting usec units to number of ticks.   */
 146 /* (number of usec *  clock_Hz) / 1,000,000) - since            */
 147 /* clk is in MHz units, no division needed.                     */
 148 #define USEC_TO_CLK(usec,clk)       ((usec) * (clk))
 149 #define CYCLES_TO_USEC(cycles,clk)  ((cycles) / (clk))
 150
 151 /* Timing macros for converting between nsec units and number of clocks. */
 152 #define NSEC_TO_CLK(nsec,clk)       DIV_CEIL(((nsec) * (clk)), 1000)
 153 #define CYCLES_TO_NSEC(cycles,clk)  (((cycles) * 1000) / (clk))
 154
 155 /* Timing macros for converting between psec units and number of clocks. */
 156 #define PSEC_TO_CLK(psec,clk)       DIV_CEIL(((psec) * (clk)), 1000000)
 157 #define CYCLES_TO_PSEC(cycles,clk)  (((cycles) * 1000000) / (clk))
 158
 159 /* Min, Max macros */
 160 #define NCSW_MIN(a,b)    ((a) < (b) ? (a) : (b))
 161 #define NCSW_MAX(a,b)    ((a) > (b) ? (a) : (b))
 162 #define IN_RANGE(min,val,max) ((min)<=(val) && (val)<=(max))
 163
 164 #define ABS(a)  ((a<0)?(a*-1):a)
 165
 166 #if !(defined(ARRAY_SIZE))
 167 #define ARRAY_SIZE(arr)   (sizeof(arr) / sizeof((arr)[0]))
 168 #endif /* !defined(ARRAY_SIZE) */
 169
 170
 171 /* possible alignments */
 172 #define HALF_WORD_ALIGNMENT     2
 173 #define WORD_ALIGNMENT          4
 174 #define DOUBLE_WORD_ALIGNMENT   8
 175 #define BURST_ALIGNMENT         32
 176
 177 #define HALF_WORD_ALIGNED       0x00000001
 178 #define WORD_ALIGNED            0x00000003
 179 #define DOUBLE_WORD_ALIGNED     0x00000007
 180 #define BURST_ALIGNED           0x0000001f
 181 #ifndef IS_ALIGNED
 182 #define IS_ALIGNED(n,align)     (!((uint32_t)(n) & (align - 1)))
 183 #endif /* IS_ALIGNED */
 184
 185
 186 #define LAST_BUF        1
 187 #define FIRST_BUF       2
 188 #define SINGLE_BUF      (LAST_BUF | FIRST_BUF)
 189 #define MIDDLE_BUF      4
 190
 191 #define ARRAY_END       -1
 192
 193 #define ILLEGAL_BASE    (~0)
 194
 195 #define BUF_POSITION(first, last)   state[(!!(last))<<1 | !!(first)]
 196 #define DECLARE_POSITION static uint8_t state[4] = { (uint8_t)MIDDLE_BUF, (uint8_t)FIRST_BUF, (uint8_t)LAST_BUF, (uint8_t)SINGLE_BUF };
 197
 198
 199 /**************************************************************************//**
 200  @Description   Timers operation mode
 201 *//***************************************************************************/
 202 typedef enum e_TimerMode
 203 {
 204     e_TIMER_MODE_INVALID = 0,
 205     e_TIMER_MODE_FREE_RUN,    /**< Free run - counter continues to increase
 206                                    after reaching the reference value. */
 207     e_TIMER_MODE_PERIODIC,    /**< Periodic - counter restarts counting from 0
 208                                    after reaching the reference value. */
 209     e_TIMER_MODE_SINGLE       /**< Single (one-shot) - counter stops counting
 210                                    after reaching the reference value. */
 211 } e_TimerMode;
 212
 213
 214 /**************************************************************************//**
 215  @Description   Enumeration (bit flags) of communication modes (Transmit,
 216                 receive or both).
 217 *//***************************************************************************/
 218 typedef enum e_CommMode
 219 {
 220     e_COMM_MODE_NONE        = 0,    /**< No transmit/receive communication */
 221     e_COMM_MODE_RX          = 1,    /**< Only receive communication */
 222     e_COMM_MODE_TX          = 2,    /**< Only transmit communication */
 223     e_COMM_MODE_RX_AND_TX   = 3     /**< Both transmit and receive communication */
 224 } e_CommMode;
 225
 226 /**************************************************************************//**
 227  @Description   General Diagnostic Mode
 228 *//***************************************************************************/
 229 typedef enum e_DiagMode
 230 {
 231     e_DIAG_MODE_NONE = 0,       /**< Normal operation; no diagnostic mode */
 232     e_DIAG_MODE_CTRL_LOOPBACK,  /**< Loopback in the controller */
 233     e_DIAG_MODE_CHIP_LOOPBACK,  /**< Loopback in the chip but not in the
 234                                      controller; e.g. IO-pins, SerDes, etc. */
 235     e_DIAG_MODE_PHY_LOOPBACK,   /**< Loopback in the external PHY */
 236     e_DIAG_MODE_EXT_LOOPBACK,   /**< Loopback in the external line (beyond the PHY) */
 237     e_DIAG_MODE_CTRL_ECHO,      /**< Echo incoming data by the controller */
 238     e_DIAG_MODE_PHY_ECHO        /**< Echo incoming data by the PHY */
 239 } e_DiagMode;
 240
 241 /**************************************************************************//**
 242  @Description   Possible RxStore callback responses.
 243 *//***************************************************************************/
 244 typedef enum e_RxStoreResponse
 245 {
 246       e_RX_STORE_RESPONSE_PAUSE     /**< Pause invoking callback with received data;
 247                                          in polling mode, start again invoking callback
 248                                          only next time user invokes the receive routine;
 249                                          in interrupt mode, start again invoking callback
 250                                          only next time a receive event triggers an interrupt;
 251                                          in all cases, received data that are pending are not
 252                                          lost, rather, their processing is temporarily deferred;
 253                                          in all cases, received data are processed in the order
 254                                          in which they were received. */
 255     , e_RX_STORE_RESPONSE_CONTINUE  /**< Continue invoking callback with received data. */
 256 } e_RxStoreResponse;
 257
 258
 259 /**************************************************************************//**
 260  @Description   General Handle
 261 *//***************************************************************************/
 262 typedef void *      t_Handle;   /**< handle, used as object's descriptor */
 263
 264 /**************************************************************************//**
 265  @Description   MUTEX type
 266 *//***************************************************************************/
 267 typedef uint32_t    t_Mutex;
 268
 269 /**************************************************************************//**
 270  @Description   Error Code.
 271
 272                 The high word of the error code is the code of the software
 273                 module (driver). The low word is the error type (e_ErrorType).
 274                 To get the values from the error code, use GET_ERROR_TYPE()
 275                 and GET_ERROR_MODULE().
 276 *//***************************************************************************/
 277 typedef uint32_t    t_Error;
 278
 279 /**************************************************************************//**
 280  @Description   General prototype of interrupt service routine (ISR).
 281
 282  @Param[in]     handle - Optional handle of the module handling the interrupt.
 283
 284  @Return        None
 285  *//***************************************************************************/
 286 typedef void (t_Isr)(t_Handle handle);
 287
 288 /**************************************************************************//**
 289  @Anchor        mem_attr
 290
 291  @Collection    Memory Attributes
 292
 293                 Various attributes of memory partitions. These values may be
 294                 or'ed together to create a mask of all memory attributes.
 295  @{
 296 *//***************************************************************************/
 297 #define MEMORY_ATTR_CACHEABLE           0x00000001
 298                                         /**< Memory is cacheable */
 299 #define MEMORY_ATTR_QE_2ND_BUS_ACCESS   0x00000002
 300                                         /**< Memory can be accessed by QUICC Engine
 301                                              through its secondary bus interface */
 302
 303 /* @} */
 304
 305
 306 /**************************************************************************//**
 307  @Function      t_GetBufFunction
 308
 309  @Description   User callback function called by driver to get data buffer.
 310
 311                 User provides this function. Driver invokes it.
 312
 313  @Param[in]     h_BufferPool        - A handle to buffer pool manager
 314  @Param[out]    p_BufContextHandle  - Returns the user's private context that
 315                                       should be associated with the buffer
 316
 317  @Return        Pointer to data buffer, NULL if error
 318  *//***************************************************************************/
 319 typedef uint8_t * (t_GetBufFunction)(t_Handle   h_BufferPool,
 320                                      t_Handle   *p_BufContextHandle);
 321
 322 /**************************************************************************//**
 323  @Function      t_PutBufFunction
 324
 325  @Description   User callback function called by driver to return data buffer.
 326
 327                 User provides this function. Driver invokes it.
 328
 329  @Param[in]     h_BufferPool    - A handle to buffer pool manager
 330  @Param[in]     p_Buffer        - A pointer to buffer to return
 331  @Param[in]     h_BufContext    - The user's private context associated with
 332                                   the returned buffer
 333
 334  @Return        E_OK on success; Error code otherwise
 335  *//***************************************************************************/
 336 typedef t_Error (t_PutBufFunction)(t_Handle h_BufferPool,
 337                                    uint8_t  *p_Buffer,
 338                                    t_Handle h_BufContext);
 339
 340 /**************************************************************************//**
 341  @Function      t_PhysToVirt
 342
 343  @Description   Translates a physical address to the matching virtual address.
 344
 345  @Param[in]     addr - The physical address to translate.
 346
 347  @Return        Virtual address.
 348 *//***************************************************************************/
 349 typedef void * t_PhysToVirt(physAddress_t addr);
 350
 351 /**************************************************************************//**
 352  @Function      t_VirtToPhys
 353
 354  @Description   Translates a virtual address to the matching physical address.
 355
 356  @Param[in]     addr - The virtual address to translate.
 357
 358  @Return        Physical address.
 359 *//***************************************************************************/
 360 typedef physAddress_t t_VirtToPhys(void *addr);
 361
 362 /**************************************************************************//**
 363  @Description   Buffer Pool Information Structure.
 364 *//***************************************************************************/
 365 typedef struct t_BufferPoolInfo
 366 {
 367     t_Handle            h_BufferPool;   /**< A handle to the buffer pool manager */
 368     t_GetBufFunction    *f_GetBuf;      /**< User callback to get a free buffer */
 369     t_PutBufFunction    *f_PutBuf;      /**< User callback to return a buffer */
 370     uint16_t            bufferSize;     /**< Buffer size (in bytes) */
 371
 372     t_PhysToVirt        *f_PhysToVirt;  /**< User callback to translate pool buffers
 373                                              physical addresses to virtual addresses  */
 374     t_VirtToPhys        *f_VirtToPhys;  /**< User callback to translate pool buffers
 375                                              virtual addresses to physical addresses */
 376 } t_BufferPoolInfo;
 377
 378
 379 /**************************************************************************//**
 380  @Description   User callback function called by driver when transmit completed.
 381
 382                 User provides this function. Driver invokes it.
 383
 384  @Param[in]     h_App           - Application's handle, as was provided to the
 385                                   driver by the user
 386  @Param[in]     queueId         - Transmit queue ID
 387  @Param[in]     p_Data          - Pointer to the data buffer
 388  @Param[in]     h_BufContext    - The user's private context associated with
 389                                   the given data buffer
 390  @Param[in]     status          - Transmit status and errors
 391  @Param[in]     flags           - Driver-dependent information
 392  *//***************************************************************************/
 393 typedef void (t_TxConfFunction)(t_Handle    h_App,
 394                                 uint32_t    queueId,
 395                                 uint8_t     *p_Data,
 396                                 t_Handle    h_BufContext,
 397                                 uint16_t    status,
 398                                 uint32_t    flags);
 399
 400 /**************************************************************************//**
 401  @Description   User callback function called by driver with receive data.
 402
 403                 User provides this function. Driver invokes it.
 404
 405  @Param[in]     h_App           - Application's handle, as was provided to the
 406                                   driver by the user
 407  @Param[in]     queueId         - Receive queue ID
 408  @Param[in]     p_Data          - Pointer to the buffer with received data
 409  @Param[in]     h_BufContext    - The user's private context associated with
 410                                   the given data buffer
 411  @Param[in]     length          - Length of received data
 412  @Param[in]     status          - Receive status and errors
 413  @Param[in]     position        - Position of buffer in frame
 414  @Param[in]     flags           - Driver-dependent information
 415
 416  @Retval        e_RX_STORE_RESPONSE_CONTINUE - order the driver to continue Rx
 417                                                operation for all ready data.
 418  @Retval        e_RX_STORE_RESPONSE_PAUSE    - order the driver to stop Rx operation.
 419  *//***************************************************************************/
 420 typedef e_RxStoreResponse (t_RxStoreFunction)(t_Handle  h_App,
 421                                               uint32_t  queueId,
 422                                               uint8_t   *p_Data,
 423                                               t_Handle  h_BufContext,
 424                                               uint32_t  length,
 425                                               uint16_t  status,
 426                                               uint8_t   position,
 427                                               uint32_t  flags);
 428
 429
 430 #endif /* __NCSW_EXT_H */