driver-api/usb/writing_musb_glue_layer.rst

12 use Universal Host Controller Interface (UHCI) or Open Host Controller
15 Instead, these embedded UDC rely on the USB On-the-Go (OTG)
18 Dual-Role Controller (MUSB HDRC) found in the Mentor Graphics Inventra™
21 As a self-taught exercise I have written an MUSB glue layer for the
28 .. _musb-basics:
33 To get started on the topic, please read USB On-the-Go Basics (see
42 Linux USB stack is a layered architecture in which the MUSB controller
43 hardware sits at the lowest. The MUSB controller driver abstract the
44 MUSB controller hardware to the Linux USB stack::
46 	  ------------------------
47 	  |                      | <------- drivers/usb/gadget
48 	  | Linux USB Core Stack | <------- drivers/usb/host
49 	  |                      | <------- drivers/usb/core
50 	  ------------------------
52 	 --------------------------
53 	 |                        | <------ drivers/usb/musb/musb_gadget.c
54 	 | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c
55 	 |                        | <------ drivers/usb/musb/musb_core.c
56 	 --------------------------
58       ---------------------------------
60       |                               | <-- drivers/usb/musb/jz4740.c
62       ---------------------------------
64       ---------------------------------
65       |   MUSB Controller Hardware    |
66       ---------------------------------
69 sitting in between the controller driver and the controller hardware.
73 MUSB controller driver. This will allow the controller driver to know
76 about an embedded controller chip here, so no insertion or removal at
77 run-time.
79 All of this information is passed to the MUSB controller driver through
86 	    .name   = "musb-jz4740",
96 In order to register itself to the controller driver, the glue layer
97 goes through a few steps, basically allocating the controller hardware
116 layer to register itself to the controller driver.
123 .. code-block:: c
124     :emphasize-lines: 8,12,18
133 	glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
135 	    return -ENOMEM;
137 	musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
139 	    dev_err(&pdev->dev, "failed to allocate musb device\n");
140 	    return -ENOMEM;
143 	clk = devm_clk_get(&pdev->dev, "udc");
145 	    dev_err(&pdev->dev, "failed to get clock\n");
152 	    dev_err(&pdev->dev, "failed to enable clock\n");
156 	musb->dev.parent        = &pdev->dev;
158 	glue->dev           = &pdev->dev;
159 	glue->musb          = musb;
160 	glue->clk           = clk;
175 (line 18) the glue layer allocates the clock -- the ``devm_`` prefix
177 allocated clock resource data when the device is released -- and enable
184 .. code-block:: c
185     :emphasize-lines: 3,5,7,9,16
191 	pdata->platform_ops     = &jz4740_musb_ops;
195 	ret = platform_device_add_resources(musb, pdev->resource,
196 			    pdev->num_resources);
198 	    dev_err(&pdev->dev, "failed to add resources\n");
204 	    dev_err(&pdev->dev, "failed to add platform_data\n");
217 The first step is to pass the device data privately held by the glue
218 layer on to the controller driver through :c:func:`platform_set_drvdata`
222 Finally comes passing on the platform specific data to the controller
223 driver (line 16). Platform data will be discussed in
224 :ref:`musb-dev-platform-data`, but here we are looking at the
226 structure (line 3). This function pointer allows the MUSB controller
235 called by the controller driver when needed. Fact is the JZ4740 MUSB
236 controller is a basic controller, lacking some features found in other
239 between OTG and non-OTG modes, for instance.
241 At that point of the registration process, the controller driver
244    .. code-block:: c
245     :emphasize-lines: 12,14
249 	musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
250 	if (!musb->xceiv) {
252 	    return -ENODEV;
258 	musb->dyn_fifo = true;
260 	musb->isr = jz4740_musb_interrupt;
266 driver data of the MUSB controller hardware and pass it on to the MUSB
267 controller driver, as usual. The transceiver is the circuitry inside the
268 controller hardware responsible for sending/receiving the USB data.
272 Getting hold of the ``MUSB PHY`` driver data is done with ``usb_get_phy()``
274 data. The next couple of instructions (line 12 and 14) are used as a
276 will be discussed later in :ref:`musb-dev-quirks` and
277 :ref:`musb-handling-irqs`\ ::
281 	usb_put_phy(musb->xceiv);
287 PHY driver when the controller hardware itself is about to be released.
290 basic set of features of the JZ4740 controller hardware. When writing an
291 musb glue layer for a more complex controller hardware, you might need
294 Returning from the init function, the MUSB controller driver jumps back
301 	    dev_err(&pdev->dev, "failed to register musb device\n");
315 layer adds the controller hardware device to Linux kernel device
319    .. code-block:: c
320     :emphasize-lines: 5,6
326 	platform_device_unregister(glue->musb);
327 	clk_disable_unprepare(glue->clk);
333 MUSB controller hardware (line 5) and disable the clock (line 6),
336 .. _musb-handling-irqs:
341 Additionally to the MUSB controller hardware basic setup and
344    .. code-block:: c
345     :emphasize-lines: 7,9-11,14,24
353 	spin_lock_irqsave(&musb->lock, flags);
355 	musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
356 	musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
357 	musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
360 	 * The controller is gadget only, the state of the host mode IRQ bits is
364 	musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
367 	if (musb->int_usb || musb->int_tx || musb->int_rx)
370 	spin_unlock_irqrestore(&musb->lock, flags);
376 and pass their values on to the controller driver which will handle the
386 -  ``MUSB_INTRUSB``: indicates which USB interrupts are currently active,
388 -  ``MUSB_INTRTX``: indicates which of the interrupts for TX endpoints are
391 -  ``MUSB_INTRRX``: indicates which of the interrupts for TX endpoints are
394 Note that :c:func:`musb_readb` is used to read 8-bit registers at most, while
395 :c:func:`musb_readw` allows us to read at most 16-bit registers. There are
400 device controller, which will be discussed later in :ref:`musb-dev-quirks`.
407 	musb->isr = jz4740_musb_interrupt;
413 in order for the controller hardware to call the handler back when an
414 IRQ comes from the controller hardware. The interrupt handler is now
417 .. _musb-dev-platform-data:
419 Device Platform Data
422 In order to write an MUSB glue layer, you need to have some data
423 describing the hardware capabilities of your controller hardware, which
424 is called the platform data.
426 Platform data is specific to your hardware, though it may cover a broad
430 For instance, platform data for the JZ4740 SoC is found in
435 Device Controller (UDC):
437    .. code-block:: c
438     :emphasize-lines: 2,7,14-17,21,22,25,26,28,29
440     /* USB Device Controller */
449 	    .end   = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
461 	.name = "musb-jz4740",
462 	.id   = -1,
475 specific name to be used for all transceivers that are either built-in
479 driver. The id field could be set to -1 (equivalent to
480 ``PLATFORM_DEVID_NONE``), -2 (equivalent to ``PLATFORM_DEVID_AUTO``) or
495 resources, and the name ``mc`` is in fact hard-coded in the MUSB core in
496 order for the controller driver to retrieve this IRQ resource by
502 The ``musb-jz4740`` name (line 22) defines the MUSB driver that is used
504 ``jz4740_driver`` platform driver structure in :ref:`musb-basics`.
505 The id field (line 23) is set to -1 (equivalent to ``PLATFORM_DEVID_NONE``)
506 since we do not need an id for the device: the MUSB controller driver was
507 already set to allocate an automatic id in :ref:`musb-basics`. In the dev field
517 With this quick overview of the UDC platform data at the ``arch/`` level now
518 done, let's get back to the MUSB glue layer specific platform data in
521    .. code-block:: c
522     :emphasize-lines: 3,5,7-9,11
540 First the glue layer configures some aspects of the controller driver
541 operation related to the controller hardware specifics. This is done
544 Defining the OTG capability of the controller hardware, the multipoint
547 endpoints of the controller hardware, including endpoint 0: here we have
549 of the RAM address bus for the MUSB controller hardware. This
550 information is needed when the controller driver cannot automatically
551 configure endpoints by reading the relevant controller hardware
553 :ref:`musb-dev-quirks`. Last two fields (line 8 and 9) are also
557 :ref:`musb-dev-quirks`.
561 the configuration structure itself, and mode tells the controller driver
562 if the controller hardware may be used as ``MUSB_HOST`` only,
566 platform data information as we have seen in the probe function in
567 :ref:`musb-basics`.
569 .. _musb-dev-quirks:
574 Completing the platform data specific to your device, you may also need
577 the result of an incomplete implementation of the USB On-the-Go
582 controller hardware you are working on.
586    .. code-block:: c
587     :emphasize-lines: 12
591 	musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
592 	if (!musb->xceiv) {
594 	    return -ENODEV;
600 	musb->dyn_fifo = true;
602 	musb->isr = jz4740_musb_interrupt;
607 Instruction on line 12 helps the MUSB controller driver to work around
608 the fact that the controller hardware is missing registers that are used
611 Without these registers, the controller driver is unable to read the
614 hard-coded table that describes the endpoints configuration instead::
624 its direction (either ``FIFO_TX`` for the controller driver to send packets
625 in the controller hardware, or ``FIFO_RX`` to receive packets from
626 hardware), and maxpacket defines the maximum size of each data packet
628 controller driver knows that endpoint 1 can be used to send and receive
629 USB data packets of 512 bytes at once (this is in fact a bulk in/out
630 endpoint), and endpoint 2 can be used to send data packets of 64 bytes
640    .. code-block:: c
641     :emphasize-lines: 18-19
649 	spin_lock_irqsave(&musb->lock, flags);
651 	musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
652 	musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
653 	musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
656 	 * The controller is gadget only, the state of the host mode IRQ bits is
660 	musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
663 	if (musb->int_usb || musb->int_tx || musb->int_rx)
666 	spin_unlock_irqrestore(&musb->lock, flags);
671 Instruction on line 18 above is a way for the controller driver to work
674 undefined hardware state, since this MUSB controller hardware is used in
681 controller. Some others were directly addressed in the MUSB core since
683 for others controller hardware eventually.
691 The JZ4740 USB device controller being fairly simple, I hope its glue
694 guidance to get started; should anything gets out of hand, the linux-usb
700 Many thanks to Lars-Peter Clausen and Maarten ter Huurne for answering
704 I would also like to thank the Qi-Hardware community at large for its
712 linux-usb Mailing List Archives: https://marc.info/?l=linux-usb
714 USB On-the-Go Basics:
715 https://www.maximintegrated.com/app-notes/index.mvp/id/1822
717 :ref:`Writing USB Device Drivers <writing-usb-driver>`