dwc_os.h File Reference

---

Detailed Description

DWC portability library, low level os-wrapper functions.

Primitive Types and Values
#define	YES   1
#define	NO   0
typedef uint8_t	dwc_bool_t
	We define a boolean type for consistency.
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
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.
#define	dwc_in_irq   DWC_IN_IRQ
#define	dwc_vprintf   DWC_VPRINTF
#define	dwc_vsnprintf   DWC_VSNPRINTF
#define	dwc_printf   DWC_PRINTF
#define	dwc_sprintf   DWC_SPRINTF
#define	dwc_snprintf   DWC_SNPRINTF
#define	dwc_exception   DWC_EXCEPTION
#define	DWC_DEBUG(_format, _args...)   __DWC_DEBUG("DEBUG:%s:%s: " _format "\n", __func__, dwc_irq(), ## _args)
	Prints out a Debug message.
#define	dwc_debug   DWC_DEBUG
#define	DWC_INFO(_format, _args...)   DWC_PRINTF("INFO:%s: " _format "\n", dwc_irq(), ## _args)
	Prints out an informative message.
#define	dwc_info   DWC_INFO
#define	DWC_WARN(_format, _args...)   __DWC_WARN("WARN:%s:%s:%d: " _format "\n", dwc_irq(), __func__, __LINE__, ## _args)
	Prints out a warning message.
#define	dwc_warn   DWC_WARN
#define	DWC_ERROR(_format, _args...)   __DWC_ERROR("ERROR:%s:%s:%d: " _format "\n", dwc_irq(), __func__, __LINE__, ## _args)
	Prints out an error message.
#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
#define	DWC_ASSERT(_expr, _format, _args...)   if (!(_expr)) { DWC_EXCEPTION("%s:%s:%d: " _format "\n", dwc_irq(), __FILE__, __LINE__, ## _args); }
	Prints out a exception error message if the _expr expression fails.
#define	dwc_assert   DWC_ASSERT
dwc_bool_t	DWC_IN_IRQ (void)
	Returns non-zero if in interrupt context.
static char *	dwc_irq (void)
	Returns "IRQ" if DWC_IN_IRQ is true.
void	DWC_VPRINTF (char *format, va_list args)
	A vprintf() clone.
int	DWC_VSNPRINTF (char *str, int size, char *format, va_list args)
	A vsnprintf() clone.
void	DWC_PRINTF (char *format,...)
	printf() clone.
int	DWC_SPRINTF (char *string, char *format,...)
	sprintf() clone.
int	DWC_SNPRINTF (char *string, int size, char *format,...)
	snprintf() clone.
void	__DWC_WARN (char *format,...)
	Prints a WARNING message.
void	__DWC_ERROR (char *format,...)
	Prints an error message.
void	DWC_EXCEPTION (char *format,...)
	Prints an exception error message and takes some user-defined action such as print out a backtrace or trigger a breakpoint.
void	__DWC_DEBUG (char *format,...)
	Prints out a debug message.
Byter Ordering
The following functions are for conversions between processor's byte ordering and specific ordering you want.
#define	dwc_cpu_to_le32   DWC_CPU_TO_LE32
#define	dwc_cpu_to_be32   DWC_CPU_TO_BE32
#define	dwc_le32_to_cpu   DWC_LE32_TO_CPU
#define	dwc_be32_to_cpu   DWC_BE32_TO_CPU
#define	dwc_cpu_to_le16   DWC_CPU_TO_LE16
#define	dwc_cpu_to_be16   DWC_CPU_TO_BE16
#define	dwc_le16_to_cpu   DWC_LE16_TO_CPU
#define	dwc_be16_to_cpu   DWC_BE16_TO_CPU
uint32_t	DWC_CPU_TO_LE32 (void *p)
	Converts 32 bit data in CPU byte ordering to little endian.
uint32_t	DWC_CPU_TO_BE32 (void *p)
	Converts 32 bit data in CPU byte orderint to big endian.
