Lines Matching +full:usb +full:- +full:glue
2 Writing a MUSB Glue Layer
10 The Linux MUSB subsystem is part of the larger Linux USB subsystem. It
11 provides support for embedded USB Device Controllers (UDC) that do not
15 Instead, these embedded UDC rely on the USB On-the-Go (OTG)
17 reference design used in most cases is the Multipoint USB Highspeed
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
22 Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the
24 ``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the
25 basics of the ``jz4740.c`` glue layer, explaining the different pieces and
26 what needs to be done in order to write your own device glue layer.
28 .. _musb-basics:
33 To get started on the topic, please read USB On-the-Go Basics (see
34 Resources) which provides an introduction of USB OTG operation at the
38 Finally, getting acquainted with the USB specification at USB home page
40 USB Device Drivers documentation (again, see Resources).
42 Linux USB stack is a layered architecture in which the MUSB controller
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
61 | aka "Glue Layer" |
62 ---------------------------------
64 ---------------------------------
66 ---------------------------------
68 As outlined above, the glue layer is actually the platform specific code
71 Just like a Linux USB driver needs to register itself with the Linux USB
72 subsystem, the MUSB glue layer needs first to register itself with the
74 about which device the glue layer supports and which functions to call
77 run-time.
80 a :c:type:`platform_driver` structure defined in the glue layer as::
86 .name = "musb-jz4740",
92 device supported by this glue layer. In the current case it matches a
96 In order to register itself to the controller driver, the glue layer
115 Let's go through the steps of the probe function that leads the glue
123 .. code-block:: c
124 :emphasize-lines: 8,12,18
129 struct jz4740_glue *glue;
133 glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
134 if (!glue)
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;
169 The first few lines of the probe function allocate and assign the glue,
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;
193 platform_set_drvdata(pdev, glue);
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
224 :ref:`musb-dev-platform-data`, but here we are looking at the
239 between OTG and non-OTG modes, for instance.
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;
268 controller hardware responsible for sending/receiving the USB data.
276 will be discussed later in :ref:`musb-dev-quirks` and
277 :ref:`musb-handling-irqs`\ ::
281 usb_put_phy(musb->xceiv);
291 musb glue layer for a more complex controller hardware, you might need
301 dev_err(&pdev->dev, "failed to register musb device\n");
314 This is the last part of the device registration process where the glue
317 passed on to the Linux USB core stack:
319 .. code-block:: c
320 :emphasize-lines: 5,6
324 struct jz4740_glue *glue = platform_get_drvdata(pdev);
326 platform_device_unregister(glue->musb);
327 clk_disable_unprepare(glue->clk);
336 .. _musb-handling-irqs:
342 registration, the glue layer is also responsible for handling the IRQs:
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);
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);
375 Here the glue layer mostly has to read the relevant hardware registers
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
399 Instruction on line 18 is another quirk specific to the JZ4740 USB
400 device controller, which will be discussed later in :ref:`musb-dev-quirks`.
402 The glue layer still needs to register the IRQ handler though. Remember
407 musb->isr = jz4740_musb_interrupt;
412 This instruction sets a pointer to the glue layer IRQ handler function,
417 .. _musb-dev-platform-data:
422 In order to write an MUSB glue layer, you need to have some data
434 Here is the part of ``arch/mips/jz4740/platform.c`` that covers the USB
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
476 with reference USB IP or autonomous and doesn't require any PHY
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
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``)
507 already set to allocate an automatic id in :ref:`musb-basics`. In the dev field
518 done, let's get back to the MUSB glue layer specific platform data in
519 ``drivers/usb/musb/jz4740.c``:
521 .. code-block:: c
522 :emphasize-lines: 3,5,7-9,11
525 /* Silicon does not implement USB OTG. */
540 First the glue layer configures some aspects of the controller driver
546 is not OTG compatible. Then ``num_eps`` (line 5) defines the number of USB
553 :ref:`musb-dev-quirks`. Last two fields (line 8 and 9) are also
554 about device quirks: ``fifo_cfg`` points to the USB endpoints configuration
557 :ref:`musb-dev-quirks`.
567 :ref:`musb-basics`.
569 .. _musb-dev-quirks:
575 to write some code in the glue layer to work around some device specific
577 the result of an incomplete implementation of the USB On-the-Go
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;
609 for USB endpoints configuration.
614 hard-coded table that describes the endpoints configuration instead::
629 USB data packets of 512 bytes at once (this is in fact a bulk in/out
635 configuration according to the USB specification. For more examples of
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);
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);
672 around the fact that some interrupt bits used for USB host mode
675 peripheral mode only. As a consequence, the glue layer masks these
680 These are only a couple of the quirks found in the JZ4740 USB device
688 Writing a Linux MUSB glue layer should be a more accessible task, as
691 The JZ4740 USB device controller being fairly simple, I hope its glue
693 current MUSB glue layers, this documentation should provide enough
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
701 my questions while I was writing the JZ4740 glue layer and for helping
704 I would also like to thank the Qi-Hardware community at large for its
710 USB Home Page: https://www.usb.org
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>`
719 Texas Instruments USB Configuration Wiki Page: