Lines Matching +full:jz4740 +full:- +full:musb
2 Writing a MUSB Glue Layer
10 The Linux MUSB subsystem is part of the larger Linux USB subsystem. It
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
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
28 .. _musb-basics:
30 Linux MUSB Basics
33 To get started on the topic, please read USB On-the-Go Basics (see
36 Devices also provide an overview of the Linux kernel MUSB configuration,
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 ---------------------------------
59 | MUSB Platform Specific Driver |
60 | | <-- drivers/usb/musb/jz4740.c
62 ---------------------------------
64 ---------------------------------
65 | MUSB Controller Hardware |
66 ---------------------------------
72 subsystem, the MUSB glue layer needs first to register itself with the
73 MUSB controller driver. This will allow the controller driver to know
77 run-time.
79 All of this information is passed to the MUSB controller driver through
86 .name = "musb-jz4740",
93 platform_device structure declared in ``arch/mips/jz4740/platform.c``. Note
104 struct platform_device *musb;
109 The dev and musb members are both device structure variables. The first
123 .. code-block:: c
124 :emphasize-lines: 8,12,18
128 struct platform_device *musb;
133 glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL);
135 return -ENOMEM;
137 musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
138 if (!musb) {
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;
165 platform_device_put(musb);
170 musb and clk variables. The ``GFP_KERNEL`` flag (line 8) allows the
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");
202 ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
204 dev_err(&pdev->dev, "failed to add platform_data\n");
213 platform_device_put(musb);
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
239 between OTG and non-OTG modes, for instance.
244 .. code-block:: c
245 :emphasize-lines: 12,14
247 static int jz4740_musb_init(struct musb *musb)
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
272 Getting hold of the ``MUSB PHY`` driver data is done with ``usb_get_phy()``
276 will be discussed later in :ref:`musb-dev-quirks` and
277 :ref:`musb-handling-irqs`\ ::
279 static int jz4740_musb_exit(struct musb *musb)
281 usb_put_phy(musb->xceiv);
286 Acting as the counterpart of init, the exit function releases the MUSB
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
299 ret = platform_device_add(musb);
301 dev_err(&pdev->dev, "failed to register musb device\n");
310 platform_device_put(musb);
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
351 struct musb *musb = __hci;
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);
361 * undefined. Mask them to make sure that the musb driver core will
364 musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
367 if (musb->int_usb || musb->int_tx || musb->int_rx)
368 retval = musb_interrupt(musb);
370 spin_unlock_irqrestore(&musb->lock, flags);
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`.
405 static int jz4740_musb_init(struct musb *musb)
407 musb->isr = jz4740_musb_interrupt;
417 .. _musb-dev-platform-data:
422 In order to write an MUSB glue layer, you need to have some data
430 For instance, platform data for the JZ4740 SoC is found in
431 ``arch/mips/jz4740/platform.c``. In the ``platform.c`` file each device of the
432 JZ4740 SoC is described through a set of structures.
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
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
493 register available for the JZ4740 UDC, start and end point at the same
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``)
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
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
545 member (line 3) is set to 0 (equivalent to false) since the JZ4740 UDC
549 of the RAM address bus for the MUSB controller hardware. This
553 :ref:`musb-dev-quirks`. Last two fields (line 8 and 9) are also
557 :ref:`musb-dev-quirks`.
567 :ref:`musb-basics`.
569 .. _musb-dev-quirks:
577 the result of an incomplete implementation of the USB On-the-Go
580 The JZ4740 UDC exhibits such quirks, some of which we will discuss here
586 .. code-block:: c
587 :emphasize-lines: 12
589 static int jz4740_musb_init(struct musb *musb)
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
614 hard-coded table that describes the endpoints configuration instead::
640 .. code-block:: c
641 :emphasize-lines: 18-19
647 struct musb *musb = __hci;
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);
657 * undefined. Mask them to make sure that the musb driver core will
660 musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
663 if (musb->int_usb || musb->int_tx || musb->int_rx)
664 retval = musb_interrupt(musb);
666 spin_unlock_irqrestore(&musb->lock, flags);
674 undefined hardware state, since this MUSB controller hardware is used in
680 These are only a couple of the quirks found in the JZ4740 USB device
681 controller. Some others were directly addressed in the MUSB core since
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
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>`