mu_dsi.h

本程序为ST公司开发的源代码

/******************************************************************
 *                                                                *
 *        Copyright Mentor Graphics Corporation 2006              *
 *                                                                *
 *                All Rights Reserved.                            *
 *                                                                *
 *    THIS WORK CONTAINS TRADE SECRET AND PROPRIETARY INFORMATION *
 *  WHICH IS THE PROPERTY OF MENTOR GRAPHICS CORPORATION OR ITS   *
 *  LICENSORS AND IS SUBJECT TO LICENSE TERMS.                    *
 *                                                                *
 ******************************************************************/

/*
 * MUSB-MicroSW USB Driver System Interface (UDSI).
 * $Revision: 1.4 $
 */

#ifndef __MUSB_SYSTEM_H__
#define __MUSB_SYSTEM_H__

#include "mu_tools.h"

/****************** SYSTEM INTERFACE CONSTANTS ********************/

/** Current controller struct version */
#define MUSB_CONTROLLER_VERSION		1

/** Current system utils struct version */
#define MUSB_SYSTEM_UTILS_VERSION	1

/** Current system services struct version */
#define MUSB_SYSTEM_SERVICES_VERSION	2

/** The controller type for the FDRC */
#define MUSB_CONTROLLER_FDRC		1

/** The controller type for the HDRC */
#define MUSB_CONTROLLER_HDRC		2

/** The controller type for the MHDRC */
#define MUSB_CONTROLLER_MHDRC		3

/** The controller type for the LSFC */
#define MUSB_CONTROLLER_LSFC		4

/** The controller type for the FSFC */
#define MUSB_CONTROLLER_FSFC		5

/** The controller type for the HSFC */
#define MUSB_CONTROLLER_HSFC		6

/******************** SYSTEM INTERFACE TYPES **********************/

/**
 * Controller ISR.
 * System glue calls this upon controller interrupt.
 *
 * @param 1 pIsrParam from MUSB_Controller
 *
 * @return -1: the interrupt did not seem to be ours (spurious or shared)
 * @return 0: interrupt processed; no need to wake IST
 * @return >0: number of IST work items queued; please wake IST
 */
typedef int (*MUSB_pfControllerIsr)(void*);

/**
 * Controller BSR (Background Service Routine).
 * When the ISR return value so indicates,
 * the system glue should call this function for non-interrupt-time processing.
 * This is typically done from a dedicated high-priority task/thread or
 * the main loop in a non-concurrent system.
 *
 * @param 1 pBsrParam from MUSB_Controller
 */
typedef void (*MUSB_pfControllerBsr)(void*);

/**
 * Timer expiration callback.
 * System glue calls this when a timer expires.
 * This must be done from a context in which it is safe to call the
 * lock/unlock services.
 *
 * @param 1 pPrivateData from MUSB_Controller
 * @param 2 index of timer (counting from 0)
 * @see #MUSB_pfLock
 * @see #MUSB_pfUnlock
 */
typedef void (*MUSB_pfTimerExpired)(void*, uint16_t);

/**
 * MUSB_Controller.
 * A controller instance.
 * This is returned by a controller initialization function,
 * and provides everything necessary for the system glue 
 * to support the controller's operation.
 *
 * @field wVersion the controller fills this with its interface version,
 * so the System can check for compatibility
 *
 * @field pPrivateData controller's private data; 
 * not to be interpreted by the System
 *
 * @field wQueueLength the maximum number of items the controller requires
 * in the background message queue
 *
 * @field wQueueItemSize the size (in bytes) of each item 
 * the controller will place in the background queue
 *
 * @field wTimerCount the number of timers required for the controller's operation;
 * the System should reserve and/or prepare this many timers for the controller's use
 *
 * @field wLockCount the number of locks required for the controller's operation;
 * the System should reserve and/or prepare this many locks for the controller's use
 *
 * @field pfIsr the controller's ISR; 
 * the System must call this upon interrupt receipt
 *
 * @field pIsrParam the parameter the System must pass to the ISR
 *
 * @field pfBsr the controller's background processing code;
 * the System must call this if the ISR's return value so indicates
 *
 * @field pBsrParam the parameter the System must pass to the BSR
 */
typedef struct
{
    uint16_t wVersion;
    void* pPrivateData;
    uint16_t wQueueLength;
    uint16_t wQueueItemSize;
    uint16_t wTimerCount;
    const uint32_t* adwTimerResolutions;
    uint16_t wLockCount;
    MUSB_pfControllerIsr pfIsr;
    void* pIsrParam;
    MUSB_pfControllerBsr pfBsr;
    void* pBsrParam;
} MUSB_Controller;