uint32_t	DWC_LE32_TO_CPU (void *p)
	Converts 32 bit little endian data to CPU byte ordering.
uint32_t	DWC_BE32_TO_CPU (void *p)
	Converts 32 bit big endian data to CPU byte ordering.
uint16_t	DWC_CPU_TO_LE16 (void *p)
	Converts 16 bit data in CPU byte ordering to little endian.
uint16_t	DWC_CPU_TO_BE16 (void *p)
	Converts 16 bit data in CPU byte orderint to big endian.
uint16_t	DWC_LE16_TO_CPU (void *p)
	Converts 16 bit little endian data to CPU byte ordering.
uint16_t	DWC_BE16_TO_CPU (void *p)
	Converts 16 bit bi endian data to CPU byte ordering.
Register Read/Write
The following five 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.
#define	dwc_read_reg32   DWC_READ_REG32
#define	dwc_read_reg64   DWC_READ_REG64
#define	dwc_write_reg32   DWC_WRITE_REG32
#define	dwc_write_reg64   DWC_WRITE_REG64
#define	dwc_modify_reg32   DWC_MODIFY_REG32
uint32_t	DWC_READ_REG32 (uint32_t volatile *reg)
	Reads the content of a 32-bit register.
uint64_t	DWC_READ_REG64 (uint64_t volatile *reg)
	Reads the content of a 64-bit register.
void	DWC_WRITE_REG32 (uint32_t volatile *reg, uint32_t value)
	Writes to a 32-bit register.
void	DWC_WRITE_REG64 (uint64_t volatile *reg, uint64_t value)
	Writes to a 64-bit register.
void	DWC_MODIFY_REG32 (uint32_t volatile *reg, uint32_t clear_mask, uint32_t set_mask)
	Modify bit values in a register.
Crypto Functions
These are the low-level cryptographic functions used by the driver.
#define	dwc_aes_cbc   DWC_AES_CBC
#define	dwc_random_bytes   DWC_RANDOM_BYTES
#define	dwc_sha256   DWC_SHA256
#define	dwc_hmac_sha256   DWC_HMAC_SHA256
int	DWC_AES_CBC (uint8_t *message, uint32_t messagelen, uint8_t *key, uint32_t keylen, uint8_t iv[16], uint8_t *out)
	Perform AES CBC.
void	DWC_RANDOM_BYTES (uint8_t *buffer, uint32_t length)
	Fill the provided buffer with random bytes.
int	DWC_SHA256 (uint8_t *message, uint32_t len, uint8_t *out)
	Perform the SHA-256 hash function.
int	DWC_HMAC_SHA256 (uint8_t *message, uint32_t messagelen, uint8_t *key, uint32_t keylen, uint8_t *out)
	Calculated the HMAC-SHA256.
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 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
#define	DWC_ALLOC(_size_)   (dwc_alloc_debug(_size_, __func__, __LINE__))
#define	DWC_ALLOC_ATOMIC(_size_)   (dwc_alloc_atomic_debug(_size_, __func__, __LINE__))
#define	DWC_FREE(_addr_)   (dwc_free_debug(_addr_, __func__, __LINE__))
#define	DWC_DMA_ALLOC(_size_, _dma_)   dwc_dma_alloc_debug(_size_, _dma_, __func__, __LINE__)
#define	DWC_DMA_FREE(_size_, _virt_, _dma_)   dwc_dma_free_debug(_size_, _virt_, _dma_, __func__, __LINE__)
#define	dwc_alloc   DWC_ALLOC
#define	dwc_alloc_atomic   DWC_ALLOC_ATOMIC
#define	dwc_free   DWC_FREE
#define	dwc_dma_alloc   DWC_DMA_ALLOC
#define	dwc_dma_free   DWC_DMA_FREE
typedef uint32_t	dwc_dma_t
void *	__DWC_DMA_ALLOC (uint32_t size, dwc_dma_t *dma_addr)
	Allocates a DMA capable buffer and zeroes its contents.
