drivers/usb/host/dwc_common_port/dwc_os.h

   1 /* =========================================================================
   2  * $File: //dwh/usb_iip/dev/software/dwc_common_port_2/dwc_os.h $
   3  * $Revision: #14 $
   4  * $Date: 2010/11/04 $
   5  * $Change: 1621695 $
   6  *
   7  * Synopsys Portability Library Software and documentation
   8  * (hereinafter, "Software") is an Unsupported proprietary work of
   9  * Synopsys, Inc. unless otherwise expressly agreed to in writing
  10  * between Synopsys and you.
  11  *
  12  * The Software IS NOT an item of Licensed Software or Licensed Product
  13  * under any End User Software License Agreement or Agreement for
  14  * Licensed Product with Synopsys or any supplement thereto. You are
  15  * permitted to use and redistribute this Software in source and binary
  16  * forms, with or without modification, provided that redistributions
  17  * of source code must retain this notice. You may not view, use,
  18  * disclose, copy or distribute this file or any information contained
  19  * herein except pursuant to this license grant from Synopsys. If you
  20  * do not agree with this notice, including the disclaimer below, then
  21  * you are not authorized to use the Software.
  22  *
  23  * THIS SOFTWARE IS BEING DISTRIBUTED BY SYNOPSYS SOLELY ON AN "AS IS"
  24  * BASIS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  26  * FOR A PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL
  27  * SYNOPSYS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  28  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  29  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  31  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  32  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  33  * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  34  * DAMAGE.
  35  * ========================================================================= */
  36 #ifndef _DWC_OS_H_
  37 #define _DWC_OS_H_
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /** @file
  44  *
  45  * DWC portability library, low level os-wrapper functions
  46  *
  47  */
  48
  49 /* These basic types need to be defined by some OS header file or custom header
  50  * file for your specific target architecture.
  51  *
  52  * uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t, int64_t
  53  *
  54  * Any custom or alternate header file must be added and enabled here.
  55  */
  56
  57 #ifdef DWC_LINUX
  58 # include <linux/types.h>
  59 # ifdef CONFIG_DEBUG_MUTEXES
  60 #  include <linux/mutex.h>
  61 # endif
  62 # include <linux/spinlock.h>
  63 # include <linux/errno.h>
  64 # include <stdarg.h>
  65 #endif
  66
  67 #if defined(DWC_FREEBSD) || defined(DWC_NETBSD)
  68 # include <os_dep.h>
  69 #endif
  70
  71
  72 /** @name Primitive Types and Values */
  73
  74 /** We define a boolean type for consistency.  Can be either YES or NO */
  75 typedef uint8_t dwc_bool_t;
  76 #define YES  1
  77 #define NO   0
  78
  79 #ifdef DWC_LINUX
  80
  81 /** @name Error Codes */
  82 #define DWC_E_INVALID           EINVAL
  83 #define DWC_E_NO_MEMORY         ENOMEM
  84 #define DWC_E_NO_DEVICE         ENODEV
  85 #define DWC_E_NOT_SUPPORTED     EOPNOTSUPP
  86 #define DWC_E_TIMEOUT           ETIMEDOUT
  87 #define DWC_E_BUSY              EBUSY
  88 #define DWC_E_AGAIN             EAGAIN
  89 #define DWC_E_RESTART           ERESTART
  90 #define DWC_E_ABORT             ECONNABORTED
  91 #define DWC_E_SHUTDOWN          ESHUTDOWN
  92 #define DWC_E_NO_DATA           ENODATA
  93 #define DWC_E_DISCONNECT        ECONNRESET
  94 #define DWC_E_UNKNOWN           EINVAL
  95 #define DWC_E_NO_STREAM_RES     ENOSR
  96 #define DWC_E_COMMUNICATION     ECOMM
  97 #define DWC_E_OVERFLOW          EOVERFLOW
  98 #define DWC_E_PROTOCOL          EPROTO
  99 #define DWC_E_IN_PROGRESS       EINPROGRESS
 100 #define DWC_E_PIPE              EPIPE
 101 #define DWC_E_IO                EIO
 102 #define DWC_E_NO_SPACE          ENOSPC
 103
 104 #else
 105
 106 /** @name Error Codes */
 107 #define DWC_E_INVALID           1001
 108 #define DWC_E_NO_MEMORY         1002
 109 #define DWC_E_NO_DEVICE         1003
 110 #define DWC_E_NOT_SUPPORTED     1004
 111 #define DWC_E_TIMEOUT           1005
 112 #define DWC_E_BUSY              1006
 113 #define DWC_E_AGAIN             1007
 114 #define DWC_E_RESTART           1008
 115 #define DWC_E_ABORT             1009
 116 #define DWC_E_SHUTDOWN          1010
 117 #define DWC_E_NO_DATA           1011
 118 #define DWC_E_DISCONNECT        2000
 119 #define DWC_E_UNKNOWN           3000
 120 #define DWC_E_NO_STREAM_RES     4001
 121 #define DWC_E_COMMUNICATION     4002
 122 #define DWC_E_OVERFLOW          4003
 123 #define DWC_E_PROTOCOL          4004
 124 #define DWC_E_IN_PROGRESS       4005
 125 #define DWC_E_PIPE              4006
 126 #define DWC_E_IO                4007
 127 #define DWC_E_NO_SPACE          4008
 128
 129 #endif
 130
 131
 132 /** @name Tracing/Logging Functions
 133  *
 134  * These function provide the capability to add tracing, debugging, and error
 135  * messages, as well exceptions as assertions.  The WUDEV uses these
 136  * extensively.  These could be logged to the main console, the serial port, an
 137  * internal buffer, etc.  These functions could also be no-op if they are too
 138  * expensive on your system.  By default undefining the DEBUG macro already
 139  * no-ops some of these functions. */
 140
 141 /** Returns non-zero if in interrupt context. */
 142 extern dwc_bool_t DWC_IN_IRQ(void);
 143 #define dwc_in_irq DWC_IN_IRQ
 144
 145 /** Returns "IRQ" if DWC_IN_IRQ is true. */
 146 static inline char *dwc_irq(void) {
 147         return DWC_IN_IRQ() ? "IRQ" : "";
 148 }
 149
 150 /** Returns non-zero if in bottom-half context. */
 151 extern dwc_bool_t DWC_IN_BH(void);
 152 #define dwc_in_bh DWC_IN_BH
 153
 154 /** Returns "BH" if DWC_IN_BH is true. */
 155 static inline char *dwc_bh(void) {
 156         return DWC_IN_BH() ? "BH" : "";
 157 }
 158
 159 /**
 160  * A vprintf() clone.  Just call vprintf if you've got it.
 161  */
 162 extern void DWC_VPRINTF(char *format, va_list args);
 163 #define dwc_vprintf DWC_VPRINTF
 164
 165 /**
 166  * A vsnprintf() clone.  Just call vprintf if you've got it.
 167  */
 168 extern int DWC_VSNPRINTF(char *str, int size, char *format, va_list args);
 169 #define dwc_vsnprintf DWC_VSNPRINTF
 170
 171 /**
 172  * printf() clone.  Just call printf if you've go it.
 173  */
 174 extern void DWC_PRINTF(char *format, ...)
 175 /* This provides compiler level static checking of the parameters if you're
 176  * using GCC. */
 177 #ifdef __GNUC__
 178         __attribute__ ((format(printf, 1, 2)));
 179 #else
 180         ;
 181 #endif
 182 #define dwc_printf DWC_PRINTF
 183
 184 /**
 185  * sprintf() clone.  Just call sprintf if you've got it.
 186  */
 187 extern int DWC_SPRINTF(char *string, char *format, ...)
 188 #ifdef __GNUC__
 189         __attribute__ ((format(printf, 2, 3)));
 190 #else
 191         ;
 192 #endif
 193 #define dwc_sprintf DWC_SPRINTF
 194
 195 /**
 196  * snprintf() clone.  Just call snprintf if you've got it.
 197  */
 198 extern int DWC_SNPRINTF(char *string, int size, char *format, ...)
 199 #ifdef __GNUC__
 200         __attribute__ ((format(printf, 3, 4)));
 201 #else
 202         ;
 203 #endif
 204 #define dwc_snprintf DWC_SNPRINTF
 205
 206 /**
 207  * Prints a WARNING message.  On systems that don't differentiate between
 208  * warnings and regular log messages, just print it.  Indicates that something
 209  * may be wrong with the driver.  Works like printf().
 210  *
 211  * Use the DWC_WARN macro to call this function.
 212  */
 213 extern void __DWC_WARN(char *format, ...)
 214 #ifdef __GNUC__
 215         __attribute__ ((format(printf, 1, 2)));
 216 #else
 217         ;
 218 #endif
 219
 220 /**
 221  * Prints an error message.  On systems that don't differentiate between errors
 222  * and regular log messages, just print it.  Indicates that something went wrong
 223  * with the driver.  Works like printf().
 224  *
 225  * Use the DWC_ERROR macro to call this function.
 226  */
 227 extern void __DWC_ERROR(char *format, ...)
 228 #ifdef __GNUC__
 229         __attribute__ ((format(printf, 1, 2)));
 230 #else
 231         ;
 232 #endif
 233
 234 /**
 235  * Prints an exception error message and takes some user-defined action such as
 236  * print out a backtrace or trigger a breakpoint.  Indicates that something went
 237  * abnormally wrong with the driver such as programmer error, or other
 238  * exceptional condition.  It should not be ignored so even on systems without
 239  * printing capability, some action should be taken to notify the developer of
 240  * it.  Works like printf().
 241  */
 242 extern void DWC_EXCEPTION(char *format, ...)
 243 #ifdef __GNUC__
 244         __attribute__ ((format(printf, 1, 2)));
 245 #else
 246         ;
 247 #endif
 248 #define dwc_exception DWC_EXCEPTION
 249
 250 #ifndef DWC_OTG_DEBUG_LEV
 251 #define DWC_OTG_DEBUG_LEV 0
 252 #endif
 253
 254 #ifdef DEBUG
 255 /**
 256  * Prints out a debug message.  Used for logging/trace messages.
 257  *
 258  * Use the DWC_DEBUG macro to call this function
 259  */
 260 extern void __DWC_DEBUG(char *format, ...)
 261 #ifdef __GNUC__
 262         __attribute__ ((format(printf, 1, 2)));
 263 #else
 264         ;
 265 #endif
 266 #else
 267 #define __DWC_DEBUG printk
 268 #endif
 269
 270 /**
 271  * Prints out a Debug message.
 272  */
 273 #define DWC_DEBUG(_format, _args...) __DWC_DEBUG("DEBUG:%s:%s: " _format "\n", \
 274                                                  __func__, dwc_irq(), ## _args)
 275 #define dwc_debug DWC_DEBUG
 276 /**
 277  * Prints out a Debug message if enabled at compile time.
 278  */
 279 #if DWC_OTG_DEBUG_LEV > 0
 280 #define DWC_DEBUGC(_format, _args...) DWC_DEBUG(_format, ##_args )
 281 #else
 282 #define DWC_DEBUGC(_format, _args...)
 283 #endif
 284 #define dwc_debugc DWC_DEBUGC
 285 /**
 286  * Prints out an informative message.
 287  */
 288 #define DWC_INFO(_format, _args...) DWC_PRINTF("INFO:%s: " _format "\n", \
 289                                                dwc_irq(), ## _args)
 290 #define dwc_info DWC_INFO
 291 /**
 292  * Prints out an informative message if enabled at compile time.
 293  */
 294 #if DWC_OTG_DEBUG_LEV > 1
 295 #define DWC_INFOC(_format, _args...) DWC_INFO(_format, ##_args )
 296 #else
 297 #define DWC_INFOC(_format, _args...)
 298 #endif
 299 #define dwc_infoc DWC_INFOC
 300 /**
 301  * Prints out a warning message.
 302  */
 303 #define DWC_WARN(_format, _args...) __DWC_WARN("WARN:%s:%s:%d: " _format "\n", \
 304                                         dwc_irq(), __func__, __LINE__, ## _args)
 305 #define dwc_warn DWC_WARN
 306 /**
 307  * Prints out an error message.
 308  */
 309 #define DWC_ERROR(_format, _args...) __DWC_ERROR("ERROR:%s:%s:%d: " _format "\n", \
 310                                         dwc_irq(), __func__, __LINE__, ## _args)
 311 #define dwc_error DWC_ERROR
 312
 313 #define DWC_PROTO_ERROR(_format, _args...) __DWC_WARN("ERROR:%s:%s:%d: " _format "\n", \
 314                                                 dwc_irq(), __func__, __LINE__, ## _args)
 315 #define dwc_proto_error DWC_PROTO_ERROR
 316
 317 #ifdef DEBUG
 318 /** Prints out a exception error message if the _expr expression fails.  Disabled
 319  * if DEBUG is not enabled. */
 320 #define DWC_ASSERT(_expr, _format, _args...) do { \
 321         if (!(_expr)) { DWC_EXCEPTION("%s:%s:%d: " _format "\n", dwc_irq(), \
 322                                       __FILE__, __LINE__, ## _args); } \
 323         } while (0)
 324 #else
 325 #define DWC_ASSERT(_x...)
 326 #endif
 327 #define dwc_assert DWC_ASSERT
 328
 329
 330 /** @name Byte Ordering
 331  * The following functions are for conversions between processor's byte ordering
 332  * and specific ordering you want.
 333  */
 334
 335 /** Converts 32 bit data in CPU byte ordering to little endian. */
 336 extern uint32_t DWC_CPU_TO_LE32(uint32_t *p);
 337 #define dwc_cpu_to_le32 DWC_CPU_TO_LE32
 338
 339 /** Converts 32 bit data in CPU byte orderint to big endian. */
 340 extern uint32_t DWC_CPU_TO_BE32(uint32_t *p);
 341 #define dwc_cpu_to_be32 DWC_CPU_TO_BE32
 342
 343 /** Converts 32 bit little endian data to CPU byte ordering. */
 344 extern uint32_t DWC_LE32_TO_CPU(uint32_t *p);
 345 #define dwc_le32_to_cpu DWC_LE32_TO_CPU
 346
 347 /** Converts 32 bit big endian data to CPU byte ordering. */
 348 extern uint32_t DWC_BE32_TO_CPU(uint32_t *p);
 349 #define dwc_be32_to_cpu DWC_BE32_TO_CPU
 350
 351 /** Converts 16 bit data in CPU byte ordering to little endian. */
 352 extern uint16_t DWC_CPU_TO_LE16(uint16_t *p);
 353 #define dwc_cpu_to_le16 DWC_CPU_TO_LE16
 354
 355 /** Converts 16 bit data in CPU byte orderint to big endian. */
 356 extern uint16_t DWC_CPU_TO_BE16(uint16_t *p);
 357 #define dwc_cpu_to_be16 DWC_CPU_TO_BE16
 358
 359 /** Converts 16 bit little endian data to CPU byte ordering. */
 360 extern uint16_t DWC_LE16_TO_CPU(uint16_t *p);
 361 #define dwc_le16_to_cpu DWC_LE16_TO_CPU
 362
 363 /** Converts 16 bit bi endian data to CPU byte ordering. */
 364 extern uint16_t DWC_BE16_TO_CPU(uint16_t *p);
 365 #define dwc_be16_to_cpu DWC_BE16_TO_CPU
 366
 367
 368 /** @name Register Read/Write
 369  *
 370  * The following six functions should be implemented to read/write registers of
 371  * 32-bit and 64-bit sizes.  All modules use this to read/write register values.
 372  * The reg value is a pointer to the register calculated from the void *base
 373  * variable passed into the driver when it is started.  */
 374
 375 #ifdef DWC_LINUX
 376 /* Linux doesn't need any extra parameters for register read/write, so we
 377  * just throw away the IO context parameter.
 378  */
 379 /** Reads the content of a 32-bit register. */
 380 extern uint32_t DWC_READ_REG32(uint32_t volatile *reg);
 381 #define dwc_read_reg32(_ctx_,_reg_) DWC_READ_REG32(_reg_)
 382
 383 /** Reads the content of a 64-bit register. */
 384 extern uint64_t DWC_READ_REG64(uint64_t volatile *reg);
 385 #define dwc_read_reg64(_ctx_,_reg_) DWC_READ_REG64(_reg_)
 386
 387 /** Writes to a 32-bit register. */
 388 extern void DWC_WRITE_REG32(uint32_t volatile *reg, uint32_t value);
 389 #define dwc_write_reg32(_ctx_,_reg_,_val_) DWC_WRITE_REG32(_reg_, _val_)
 390
 391 /** Writes to a 64-bit register. */
 392 extern void DWC_WRITE_REG64(uint64_t volatile *reg, uint64_t value);
 393 #define dwc_write_reg64(_ctx_,_reg_,_val_) DWC_WRITE_REG64(_reg_, _val_)
 394
 395 /**
 396  * Modify bit values in a register.  Using the
 397  * algorithm: (reg_contents & ~clear_mask) | set_mask.
 398  */
 399 extern void DWC_MODIFY_REG32(uint32_t volatile *reg, uint32_t clear_mask, uint32_t set_mask);
 400 #define dwc_modify_reg32(_ctx_,_reg_,_cmsk_,_smsk_) DWC_MODIFY_REG32(_reg_,_cmsk_,_smsk_)
 401 extern void DWC_MODIFY_REG64(uint64_t volatile *reg, uint64_t clear_mask, uint64_t set_mask);
 402 #define dwc_modify_reg64(_ctx_,_reg_,_cmsk_,_smsk_) DWC_MODIFY_REG64(_reg_,_cmsk_,_smsk_)
 403
 404 #endif  /* DWC_LINUX */
 405
 406 #if defined(DWC_FREEBSD) || defined(DWC_NETBSD)
 407 typedef struct dwc_ioctx {
 408         struct device *dev;
 409         bus_space_tag_t iot;
 410         bus_space_handle_t ioh;
 411 } dwc_ioctx_t;
 412
 413 /** BSD needs two extra parameters for register read/write, so we pass
 414  * them in using the IO context parameter.
 415  */
 416 /** Reads the content of a 32-bit register. */
 417 extern uint32_t DWC_READ_REG32(void *io_ctx, uint32_t volatile *reg);
 418 #define dwc_read_reg32 DWC_READ_REG32
 419
 420 /** Reads the content of a 64-bit register. */
 421 extern uint64_t DWC_READ_REG64(void *io_ctx, uint64_t volatile *reg);
 422 #define dwc_read_reg64 DWC_READ_REG64
 423
 424 /** Writes to a 32-bit register. */
 425 extern void DWC_WRITE_REG32(void *io_ctx, uint32_t volatile *reg, uint32_t value);
 426 #define dwc_write_reg32 DWC_WRITE_REG32
 427
 428 /** Writes to a 64-bit register. */
 429 extern void DWC_WRITE_REG64(void *io_ctx, uint64_t volatile *reg, uint64_t value);
 430 #define dwc_write_reg64 DWC_WRITE_REG64
 431
 432 /**
 433  * Modify bit values in a register.  Using the
 434  * algorithm: (reg_contents & ~clear_mask) | set_mask.
 435  */
 436 extern void DWC_MODIFY_REG32(void *io_ctx, uint32_t volatile *reg, uint32_t clear_mask, uint32_t set_mask);
 437 #define dwc_modify_reg32 DWC_MODIFY_REG32
 438 extern void DWC_MODIFY_REG64(void *io_ctx, uint64_t volatile *reg, uint64_t clear_mask, uint64_t set_mask);
 439 #define dwc_modify_reg64 DWC_MODIFY_REG64
 440
 441 #endif  /* DWC_FREEBSD || DWC_NETBSD */
 442
 443 /** @cond */
 444
 445 /** @name Some convenience MACROS used internally.  Define DWC_DEBUG_REGS to log the
 446  * register writes. */
 447
 448 #ifdef DWC_LINUX
 449
 450 # ifdef DWC_DEBUG_REGS
 451
 452 #define dwc_define_read_write_reg_n(_reg,_container_type) \
 453 static inline uint32_t dwc_read_##_reg##_n(_container_type *container, int num) { \
 454         return DWC_READ_REG32(&container->regs->_reg[num]); \
 455 } \
 456 static inline void dwc_write_##_reg##_n(_container_type *container, int num, uint32_t data) { \
 457         DWC_DEBUG("WRITING %8s[%d]: %p: %08x", #_reg, num, \
 458                   &(((uint32_t*)container->regs->_reg)[num]), data); \
 459         DWC_WRITE_REG32(&(((uint32_t*)container->regs->_reg)[num]), data); \
 460 }
 461
 462 #define dwc_define_read_write_reg(_reg,_container_type) \
 463 static inline uint32_t dwc_read_##_reg(_container_type *container) { \
 464         return DWC_READ_REG32(&container->regs->_reg); \
 465 } \
 466 static inline void dwc_write_##_reg(_container_type *container, uint32_t data) { \
 467         DWC_DEBUG("WRITING %11s: %p: %08x", #_reg, &container->regs->_reg, data); \
 468         DWC_WRITE_REG32(&container->regs->_reg, data); \
 469 }
 470
 471 # else  /* DWC_DEBUG_REGS */
 472
 473 #define dwc_define_read_write_reg_n(_reg,_container_type) \
 474 static inline uint32_t dwc_read_##_reg##_n(_container_type *container, int num) { \
 475         return DWC_READ_REG32(&container->regs->_reg[num]); \
 476 } \
 477 static inline void dwc_write_##_reg##_n(_container_type *container, int num, uint32_t data) { \
 478         DWC_WRITE_REG32(&(((uint32_t*)container->regs->_reg)[num]), data); \
 479 }
 480
 481 #define dwc_define_read_write_reg(_reg,_container_type) \
 482 static inline uint32_t dwc_read_##_reg(_container_type *container) { \
 483         return DWC_READ_REG32(&container->regs->_reg); \
 484 } \
 485 static inline void dwc_write_##_reg(_container_type *container, uint32_t data) { \
 486         DWC_WRITE_REG32(&container->regs->_reg, data); \
 487 }
 488
 489 # endif /* DWC_DEBUG_REGS */
 490
 491 #endif  /* DWC_LINUX */
 492
 493 #if defined(DWC_FREEBSD) || defined(DWC_NETBSD)
 494
 495 # ifdef DWC_DEBUG_REGS
 496
 497 #define dwc_define_read_write_reg_n(_reg,_container_type) \
 498 static inline uint32_t dwc_read_##_reg##_n(void *io_ctx, _container_type *container, int num) { \
 499         return DWC_READ_REG32(io_ctx, &container->regs->_reg[num]); \
 500 } \
 501 static inline void dwc_write_##_reg##_n(void *io_ctx, _container_type *container, int num, uint32_t data) { \
 502         DWC_DEBUG("WRITING %8s[%d]: %p: %08x", #_reg, num, \
 503                   &(((uint32_t*)container->regs->_reg)[num]), data); \
 504         DWC_WRITE_REG32(io_ctx, &(((uint32_t*)container->regs->_reg)[num]), data); \
 505 }
 506
 507 #define dwc_define_read_write_reg(_reg,_container_type) \
 508 static inline uint32_t dwc_read_##_reg(void *io_ctx, _container_type *container) { \
 509         return DWC_READ_REG32(io_ctx, &container->regs->_reg); \
 510 } \
 511 static inline void dwc_write_##_reg(void *io_ctx, _container_type *container, uint32_t data) { \
 512         DWC_DEBUG("WRITING %11s: %p: %08x", #_reg, &container->regs->_reg, data); \
 513         DWC_WRITE_REG32(io_ctx, &container->regs->_reg, data); \
 514 }
 515
 516 # else  /* DWC_DEBUG_REGS */
 517
 518 #define dwc_define_read_write_reg_n(_reg,_container_type) \
 519 static inline uint32_t dwc_read_##_reg##_n(void *io_ctx, _container_type *container, int num) { \
 520         return DWC_READ_REG32(io_ctx, &container->regs->_reg[num]); \
 521 } \
 522 static inline void dwc_write_##_reg##_n(void *io_ctx, _container_type *container, int num, uint32_t data) { \
 523         DWC_WRITE_REG32(io_ctx, &(((uint32_t*)container->regs->_reg)[num]), data); \
 524 }
 525
 526 #define dwc_define_read_write_reg(_reg,_container_type) \
 527 static inline uint32_t dwc_read_##_reg(void *io_ctx, _container_type *container) { \
 528         return DWC_READ_REG32(io_ctx, &container->regs->_reg); \
 529 } \
 530 static inline void dwc_write_##_reg(void *io_ctx, _container_type *container, uint32_t data) { \
 531         DWC_WRITE_REG32(io_ctx, &container->regs->_reg, data); \
 532 }
 533
 534 # endif /* DWC_DEBUG_REGS */
 535
 536 #endif  /* DWC_FREEBSD || DWC_NETBSD */
 537
 538 /** @endcond */
 539
 540
 541 #ifdef DWC_CRYPTOLIB
 542 /** @name Crypto Functions
 543  *
 544  * These are the low-level cryptographic functions used by the driver. */
 545
 546 /** Perform AES CBC */
 547 extern int DWC_AES_CBC(uint8_t *message, uint32_t messagelen, uint8_t *key, uint32_t keylen, uint8_t iv[16], uint8_t *out);
 548 #define dwc_aes_cbc DWC_AES_CBC
 549
 550 /** Fill the provided buffer with random bytes.  These should be cryptographic grade random numbers. */
 551 extern void DWC_RANDOM_BYTES(uint8_t *buffer, uint32_t length);
 552 #define dwc_random_bytes DWC_RANDOM_BYTES
 553
 554 /** Perform the SHA-256 hash function */
 555 extern int DWC_SHA256(uint8_t *message, uint32_t len, uint8_t *out);
 556 #define dwc_sha256 DWC_SHA256
 557
 558 /** Calculated the HMAC-SHA256 */
 559 extern int DWC_HMAC_SHA256(uint8_t *message, uint32_t messagelen, uint8_t *key, uint32_t keylen, uint8_t *out);
 560 #define dwc_hmac_sha256 DWC_HMAC_SHA256
 561
 562 #endif  /* DWC_CRYPTOLIB */
 563
 564
 565 /** @name Memory Allocation
 566  *
 567  * These function provide access to memory allocation.  There are only 2 DMA
 568  * functions and 3 Regular memory functions that need to be implemented.  None
 569  * of the memory debugging routines need to be implemented.  The allocation
 570  * routines all ZERO the contents of the memory.
 571  *
 572  * Defining DWC_DEBUG_MEMORY turns on memory debugging and statistic gathering.
 573  * This checks for memory leaks, keeping track of alloc/free pairs.  It also
 574  * keeps track of how much memory the driver is using at any given time. */
 575
 576 #define DWC_PAGE_SIZE 4096
 577 #define DWC_PAGE_OFFSET(addr) (((uint32_t)addr) & 0xfff)
 578 #define DWC_PAGE_ALIGNED(addr) ((((uint32_t)addr) & 0xfff) == 0)
 579
 580 #define DWC_INVALID_DMA_ADDR 0x0
 581
 582 #ifdef DWC_LINUX
 583 /** Type for a DMA address */
 584 typedef dma_addr_t dwc_dma_t;
 585 #endif
 586
 587 #if defined(DWC_FREEBSD) || defined(DWC_NETBSD)
 588 typedef bus_addr_t dwc_dma_t;
 589 #endif
 590
 591 #ifdef DWC_FREEBSD
 592 typedef struct dwc_dmactx {
 593         struct device *dev;
 594         bus_dma_tag_t dma_tag;
 595         bus_dmamap_t dma_map;
 596         bus_addr_t dma_paddr;
 597         void *dma_vaddr;
 598 } dwc_dmactx_t;
 599 #endif
 600
 601 #ifdef DWC_NETBSD
 602 typedef struct dwc_dmactx {
 603         struct device *dev;
 604         bus_dma_tag_t dma_tag;
 605         bus_dmamap_t dma_map;
 606         bus_dma_segment_t segs[1];
 607         int nsegs;
 608         bus_addr_t dma_paddr;
 609         void *dma_vaddr;
 610 } dwc_dmactx_t;
 611 #endif
 612
 613 /* @todo these functions will be added in the future */
 614 #if 0
 615 /**
 616  * Creates a DMA pool from which you can allocate DMA buffers.  Buffers
 617  * allocated from this pool will be guaranteed to meet the size, alignment, and
 618  * boundary requirements specified.
 619  *
 620  * @param[in] size Specifies the size of the buffers that will be allocated from
 621  * this pool.
 622  * @param[in] align Specifies the byte alignment requirements of the buffers
 623  * allocated from this pool.  Must be a power of 2.
 624  * @param[in] boundary Specifies the N-byte boundary that buffers allocated from
 625  * this pool must not cross.
 626  *
 627  * @returns A pointer to an internal opaque structure which is not to be
 628  * accessed outside of these library functions.  Use this handle to specify
 629  * which pools to allocate/free DMA buffers from and also to destroy the pool,
 630  * when you are done with it.
 631  */
 632 extern dwc_pool_t *DWC_DMA_POOL_CREATE(uint32_t size, uint32_t align, uint32_t boundary);
 633
 634 /**
 635  * Destroy a DMA pool.  All buffers allocated from that pool must be freed first.
 636  */
 637 extern void DWC_DMA_POOL_DESTROY(dwc_pool_t *pool);
 638
 639 /**
 640  * Allocate a buffer from the specified DMA pool and zeros its contents.
 641  */
 642 extern void *DWC_DMA_POOL_ALLOC(dwc_pool_t *pool, uint64_t *dma_addr);
 643
 644 /**
 645  * Free a previously allocated buffer from the DMA pool.
 646  */
 647 extern void DWC_DMA_POOL_FREE(dwc_pool_t *pool, void *vaddr, void *daddr);
 648 #endif
 649
 650 /** Allocates a DMA capable buffer and zeroes its contents. */
 651 extern void *__DWC_DMA_ALLOC(void *dma_ctx, uint32_t size, dwc_dma_t *dma_addr);
 652
 653 /** Allocates a DMA capable buffer and zeroes its contents in atomic contest */
 654 extern void *__DWC_DMA_ALLOC_ATOMIC(void *dma_ctx, uint32_t size, dwc_dma_t *dma_addr);
 655
 656 /** Frees a previously allocated buffer. */
 657 extern void __DWC_DMA_FREE(void *dma_ctx, uint32_t size, void *virt_addr, dwc_dma_t dma_addr);
 658
 659 /** Allocates a block of memory and zeroes its contents. */
 660 extern void *__DWC_ALLOC(void *mem_ctx, uint32_t size);
 661
 662 /** Allocates a block of memory and zeroes its contents, in an atomic manner
 663  * which can be used inside interrupt context.  The size should be sufficiently
 664  * small, a few KB at most, such that failures are not likely to occur.  Can just call
 665  * __DWC_ALLOC if it is atomic. */
 666 extern void *__DWC_ALLOC_ATOMIC(void *mem_ctx, uint32_t size);
 667
 668 /** Frees a previously allocated buffer. */
 669 extern void __DWC_FREE(void *mem_ctx, void *addr);
 670
 671 #ifndef DWC_DEBUG_MEMORY
 672
 673 #define DWC_ALLOC(_size_) __DWC_ALLOC(NULL, _size_)
 674 #define DWC_ALLOC_ATOMIC(_size_) __DWC_ALLOC_ATOMIC(NULL, _size_)
 675 #define DWC_FREE(_addr_) __DWC_FREE(NULL, _addr_)
 676
 677 # ifdef DWC_LINUX
 678 #define DWC_DMA_ALLOC(_dev, _size_, _dma_) __DWC_DMA_ALLOC(_dev, _size_, _dma_)
 679 #define DWC_DMA_ALLOC_ATOMIC(_dev, _size_, _dma_) __DWC_DMA_ALLOC_ATOMIC(_dev, _size_, _dma_)
 680 #define DWC_DMA_FREE(_dev, _size_,_virt_, _dma_) __DWC_DMA_FREE(_dev, _size_, _virt_, _dma_)
 681 # endif
 682
 683 # if defined(DWC_FREEBSD) || defined(DWC_NETBSD)
 684 #define DWC_DMA_ALLOC __DWC_DMA_ALLOC
 685 #define DWC_DMA_FREE __DWC_DMA_FREE
 686 # endif
 687 extern void *dwc_dma_alloc_atomic_debug(uint32_t size, dwc_dma_t *dma_addr, char const *func, int line);
 688
 689 #else   /* DWC_DEBUG_MEMORY */
 690
 691 extern void *dwc_alloc_debug(void *mem_ctx, uint32_t size, char const *func, int line);
 692 extern void *dwc_alloc_atomic_debug(void *mem_ctx, uint32_t size, char const *func, int line);
 693 extern void dwc_free_debug(void *mem_ctx, void *addr, char const *func, int line);
 694 extern void *dwc_dma_alloc_debug(void *dma_ctx, uint32_t size, dwc_dma_t *dma_addr,
 695                                  char const *func, int line);
 696 extern void *dwc_dma_alloc_atomic_debug(void *dma_ctx, uint32_t size, dwc_dma_t *dma_addr,
 697                                 char const *func, int line);
 698 extern void dwc_dma_free_debug(void *dma_ctx, uint32_t size, void *virt_addr,
 699                                dwc_dma_t dma_addr, char const *func, int line);
 700
 701 extern int dwc_memory_debug_start(void *mem_ctx);
 702 extern void dwc_memory_debug_stop(void);
 703 extern void dwc_memory_debug_report(void);
 704
 705 #define DWC_ALLOC(_size_) dwc_alloc_debug(NULL, _size_, __func__, __LINE__)
 706 #define DWC_ALLOC_ATOMIC(_size_) dwc_alloc_atomic_debug(NULL, _size_, \
 707                                                         __func__, __LINE__)
 708 #define DWC_FREE(_addr_) dwc_free_debug(NULL, _addr_, __func__, __LINE__)
 709
 710 # ifdef DWC_LINUX
 711 #define DWC_DMA_ALLOC(_dev, _size_, _dma_) \
 712         dwc_dma_alloc_debug(_dev, _size_, _dma_, __func__, __LINE__)
 713 #define DWC_DMA_ALLOC_ATOMIC(_dev, _size_, _dma_) \
 714         dwc_dma_alloc_atomic_debug(_dev, _size_, _dma_, __func__, __LINE__)
 715 #define DWC_DMA_FREE(_dev, _size_, _virt_, _dma_) \
 716         dwc_dma_free_debug(_dev, _size_, _virt_, _dma_, __func__, __LINE__)
 717 # endif
 718
 719 # if defined(DWC_FREEBSD) || defined(DWC_NETBSD)
 720 #define DWC_DMA_ALLOC(_ctx_,_size_,_dma_) dwc_dma_alloc_debug(_ctx_, _size_, \
 721                                                 _dma_, __func__, __LINE__)
 722 #define DWC_DMA_FREE(_ctx_,_size_,_virt_,_dma_) dwc_dma_free_debug(_ctx_, _size_, \
 723                                                  _virt_, _dma_, __func__, __LINE__)
 724 # endif
 725
 726 #endif /* DWC_DEBUG_MEMORY */
 727
 728 #define dwc_alloc(_ctx_,_size_) DWC_ALLOC(_size_)
 729 #define dwc_alloc_atomic(_ctx_,_size_) DWC_ALLOC_ATOMIC(_size_)
 730 #define dwc_free(_ctx_,_addr_) DWC_FREE(_addr_)
 731
 732 #ifdef DWC_LINUX
 733 /* Linux doesn't need any extra parameters for DMA buffer allocation, so we
 734  * just throw away the DMA context parameter.
 735  */
 736 #define dwc_dma_alloc(_ctx_,_size_,_dma_) DWC_DMA_ALLOC(_size_, _dma_)
 737 #define dwc_dma_alloc_atomic(_ctx_,_size_,_dma_) DWC_DMA_ALLOC_ATOMIC(_size_, _dma_)
 738 #define dwc_dma_free(_ctx_,_size_,_virt_,_dma_) DWC_DMA_FREE(_size_, _virt_, _dma_)
 739 #endif
 740
 741 #if defined(DWC_FREEBSD) || defined(DWC_NETBSD)
 742 /** BSD needs several extra parameters for DMA buffer allocation, so we pass
 743  * them in using the DMA context parameter.
 744  */
 745 #define dwc_dma_alloc DWC_DMA_ALLOC
 746 #define dwc_dma_free DWC_DMA_FREE
 747 #endif
 748
 749
 750 /** @name Memory and String Processing */
 751
 752 /** memset() clone */
 753 extern void *DWC_MEMSET(void *dest, uint8_t byte, uint32_t size);
 754 #define dwc_memset DWC_MEMSET
 755
 756 /** memcpy() clone */
 757 extern void *DWC_MEMCPY(void *dest, void const *src, uint32_t size);
 758 #define dwc_memcpy DWC_MEMCPY
 759
 760 /** memmove() clone */
 761 extern void *DWC_MEMMOVE(void *dest, void *src, uint32_t size);
 762 #define dwc_memmove DWC_MEMMOVE
 763
 764 /** memcmp() clone */
 765 extern int DWC_MEMCMP(void *m1, void *m2, uint32_t size);
 766 #define dwc_memcmp DWC_MEMCMP
 767
 768 /** strcmp() clone */
 769 extern int DWC_STRCMP(void *s1, void *s2);
 770 #define dwc_strcmp DWC_STRCMP
 771
 772 /** strncmp() clone */
 773 extern int DWC_STRNCMP(void *s1, void *s2, uint32_t size);
 774 #define dwc_strncmp DWC_STRNCMP
 775
 776 /** strlen() clone, for NULL terminated ASCII strings */
 777 extern int DWC_STRLEN(char const *str);
 778 #define dwc_strlen DWC_STRLEN
 779
 780 /** strcpy() clone, for NULL terminated ASCII strings */
 781 extern char *DWC_STRCPY(char *to, const char *from);
 782 #define dwc_strcpy DWC_STRCPY
 783
 784 /** strdup() clone.  If you wish to use memory allocation debugging, this
 785  * implementation of strdup should use the DWC_* memory routines instead of
 786  * calling a predefined strdup.  Otherwise the memory allocated by this routine
 787  * will not be seen by the debugging routines. */
 788 extern char *DWC_STRDUP(char const *str);
 789 #define dwc_strdup(_ctx_,_str_) DWC_STRDUP(_str_)
 790
 791 /** NOT an atoi() clone.  Read the description carefully.  Returns an integer
 792  * converted from the string str in base 10 unless the string begins with a "0x"
 793  * in which case it is base 16.  String must be a NULL terminated sequence of
 794  * ASCII characters and may optionally begin with whitespace, a + or -, and a
 795  * "0x" prefix if base 16.  The remaining characters must be valid digits for
 796  * the number and end with a NULL character.  If any invalid characters are
 797  * encountered or it returns with a negative error code and the results of the
 798  * conversion are undefined.  On sucess it returns 0.  Overflow conditions are
 799  * undefined.  An example implementation using atoi() can be referenced from the
 800  * Linux implementation. */
 801 extern int DWC_ATOI(const char *str, int32_t *value);
 802 #define dwc_atoi DWC_ATOI
 803
 804 /** Same as above but for unsigned. */
 805 extern int DWC_ATOUI(const char *str, uint32_t *value);
 806 #define dwc_atoui DWC_ATOUI
 807
 808 #ifdef DWC_UTFLIB
 809 /** This routine returns a UTF16LE unicode encoded string from a UTF8 string. */
 810 extern int DWC_UTF8_TO_UTF16LE(uint8_t const *utf8string, uint16_t *utf16string, unsigned len);
 811 #define dwc_utf8_to_utf16le DWC_UTF8_TO_UTF16LE
 812 #endif
 813
 814
 815 /** @name Wait queues
 816  *
 817  * Wait queues provide a means of synchronizing between threads or processes.  A
 818  * process can block on a waitq if some condition is not true, waiting for it to
 819  * become true.  When the waitq is triggered all waiting process will get
 820  * unblocked and the condition will be check again.  Waitqs should be triggered
 821  * every time a condition can potentially change.*/
 822 struct dwc_waitq;
 823
 824 /** Type for a waitq */
 825 typedef struct dwc_waitq dwc_waitq_t;
 826
 827 /** The type of waitq condition callback function.  This is called every time
 828  * condition is evaluated. */
 829 typedef int (*dwc_waitq_condition_t)(void *data);
 830
 831 /** Allocate a waitq */
 832 extern dwc_waitq_t *DWC_WAITQ_ALLOC(void);
 833 #define dwc_waitq_alloc(_ctx_) DWC_WAITQ_ALLOC()
 834
 835 /** Free a waitq */
 836 extern void DWC_WAITQ_FREE(dwc_waitq_t *wq);
 837 #define dwc_waitq_free DWC_WAITQ_FREE
 838
 839 /** Check the condition and if it is false, block on the waitq.  When unblocked, check the
 840  * condition again.  The function returns when the condition becomes true.  The return value
 841  * is 0 on condition true, DWC_WAITQ_ABORTED on abort or killed, or DWC_WAITQ_UNKNOWN on error. */
 842 extern int32_t DWC_WAITQ_WAIT(dwc_waitq_t *wq, dwc_waitq_condition_t cond, void *data);
 843 #define dwc_waitq_wait DWC_WAITQ_WAIT
 844
 845 /** Check the condition and if it is false, block on the waitq.  When unblocked,
 846  * check the condition again.  The function returns when the condition become
 847  * true or the timeout has passed.  The return value is 0 on condition true or
 848  * DWC_TIMED_OUT on timeout, or DWC_WAITQ_ABORTED, or DWC_WAITQ_UNKNOWN on
 849  * error. */
 850 extern int32_t DWC_WAITQ_WAIT_TIMEOUT(dwc_waitq_t *wq, dwc_waitq_condition_t cond,
 851                                       void *data, int32_t msecs);
 852 #define dwc_waitq_wait_timeout DWC_WAITQ_WAIT_TIMEOUT
 853
 854 /** Trigger a waitq, unblocking all processes.  This should be called whenever a condition
 855  * has potentially changed. */
 856 extern void DWC_WAITQ_TRIGGER(dwc_waitq_t *wq);
 857 #define dwc_waitq_trigger DWC_WAITQ_TRIGGER
 858
 859 /** Unblock all processes waiting on the waitq with an ABORTED result. */
 860 extern void DWC_WAITQ_ABORT(dwc_waitq_t *wq);
 861 #define dwc_waitq_abort DWC_WAITQ_ABORT
 862
 863
 864 /** @name Threads
 865  *
 866  * A thread must be explicitly stopped.  It must check DWC_THREAD_SHOULD_STOP
 867  * whenever it is woken up, and then return.  The DWC_THREAD_STOP function
 868  * returns the value from the thread.
 869  */
 870
 871 struct dwc_thread;
 872
 873 /** Type for a thread */
 874 typedef struct dwc_thread dwc_thread_t;
 875
 876 /** The thread function */
 877 typedef int (*dwc_thread_function_t)(void *data);
 878
 879 /** Create a thread and start it running the thread_function.  Returns a handle
 880  * to the thread */
 881 extern dwc_thread_t *DWC_THREAD_RUN(dwc_thread_function_t func, char *name, void *data);
 882 #define dwc_thread_run(_ctx_,_func_,_name_,_data_) DWC_THREAD_RUN(_func_, _name_, _data_)
 883
 884 /** Stops a thread.  Return the value returned by the thread.  Or will return
 885  * DWC_ABORT if the thread never started. */
 886 extern int DWC_THREAD_STOP(dwc_thread_t *thread);
 887 #define dwc_thread_stop DWC_THREAD_STOP
 888
 889 /** Signifies to the thread that it must stop. */
 890 #ifdef DWC_LINUX
 891 /* Linux doesn't need any parameters for kthread_should_stop() */
 892 extern dwc_bool_t DWC_THREAD_SHOULD_STOP(void);
 893 #define dwc_thread_should_stop(_thrd_) DWC_THREAD_SHOULD_STOP()
 894
 895 /* No thread_exit function in Linux */
 896 #define dwc_thread_exit(_thrd_)
 897 #endif
 898
 899 #if defined(DWC_FREEBSD) || defined(DWC_NETBSD)
 900 /** BSD needs the thread pointer for kthread_suspend_check() */
 901 extern dwc_bool_t DWC_THREAD_SHOULD_STOP(dwc_thread_t *thread);
 902 #define dwc_thread_should_stop DWC_THREAD_SHOULD_STOP
 903
 904 /** The thread must call this to exit. */
 905 extern void DWC_THREAD_EXIT(dwc_thread_t *thread);
 906 #define dwc_thread_exit DWC_THREAD_EXIT
 907 #endif
 908
 909
 910 /** @name Work queues
 911  *
 912  * Workqs are used to queue a callback function to be called at some later time,
 913  * in another thread. */
 914 struct dwc_workq;
 915
 916 /** Type for a workq */
 917 typedef struct dwc_workq dwc_workq_t;
 918
 919 /** The type of the callback function to be called. */
 920 typedef void (*dwc_work_callback_t)(void *data);
 921
 922 /** Allocate a workq */
 923 extern dwc_workq_t *DWC_WORKQ_ALLOC(char *name);
 924 #define dwc_workq_alloc(_ctx_,_name_) DWC_WORKQ_ALLOC(_name_)
 925
 926 /** Free a workq.  All work must be completed before being freed. */
 927 extern void DWC_WORKQ_FREE(dwc_workq_t *workq);
 928 #define dwc_workq_free DWC_WORKQ_FREE
 929
 930 /** Schedule a callback on the workq, passing in data.  The function will be
 931  * scheduled at some later time. */
 932 extern void DWC_WORKQ_SCHEDULE(dwc_workq_t *workq, dwc_work_callback_t cb,
 933                                void *data, char *format, ...)
 934 #ifdef __GNUC__
 935         __attribute__ ((format(printf, 4, 5)));
 936 #else
 937         ;
 938 #endif
 939 #define dwc_workq_schedule DWC_WORKQ_SCHEDULE
 940
 941 /** Schedule a callback on the workq, that will be called until at least
 942  * given number miliseconds have passed. */
 943 extern void DWC_WORKQ_SCHEDULE_DELAYED(dwc_workq_t *workq, dwc_work_callback_t cb,
 944                                        void *data, uint32_t time, char *format, ...)
 945 #ifdef __GNUC__
 946         __attribute__ ((format(printf, 5, 6)));
 947 #else
 948         ;
 949 #endif
 950 #define dwc_workq_schedule_delayed DWC_WORKQ_SCHEDULE_DELAYED
 951
 952 /** The number of processes in the workq */
 953 extern int DWC_WORKQ_PENDING(dwc_workq_t *workq);
 954 #define dwc_workq_pending DWC_WORKQ_PENDING
 955
 956 /** Blocks until all the work in the workq is complete or timed out.  Returns <
 957  * 0 on timeout. */
 958 extern int DWC_WORKQ_WAIT_WORK_DONE(dwc_workq_t *workq, int timeout);
 959 #define dwc_workq_wait_work_done DWC_WORKQ_WAIT_WORK_DONE
 960
 961
 962 /** @name Tasklets
 963  *
 964  */
 965 struct dwc_tasklet;
 966
 967 /** Type for a tasklet */
 968 typedef struct dwc_tasklet dwc_tasklet_t;
 969
 970 /** The type of the callback function to be called */
 971 typedef void (*dwc_tasklet_callback_t)(void *data);
 972
 973 /** Allocates a tasklet */
 974 extern dwc_tasklet_t *DWC_TASK_ALLOC(char *name, dwc_tasklet_callback_t cb, void *data);
 975 #define dwc_task_alloc(_ctx_,_name_,_cb_,_data_) DWC_TASK_ALLOC(_name_, _cb_, _data_)
 976
 977 /** Frees a tasklet */
 978 extern void DWC_TASK_FREE(dwc_tasklet_t *task);
 979 #define dwc_task_free DWC_TASK_FREE
 980
 981 /** Schedules a tasklet to run */
 982 extern void DWC_TASK_SCHEDULE(dwc_tasklet_t *task);
 983 #define dwc_task_schedule DWC_TASK_SCHEDULE
 984
 985 extern void DWC_TASK_HI_SCHEDULE(dwc_tasklet_t *task);
 986 #define dwc_task_hi_schedule DWC_TASK_HI_SCHEDULE
 987
 988 /** @name Timer
 989  *
 990  * Callbacks must be small and atomic.
 991  */
 992 struct dwc_timer;
 993
 994 /** Type for a timer */
 995 typedef struct dwc_timer dwc_timer_t;
 996
 997 /** The type of the callback function to be called */
 998 typedef void (*dwc_timer_callback_t)(void *data);
 999