/**
 * Buffer-overrun-safe strcat.
 * A controller calls this to concatenate a string to a message buffer.
 * The controller is responsible for initializing the buffer.
 * Most platforms can create a very simple implementation
 * based on strlen/strcat.
 *
 * @param 1 pointer to NUL-terminated message buffer
 * @param 2 size (in bytes) of message buffer
 * @param 3 NUL-terminated string to append
 *
 * @return TRUE on success
 * @return FALSE on failure (result would overflow buffer)
 */
typedef uint8_t (*MUSB_pfMessageString)(char*, uint16_t, const char*);

/**
 * Simplified snprintf.
 * A controller calls this to format a number and append 
 * the result to a message buffer.
 * Most platforms can use a very simple implemenation
 * using sprintf, strlen and strncat.
 *
 * @param 1 pointer to diagnostic message buffer
 * @param 2 size (in bytes) of message buffer
 * @param 3 number to format
 * @param 4 base: 2, 8, 10, or 16 for binary, octal, decimal, or hex
 * @param 4 justification: if non-zero, pad with leading 0s as necessary
 * to output this length
 *
 * @return TRUE on success
 * @return FALSE on failure (result would overflow buffer)
 */
typedef uint8_t (*MUSB_pfMessageNumber)(char*, uint16_t, uint32_t, 
uint8_t, uint8_t);

/**
 * Get high-resolution time.
 * If overhead timing measurement is enabled, 
 * a controller calls this to get the current absolute time
 * in some high-resolution unit like microseconds.
 * Naturally, it is expected that this counter will roll over frequently.
 * @return absolute time in whatever high-resolution unit is supported
 */
typedef uint32_t (*MUSB_pfGetTime)(void);

/**
 * MUSB_SystemUtils.
 * System utilities for a controller.
 *
 * This is provided by System-specific code to support a controller's 
 * initialization and operation.
 *
 * @field wVersion the System fills this with its current interface version
 * so the controller can check for compatibility
 *
 * @field pfMessageString the function the controller should use to 
 * append a string to a message buffer
 * (usually in preparation for printing diagnostics)
 *
 * @field pfMessageNumber the function the controller should use to 
 * format and append a number to a message buffer
 * (usually in preparation for printing diagnostics)
 *
 * @field pfGetTime the function the controller should use to get 
 * the current time in high-resolution units for timing statistics
 */
typedef struct
{
    uint16_t wVersion;
    MUSB_pfMessageString pfMessageString;
    MUSB_pfMessageNumber pfMessageNumber;
    MUSB_pfGetTime pfGetTime;
} MUSB_SystemUtils;

/**
 * Get address for DMA.
 * A controller calls this to get a bus address (for DMA) 
 * from a system address.
 *
 * @param 1 pPrivateData from MUSB_SystemServices
 * @param 2 system address
 *
 * @return bus address on success; NULL on failure
 */
typedef void* (*MUSB_pfSystemToBusAddress)(void*, const void*);

/**
 * Enqueue background task.
 * A controller calls this to enqueue a background item.
 *
 * @param 1 pPrivateData from MUSB_SystemServices
 * @param 2 pointer to an item of wQueueItemSize bytes;
 * data should be copied into the queue
 *
 * @return TRUE on success
 * @return FALSE on failure
 */
typedef uint8_t (*MUSB_pfQueueBackgroundItem)(void*, const void*);

/**
 * Dequeue background task.
 * A controller calls this to dequeue a background item.
 *
 * @param 1 pPrivateData from MUSB_SystemServices
 * @param 2 pointer to storage for an item of wQueueItemSize bytes;
 * the implementation should copy data here
 *
 * @return TRUE on success
 * @return FALSE on failure
 */
typedef uint8_t (*MUSB_pfDequeueBackgroundItem)(void*, void*);

/**
 * Flush background queue.
 * A controller calls this to flush the background item queue
 *
 * @param 1 pPrivateData from MUSB_SystemServices
 */
typedef void (*MUSB_pfFlushBackgroundQueue)(void*);

/**
 * Arm a timer.
 * A controller calls this to arm a timer (periodic or one-shot).
 *
 * @param 1 pPrivateData from MUSB_SystemServices
 * @param 2 index of timer (counting from 0)
 * @param 3 time (milliseconds)
 * @param 4 TRUE for periodic; FALSE for one-shot
 * @param 5 function to call on expiration
 * @return TRUE on success
 * @return FALSE on failure