void	__DWC_DMA_FREE (uint32_t size, void *virt_addr, dwc_dma_t dma_addr)
	Frees a previosly allocated buffer.
void *	__DWC_ALLOC (uint32_t size)
	Allocates a block of memory and zeroes its contents.
void *	__DWC_ALLOC_ATOMIC (uint32_t size)
	Allocates a block of memory and zeroes its contents, in an atomic manner which can be used inside interrupt context.
void	__DWC_FREE (void *addr)
	Frees a previously allocated buffer.
void *	dwc_alloc_debug (uint32_t size, char const *func, int line)
void *	dwc_alloc_atomic_debug (uint32_t size, char const *func, int line)
void	dwc_free_debug (void *addr, char const *func, int line)
void *	dwc_dma_alloc_debug (uint32_t size, dwc_dma_t *dma_addr, char const *func, int line)
void	dwc_dma_free_debug (uint32_t size, void *virt_addr, dwc_dma_t dma_addr, char const *func, int line)
void	dwc_memory_debug_start (void)
void	dwc_memory_debug_stop (void)
void	dwc_memory_debug_report (void)
Memory and String Processing
#define	dwc_memset   DWC_MEMSET
#define	dwc_memcpy   DWC_MEMCPY
#define	dwc_memmove   DWC_MEMMOVE
#define	dwc_memcmp   DWC_MEMCMP
#define	dwc_strcmp   DWC_STRCMP
#define	dwc_strncmp   DWC_STRNCMP
#define	dwc_strlen   DWC_STRLEN
#define	dwc_strcpy   DWC_STRCPY
#define	dwc_strdup   DWC_STRDUP
#define	dwc_atoi   DWC_ATOI
#define	dwc_atoui   DWC_ATOUI
#define	dwc_utf8_to_utf16le   DWC_UTF8_TO_UTF16LE
void *	DWC_MEMSET (void *dest, uint8_t byte, uint32_t size)
	memset() clone
void *	DWC_MEMCPY (void *dest, void const *src, uint32_t size)
	memcpy() clone
void *	DWC_MEMMOVE (void *dest, void *src, uint32_t size)
	memmove() clone
int	DWC_MEMCMP (void *m1, void *m2, uint32_t size)
	memcmp() clone
int	DWC_STRCMP (void *s1, void *s2)
	strcmp() clone
int	DWC_STRNCMP (void *s1, void *s2, uint32_t size)
	strncmp() clone
int	DWC_STRLEN (char const *str)
	strlen() clone, for NULL terminated ASCII strings
char *	DWC_STRCPY (char *to, const char *from)
	strcpy() clone, for NULL terminated ASCII strings
char *	DWC_STRDUP (char const *str)
	strdup() clone.
int	DWC_ATOI (char *str, int32_t *value)
	NOT an atoi() clone.
int	DWC_ATOUI (char *str, uint32_t *value)
	Same as above but for unsigned.
int	DWC_UTF8_TO_UTF16LE (uint8_t const *utf8string, uint16_t *utf16string, unsigned len)
	This routine returns a UTF16LE unicode encoded string from a UTF8 string.
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.
#define	dwc_waitq_alloc   DWC_WAITQ_ALLOC
#define	dwc_waitq_free   DWC_WAITQ_FREE
#define	dwc_waitq_wait   DWC_WAITQ_WAIT;
#define	dwc_waitq_wait_timeout   DWC_WAITQ_WAIT_TIMEOUT
#define	dwc_waitq_trigger   DWC_WAITQ_TRIGGER
#define	dwc_waitq_abort   DWC_WAITQ_ABORT
typedef dwc_waitq	dwc_waitq_t
typedef int(*)	dwc_waitq_condition_t (void *data)
	The type of waitq condition callback function.
dwc_waitq_t *	DWC_WAITQ_ALLOC (void)
	Allocate a waitq.
void	DWC_WAITQ_FREE (dwc_waitq_t *wq)
	Free a waitq.
int32_t	DWC_WAITQ_WAIT (dwc_waitq_t *wq, dwc_waitq_condition_t condition, void *data)
	Check the condition and if it is false, block on the waitq.
int32_t	DWC_WAITQ_WAIT_TIMEOUT (dwc_waitq_t *wq, dwc_waitq_condition_t condition, void *data, int32_t msecs)
	Check the condition and if it is false, block on the waitq.
void	DWC_WAITQ_TRIGGER (dwc_waitq_t *wq)
	Trigger a waitq, unblocking all processes.
void	DWC_WAITQ_ABORT (dwc_waitq_t *wq)
	Unblock all processes waiting on the waitq with an ABORTED result.
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.
#define	dwc_thread_run   DWC_THREAD_RUN
#define	dwc_thread_stop   DWC_THREAD_STOP
#define	dwc_thread_should_stop   DWC_THREAD_SHOULD_STOP
typedef dwc_thread	dwc_thread_t
typedef int(*)	dwc_thread_function_t (void *data)
	The thread function.
dwc_thread_t *	DWC_THREAD_RUN (dwc_thread_function_t thread_function, char *name, void *data)
	Create a thread and start it running the thread_function.
int	DWC_THREAD_STOP (dwc_thread_t *thread)
	Stops a thread.
dwc_bool_t	DWC_THREAD_SHOULD_STOP (void)
	Signifies to the thread that it must stop.
Work queues
Workqs are used to queue a callback function to be called at some later time, in another thread.
#define	dwc_workq_alloc   DWC_WORKQ_ALLOC
#define	dwc_workq_free   DWC_WORKQ_FREE
#define	dwc_workq_schedule   DWC_WORKQ_SCHEDULE
#define	dwc_workq_schedule_delayed   DWC_WORKQ_SCHEDULE_DELAYED
#define	dwc_workq_pending   DWC_WORKQ_PENDING
#define	dwc_workq_wait_work_done   DWC_WORKQ_WAIT_WORK_DONE
typedef dwc_workq	dwc_workq_t
typedef void(*)	dwc_work_callback_t (void *data)
	The type of the callback function to be called.
dwc_workq_t *	DWC_WORKQ_ALLOC (char *name)
	Allocate a workq.
void	DWC_WORKQ_FREE (dwc_workq_t *workq)
	Free a workq.
void	DWC_WORKQ_SCHEDULE (dwc_workq_t *workq, dwc_work_callback_t work_cb, void *data, char *format,...)
	Schedule a callback on the workq, passing in data.
void	DWC_WORKQ_SCHEDULE_DELAYED (dwc_workq_t *workq, dwc_work_callback_t work_cb, void *data, uint32_t time, char *format,...)
	Schedule a callback on the workq, that will be called until at least given number miliseconds have passed.
int	DWC_WORKQ_PENDING (dwc_workq_t *workq)
	The number of processes in the workq.
int	DWC_WORKQ_WAIT_WORK_DONE (dwc_workq_t *workq, int timeout)
	Blocks until all the work in the workq is complete or timed out.
Tasklets
#define	dwc_task_alloc   DWC_TASK_ALLOC
#define	dwc_task_free   DWC_TASK_FREE
#define	dwc_task_schedule   DWC_TASK_SCHEDULE
typedef dwc_tasklet	dwc_tasklet_t
typedef void(*)	dwc_tasklet_callback_t (void *data)
dwc_tasklet_t *	DWC_TASK_ALLOC (dwc_tasklet_callback_t cb, void *data)
void	DWC_TASK_FREE (dwc_tasklet_t *t)
void	DWC_TASK_SCHEDULE (dwc_tasklet_t *task)
Timer
Callbacks must be small and atomic.
#define	dwc_timer_alloc   DWC_TIMER_ALLOC
#define	dwc_timer_free   DWC_TIMER_FREE
#define	dwc_timer_schedule   DWC_TIMER_SCHEDULE
#define	dwc_timer_cancel   DWC_TIMER_CANCEL
typedef dwc_timer	dwc_timer_t
typedef void(*)	dwc_timer_callback_t (void *data)
dwc_timer_t *	DWC_TIMER_ALLOC (char *name, dwc_timer_callback_t cb, void *data)
void	DWC_TIMER_FREE (dwc_timer_t *timer)
void	DWC_TIMER_SCHEDULE (dwc_timer_t *timer, uint32_t time)
	Schedules the timer to run at time ms from now.