1000 /** Allocates a timer */
1001 extern dwc_timer_t *DWC_TIMER_ALLOC(char *name, dwc_timer_callback_t cb, void *data);
1002 #define dwc_timer_alloc(_ctx_,_name_,_cb_,_data_) DWC_TIMER_ALLOC(_name_,_cb_,_data_)
1003
1004 /** Frees a timer */
1005 extern void DWC_TIMER_FREE(dwc_timer_t *timer);
1006 #define dwc_timer_free DWC_TIMER_FREE
1007
1008 /** Schedules the timer to run at time ms from now.  And will repeat at every
1009  * repeat_interval msec therafter
1010  *
1011  * Modifies a timer that is still awaiting execution to a new expiration time.
1012  * The mod_time is added to the old time.  */
1013 extern void DWC_TIMER_SCHEDULE(dwc_timer_t *timer, uint32_t time);
1014 #define dwc_timer_schedule DWC_TIMER_SCHEDULE
1015
1016 /** Disables the timer from execution. */
1017 extern void DWC_TIMER_CANCEL(dwc_timer_t *timer);
1018 #define dwc_timer_cancel DWC_TIMER_CANCEL
1019
1020
1021 /** @name Spinlocks
1022  *
1023  * These locks are used when the work between the lock/unlock is atomic and
1024  * short.  Interrupts are also disabled during the lock/unlock and thus they are
1025  * suitable to lock between interrupt/non-interrupt context.  They also lock
1026  * between processes if you have multiple CPUs or Preemption.  If you don't have
1027  * multiple CPUS or Preemption, then the you can simply implement the
1028  * DWC_SPINLOCK and DWC_SPINUNLOCK to disable and enable interrupts.  Because
1029  * the work between the lock/unlock is atomic, the process context will never
1030  * change, and so you never have to lock between processes.  */
1031
1032 struct dwc_spinlock;
1033
1034 /** Type for a spinlock */
1035 typedef struct dwc_spinlock dwc_spinlock_t;
1036
1037 /** Type for the 'flags' argument to spinlock funtions */
1038 typedef unsigned long dwc_irqflags_t;
1039
1040 /** Returns an initialized lock variable.  This function should allocate and
1041  * initialize the OS-specific data structure used for locking.  This data
1042  * structure is to be used for the DWC_LOCK and DWC_UNLOCK functions and should
1043  * be freed by the DWC_FREE_LOCK when it is no longer used.
1044  *
1045  * For Linux Spinlock Debugging make it macro because the debugging routines use
1046  * the symbol name to determine recursive locking. Using a wrapper function
1047  * makes it falsely think recursive locking occurs. */
1048 #if defined(DWC_LINUX) && defined(CONFIG_DEBUG_SPINLOCK)
1049 #define DWC_SPINLOCK_ALLOC_LINUX_DEBUG(lock) ({ \
1050         lock = DWC_ALLOC(sizeof(spinlock_t)); \
1051         if (lock) { \
1052                 spin_lock_init((spinlock_t *)lock); \
1053         } \
1054 })
1055 #else
1056 extern dwc_spinlock_t *DWC_SPINLOCK_ALLOC(void);
1057 #define dwc_spinlock_alloc(_ctx_) DWC_SPINLOCK_ALLOC()
1058 #endif
1059
1060 /** Frees an initialized lock variable. */
1061 extern void DWC_SPINLOCK_FREE(dwc_spinlock_t *lock);
1062 #define dwc_spinlock_free(_ctx_,_lock_) DWC_SPINLOCK_FREE(_lock_)
1063
1064 /** Disables interrupts and blocks until it acquires the lock.
1065  *
1066  * @param lock Pointer to the spinlock.
1067  * @param flags Unsigned long for irq flags storage.
1068  */
1069 extern void DWC_SPINLOCK_IRQSAVE(dwc_spinlock_t *lock, dwc_irqflags_t *flags);
1070 #define dwc_spinlock_irqsave DWC_SPINLOCK_IRQSAVE
1071
1072 /** Re-enables the interrupt and releases the lock.
1073  *
1074  * @param lock Pointer to the spinlock.
1075  * @param flags Unsigned long for irq flags storage.  Must be the same as was
1076  * passed into DWC_LOCK.
1077  */
1078 extern void DWC_SPINUNLOCK_IRQRESTORE(dwc_spinlock_t *lock, dwc_irqflags_t flags);
1079 #define dwc_spinunlock_irqrestore DWC_SPINUNLOCK_IRQRESTORE
1080
1081 /** Blocks until it acquires the lock.
1082  *
1083  * @param lock Pointer to the spinlock.
1084  */
1085 extern void DWC_SPINLOCK(dwc_spinlock_t *lock);
1086 #define dwc_spinlock DWC_SPINLOCK
1087
1088 /** Releases the lock.
1089  *
1090  * @param lock Pointer to the spinlock.
1091  */
1092 extern void DWC_SPINUNLOCK(dwc_spinlock_t *lock);
1093 #define dwc_spinunlock DWC_SPINUNLOCK
1094
1095
1096 /** @name Mutexes
1097  *
1098  * Unlike spinlocks Mutexes lock only between processes and the work between the
1099  * lock/unlock CAN block, therefore it CANNOT be called from interrupt context.
1100  */
1101
1102 struct dwc_mutex;
1103
1104 /** Type for a mutex */
1105 typedef struct dwc_mutex dwc_mutex_t;
1106
1107 /* For Linux Mutex Debugging make it inline because the debugging routines use
1108  * the symbol to determine recursive locking.  This makes it falsely think
1109  * recursive locking occurs. */
1110 #if defined(DWC_LINUX) && defined(CONFIG_DEBUG_MUTEXES)
1111 #define DWC_MUTEX_ALLOC_LINUX_DEBUG(__mutexp) ({ \
1112         __mutexp = (dwc_mutex_t *)DWC_ALLOC(sizeof(struct mutex)); \
1113         mutex_init((struct mutex *)__mutexp); \
1114 })
1115 #endif
1116
1117 /** Allocate a mutex */
1118 extern dwc_mutex_t *DWC_MUTEX_ALLOC(void);
1119 #define dwc_mutex_alloc(_ctx_) DWC_MUTEX_ALLOC()
1120
1121 /* For memory leak debugging when using Linux Mutex Debugging */
1122 #if defined(DWC_LINUX) && defined(CONFIG_DEBUG_MUTEXES)
1123 #define DWC_MUTEX_FREE(__mutexp) do { \
1124         mutex_destroy((struct mutex *)__mutexp); \
1125         DWC_FREE(__mutexp); \
1126 } while(0)
1127 #else
1128 /** Free a mutex */
1129 extern void DWC_MUTEX_FREE(dwc_mutex_t *mutex);
1130 #define dwc_mutex_free(_ctx_,_mutex_) DWC_MUTEX_FREE(_mutex_)
1131 #endif
1132
1133 /** Lock a mutex */
1134 extern void DWC_MUTEX_LOCK(dwc_mutex_t *mutex);
1135 #define dwc_mutex_lock DWC_MUTEX_LOCK
1136
1137 /** Non-blocking lock returns 1 on successful lock. */
1138 extern int DWC_MUTEX_TRYLOCK(dwc_mutex_t *mutex);
1139 #define dwc_mutex_trylock DWC_MUTEX_TRYLOCK
1140
1141 /** Unlock a mutex */
1142 extern void DWC_MUTEX_UNLOCK(dwc_mutex_t *mutex);
1143 #define dwc_mutex_unlock DWC_MUTEX_UNLOCK
1144
1145
1146 /** @name Time */
1147
1148 /** Microsecond delay.
1149  *
1150  * @param usecs  Microseconds to delay.
1151  */
1152 extern void DWC_UDELAY(uint32_t usecs);
1153 #define dwc_udelay DWC_UDELAY
1154
1155 /** Millisecond delay.
1156  *
1157  * @param msecs  Milliseconds to delay.
1158  */
1159 extern void DWC_MDELAY(uint32_t msecs);
1160 #define dwc_mdelay DWC_MDELAY
1161
1162 /** Non-busy waiting.
1163  * Sleeps for specified number of milliseconds.
1164  *
1165  * @param msecs Milliseconds to sleep.
1166  */
1167 extern void DWC_MSLEEP(uint32_t msecs);
1168 #define dwc_msleep DWC_MSLEEP
1169
1170 /**
1171  * Returns number of milliseconds since boot.
1172  */
1173 extern uint32_t DWC_TIME(void);
1174 #define dwc_time DWC_TIME
1175
1176
1177
1178
1179 /* @mainpage DWC Portability and Common Library
1180  *
1181  * This is the documentation for the DWC Portability and Common Library.
1182  *
1183  * @section intro Introduction
1184  *
1185  * The DWC Portability library consists of wrapper calls and data structures to
1186  * all low-level functions which are typically provided by the OS.  The WUDEV
1187  * driver uses only these functions.  In order to port the WUDEV driver, only
1188  * the functions in this library need to be re-implemented, with the same
1189  * behavior as documented here.
1190  *
1191  * The Common library consists of higher level functions, which rely only on
1192  * calling the functions from the DWC Portability library.  These common
1193  * routines are shared across modules.  Some of the common libraries need to be
1194  * used directly by the driver programmer when porting WUDEV.  Such as the
1195  * parameter and notification libraries.
1196  *
1197  * @section low Portability Library OS Wrapper Functions
1198  *
1199  * Any function starting with DWC and in all CAPS is a low-level OS-wrapper that
1200  * needs to be implemented when porting, for example DWC_MUTEX_ALLOC().  All of
1201  * these functions are included in the dwc_os.h file.
1202  *
1203  * There are many functions here covering a wide array of OS services.  Please
1204  * see dwc_os.h for details, and implementation notes for each function.
1205  *
1206  * @section common Common Library Functions
1207  *
1208  * Any function starting with dwc and in all lowercase is a common library
1209  * routine.  These functions have a portable implementation and do not need to
1210  * be reimplemented when porting.  The common routines can be used by any
1211  * driver, and some must be used by the end user to control the drivers.  For
1212  * example, you must use the Parameter common library in order to set the
1213  * parameters in the WUDEV module.
1214  *
1215  * The common libraries consist of the following:
1216  *
1217  * - Connection Contexts - Used internally and can be used by end-user.  See dwc_cc.h
1218  * - Parameters - Used internally and can be used by end-user.  See dwc_params.h
1219  * - Notifications - Used internally and can be used by end-user.  See dwc_notifier.h
1220  * - Lists - Used internally and can be used by end-user.  See dwc_list.h
1221  * - Memory Debugging - Used internally and can be used by end-user.  See dwc_os.h
1222  * - Modpow - Used internally only.  See dwc_modpow.h
1223  * - DH - Used internally only.  See dwc_dh.h
1224  * - Crypto - Used internally only.  See dwc_crypto.h
1225  *
1226  *
1227  * @section prereq Prerequistes For dwc_os.h
1228  * @subsection types Data Types
1229  *
1230  * The dwc_os.h file assumes that several low-level data types are pre defined for the
1231  * compilation environment.  These data types are:
1232  *
1233  * - uint8_t - unsigned 8-bit data type
1234  * - int8_t - signed 8-bit data type
1235  * - uint16_t - unsigned 16-bit data type
1236  * - int16_t - signed 16-bit data type
1237  * - uint32_t - unsigned 32-bit data type
1238  * - int32_t - signed 32-bit data type
1239  * - uint64_t - unsigned 64-bit data type
1240  * - int64_t - signed 64-bit data type
1241  *
1242  * Ensure that these are defined before using dwc_os.h.  The easiest way to do
1243  * that is to modify the top of the file to include the appropriate header.
1244  * This is already done for the Linux environment.  If the DWC_LINUX macro is
1245  * defined, the correct header will be added.  A standard header <stdint.h> is
1246  * also used for environments where standard C headers are available.
1247  *
1248  * @subsection stdarg Variable Arguments
1249  *
1250  * Variable arguments are provided by a standard C header <stdarg.h>.  it is
1251  * available in Both the Linux and ANSI C enviornment.  An equivalent must be
1252  * provided in your enviornment in order to use dwc_os.h with the debug and
1253  * tracing message functionality.
1254  *
1255  * @subsection thread Threading
1256  *
1257  * WUDEV Core must be run on an operating system that provides for multiple
1258  * threads/processes.  Threading can be implemented in many ways, even in
1259  * embedded systems without an operating system.  At the bare minimum, the
1260  * system should be able to start any number of processes at any time to handle
1261  * special work.  It need not be a pre-emptive system.  Process context can
1262  * change upon a call to a blocking function.  The hardware interrupt context
1263  * that calls the module's ISR() function must be differentiable from process
1264  * context, even if your processes are impemented via a hardware interrupt.
1265  * Further locking mechanism between process must exist (or be implemented), and
1266  * process context must have a way to disable interrupts for a period of time to
1267  * lock them out.  If all of this exists, the functions in dwc_os.h related to
1268  * threading should be able to be implemented with the defined behavior.
1269  *
1270  */
1271
1272 #ifdef __cplusplus
1273 }
1274 #endif
1275
1276 #endif /* _DWC_OS_H_ */