mirror of
https://mirrors.bfsu.edu.cn/git/linux.git
synced 2024-11-29 15:14:18 +08:00
usb: dwc3: update documentation
No functional changes, just making sure we can use these for ReST docs later. Signed-off-by: Felipe Balbi <felipe.balbi@linux.intel.com>
This commit is contained in:
Felipe Balbi
parent
a7ea58f381
commit
bfad65ee9b
@ -1,4 +1,4 @@
|
||||
/**
|
||||
/*
|
||||
* core.h - DesignWare USB3 DRD Core Header
|
||||
*
|
||||
* Copyright (C) 2010-2011 Texas Instruments Incorporated - http://www.ti.com
|
||||
@ -523,7 +523,6 @@ struct dwc3_event_buffer {
|
||||
* @trb_pool_dma: dma address of @trb_pool
|
||||
* @trb_enqueue: enqueue 'pointer' into TRB array
|
||||
* @trb_dequeue: dequeue 'pointer' into TRB array
|
||||
* @desc: usb_endpoint_descriptor pointer
|
||||
* @dwc: pointer to DWC controller
|
||||
* @saved_state: ep state saved during hibernation
|
||||
* @flags: endpoint flags (wedged, stalled, ...)
|
||||
@ -665,7 +664,7 @@ enum dwc3_link_state {
|
||||
* @bpl: DW0-3
|
||||
* @bph: DW4-7
|
||||
* @size: DW8-B
|
||||
* @trl: DWC-F
|
||||
* @ctrl: DWC-F
|
||||
*/
|
||||
struct dwc3_trb {
|
||||
u32 bpl;
|
||||
@ -675,16 +674,16 @@ struct dwc3_trb {
|
||||
} __packed;
|
||||
|
||||
/**
|
||||
* dwc3_hwparams - copy of HWPARAMS registers
|
||||
* @hwparams0 - GHWPARAMS0
|
||||
* @hwparams1 - GHWPARAMS1
|
||||
* @hwparams2 - GHWPARAMS2
|
||||
* @hwparams3 - GHWPARAMS3
|
||||
* @hwparams4 - GHWPARAMS4
|
||||
* @hwparams5 - GHWPARAMS5
|
||||
* @hwparams6 - GHWPARAMS6
|
||||
* @hwparams7 - GHWPARAMS7
|
||||
* @hwparams8 - GHWPARAMS8
|
||||
* struct dwc3_hwparams - copy of HWPARAMS registers
|
||||
* @hwparams0: GHWPARAMS0
|
||||
* @hwparams1: GHWPARAMS1
|
||||
* @hwparams2: GHWPARAMS2
|
||||
* @hwparams3: GHWPARAMS3
|
||||
* @hwparams4: GHWPARAMS4
|
||||
* @hwparams5: GHWPARAMS5
|
||||
* @hwparams6: GHWPARAMS6
|
||||
* @hwparams7: GHWPARAMS7
|
||||
* @hwparams8: GHWPARAMS8
|
||||
*/
|
||||
struct dwc3_hwparams {
|
||||
u32 hwparams0;
|
||||
@ -731,7 +730,8 @@ struct dwc3_hwparams {
|
||||
* @unaligned: true for OUT endpoints with length not divisible by maxp
|
||||
* @direction: IN or OUT direction flag
|
||||
* @mapped: true when request has been dma-mapped
|
||||
* @queued: true when request has been queued to HW
|
||||
* @started: request is started
|
||||
* @zero: wants a ZLP
|
||||
*/
|
||||
struct dwc3_request {
|
||||
struct usb_request request;
|
||||
@ -762,17 +762,23 @@ struct dwc3_scratchpad_array {
|
||||
|
||||
/**
|
||||
* struct dwc3 - representation of our controller
|
||||
* @drd_work - workqueue used for role swapping
|
||||
* @drd_work: workqueue used for role swapping
|
||||
* @ep0_trb: trb which is used for the ctrl_req
|
||||
* @bounce: address of bounce buffer
|
||||
* @scratchbuf: address of scratch buffer
|
||||
* @setup_buf: used while precessing STD USB requests
|
||||
* @ep0_trb: dma address of ep0_trb
|
||||
* @ep0_trb_addr: dma address of @ep0_trb
|
||||
* @bounce_addr: dma address of @bounce
|
||||
* @ep0_usb_req: dummy req used while handling STD USB requests
|
||||
* @scratch_addr: dma address of scratchbuf
|
||||
* @ep0_in_setup: one control transfer is completed and enter setup phase
|
||||
* @lock: for synchronizing
|
||||
* @dev: pointer to our struct device
|
||||
* @sysdev: pointer to the DMA-capable device
|
||||
* @xhci: pointer to our xHCI child
|
||||
* @event_buffer_list: a list of event buffers
|
||||
* @xhci_resources: struct resources for our @xhci child
|
||||
* @ev_buf: struct dwc3_event_buffer pointer
|
||||
* @eps: endpoint array
|
||||
* @gadget: device side representation of the peripheral controller
|
||||
* @gadget_driver: pointer to the gadget driver
|
||||
* @regs: base address for our registers
|
||||
@ -796,8 +802,6 @@ struct dwc3_scratchpad_array {
|
||||
* @usb2_generic_phy: pointer to USB2 PHY
|
||||
* @usb3_generic_phy: pointer to USB3 PHY
|
||||
* @ulpi: pointer to ulpi interface
|
||||
* @dcfg: saved contents of DCFG register
|
||||
* @gctl: saved contents of GCTL register
|
||||
* @isoch_delay: wValue from Set Isochronous Delay request;
|
||||
* @u2sel: parameter from Set SEL request.
|
||||
* @u2pel: parameter from Set SEL request.
|
||||
@ -831,7 +835,6 @@ struct dwc3_scratchpad_array {
|
||||
* @pending_events: true when we have pending IRQs to be handled
|
||||
* @pullups_connected: true when Run/Stop bit is set
|
||||
* @setup_packet_pending: true when there's a Setup Packet in FIFO. Workaround
|
||||
* @start_config_issued: true when StartConfig command has been issued
|
||||
* @three_stage_setup: set if we perform a three phase setup
|
||||
* @usb3_lpm_capable: set if hadrware supports Link Power Management
|
||||
* @disable_scramble_quirk: set if we enable the disable scramble quirk
|
||||
@ -846,6 +849,7 @@ struct dwc3_scratchpad_array {
|
||||
* @dis_u2_susphy_quirk: set if we disable usb2 suspend phy
|
||||
* @dis_enblslpm_quirk: set if we clear enblslpm in GUSB2PHYCFG,
|
||||
* disabling the suspend signal to the PHY.
|
||||
* @dis_rxdet_inp3_quirk: set if we disable Rx.Detect in P3
|
||||
* @dis_u2_freeclk_exists_quirk : set if we clear u2_freeclk_exists
|
||||
* in GUSB2PHYCFG, specify that USB2 PHY doesn't
|
||||
* provide a free-running PHY clock.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
/**
|
||||
/*
|
||||
* ep0.c - DesignWare USB3 DRD Controller Endpoint 0 Handling
|
||||
*
|
||||
* Copyright (C) 2010-2011 Texas Instruments Incorporated - http://www.ti.com
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
/**
|
||||
/*
|
||||
* gadget.c - DesignWare USB3 DRD Controller Gadget Framework Link
|
||||
*
|
||||
* Copyright (C) 2010-2011 Texas Instruments Incorporated - http://www.ti.com
|
||||
@ -36,13 +36,12 @@
|
||||
#include "io.h"
|
||||
|
||||
/**
|
||||
* dwc3_gadget_set_test_mode - Enables USB2 Test Modes
|
||||
* dwc3_gadget_set_test_mode - enables usb2 test modes
|
||||
* @dwc: pointer to our context structure
|
||||
* @mode: the mode to set (J, K SE0 NAK, Force Enable)
|
||||
*
|
||||
* Caller should take care of locking. This function will
|
||||
* return 0 on success or -EINVAL if wrong Test Selector
|
||||
* is passed
|
||||
* Caller should take care of locking. This function will return 0 on
|
||||
* success or -EINVAL if wrong Test Selector is passed.
|
||||
*/
|
||||
int dwc3_gadget_set_test_mode(struct dwc3 *dwc, int mode)
|
||||
{
|
||||
@ -69,7 +68,7 @@ int dwc3_gadget_set_test_mode(struct dwc3 *dwc, int mode)
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_gadget_get_link_state - Gets current state of USB Link
|
||||
* dwc3_gadget_get_link_state - gets current state of usb link
|
||||
* @dwc: pointer to our context structure
|
||||
*
|
||||
* Caller should take care of locking. This function will
|
||||
@ -85,7 +84,7 @@ int dwc3_gadget_get_link_state(struct dwc3 *dwc)
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_gadget_set_link_state - Sets USB Link to a particular State
|
||||
* dwc3_gadget_set_link_state - sets usb link to a particular state
|
||||
* @dwc: pointer to our context structure
|
||||
* @state: the state to put link into
|
||||
*
|
||||
@ -143,8 +142,8 @@ int dwc3_gadget_set_link_state(struct dwc3 *dwc, enum dwc3_link_state state)
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_ep_inc_trb() - Increment a TRB index.
|
||||
* @index - Pointer to the TRB index to increment.
|
||||
* dwc3_ep_inc_trb - increment a trb index.
|
||||
* @index: Pointer to the TRB index to increment.
|
||||
*
|
||||
* The index should never point to the link TRB. After incrementing,
|
||||
* if it is point to the link TRB, wrap around to the beginning. The
|
||||
@ -157,16 +156,34 @@ static void dwc3_ep_inc_trb(u8 *index)
|
||||
*index = 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_ep_inc_enq - increment endpoint's enqueue pointer
|
||||
* @dep: The endpoint whose enqueue pointer we're incrementing
|
||||
*/
|
||||
static void dwc3_ep_inc_enq(struct dwc3_ep *dep)
|
||||
{
|
||||
dwc3_ep_inc_trb(&dep->trb_enqueue);
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_ep_inc_deq - increment endpoint's dequeue pointer
|
||||
* @dep: The endpoint whose enqueue pointer we're incrementing
|
||||
*/
|
||||
static void dwc3_ep_inc_deq(struct dwc3_ep *dep)
|
||||
{
|
||||
dwc3_ep_inc_trb(&dep->trb_dequeue);
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_gadget_giveback - call struct usb_request's ->complete callback
|
||||
* @dep: The endpoint to whom the request belongs to
|
||||
* @req: The request we're giving back
|
||||
* @status: completion code for the request
|
||||
*
|
||||
* Must be called with controller's lock held and interrupts disabled. This
|
||||
* function will unmap @req and call its ->complete() callback to notify upper
|
||||
* layers that it has completed.
|
||||
*/
|
||||
void dwc3_gadget_giveback(struct dwc3_ep *dep, struct dwc3_request *req,
|
||||
int status)
|
||||
{
|
||||
@ -193,6 +210,15 @@ void dwc3_gadget_giveback(struct dwc3_ep *dep, struct dwc3_request *req,
|
||||
pm_runtime_put(dwc->dev);
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_send_gadget_generic_command - issue a generic command for the controller
|
||||
* @dwc: pointer to the controller context
|
||||
* @cmd: the command to be issued
|
||||
* @param: command parameter
|
||||
*
|
||||
* Caller should take care of locking. Issue @cmd with a given @param to @dwc
|
||||
* and wait for its completion.
|
||||
*/
|
||||
int dwc3_send_gadget_generic_command(struct dwc3 *dwc, unsigned cmd, u32 param)
|
||||
{
|
||||
u32 timeout = 500;
|
||||
@ -225,6 +251,15 @@ int dwc3_send_gadget_generic_command(struct dwc3 *dwc, unsigned cmd, u32 param)
|
||||
|
||||
static int __dwc3_gadget_wakeup(struct dwc3 *dwc);
|
||||
|
||||
/**
|
||||
* dwc3_send_gadget_ep_cmd - issue an endpoint command
|
||||
* @dep: the endpoint to which the command is going to be issued
|
||||
* @cmd: the command to be issued
|
||||
* @params: parameters to the command
|
||||
*
|
||||
* Caller should handle locking. This function will issue @cmd with given
|
||||
* @params to @dep and wait for its completion.
|
||||
*/
|
||||
int dwc3_send_gadget_ep_cmd(struct dwc3_ep *dep, unsigned cmd,
|
||||
struct dwc3_gadget_ep_cmd_params *params)
|
||||
{
|
||||
@ -422,36 +457,38 @@ static void dwc3_free_trb_pool(struct dwc3_ep *dep)
|
||||
static int dwc3_gadget_set_xfer_resource(struct dwc3 *dwc, struct dwc3_ep *dep);
|
||||
|
||||
/**
|
||||
* dwc3_gadget_start_config - Configure EP resources
|
||||
* dwc3_gadget_start_config - configure ep resources
|
||||
* @dwc: pointer to our controller context structure
|
||||
* @dep: endpoint that is being enabled
|
||||
*
|
||||
* The assignment of transfer resources cannot perfectly follow the
|
||||
* data book due to the fact that the controller driver does not have
|
||||
* all knowledge of the configuration in advance. It is given this
|
||||
* information piecemeal by the composite gadget framework after every
|
||||
* SET_CONFIGURATION and SET_INTERFACE. Trying to follow the databook
|
||||
* programming model in this scenario can cause errors. For two
|
||||
* reasons:
|
||||
* Issue a %DWC3_DEPCMD_DEPSTARTCFG command to @dep. After the command's
|
||||
* completion, it will set Transfer Resource for all available endpoints.
|
||||
*
|
||||
* 1) The databook says to do DEPSTARTCFG for every SET_CONFIGURATION
|
||||
* and SET_INTERFACE (8.1.5). This is incorrect in the scenario of
|
||||
* multiple interfaces.
|
||||
* The assignment of transfer resources cannot perfectly follow the data book
|
||||
* due to the fact that the controller driver does not have all knowledge of the
|
||||
* configuration in advance. It is given this information piecemeal by the
|
||||
* composite gadget framework after every SET_CONFIGURATION and
|
||||
* SET_INTERFACE. Trying to follow the databook programming model in this
|
||||
* scenario can cause errors. For two reasons:
|
||||
*
|
||||
* 2) The databook does not mention doing more DEPXFERCFG for new
|
||||
* 1) The databook says to do %DWC3_DEPCMD_DEPSTARTCFG for every
|
||||
* %USB_REQ_SET_CONFIGURATION and %USB_REQ_SET_INTERFACE (8.1.5). This is
|
||||
* incorrect in the scenario of multiple interfaces.
|
||||
*
|
||||
* 2) The databook does not mention doing more %DWC3_DEPCMD_DEPXFERCFG for new
|
||||
* endpoint on alt setting (8.1.6).
|
||||
*
|
||||
* The following simplified method is used instead:
|
||||
*
|
||||
* All hardware endpoints can be assigned a transfer resource and this
|
||||
* setting will stay persistent until either a core reset or
|
||||
* hibernation. So whenever we do a DEPSTARTCFG(0) we can go ahead and
|
||||
* do DEPXFERCFG for every hardware endpoint as well. We are
|
||||
* All hardware endpoints can be assigned a transfer resource and this setting
|
||||
* will stay persistent until either a core reset or hibernation. So whenever we
|
||||
* do a %DWC3_DEPCMD_DEPSTARTCFG(0) we can go ahead and do
|
||||
* %DWC3_DEPCMD_DEPXFERCFG for every hardware endpoint as well. We are
|
||||
* guaranteed that there are as many transfer resources as endpoints.
|
||||
*
|
||||
* This function is called for each endpoint when it is being enabled
|
||||
* but is triggered only when called for EP0-out, which always happens
|
||||
* first, and which should only happen in one of the above conditions.
|
||||
* This function is called for each endpoint when it is being enabled but is
|
||||
* triggered only when called for EP0-out, which always happens first, and which
|
||||
* should only happen in one of the above conditions.
|
||||
*/
|
||||
static int dwc3_gadget_start_config(struct dwc3 *dwc, struct dwc3_ep *dep)
|
||||
{
|
||||
@ -569,11 +606,13 @@ static int dwc3_gadget_set_xfer_resource(struct dwc3 *dwc, struct dwc3_ep *dep)
|
||||
}
|
||||
|
||||
/**
|
||||
* __dwc3_gadget_ep_enable - Initializes a HW endpoint
|
||||
* __dwc3_gadget_ep_enable - initializes a hw endpoint
|
||||
* @dep: endpoint to be initialized
|
||||
* @desc: USB Endpoint Descriptor
|
||||
* @modify: if true, modify existing endpoint configuration
|
||||
* @restore: if true, restore endpoint configuration from scratch buffer
|
||||
*
|
||||
* Caller should take care of locking
|
||||
* Caller should take care of locking. Execute all necessary commands to
|
||||
* initialize a HW endpoint so it can be used by a gadget driver.
|
||||
*/
|
||||
static int __dwc3_gadget_ep_enable(struct dwc3_ep *dep,
|
||||
bool modify, bool restore)
|
||||
@ -685,11 +724,13 @@ static void dwc3_remove_requests(struct dwc3 *dwc, struct dwc3_ep *dep)
|
||||
}
|
||||
|
||||
/**
|
||||
* __dwc3_gadget_ep_disable - Disables a HW endpoint
|
||||
* __dwc3_gadget_ep_disable - disables a hw endpoint
|
||||
* @dep: the endpoint to disable
|
||||
*
|
||||
* This function also removes requests which are currently processed ny the
|
||||
* hardware and those which are not yet scheduled.
|
||||
* This function undoes what __dwc3_gadget_ep_enable did and also removes
|
||||
* requests which are currently being processed by the hardware and those which
|
||||
* are not yet scheduled.
|
||||
*
|
||||
* Caller should take care of locking.
|
||||
*/
|
||||
static int __dwc3_gadget_ep_disable(struct dwc3_ep *dep)
|
||||
@ -932,7 +973,7 @@ static void dwc3_prepare_one_trb(struct dwc3_ep *dep,
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_ep_prev_trb() - Returns the previous TRB in the ring
|
||||
* dwc3_ep_prev_trb - returns the previous TRB in the ring
|
||||
* @dep: The endpoint with the TRB ring
|
||||
* @index: The index of the current TRB in the ring
|
||||
*
|
||||
@ -1729,8 +1770,8 @@ static irqreturn_t dwc3_interrupt(int irq, void *_dwc);
|
||||
static irqreturn_t dwc3_thread_interrupt(int irq, void *_dwc);
|
||||
|
||||
/**
|
||||
* dwc3_gadget_setup_nump - Calculate and initialize NUMP field of DCFG
|
||||
* dwc: pointer to our context structure
|
||||
* dwc3_gadget_setup_nump - calculate and initialize NUMP field of %DWC3_DCFG
|
||||
* @dwc: pointer to our context structure
|
||||
*
|
||||
* The following looks like complex but it's actually very simple. In order to
|
||||
* calculate the number of packets we can burst at once on OUT transfers, we're
|
||||
@ -1789,7 +1830,7 @@ static int __dwc3_gadget_start(struct dwc3 *dwc)
|
||||
reg = dwc3_readl(dwc->regs, DWC3_DCFG);
|
||||
reg &= ~(DWC3_DCFG_SPEED_MASK);
|
||||
|
||||
/**
|
||||
/*
|
||||
* WORKAROUND: DWC3 revision < 2.20a have an issue
|
||||
* which would cause metastability state on Run/Stop
|
||||
* bit if we try to force the IP to USB2-only mode.
|
||||
@ -2859,7 +2900,7 @@ static void dwc3_gadget_hibernation_interrupt(struct dwc3 *dwc,
|
||||
{
|
||||
unsigned int is_ss = evtinfo & BIT(4);
|
||||
|
||||
/**
|
||||
/*
|
||||
* WORKAROUND: DWC3 revison 2.20a with hibernation support
|
||||
* have a known issue which can cause USB CV TD.9.23 to fail
|
||||
* randomly.
|
||||
@ -3089,7 +3130,7 @@ out:
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_gadget_init - Initializes gadget related registers
|
||||
* dwc3_gadget_init - initializes gadget related registers
|
||||
* @dwc: pointer to our controller context structure
|
||||
*
|
||||
* Returns 0 on success otherwise negative errno.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
/**
|
||||
/*
|
||||
* gadget.h - DesignWare USB3 DRD Gadget Header
|
||||
*
|
||||
* Copyright (C) 2010-2011 Texas Instruments Incorporated - http://www.ti.com
|
||||
@ -60,11 +60,25 @@ struct dwc3;
|
||||
|
||||
#define to_dwc3_request(r) (container_of(r, struct dwc3_request, request))
|
||||
|
||||
/**
|
||||
* next_request - gets the next request on the given list
|
||||
* @list: the request list to operate on
|
||||
*
|
||||
* Caller should take care of locking. This function return %NULL or the first
|
||||
* request available on @list.
|
||||
*/
|
||||
static inline struct dwc3_request *next_request(struct list_head *list)
|
||||
{
|
||||
return list_first_entry_or_null(list, struct dwc3_request, list);
|
||||
}
|
||||
|
||||
/**
|
||||
* dwc3_gadget_move_started_request - move @req to the started_list
|
||||
* @req: the request to be moved
|
||||
*
|
||||
* Caller should take care of locking. This function will move @req from its
|
||||
* current list to the endpoint's started_list.
|
||||
*/
|
||||
static inline void dwc3_gadget_move_started_request(struct dwc3_request *req)
|
||||
{
|
||||
struct dwc3_ep *dep = req->dep;
|
||||
@ -87,10 +101,10 @@ int __dwc3_gadget_ep_set_halt(struct dwc3_ep *dep, int value, int protocol);
|
||||
|
||||
/**
|
||||
* dwc3_gadget_ep_get_transfer_index - Gets transfer index from HW
|
||||
* @dwc: DesignWare USB3 Pointer
|
||||
* @number: DWC endpoint number
|
||||
* @dep: dwc3 endpoint
|
||||
*
|
||||
* Caller should take care of locking
|
||||
* Caller should take care of locking. Returns the transfer resource
|
||||
* index for a given endpoint.
|
||||
*/
|
||||
static inline u32 dwc3_gadget_ep_get_transfer_index(struct dwc3_ep *dep)
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user