void	DWC_TIMER_CANCEL (dwc_timer_t *timer)
	Disables the timer from execution.
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.
#define	dwc_spinlock_alloc   DWC_SPINLOCK_ALLOC
#define	dwc_spinlock_free   DWC_SPINLOCK_FREE
#define	dwc_spinlock_irqsave   DWC_SPINLOCK_IRQSAVE
#define	dwc_spinunlock_irqrestore   DWC_SPINUNLOCK_IRQRESTORE
#define	dwc_spinlock   DWC_SPINLOCK
#define	dwc_spinunlock   DWC_SPINUNLOCK
typedef dwc_spinlock	dwc_spinlock_t
dwc_spinlock_t *	DWC_SPINLOCK_ALLOC (void)
	Returns an initialized lock variable.
void	DWC_SPINLOCK_FREE (dwc_spinlock_t *lock)
	Frees an initialized lock variable.
void	DWC_SPINLOCK_IRQSAVE (dwc_spinlock_t *lock, uint64_t *flags)
	Disables interrupts and blocks until it acquires the lock.
void	DWC_SPINUNLOCK_IRQRESTORE (dwc_spinlock_t *lock, uint64_t flags)
	Re-enables the interrupt and releases the lock.
void	DWC_SPINLOCK (dwc_spinlock_t *lock)
	Blocks until it acquires the lock.
void	DWC_SPINUNLOCK (dwc_spinlock_t *lock)
	Releases the lock.
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.
#define	dwc_mutex_alloc   DWC_MUTEX_ALLOC
#define	dwc_mutex_free   DWC_MUTEX_FREE
#define	dwc_mutex_lock   DWC_MUTEX_LOCK
#define	dwc_mutex_trylock   DWC_MUTEX_TRYLOCK
#define	dwc_mutex_unlock   DWC_MUTEX_UNLOCK
typedef dwc_mutex	dwc_mutex_t
dwc_mutex_t *	DWC_MUTEX_ALLOC (void)
void	DWC_MUTEX_FREE (dwc_mutex_t *mutex)
void	DWC_MUTEX_LOCK (dwc_mutex_t *mutex)
int	DWC_MUTEX_TRYLOCK (dwc_mutex_t *mutex)
	Non-blocking lock returns 1 on successful lock.
void	DWC_MUTEX_UNLOCK (dwc_mutex_t *mutex)
Time
#define	dwc_udelay   DWC_UDELAY
#define	dwc_mdelay   DWC_MDELAY
#define	dwc_msleep   DWC_MSLEEP
#define	dwc_time   DWC_TIME
void	DWC_UDELAY (uint32_t usecs)
	Microsecond delay.
void	DWC_MDELAY (uint32_t msecs)
	Millisecond delay.
void	DWC_MSLEEP (uint32_t msecs)
	Non-busy waiting.
uint32_t	DWC_TIME (void)

---

Define Documentation

