diff options
Diffstat (limited to 'drivers/usb/host/dwc_common_port/dwc_os.h')
| -rw-r--r-- | drivers/usb/host/dwc_common_port/dwc_os.h | 1276 |
1 files changed, 1276 insertions, 0 deletions
diff --git a/drivers/usb/host/dwc_common_port/dwc_os.h b/drivers/usb/host/dwc_common_port/dwc_os.h new file mode 100644 index 000000000000..9a86d299403b --- /dev/null +++ b/drivers/usb/host/dwc_common_port/dwc_os.h @@ -0,0 +1,1276 @@ +/* ========================================================================= + * $File: //dwh/usb_iip/dev/software/dwc_common_port_2/dwc_os.h $ + * $Revision: #14 $ + * $Date: 2010/11/04 $ + * $Change: 1621695 $ + * + * Synopsys Portability Library Software and documentation + * (hereinafter, "Software") is an Unsupported proprietary work of + * Synopsys, Inc. unless otherwise expressly agreed to in writing + * between Synopsys and you. + * + * The Software IS NOT an item of Licensed Software or Licensed Product + * under any End User Software License Agreement or Agreement for + * Licensed Product with Synopsys or any supplement thereto. You are + * permitted to use and redistribute this Software in source and binary + * forms, with or without modification, provided that redistributions + * of source code must retain this notice. You may not view, use, + * disclose, copy or distribute this file or any information contained + * herein except pursuant to this license grant from Synopsys. If you + * do not agree with this notice, including the disclaimer below, then + * you are not authorized to use the Software. + * + * THIS SOFTWARE IS BEING DISTRIBUTED BY SYNOPSYS SOLELY ON AN "AS IS" + * BASIS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + * FOR A PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL + * SYNOPSYS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE + * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + * DAMAGE. + * ========================================================================= */ +#ifndef _DWC_OS_H_ +#define _DWC_OS_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +/** @file + * + * DWC portability library, low level os-wrapper functions + * + */ + +/* These basic types need to be defined by some OS header file or custom header + * file for your specific target architecture. + * + * uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t, int64_t + * + * Any custom or alternate header file must be added and enabled here. + */ + +#ifdef DWC_LINUX +# include <linux/types.h> +# ifdef CONFIG_DEBUG_MUTEXES +# include <linux/mutex.h> +# endif +# include <linux/spinlock.h> +# include <linux/errno.h> +# include <stdarg.h> +#endif + +#if defined(DWC_FREEBSD) || defined(DWC_NETBSD) +# include <os_dep.h> +#endif + + +/** @name Primitive Types and Values */ + +/** We define a boolean type for consistency. Can be either YES or NO */ +typedef uint8_t dwc_bool_t; +#define YES 1 +#define NO 0 + +#ifdef DWC_LINUX + +/** @name Error Codes */ +#define DWC_E_INVALID EINVAL +#define DWC_E_NO_MEMORY ENOMEM +#define DWC_E_NO_DEVICE ENODEV +#define DWC_E_NOT_SUPPORTED EOPNOTSUPP +#define DWC_E_TIMEOUT ETIMEDOUT +#define DWC_E_BUSY EBUSY +#define DWC_E_AGAIN EAGAIN +#define DWC_E_RESTART ERESTART +#define DWC_E_ABORT ECONNABORTED +#define DWC_E_SHUTDOWN ESHUTDOWN +#define DWC_E_NO_DATA ENODATA +#define DWC_E_DISCONNECT ECONNRESET +#define DWC_E_UNKNOWN EINVAL +#define DWC_E_NO_STREAM_RES ENOSR +#define DWC_E_COMMUNICATION ECOMM +#define DWC_E_OVERFLOW EOVERFLOW +#define DWC_E_PROTOCOL EPROTO +#define DWC_E_IN_PROGRESS EINPROGRESS +#define DWC_E_PIPE EPIPE +#define DWC_E_IO EIO +#define DWC_E_NO_SPACE ENOSPC + +#else + +/** @name Error Codes */ +#define DWC_E_INVALID 1001 +#define DWC_E_NO_MEMORY 1002 +#define DWC_E_NO_DEVICE 1003 +#define DWC_E_NOT_SUPPORTED 1004 +#define DWC_E_TIMEOUT 1005 +#define DWC_E_BUSY 1006 +#define DWC_E_AGAIN 1007 +#define DWC_E_RESTART 1008 +#define DWC_E_ABORT 1009 +#define DWC_E_SHUTDOWN 1010 +#define DWC_E_NO_DATA 1011 +#define DWC_E_DISCONNECT 2000 +#define DWC_E_UNKNOWN 3000 +#define DWC_E_NO_STREAM_RES 4001 +#define DWC_E_COMMUNICATION 4002 +#define DWC_E_OVERFLOW 4003 +#define DWC_E_PROTOCOL 4004 +#define DWC_E_IN_PROGRESS 4005 +#define DWC_E_PIPE 4006 +#define DWC_E_IO 4007 +#define DWC_E_NO_SPACE 4008 + +#endif + + +/** @name Tracing/Logging Functions + * + * These function provide the capability to add tracing, debugging, and error + * messages, as well exceptions as assertions. The WUDEV uses these + * extensively. These could be logged to the main console, the serial port, an + * internal buffer, etc. These functions could also be no-op if they are too + * expensive on your system. By default undefining the DEBUG macro already + * no-ops some of these functions. */ + +/** Returns non-zero if in interrupt context. */ +extern dwc_bool_t DWC_IN_IRQ(void); +#define dwc_in_irq DWC_IN_IRQ + +/** Returns "IRQ" if DWC_IN_IRQ is true. */ +static inline char *dwc_irq(void) { + return DWC_IN_IRQ() ? "IRQ" : ""; +} + +/** Returns non-zero if in bottom-half context. */ +extern dwc_bool_t DWC_IN_BH(void); +#define dwc_in_bh DWC_IN_BH + +/** Returns "BH" if DWC_IN_BH is true. */ +static inline char *dwc_bh(void) { + return DWC_IN_BH() ? "BH" : ""; +} + +/** + * A vprintf() clone. Just call vprintf if you've got it. + */ +extern void DWC_VPRINTF(char *format, va_list args); +#define dwc_vprintf DWC_VPRINTF + +/** + * A vsnprintf() clone. Just call vprintf if you've got it. + */ +extern int DWC_VSNPRINTF(char *str, int size, char *format, va_list args); +#define dwc_vsnprintf DWC_VSNPRINTF + +/** + * printf() clone. Just call printf if you've go it. + */ +extern void DWC_PRINTF(char *format, ...) +/* This provides compiler level static checking of the parameters if you're + * using GCC. */ +#ifdef __GNUC__ + __attribute__ ((format(printf, 1, 2))); +#else + ; +#endif +#define dwc_printf DWC_PRINTF + +/** + * sprintf() clone. Just call sprintf if you've got it. + */ +extern int DWC_SPRINTF(char *string, char *format, ...) +#ifdef __GNUC__ + __attribute__ ((format(printf, 2, 3))); +#else + ; +#endif +#define dwc_sprintf DWC_SPRINTF + +/** + * snprintf() clone. Just call snprintf if you've got it. + */ +extern int DWC_SNPRINTF(char *string, int size, char *format, ...) +#ifdef __GNUC__ + __attribute__ ((format(printf, 3, 4))); +#else + ; +#endif +#define dwc_snprintf DWC_SNPRINTF + +/** + * Prints a WARNING message. On systems that don't differentiate between + * warnings and regular log messages, just print it. Indicates that something + * may be wrong with the driver. Works like printf(). + * + * Use the DWC_WARN macro to call this function. + */ +extern void __DWC_WARN(char *format, ...) +#ifdef __GNUC__ + __attribute__ ((format(printf, 1, 2))); +#else + ; +#endif + +/** + * Prints an error message. On systems that don't differentiate between errors + * and regular log messages, just print it. Indicates that something went wrong + * with the driver. Works like printf(). + * + * Use the DWC_ERROR macro to call this function. + */ +extern void __DWC_ERROR(char *format, ...) +#ifdef __GNUC__ + __attribute__ ((format(printf, 1, 2))); +#else + ; +#endif + +/** + * Prints an exception error message and takes some user-defined action such as + * print out a backtrace or trigger a breakpoint. Indicates that something went + * abnormally wrong with the driver such as programmer error, or other + * exceptional condition. It should not be ignored so even on systems without + * printing capability, some action should be taken to notify the developer of + * it. Works like printf(). + */ +extern void DWC_EXCEPTION(char *format, ...) +#ifdef __GNUC__ + __attribute__ ((format(printf, 1, 2))); +#else + ; +#endif +#define dwc_exception DWC_EXCEPTION + +#ifndef DWC_OTG_DEBUG_LEV +#define DWC_OTG_DEBUG_LEV 0 +#endif + +#ifdef DEBUG +/** + * Prints out a debug message. Used for logging/trace messages. + * + * Use the DWC_DEBUG macro to call this function + */ +extern void __DWC_DEBUG(char *format, ...) +#ifdef __GNUC__ + __attribute__ ((format(printf, 1, 2))); +#else + ; +#endif +#else +#define __DWC_DEBUG printk +#endif + +/** + * Prints out a Debug message. + */ +#define DWC_DEBUG(_format, _args...) __DWC_DEBUG("DEBUG:%s:%s: " _format "\n", \ + __func__, dwc_irq(), ## _args) +#define dwc_debug DWC_DEBUG +/** + * Prints out a Debug message if enabled at compile time. + */ +#if DWC_OTG_DEBUG_LEV > 0 +#define DWC_DEBUGC(_format, _args...) DWC_DEBUG(_format, ##_args ) +#else +#define DWC_DEBUGC(_format, _args...) +#endif +#define dwc_debugc DWC_DEBUGC +/** + * Prints out an informative message. + */ +#define DWC_INFO(_format, _args...) DWC_PRINTF("INFO:%s: " _format "\n", \ + dwc_irq(), ## _args) +#define dwc_info DWC_INFO +/** + * Prints out an informative message if enabled at compile time. + */ +#if DWC_OTG_DEBUG_LEV > 1 +#define DWC_INFOC(_format, _args...) DWC_INFO(_format, ##_args ) +#else +#define DWC_INFOC(_format, _args...) +#endif +#define dwc_infoc DWC_INFOC +/** + * Prints out a warning message. + */ +#define DWC_WARN(_format, _args...) __DWC_WARN("WARN:%s:%s:%d: " _format "\n", \ + dwc_irq(), __func__, __LINE__, ## _args) +#define dwc_warn DWC_WARN +/** + * Prints out an error message. + */ +#define DWC_ERROR(_format, _args...) __DWC_ERROR("ERROR:%s:%s:%d: " _format "\n", \ + dwc_irq(), __func__, __LINE__, ## _args) +#define dwc_error DWC_ERROR + +#define DWC_PROTO_ERROR(_format, _args...) __DWC_WARN("ERROR:%s:%s:%d: " _format "\n", \ + dwc_irq(), __func__, __LINE__, ## _args) +#define dwc_proto_error DWC_PROTO_ERROR + +#ifdef DEBUG +/** Prints out a exception error message if the _expr expression fails. Disabled + * if DEBUG is not enabled. */ +#define DWC_ASSERT(_expr, _format, _args...) do { \ + if (!(_expr)) { DWC_EXCEPTION("%s:%s:%d: " _format "\n", dwc_irq(), \ + __FILE__, __LINE__, ## _args); } \ + } while (0) +#else +#define DWC_ASSERT(_x...) +#endif +#define dwc_assert DWC_ASSERT + + +/** @name Byte Ordering + * The following functions are for conversions between processor's byte ordering + * and specific ordering you want. + */ + +/** Converts 32 bit data in CPU byte ordering to little endian. */ +extern uint32_t DWC_CPU_TO_LE32(uint32_t *p); +#define dwc_cpu_to_le32 DWC_CPU_TO_LE32 + +/** Converts 32 bit data in CPU byte orderint to big endian. */ +extern uint32_t DWC_CPU_TO_BE32(uint32_t *p); +#define dwc_cpu_to_be32 DWC_CPU_TO_BE32 + +/** Converts 32 bit little endian data to CPU byte ordering. */ +extern uint32_t DWC_LE32_TO_CPU(uint32_t *p); +#define dwc_le32_to_cpu DWC_LE32_TO_CPU + +/** Converts 32 bit big endian data to CPU byte ordering. */ +extern uint32_t DWC_BE32_TO_CPU(uint32_t *p); +#define dwc_be32_to_cpu DWC_BE32_TO_CPU + +/** Converts 16 bit data in CPU byte ordering to little endian. */ +extern uint16_t DWC_CPU_TO_LE16(uint16_t *p); +#define dwc_cpu_to_le16 DWC_CPU_TO_LE16 + +/** Converts 16 bit data in CPU byte orderint to big endian. */ +extern uint16_t DWC_CPU_TO_BE16(uint16_t *p); +#define dwc_cpu_to_be16 DWC_CPU_TO_BE16 + +/** Converts 16 bit little endian data to CPU byte ordering. */ +extern uint16_t DWC_LE16_TO_CPU(uint16_t *p); +#define dwc_le16_to_cpu DWC_LE16_TO_CPU + +/** Converts 16 bit bi endian data to CPU byte ordering. */ +extern uint16_t DWC_BE16_TO_CPU(uint16_t *p); +#define dwc_be16_to_cpu DWC_BE16_TO_CPU + + +/** @name Register Read/Write + * + * The following six functions should be implemented to read/write registers of + * 32-bit and 64-bit sizes. All modules use this to read/write register values. + * The reg value is a pointer to the register calculated from the void *base + * variable passed into the driver when it is started. */ + +#ifdef DWC_LINUX +/* Linux doesn't need any extra parameters for register read/write, so we + * just throw away the IO context parameter. + */ +/** Reads the content of a 32-bit register. */ +extern uint32_t DWC_READ_REG32(uint32_t volatile *reg); +#define dwc_read_reg32(_ctx_,_reg_) DWC_READ_REG32(_reg_) + +/** Reads the content of a 64-bit register. */ +extern uint64_t DWC_READ_REG64(uint64_t volatile *reg); +#define dwc_read_reg64(_ctx_,_reg_) DWC_READ_REG64(_reg_) + +/** Writes to a 32-bit register. */ +extern void DWC_WRITE_REG32(uint32_t volatile *reg, uint32_t value); +#define dwc_write_reg32(_ctx_,_reg_,_val_) DWC_WRITE_REG32(_reg_, _val_) + +/** Writes to a 64-bit register. */ +extern void DWC_WRITE_REG64(uint64_t volatile *reg, uint64_t value); +#define dwc_write_reg64(_ctx_,_reg_,_val_) DWC_WRITE_REG64(_reg_, _val_) + +/** + * Modify bit values in a register. Using the + * algorithm: (reg_contents & ~clear_mask) | set_mask. + */ +extern void DWC_MODIFY_REG32(uint32_t volatile *reg, uint32_t clear_mask, uint32_t set_mask); +#define dwc_modify_reg32(_ctx_,_reg_,_cmsk_,_smsk_) DWC_MODIFY_REG32(_reg_,_cmsk_,_smsk_) +extern void DWC_MODIFY_REG64(uint64_t volatile *reg, uint64_t clear_mask, uint64_t set_mask); +#define dwc_modify_reg64(_ctx_,_reg_,_cmsk_,_smsk_) DWC_MODIFY_REG64(_reg_,_cmsk_,_smsk_) + +#endif /* DWC_LINUX */ + +#if defined(DWC_FREEBSD) || defined(DWC_NETBSD) +typedef struct dwc_ioctx { + struct device *dev; + bus_space_tag_t iot; + bus_space_handle_t ioh; +} dwc_ioctx_t; + +/** BSD needs two extra parameters for register read/write, so we pass + * them in using the IO context parameter. + */ +/** Reads the content of a 32-bit register. */ +extern uint32_t DWC_READ_REG32(void *io_ctx, uint32_t volatile *reg); +#define dwc_read_reg32 DWC_READ_REG32 + +/** Reads the content of a 64-bit register. */ +extern uint64_t DWC_READ_REG64(void *io_ctx, uint64_t volatile *reg); +#define dwc_read_reg64 DWC_READ_REG64 + +/** Writes to a 32-bit register. */ +extern void DWC_WRITE_REG32(void *io_ctx, uint32_t volatile *reg, uint32_t value); +#define dwc_write_reg32 DWC_WRITE_REG32 + +/** Writes to a 64-bit register. */ +extern void DWC_WRITE_REG64(void *io_ctx, uint64_t volatile *reg, uint64_t value); +#define dwc_write_reg64 DWC_WRITE_REG64 + +/** + * Modify bit values in a register. Using the + * algorithm: (reg_contents & ~clear_mask) | set_mask. + */ +extern void DWC_MODIFY_REG32(void *io_ctx, uint32_t volatile *reg, uint32_t clear_mask, uint32_t set_mask); +#define dwc_modify_reg32 DWC_MODIFY_REG32 +extern void DWC_MODIFY_REG64(void *io_ctx, uint64_t volatile *reg, uint64_t clear_mask, uint64_t set_mask); +#define dwc_modify_reg64 DWC_MODIFY_REG64 + +#endif /* DWC_FREEBSD || DWC_NETBSD */ + +/** @cond */ + +/** @name Some convenience MACROS used internally. Define DWC_DEBUG_REGS to log the + * register writes. */ + +#ifdef DWC_LINUX + +# ifdef DWC_DEBUG_REGS + +#define dwc_define_read_write_reg_n(_reg,_container_type) \ +static inline uint32_t dwc_read_##_reg##_n(_container_type *container, int num) { \ + return DWC_READ_REG32(&container->regs->_reg[num]); \ +} \ +static inline void dwc_write_##_reg##_n(_container_type *container, int num, uint32_t data) { \ + DWC_DEBUG("WRITING %8s[%d]: %p: %08x", #_reg, num, \ + &(((uint32_t*)container->regs->_reg)[num]), data); \ + DWC_WRITE_REG32(&(((uint32_t*)container->regs->_reg)[num]), data); \ +} + +#define dwc_define_read_write_reg(_reg,_container_type) \ +static inline uint32_t dwc_read_##_reg(_container_type *container) { \ + return DWC_READ_REG32(&container->regs->_reg); \ +} \ +static inline void dwc_write_##_reg(_container_type *container, uint32_t data) { \ + DWC_DEBUG("WRITING %11s: %p: %08x", #_reg, &container->regs->_reg, data); \ + DWC_WRITE_REG32(&container->regs->_reg, data); \ +} + +# else /* DWC_DEBUG_REGS */ + +#define dwc_define_read_write_reg_n(_reg,_container_type) \ +static inline uint32_t dwc_read_##_reg##_n(_container_type *container, int num) { \ + return DWC_READ_REG32(&container->regs->_reg[num]); \ +} \ +static inline void dwc_write_##_reg##_n(_container_type *container, int num, uint32_t data) { \ + DWC_WRITE_REG32(&(((uint32_t*)container->regs->_reg)[num]), data); \ +} + +#define dwc_define_read_write_reg(_reg,_container_type) \ +static inline uint32_t dwc_read_##_reg(_container_type *container) { \ + return DWC_READ_REG32(&container->regs->_reg); \ +} \ +static inline void dwc_write_##_reg(_container_type *container, uint32_t data) { \ + DWC_WRITE_REG32(&container->regs->_reg, data); \ +} + +# endif /* DWC_DEBUG_REGS */ + +#endif /* DWC_LINUX */ + +#if defined(DWC_FREEBSD) || defined(DWC_NETBSD) + +# ifdef DWC_DEBUG_REGS + +#define dwc_define_read_write_reg_n(_reg,_container_type) \ +static inline uint32_t dwc_read_##_reg##_n(void *io_ctx, _container_type *container, int num) { \ + return DWC_READ_REG32(io_ctx, &container->regs->_reg[num]); \ +} \ +static inline void dwc_write_##_reg##_n(void *io_ctx, _container_type *container, int num, uint32_t data) { \ + DWC_DEBUG("WRITING %8s[%d]: %p: %08x", #_reg, num, \ + &(((uint32_t*)container->regs->_reg)[num]), data); \ + DWC_WRITE_REG32(io_ctx, &(((uint32_t*)container->regs->_reg)[num]), data); \ +} + +#define dwc_define_read_write_reg(_reg,_container_type) \ +static inline uint32_t dwc_read_##_reg(void *io_ctx, _container_type *container) { \ + return DWC_READ_REG32(io_ctx, &container->regs->_reg); \ +} \ +static inline void dwc_write_##_reg(void *io_ctx, _container_type *container, uint32_t data) { \ + DWC_DEBUG("WRITING %11s: %p: %08x", #_reg, &container->regs->_reg, data); \ + DWC_WRITE_REG32(io_ctx, &container->regs->_reg, data); \ +} + +# else /* DWC_DEBUG_REGS */ + +#define dwc_define_read_write_reg_n(_reg,_container_type) \ +static inline uint32_t dwc_read_##_reg##_n(void *io_ctx, _container_type *container, int num) { \ + return DWC_READ_REG32(io_ctx, &container->regs->_reg[num]); \ +} \ +static inline void dwc_write_##_reg##_n(void *io_ctx, _container_type *container, int num, uint32_t data) { \ + DWC_WRITE_REG32(io_ctx, &(((uint32_t*)container->regs->_reg)[num]), data); \ +} + +#define dwc_define_read_write_reg(_reg,_container_type) \ +static inline uint32_t dwc_read_##_reg(void *io_ctx, _container_type *container) { \ + return DWC_READ_REG32(io_ctx, &container->regs->_reg); \ +} \ +static inline void dwc_write_##_reg(void *io_ctx, _container_type *container, uint32_t data) { \ + DWC_WRITE_REG32(io_ctx, &container->regs->_reg, data); \ +} + +# endif /* DWC_DEBUG_REGS */ + +#endif /* DWC_FREEBSD || DWC_NETBSD */ + +/** @endcond */ + + +#ifdef DWC_CRYPTOLIB +/** @name Crypto Functions + * + * These are the low-level cryptographic functions used by the driver. */ + +/** Perform AES CBC */ +extern int DWC_AES_CBC(uint8_t *message, uint32_t messagelen, uint8_t *key, uint32_t keylen, uint8_t iv[16], uint8_t *out); +#define dwc_aes_cbc DWC_AES_CBC + +/** Fill the provided buffer with random bytes. These should be cryptographic grade random numbers. */ +extern void DWC_RANDOM_BYTES(uint8_t *buffer, uint32_t length); +#define dwc_random_bytes DWC_RANDOM_BYTES + +/** Perform the SHA-256 hash function */ +extern int DWC_SHA256(uint8_t *message, uint32_t len, uint8_t *out); +#define dwc_sha256 DWC_SHA256 + +/** Calculated the HMAC-SHA256 */ +extern int DWC_HMAC_SHA256(uint8_t *message, uint32_t messagelen, uint8_t *key, uint32_t keylen, uint8_t *out); +#define dwc_hmac_sha256 DWC_HMAC_SHA256 + +#endif /* DWC_CRYPTOLIB */ + + +/** @name Memory Allocation + * + * These function provide access to memory allocation. There are only 2 DMA + * functions and 3 Regular memory functions that need to be implemented. None + * of the memory debugging routines need to be implemented. The allocation + * routines all ZERO the contents of the memory. + * + * Defining DWC_DEBUG_MEMORY turns on memory debugging and statistic gathering. + * This checks for memory leaks, keeping track of alloc/free pairs. It also + * keeps track of how much memory the driver is using at any given time. */ + +#define DWC_PAGE_SIZE 4096 +#define DWC_PAGE_OFFSET(addr) (((uint32_t)addr) & 0xfff) +#define DWC_PAGE_ALIGNED(addr) ((((uint32_t)addr) & 0xfff) == 0) + +#define DWC_INVALID_DMA_ADDR 0x0 + +#ifdef DWC_LINUX +/** Type for a DMA address */ +typedef dma_addr_t dwc_dma_t; +#endif + +#if defined(DWC_FREEBSD) || defined(DWC_NETBSD) +typedef bus_addr_t dwc_dma_t; +#endif + +#ifdef DWC_FREEBSD +typedef struct dwc_dmactx { + struct device *dev; + bus_dma_tag_t dma_tag; + bus_dmamap_t dma_map; + bus_addr_t dma_paddr; + void *dma_vaddr; +} dwc_dmactx_t; +#endif + +#ifdef DWC_NETBSD +typedef struct dwc_dmactx { + struct device *dev; + bus_dma_tag_t dma_tag; + bus_dmamap_t dma_map; + bus_dma_segment_t segs[1]; + int nsegs; + bus_addr_t dma_paddr; + void *dma_vaddr; +} dwc_dmactx_t; +#endif + +/* @todo these functions will be added in the future */ +#if 0 +/** + * Creates a DMA pool from which you can allocate DMA buffers. Buffers + * allocated from this pool will be guaranteed to meet the size, alignment, and + * boundary requirements specified. + * + * @param[in] size Specifies the size of the buffers that will be allocated from + * this pool. + * @param[in] align Specifies the byte alignment requirements of the buffers + * allocated from this pool. Must be a power of 2. + * @param[in] boundary Specifies the N-byte boundary that buffers allocated from + * this pool must not cross. + * + * @returns A pointer to an internal opaque structure which is not to be + * accessed outside of these library functions. Use this handle to specify + * which pools to allocate/free DMA buffers from and also to destroy the pool, + * when you are done with it. + */ +extern dwc_pool_t *DWC_DMA_POOL_CREATE(uint32_t size, uint32_t align, uint32_t boundary); + +/** + * Destroy a DMA pool. All buffers allocated from that pool must be freed first. + */ +extern void DWC_DMA_POOL_DESTROY(dwc_pool_t *pool); + +/** + * Allocate a buffer from the specified DMA pool and zeros its contents. + */ +extern void *DWC_DMA_POOL_ALLOC(dwc_pool_t *pool, uint64_t *dma_addr); + +/** + * Free a previously allocated buffer from the DMA pool. + */ +extern void DWC_DMA_POOL_FREE(dwc_pool_t *pool, void *vaddr, void *daddr); +#endif + +/** Allocates a DMA capable buffer and zeroes its contents. */ +extern void *__DWC_DMA_ALLOC(void *dma_ctx, uint32_t size, dwc_dma_t *dma_addr); + +/** Allocates a DMA capable buffer and zeroes its contents in atomic contest */ +extern void *__DWC_DMA_ALLOC_ATOMIC(void *dma_ctx, uint32_t size, dwc_dma_t *dma_addr); + +/** Frees a previously allocated buffer. */ +extern void __DWC_DMA_FREE(void *dma_ctx, uint32_t size, void *virt_addr, dwc_dma_t dma_addr); + +/** Allocates a block of memory and zeroes its contents. */ +extern void *__DWC_ALLOC(void *mem_ctx, uint32_t size); + +/** Allocates a block of memory and zeroes its contents, in an atomic manner + * which can be used inside interrupt context. The size should be sufficiently + * small, a few KB at most, such that failures are not likely to occur. Can just call + * __DWC_ALLOC if it is atomic. */ +extern void *__DWC_ALLOC_ATOMIC(void *mem_ctx, uint32_t size); + +/** Frees a previously allocated buffer. */ +extern void __DWC_FREE(void *mem_ctx, void *addr); + +#ifndef DWC_DEBUG_MEMORY + +#define DWC_ALLOC(_size_) __DWC_ALLOC(NULL, _size_) +#define DWC_ALLOC_ATOMIC(_size_) __DWC_ALLOC_ATOMIC(NULL, _size_) +#define DWC_FREE(_addr_) __DWC_FREE(NULL, _addr_) + +# ifdef DWC_LINUX +#define DWC_DMA_ALLOC(_dev, _size_, _dma_) __DWC_DMA_ALLOC(_dev, _size_, _dma_) +#define DWC_DMA_ALLOC_ATOMIC(_dev, _size_, _dma_) __DWC_DMA_ALLOC_ATOMIC(_dev, _size_, _dma_) +#define DWC_DMA_FREE(_dev, _size_,_virt_, _dma_) __DWC_DMA_FREE(_dev, _size_, _virt_, _dma_) +# endif + +# if defined(DWC_FREEBSD) || defined(DWC_NETBSD) +#define DWC_DMA_ALLOC __DWC_DMA_ALLOC +#define DWC_DMA_FREE __DWC_DMA_FREE +# endif +extern void *dwc_dma_alloc_atomic_debug(uint32_t size, dwc_dma_t *dma_addr, char const *func, int line); + +#else /* DWC_DEBUG_MEMORY */ + +extern void *dwc_alloc_debug(void *mem_ctx, uint32_t size, char const *func, int line); +extern void *dwc_alloc_atomic_debug(void *mem_ctx, uint32_t size, char const *func, int line); +extern void dwc_free_debug(void *mem_ctx, void *addr, char const *func, int line); +extern void *dwc_dma_alloc_debug(void *dma_ctx, uint32_t size, dwc_dma_t *dma_addr, + char const *func, int line); +extern void *dwc_dma_alloc_atomic_debug(void *dma_ctx, uint32_t size, dwc_dma_t *dma_addr, + char const *func, int line); +extern void dwc_dma_free_debug(void *dma_ctx, uint32_t size, void *virt_addr, + dwc_dma_t dma_addr, char const *func, int line); + +extern int dwc_memory_debug_start(void *mem_ctx); +extern void dwc_memory_debug_stop(void); +extern void dwc_memory_debug_report(void); + +#define DWC_ALLOC(_size_) dwc_alloc_debug(NULL, _size_, __func__, __LINE__) +#define DWC_ALLOC_ATOMIC(_size_) dwc_alloc_atomic_debug(NULL, _size_, \ + __func__, __LINE__) +#define DWC_FREE(_addr_) dwc_free_debug(NULL, _addr_, __func__, __LINE__) + +# ifdef DWC_LINUX +#define DWC_DMA_ALLOC(_dev, _size_, _dma_) \ + dwc_dma_alloc_debug(_dev, _size_, _dma_, __func__, __LINE__) +#define DWC_DMA_ALLOC_ATOMIC(_dev, _size_, _dma_) \ + dwc_dma_alloc_atomic_debug(_dev, _size_, _dma_, __func__, __LINE__) +#define DWC_DMA_FREE(_dev, _size_, _virt_, _dma_) \ + dwc_dma_free_debug(_dev, _size_, _virt_, _dma_, __func__, __LINE__) +# endif + +# if defined(DWC_FREEBSD) || defined(DWC_NETBSD) +#define DWC_DMA_ALLOC(_ctx_,_size_,_dma_) dwc_dma_alloc_debug(_ctx_, _size_, \ + _dma_, __func__, __LINE__) +#define DWC_DMA_FREE(_ctx_,_size_,_virt_,_dma_) dwc_dma_free_debug(_ctx_, _size_, \ + _virt_, _dma_, __func__, __LINE__) +# endif + +#endif /* DWC_DEBUG_MEMORY */ + +#define dwc_alloc(_ctx_,_size_) DWC_ALLOC(_size_) +#define dwc_alloc_atomic(_ctx_,_size_) DWC_ALLOC_ATOMIC(_size_) +#define dwc_free(_ctx_,_addr_) DWC_FREE(_addr_) + +#ifdef DWC_LINUX +/* Linux doesn't need any extra parameters for DMA buffer allocation, so we + * just throw away the DMA context parameter. + */ +#define dwc_dma_alloc(_ctx_,_size_,_dma_) DWC_DMA_ALLOC(_size_, _dma_) +#define dwc_dma_alloc_atomic(_ctx_,_size_,_dma_) DWC_DMA_ALLOC_ATOMIC(_size_, _dma_) +#define dwc_dma_free(_ctx_,_size_,_virt_,_dma_) DWC_DMA_FREE(_size_, _virt_, _dma_) +#endif + +#if defined(DWC_FREEBSD) || defined(DWC_NETBSD) +/** BSD needs several extra parameters for DMA buffer allocation, so we pass + * them in using the DMA context parameter. + */ +#define dwc_dma_alloc DWC_DMA_ALLOC +#define dwc_dma_free DWC_DMA_FREE +#endif + + +/** @name Memory and String Processing */ + +/** memset() clone */ +extern void *DWC_MEMSET(void *dest, uint8_t byte, uint32_t size); +#define dwc_memset DWC_MEMSET + +/** memcpy() clone */ +extern void *DWC_MEMCPY(void *dest, void const *src, uint32_t size); +#define dwc_memcpy DWC_MEMCPY + +/** memmove() clone */ +extern void *DWC_MEMMOVE(void *dest, void *src, uint32_t size); +#define dwc_memmove DWC_MEMMOVE + +/** memcmp() clone */ +extern int DWC_MEMCMP(void *m1, void *m2, uint32_t size); +#define dwc_memcmp DWC_MEMCMP + +/** strcmp() clone */ +extern int DWC_STRCMP(void *s1, void *s2); +#define dwc_strcmp DWC_STRCMP + +/** strncmp() clone */ +extern int DWC_STRNCMP(void *s1, void *s2, uint32_t size); +#define dwc_strncmp DWC_STRNCMP + +/** strlen() clone, for NULL terminated ASCII strings */ +extern int DWC_STRLEN(char const *str); +#define dwc_strlen DWC_STRLEN + +/** strcpy() clone, for NULL terminated ASCII strings */ +extern char *DWC_STRCPY(char *to, const char *from); +#define dwc_strcpy DWC_STRCPY + +/** strdup() clone. If you wish to use memory allocation debugging, this + * implementation of strdup should use the DWC_* memory routines instead of + * calling a predefined strdup. Otherwise the memory allocated by this routine + * will not be seen by the debugging routines. */ +extern char *DWC_STRDUP(char const *str); +#define dwc_strdup(_ctx_,_str_) DWC_STRDUP(_str_) + +/** NOT an atoi() clone. Read the description carefully. Returns an integer + * converted from the string str in base 10 unless the string begins with a "0x" + * in which case it is base 16. String must be a NULL terminated sequence of + * ASCII characters and may optionally begin with whitespace, a + or -, and a + * "0x" prefix if base 16. The remaining characters must be valid digits for + * the number and end with a NULL character. If any invalid characters are + * encountered or it returns with a negative error code and the results of the + * conversion are undefined. On sucess it returns 0. Overflow conditions are + * undefined. An example implementation using atoi() can be referenced from the + * Linux implementation. */ +extern int DWC_ATOI(const char *str, int32_t *value); +#define dwc_atoi DWC_ATOI + +/** Same as above but for unsigned. */ +extern int DWC_ATOUI(const char *str, uint32_t *value); +#define dwc_atoui DWC_ATOUI + +#ifdef DWC_UTFLIB +/** This routine returns a UTF16LE unicode encoded string from a UTF8 string. */ +extern int DWC_UTF8_TO_UTF16LE(uint8_t const *utf8string, uint16_t *utf16string, unsigned len); +#define dwc_utf8_to_utf16le DWC_UTF8_TO_UTF16LE +#endif + + +/** @name Wait queues + * + * Wait queues provide a means of synchronizing between threads or processes. A + * process can block on a waitq if some condition is not true, waiting for it to + * become true. When the waitq is triggered all waiting process will get + * unblocked and the condition will be check again. Waitqs should be triggered + * every time a condition can potentially change.*/ +struct dwc_waitq; + +/** Type for a waitq */ +typedef struct dwc_waitq dwc_waitq_t; + +/** The type of waitq condition callback function. This is called every time + * condition is evaluated. */ +typedef int (*dwc_waitq_condition_t)(void *data); + +/** Allocate a waitq */ +extern dwc_waitq_t *DWC_WAITQ_ALLOC(void); +#define dwc_waitq_alloc(_ctx_) DWC_WAITQ_ALLOC() + +/** Free a waitq */ +extern void DWC_WAITQ_FREE(dwc_waitq_t *wq); +#define dwc_waitq_free DWC_WAITQ_FREE + +/** Check the condition and if it is false, block on the waitq. When unblocked, check the + * condition again. The function returns when the condition becomes true. The return value + * is 0 on condition true, DWC_WAITQ_ABORTED on abort or killed, or DWC_WAITQ_UNKNOWN on error. */ +extern int32_t DWC_WAITQ_WAIT(dwc_waitq_t *wq, dwc_waitq_condition_t cond, void *data); +#define dwc_waitq_wait DWC_WAITQ_WAIT + +/** Check the condition and if it is false, block on the waitq. When unblocked, + * check the condition again. The function returns when the condition become + * true or the timeout has passed. The return value is 0 on condition true or + * DWC_TIMED_OUT on timeout, or DWC_WAITQ_ABORTED, or DWC_WAITQ_UNKNOWN on + * error. */ +extern int32_t DWC_WAITQ_WAIT_TIMEOUT(dwc_waitq_t *wq, dwc_waitq_condition_t cond, + void *data, int32_t msecs); +#define dwc_waitq_wait_timeout DWC_WAITQ_WAIT_TIMEOUT + +/** Trigger a waitq, unblocking all processes. This should be called whenever a condition + * has potentially changed. */ +extern void DWC_WAITQ_TRIGGER(dwc_waitq_t *wq); +#define dwc_waitq_trigger DWC_WAITQ_TRIGGER + +/** Unblock all processes waiting on the waitq with an ABORTED result. */ +extern void DWC_WAITQ_ABORT(dwc_waitq_t *wq); +#define dwc_waitq_abort DWC_WAITQ_ABORT + + +/** @name Threads + * + * A thread must be explicitly stopped. It must check DWC_THREAD_SHOULD_STOP + * whenever it is woken up, and then return. The DWC_THREAD_STOP function + * returns the value from the thread. + */ + +struct dwc_thread; + +/** Type for a thread */ +typedef struct dwc_thread dwc_thread_t; + +/** The thread function */ +typedef int (*dwc_thread_function_t)(void *data); + +/** Create a thread and start it running the thread_function. Returns a handle + * to the thread */ +extern dwc_thread_t *DWC_THREAD_RUN(dwc_thread_function_t func, char *name, void *data); +#define dwc_thread_run(_ctx_,_func_,_name_,_data_) DWC_THREAD_RUN(_func_, _name_, _data_) + +/** Stops a thread. Return the value returned by the thread. Or will return + * DWC_ABORT if the thread never started. */ +extern int DWC_THREAD_STOP(dwc_thread_t *thread); +#define dwc_thread_stop DWC_THREAD_STOP + +/** Signifies to the thread that it must stop. */ +#ifdef DWC_LINUX +/* Linux doesn't need any parameters for kthread_should_stop() */ +extern dwc_bool_t DWC_THREAD_SHOULD_STOP(void); +#define dwc_thread_should_stop(_thrd_) DWC_THREAD_SHOULD_STOP() + +/* No thread_exit function in Linux */ +#define dwc_thread_exit(_thrd_) +#endif + +#if defined(DWC_FREEBSD) || defined(DWC_NETBSD) +/** BSD needs the thread pointer for kthread_suspend_check() */ +extern dwc_bool_t DWC_THREAD_SHOULD_STOP(dwc_thread_t *thread); +#define dwc_thread_should_stop DWC_THREAD_SHOULD_STOP + +/** The thread must call this to exit. */ +extern void DWC_THREAD_EXIT(dwc_thread_t *thread); +#define dwc_thread_exit DWC_THREAD_EXIT +#endif + + +/** @name Work queues + * + * Workqs are used to queue a callback function to be called at some later time, + * in another thread. */ +struct dwc_workq; + +/** Type for a workq */ +typedef struct dwc_workq dwc_workq_t; + +/** The type of the callback function to be called. */ +typedef void (*dwc_work_callback_t)(void *data); + +/** Allocate a workq */ +extern dwc_workq_t *DWC_WORKQ_ALLOC(char *name); +#define dwc_workq_alloc(_ctx_,_name_) DWC_WORKQ_ALLOC(_name_) + +/** Free a workq. All work must be completed before being freed. */ +extern void DWC_WORKQ_FREE(dwc_workq_t *workq); +#define dwc_workq_free DWC_WORKQ_FREE + +/** Schedule a callback on the workq, passing in data. The function will be + * scheduled at some later time. */ +extern void DWC_WORKQ_SCHEDULE(dwc_workq_t *workq, dwc_work_callback_t cb, + void *data, char *format, ...) +#ifdef __GNUC__ + __attribute__ ((format(printf, 4, 5))); +#else + ; +#endif +#define dwc_workq_schedule DWC_WORKQ_SCHEDULE + +/** Schedule a callback on the workq, that will be called until at least + * given number miliseconds have passed. */ +extern void DWC_WORKQ_SCHEDULE_DELAYED(dwc_workq_t *workq, dwc_work_callback_t cb, + void *data, uint32_t time, char *format, ...) +#ifdef __GNUC__ + __attribute__ ((format(printf, 5, 6))); +#else + ; +#endif +#define dwc_workq_schedule_delayed DWC_WORKQ_SCHEDULE_DELAYED + +/** The number of processes in the workq */ +extern int DWC_WORKQ_PENDING(dwc_workq_t *workq); +#define dwc_workq_pending DWC_WORKQ_PENDING + +/** Blocks until all the work in the workq is complete or timed out. Returns < + * 0 on timeout. */ +extern int DWC_WORKQ_WAIT_WORK_DONE(dwc_workq_t *workq, int timeout); +#define dwc_workq_wait_work_done DWC_WORKQ_WAIT_WORK_DONE + + +/** @name Tasklets + * + */ +struct dwc_tasklet; + +/** Type for a tasklet */ +typedef struct dwc_tasklet dwc_tasklet_t; + +/** The type of the callback function to be called */ +typedef void (*dwc_tasklet_callback_t)(void *data); + +/** Allocates a tasklet */ +extern dwc_tasklet_t *DWC_TASK_ALLOC(char *name, dwc_tasklet_callback_t cb, void *data); +#define dwc_task_alloc(_ctx_,_name_,_cb_,_data_) DWC_TASK_ALLOC(_name_, _cb_, _data_) + +/** Frees a tasklet */ +extern void DWC_TASK_FREE(dwc_tasklet_t *task); +#define dwc_task_free DWC_TASK_FREE + +/** Schedules a tasklet to run */ +extern void DWC_TASK_SCHEDULE(dwc_tasklet_t *task); +#define dwc_task_schedule DWC_TASK_SCHEDULE + +extern void DWC_TASK_HI_SCHEDULE(dwc_tasklet_t *task); +#define dwc_task_hi_schedule DWC_TASK_HI_SCHEDULE + +/** @name Timer + * + * Callbacks must be small and atomic. + */ +struct dwc_timer; + +/** Type for a timer */ +typedef struct dwc_timer dwc_timer_t; + +/** The type of the callback function to be called */ +typedef void (*dwc_timer_callback_t)(void *data); + +/** Allocates a timer */ +extern dwc_timer_t *DWC_TIMER_ALLOC(char *name, dwc_timer_callback_t cb, void *data); +#define dwc_timer_alloc(_ctx_,_name_,_cb_,_data_) DWC_TIMER_ALLOC(_name_,_cb_,_data_) + +/** Frees a timer */ +extern void DWC_TIMER_FREE(dwc_timer_t *timer); +#define dwc_timer_free DWC_TIMER_FREE + +/** Schedules the timer to run at time ms from now. And will repeat at every + * repeat_interval msec therafter + * + * Modifies a timer that is still awaiting execution to a new expiration time. + * The mod_time is added to the old time. */ +extern void DWC_TIMER_SCHEDULE(dwc_timer_t *timer, uint32_t time); +#define dwc_timer_schedule DWC_TIMER_SCHEDULE + +/** Disables the timer from execution. */ +extern void DWC_TIMER_CANCEL(dwc_timer_t *timer); +#define dwc_timer_cancel DWC_TIMER_CANCEL + + +/** @name Spinlocks + * + * These locks are used when the work between the lock/unlock is atomic and + * short. Interrupts are also disabled during the lock/unlock and thus they are + * suitable to lock between interrupt/non-interrupt context. They also lock + * between processes if you have multiple CPUs or Preemption. If you don't have + * multiple CPUS or Preemption, then the you can simply implement the + * DWC_SPINLOCK and DWC_SPINUNLOCK to disable and enable interrupts. Because + * the work between the lock/unlock is atomic, the process context will never + * change, and so you never have to lock between processes. */ + +struct dwc_spinlock; + +/** Type for a spinlock */ +typedef struct dwc_spinlock dwc_spinlock_t; + +/** Type for the 'flags' argument to spinlock funtions */ +typedef unsigned long dwc_irqflags_t; + +/** Returns an initialized lock variable. This function should allocate and + * initialize the OS-specific data structure used for locking. This data + * structure is to be used for the DWC_LOCK and DWC_UNLOCK functions and should + * be freed by the DWC_FREE_LOCK when it is no longer used. + * + * For Linux Spinlock Debugging make it macro because the debugging routines use + * the symbol name to determine recursive locking. Using a wrapper function + * makes it falsely think recursive locking occurs. */ +#if defined(DWC_LINUX) && defined(CONFIG_DEBUG_SPINLOCK) +#define DWC_SPINLOCK_ALLOC_LINUX_DEBUG(lock) ({ \ + lock = DWC_ALLOC(sizeof(spinlock_t)); \ + if (lock) { \ + spin_lock_init((spinlock_t *)lock); \ + } \ +}) +#else +extern dwc_spinlock_t *DWC_SPINLOCK_ALLOC(void); +#define dwc_spinlock_alloc(_ctx_) DWC_SPINLOCK_ALLOC() +#endif + +/** Frees an initialized lock variable. */ +extern void DWC_SPINLOCK_FREE(dwc_spinlock_t *lock); +#define dwc_spinlock_free(_ctx_,_lock_) DWC_SPINLOCK_FREE(_lock_) + +/** Disables interrupts and blocks until it acquires the lock. + * + * @param lock Pointer to the spinlock. + * @param flags Unsigned long for irq flags storage. + */ +extern void DWC_SPINLOCK_IRQSAVE(dwc_spinlock_t *lock, dwc_irqflags_t *flags); +#define dwc_spinlock_irqsave DWC_SPINLOCK_IRQSAVE + +/** Re-enables the interrupt and releases the lock. + * + * @param lock Pointer to the spinlock. + * @param flags Unsigned long for irq flags storage. Must be the same as was + * passed into DWC_LOCK. + */ +extern void DWC_SPINUNLOCK_IRQRESTORE(dwc_spinlock_t *lock, dwc_irqflags_t flags); +#define dwc_spinunlock_irqrestore DWC_SPINUNLOCK_IRQRESTORE + +/** Blocks until it acquires the lock. + * + * @param lock Pointer to the spinlock. + */ +extern void DWC_SPINLOCK(dwc_spinlock_t *lock); +#define dwc_spinlock DWC_SPINLOCK + +/** Releases the lock. + * + * @param lock Pointer to the spinlock. + */ +extern void DWC_SPINUNLOCK(dwc_spinlock_t *lock); +#define dwc_spinunlock DWC_SPINUNLOCK + + +/** @name Mutexes + * + * Unlike spinlocks Mutexes lock only between processes and the work between the + * lock/unlock CAN block, therefore it CANNOT be called from interrupt context. + */ + +struct dwc_mutex; + +/** Type for a mutex */ +typedef struct dwc_mutex dwc_mutex_t; + +/* For Linux Mutex Debugging make it inline because the debugging routines use + * the symbol to determine recursive locking. This makes it falsely think + * recursive locking occurs. */ +#if defined(DWC_LINUX) && defined(CONFIG_DEBUG_MUTEXES) +#define DWC_MUTEX_ALLOC_LINUX_DEBUG(__mutexp) ({ \ + __mutexp = (dwc_mutex_t *)DWC_ALLOC(sizeof(struct mutex)); \ + mutex_init((struct mutex *)__mutexp); \ +}) +#endif + +/** Allocate a mutex */ +extern dwc_mutex_t *DWC_MUTEX_ALLOC(void); +#define dwc_mutex_alloc(_ctx_) DWC_MUTEX_ALLOC() + +/* For memory leak debugging when using Linux Mutex Debugging */ +#if defined(DWC_LINUX) && defined(CONFIG_DEBUG_MUTEXES) +#define DWC_MUTEX_FREE(__mutexp) do { \ + mutex_destroy((struct mutex *)__mutexp); \ + DWC_FREE(__mutexp); \ +} while(0) +#else +/** Free a mutex */ +extern void DWC_MUTEX_FREE(dwc_mutex_t *mutex); +#define dwc_mutex_free(_ctx_,_mutex_) DWC_MUTEX_FREE(_mutex_) +#endif + +/** Lock a mutex */ +extern void DWC_MUTEX_LOCK(dwc_mutex_t *mutex); +#define dwc_mutex_lock DWC_MUTEX_LOCK + +/** Non-blocking lock returns 1 on successful lock. */ +extern int DWC_MUTEX_TRYLOCK(dwc_mutex_t *mutex); +#define dwc_mutex_trylock DWC_MUTEX_TRYLOCK + +/** Unlock a mutex */ +extern void DWC_MUTEX_UNLOCK(dwc_mutex_t *mutex); +#define dwc_mutex_unlock DWC_MUTEX_UNLOCK + + +/** @name Time */ + +/** Microsecond delay. + * + * @param usecs Microseconds to delay. + */ +extern void DWC_UDELAY(uint32_t usecs); +#define dwc_udelay DWC_UDELAY + +/** Millisecond delay. + * + * @param msecs Milliseconds to delay. + */ +extern void DWC_MDELAY(uint32_t msecs); +#define dwc_mdelay DWC_MDELAY + +/** Non-busy waiting. + * Sleeps for specified number of milliseconds. + * + * @param msecs Milliseconds to sleep. + */ +extern void DWC_MSLEEP(uint32_t msecs); +#define dwc_msleep DWC_MSLEEP + +/** + * Returns number of milliseconds since boot. + */ +extern uint32_t DWC_TIME(void); +#define dwc_time DWC_TIME + + + + +/* @mainpage DWC Portability and Common Library + * + * This is the documentation for the DWC Portability and Common Library. + * + * @section intro Introduction + * + * The DWC Portability library consists of wrapper calls and data structures to + * all low-level functions which are typically provided by the OS. The WUDEV + * driver uses only these functions. In order to port the WUDEV driver, only + * the functions in this library need to be re-implemented, with the same + * behavior as documented here. + * + * The Common library consists of higher level functions, which rely only on + * calling the functions from the DWC Portability library. These common + * routines are shared across modules. Some of the common libraries need to be + * used directly by the driver programmer when porting WUDEV. Such as the + * parameter and notification libraries. + * + * @section low Portability Library OS Wrapper Functions + * + * Any function starting with DWC and in all CAPS is a low-level OS-wrapper that + * needs to be implemented when porting, for example DWC_MUTEX_ALLOC(). All of + * these functions are included in the dwc_os.h file. + * + * There are many functions here covering a wide array of OS services. Please + * see dwc_os.h for details, and implementation notes for each function. + * + * @section common Common Library Functions + * + * Any function starting with dwc and in all lowercase is a common library + * routine. These functions have a portable implementation and do not need to + * be reimplemented when porting. The common routines can be used by any + * driver, and some must be used by the end user to control the drivers. For + * example, you must use the Parameter common library in order to set the + * parameters in the WUDEV module. + * + * The common libraries consist of the following: + * + * - Connection Contexts - Used internally and can be used by end-user. See dwc_cc.h + * - Parameters - Used internally and can be used by end-user. See dwc_params.h + * - Notifications - Used internally and can be used by end-user. See dwc_notifier.h + * - Lists - Used internally and can be used by end-user. See dwc_list.h + * - Memory Debugging - Used internally and can be used by end-user. See dwc_os.h + * - Modpow - Used internally only. See dwc_modpow.h + * - DH - Used internally only. See dwc_dh.h + * - Crypto - Used internally only. See dwc_crypto.h + * + * + * @section prereq Prerequistes For dwc_os.h + * @subsection types Data Types + * + * The dwc_os.h file assumes that several low-level data types are pre defined for the + * compilation environment. These data types are: + * + * - uint8_t - unsigned 8-bit data type + * - int8_t - signed 8-bit data type + * - uint16_t - unsigned 16-bit data type + * - int16_t - signed 16-bit data type + * - uint32_t - unsigned 32-bit data type + * - int32_t - signed 32-bit data type + * - uint64_t - unsigned 64-bit data type + * - int64_t - signed 64-bit data type + * + * Ensure that these are defined before using dwc_os.h. The easiest way to do + * that is to modify the top of the file to include the appropriate header. + * This is already done for the Linux environment. If the DWC_LINUX macro is + * defined, the correct header will be added. A standard header <stdint.h> is + * also used for environments where standard C headers are available. + * + * @subsection stdarg Variable Arguments + * + * Variable arguments are provided by a standard C header <stdarg.h>. it is + * available in Both the Linux and ANSI C enviornment. An equivalent must be + * provided in your enviornment in order to use dwc_os.h with the debug and + * tracing message functionality. + * + * @subsection thread Threading + * + * WUDEV Core must be run on an operating system that provides for multiple + * threads/processes. Threading can be implemented in many ways, even in + * embedded systems without an operating system. At the bare minimum, the + * system should be able to start any number of processes at any time to handle + * special work. It need not be a pre-emptive system. Process context can + * change upon a call to a blocking function. The hardware interrupt context + * that calls the module's ISR() function must be differentiable from process + * context, even if your processes are impemented via a hardware interrupt. + * Further locking mechanism between process must exist (or be implemented), and + * process context must have a way to disable interrupts for a period of time to + * lock them out. If all of this exists, the functions in dwc_os.h related to + * threading should be able to be implemented with the defined behavior. + * + */ + +#ifdef __cplusplus +} +#endif + +#endif /* _DWC_OS_H_ */ |