#define DWC_DEBUG	(	_format,
		_args...		)	__DWC_DEBUG("DEBUG:%s:%s: " _format "\n", __func__, dwc_irq(), ## _args)

Prints out a Debug message.

#define DWC_INFO	(	_format,
		_args...		)	DWC_PRINTF("INFO:%s: " _format "\n", dwc_irq(), ## _args)

Prints out an informative message.

#define DWC_WARN	(	_format,
		_args...		)	__DWC_WARN("WARN:%s:%s:%d: " _format "\n", dwc_irq(), __func__, __LINE__, ## _args)

Prints out a warning message.

#define DWC_ERROR	(	_format,
		_args...		)	__DWC_ERROR("ERROR:%s:%s:%d: " _format "\n", dwc_irq(), __func__, __LINE__, ## _args)

Prints out an error message.

#define DWC_ASSERT	(	_expr,
		_format,
		_args...		)	if (!(_expr)) { DWC_EXCEPTION("%s:%s:%d: " _format "\n", dwc_irq(), __FILE__, __LINE__, ## _args); }

Prints out a exception error message if the _expr expression fails.

Disabled if DEBUG is not enabled.

---

Typedef Documentation

typedef uint8_t dwc_bool_t

We define a boolean type for consistency.

Can be either YES or NO

typedef int(*) dwc_waitq_condition_t(void *data)

The type of waitq condition callback function.

This is called every time condition is evaluated.

typedef int(*) dwc_thread_function_t(void *data)

The thread function.

typedef void(*) dwc_work_callback_t(void *data)

The type of the callback function to be called.

---

Function Documentation

dwc_bool_t DWC_IN_IRQ

(

void

)

Returns non-zero if in interrupt context.

static char* dwc_irq

(

void

)

[inline, static]

Returns "IRQ" if DWC_IN_IRQ is true.

void DWC_VPRINTF	(	char *	format,
		va_list	args
	)

A vprintf() clone.

Just call vprintf if you've got it.

int DWC_VSNPRINTF	(	char *	str,
		int	size,
		char *	format,
		va_list	args
	)

A vsnprintf() clone.

Just call vprintf if you've got it.

void DWC_PRINTF	(	char *	format,
			...
	)

printf() clone.

Just call printf if you've go it.

int DWC_SPRINTF	(	char *	string,
		char *	format,
			...
	)

sprintf() clone.

Just call sprintf if you've got it.

int DWC_SNPRINTF	(	char *	string,
		int	size,
		char *	format,
			...
	)

snprintf() clone.

Just call snprintf if you've got it.

void __DWC_WARN	(	char *	format,
			...
	)

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.

void __DWC_ERROR	(	char *	format,
			...
	)

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, but it can be recovered from. Works like printf().

Use the DWC_ERROR macro to call this function.

void DWC_EXCEPTION	(	char *	format,
			...
	)

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().

void __DWC_DEBUG	(	char *	format,
			...
	)

Prints out a debug message.

Used for logging/trace messages.

Use the DWC_DEBUG macro to call this function

uint32_t DWC_CPU_TO_LE32

(

void *

p

)

Converts 32 bit data in CPU byte ordering to little endian.

uint32_t DWC_CPU_TO_BE32

(

void *

p

)

Converts 32 bit data in CPU byte orderint to big endian.

uint32_t DWC_LE32_TO_CPU

(

void *

p

)

Converts 32 bit little endian data to CPU byte ordering.

uint32_t DWC_BE32_TO_CPU

(

void *

p

)

Converts 32 bit big endian data to CPU byte ordering.

uint16_t DWC_CPU_TO_LE16

(

void *

p

)

Converts 16 bit data in CPU byte ordering to little endian.

uint16_t DWC_CPU_TO_BE16

(

void *

p

)

Converts 16 bit data in CPU byte orderint to big endian.

uint16_t DWC_LE16_TO_CPU

(

void *

p

)

Converts 16 bit little endian data to CPU byte ordering.

uint16_t DWC_BE16_TO_CPU

(

void *

p

)

Converts 16 bit bi endian data to CPU byte ordering.

uint32_t DWC_READ_REG32

(

uint32_t volatile *

reg

)

Reads the content of a 32-bit register.

uint64_t DWC_READ_REG64

(

uint64_t volatile *

reg

)

Reads the content of a 64-bit register.

void DWC_WRITE_REG32	(	uint32_t volatile *	reg,
		uint32_t	value
	)

Writes to a 32-bit register.

void DWC_WRITE_REG64	(	uint64_t volatile *	reg,
		uint64_t	value
	)

Writes to a 64-bit register.

void DWC_MODIFY_REG32	(	uint32_t volatile *	reg,
		uint32_t	clear_mask,
		uint32_t	set_mask
	)

Modify bit values in a register.

Using the algorithm: (reg_contents & ~clear_mask) | set_mask.

int DWC_AES_CBC	(	uint8_t *	message,
		uint32_t	messagelen,
		uint8_t *	key,
		uint32_t	keylen,
		uint8_t	iv[16],
		uint8_t *	out
	)

Perform AES CBC.

void DWC_RANDOM_BYTES	(	uint8_t *	buffer,
		uint32_t	length
	)

Fill the provided buffer with random bytes.

These should be cryptographic grade random numbers.

int DWC_SHA256	(	uint8_t *	message,
		uint32_t	len,
		uint8_t *	out
	)

Perform the SHA-256 hash function.

int DWC_HMAC_SHA256	(	uint8_t *	message,
		uint32_t	messagelen,
		uint8_t *	key,
		uint32_t	keylen,
		uint8_t *	out
	)

Calculated the HMAC-SHA256.

void* __DWC_DMA_ALLOC	(	uint32_t	size,
		dwc_dma_t *	dma_addr
	)

Allocates a DMA capable buffer and zeroes its contents.

void __DWC_DMA_FREE	(	uint32_t	size,
		void *	virt_addr,
		dwc_dma_t	dma_addr
	)

Frees a previosly allocated buffer.

void* __DWC_ALLOC

(

uint32_t

size

)

Allocates a block of memory and zeroes its contents.

void* __DWC_ALLOC_ATOMIC

(

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.

void __DWC_FREE

(

void *

addr

)

Frees a previously allocated buffer.

void* DWC_MEMSET	(	void *	dest,
		uint8_t	byte,
		uint32_t	size
	)

memset() clone

void* DWC_MEMCPY	(	void *	dest,
		void const *	src,
		uint32_t	size
	)

memcpy() clone

void* DWC_MEMMOVE	(	void *	dest,
		void *	src,
		uint32_t	size
	)

memmove() clone

int DWC_MEMCMP	(	void *	m1,
		void *	m2,
		uint32_t	size
	)

memcmp() clone

int DWC_STRCMP	(	void *	s1,
		void *	s2
	)

strcmp() clone

int DWC_STRNCMP	(	void *	s1,
		void *	s2,
		uint32_t	size
	)

strncmp() clone

int DWC_STRLEN

(

char const *

str

)

strlen() clone, for NULL terminated ASCII strings

char* DWC_STRCPY	(	char *	to,
		const char *	from
	)

strcpy() clone, for NULL terminated ASCII strings

char* DWC_STRDUP

(

char const *

str

)

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.

int DWC_ATOI	(	char *	str,
		int32_t *	value
	)

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.

int DWC_ATOUI	(	char *	str,
		uint32_t *	value
	)

Same as above but for unsigned.

int DWC_UTF8_TO_UTF16LE	(	uint8_t const *	utf8string,
		uint16_t *	utf16string,
		unsigned	len
	)

This routine returns a UTF16LE unicode encoded string from a UTF8 string.

dwc_waitq_t* DWC_WAITQ_ALLOC

(

void

)

Allocate a waitq.

void DWC_WAITQ_FREE

(

dwc_waitq_t *

wq

)

Free a waitq.

int32_t DWC_WAITQ_WAIT	(	dwc_waitq_t *	wq,
		dwc_waitq_condition_t	condition,
		void *	data
	)

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.

int32_t DWC_WAITQ_WAIT_TIMEOUT	(	dwc_waitq_t *	wq,
		dwc_waitq_condition_t	condition,
		void *	data,
		int32_t	msecs
	)

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.

void DWC_WAITQ_TRIGGER

(

dwc_waitq_t *

wq

)

Trigger a waitq, unblocking all processes.

This should be called whenever a condition has potentially changed.

void DWC_WAITQ_ABORT

(

dwc_waitq_t *

wq

)

Unblock all processes waiting on the waitq with an ABORTED result.

dwc_thread_t* DWC_THREAD_RUN	(	dwc_thread_function_t	thread_function,
		char *	name,
		void *	data
	)

Create a thread and start it running the thread_function.

Returns a handle to the thread

int DWC_THREAD_STOP

(

dwc_thread_t *

thread

)

Stops a thread.

Return the value returned by the thread. Or will return DWC_ABORT if the thread never started.

dwc_bool_t DWC_THREAD_SHOULD_STOP

(

void

)

Signifies to the thread that it must stop.

dwc_workq_t* DWC_WORKQ_ALLOC

(

char *

name

)

Allocate a workq.

void DWC_WORKQ_FREE

(

dwc_workq_t *

workq

)

Free a workq.

All work must be completed before being freed.

void DWC_WORKQ_SCHEDULE	(	dwc_workq_t *	workq,
		dwc_work_callback_t	work_cb,
		void *	data,
		char *	format,
			...
	)

Schedule a callback on the workq, passing in data.

The function will be scheduled at some later time.

void DWC_WORKQ_SCHEDULE_DELAYED	(	dwc_workq_t *	workq,
		dwc_work_callback_t	work_cb,
		void *	data,
		uint32_t	time,
		char *	format,
			...
	)

Schedule a callback on the workq, that will be called until at least given number miliseconds have passed.

int DWC_WORKQ_PENDING

(

dwc_workq_t *

workq

)

The number of processes in the workq.

int DWC_WORKQ_WAIT_WORK_DONE	(	dwc_workq_t *	workq,
		int	timeout
	)

Blocks until all the work in the workq is complete or timed out.

Returns < 0 on timeout.

void DWC_TIMER_SCHEDULE	(	dwc_timer_t *	timer,
		uint32_t	time
	)

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.

void DWC_TIMER_CANCEL

(

dwc_timer_t *

timer

)

Disables the timer from execution.

dwc_spinlock_t* DWC_SPINLOCK_ALLOC

(

void

)

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.

void DWC_SPINLOCK_FREE

(

dwc_spinlock_t *

lock

)

Frees an initialized lock variable.

void DWC_SPINLOCK_IRQSAVE	(	dwc_spinlock_t *	lock,
		uint64_t *	flags
	)

Disables interrupts and blocks until it acquires the lock.

Parameters:

	lock	Pointer to the spinlock.
	flags	Unsigned long for irq flags storage.

void DWC_SPINUNLOCK_IRQRESTORE	(	dwc_spinlock_t *	lock,
		uint64_t	flags
	)

Re-enables the interrupt and releases the lock.

Parameters:

	lock	Pointer to the spinlock.
	flags	Unsigned long for irq flags storage. Must be the same as was passed into DWC_LOCK.

void DWC_SPINLOCK

(

dwc_spinlock_t *

lock

)

Blocks until it acquires the lock.

Parameters:

lock

Pointer to the spinlock.

void DWC_SPINUNLOCK

(

dwc_spinlock_t *

lock

)

Releases the lock.

Parameters:

lock

Pointer to the spinlock.

int DWC_MUTEX_TRYLOCK

(

dwc_mutex_t *

mutex

)

Non-blocking lock returns 1 on successful lock.

void DWC_UDELAY

(

uint32_t

usecs

)

Microsecond delay.

Parameters:

usecs

Microseconds to delay.

void DWC_MDELAY

(

uint32_t

msecs

)

Millisecond delay.

Parameters:

msecs

Milliseconds to delay.

void DWC_MSLEEP

(

uint32_t

msecs

)

Non-busy waiting.

Sleeps for specified number of milliseconds.

Parameters:

msecs

Milliseconds to sleep.

---