Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 1 | ========================= |
| 2 | Writing a MUSB Glue Layer |
| 3 | ========================= |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 4 | |
| 5 | :Author: Apelete Seketeli |
| 6 | |
| 7 | Introduction |
| 8 | ============ |
| 9 | |
| 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 |
| 12 | use Universal Host Controller Interface (UHCI) or Open Host Controller |
| 13 | Interface (OHCI). |
| 14 | |
| 15 | Instead, these embedded UDC rely on the USB On-the-Go (OTG) |
| 16 | specification which they implement at least partially. The silicon |
| 17 | reference design used in most cases is the Multipoint USB Highspeed |
| 18 | Dual-Role Controller (MUSB HDRC) found in the Mentor Graphics Inventra™ |
| 19 | design. |
| 20 | |
| 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 |
| 23 | kernel source tree. This layer can be found at |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 26 | what needs to be done in order to write your own device glue layer. |
| 27 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 28 | .. _musb-basics: |
| 29 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 30 | Linux MUSB Basics |
| 31 | ================= |
| 32 | |
| 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 |
| 35 | hardware level. A couple of wiki pages by Texas Instruments and Analog |
| 36 | Devices also provide an overview of the Linux kernel MUSB configuration, |
| 37 | albeit focused on some specific devices provided by these companies. |
| 38 | Finally, getting acquainted with the USB specification at USB home page |
| 39 | may come in handy, with practical instance provided through the Writing |
| 40 | USB Device Drivers documentation (again, see Resources). |
| 41 | |
| 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 |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 44 | MUSB controller hardware to the Linux USB stack:: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 45 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 46 | ------------------------ |
| 47 | | | <------- drivers/usb/gadget |
| 48 | | Linux USB Core Stack | <------- drivers/usb/host |
| 49 | | | <------- drivers/usb/core |
| 50 | ------------------------ |
| 51 | ⬍ |
| 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 | -------------------------- |
| 57 | ⬍ |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 58 | --------------------------------- |
| 59 | | MUSB Platform Specific Driver | |
| 60 | | | <-- drivers/usb/musb/jz4740.c |
| 61 | | aka "Glue Layer" | |
| 62 | --------------------------------- |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 63 | ⬍ |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 64 | --------------------------------- |
| 65 | | MUSB Controller Hardware | |
| 66 | --------------------------------- |
| 67 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 68 | As outlined above, the glue layer is actually the platform specific code |
| 69 | sitting in between the controller driver and the controller hardware. |
| 70 | |
| 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 |
| 73 | MUSB controller driver. This will allow the controller driver to know |
| 74 | about which device the glue layer supports and which functions to call |
| 75 | when a supported device is detected or released; remember we are talking |
| 76 | about an embedded controller chip here, so no insertion or removal at |
| 77 | run-time. |
| 78 | |
| 79 | All of this information is passed to the MUSB controller driver through |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 80 | a :c:type:`platform_driver` structure defined in the glue layer as:: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 81 | |
| 82 | static struct platform_driver jz4740_driver = { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 83 | .probe = jz4740_probe, |
| 84 | .remove = jz4740_remove, |
| 85 | .driver = { |
| 86 | .name = "musb-jz4740", |
| 87 | }, |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 88 | }; |
| 89 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 90 | The probe and remove function pointers are called when a matching device |
| 91 | is detected and, respectively, released. The name string describes the |
| 92 | device supported by this glue layer. In the current case it matches a |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 93 | platform_device structure declared in ``arch/mips/jz4740/platform.c``. Note |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 94 | that we are not using device tree bindings here. |
| 95 | |
| 96 | In order to register itself to the controller driver, the glue layer |
| 97 | goes through a few steps, basically allocating the controller hardware |
| 98 | resources and initialising a couple of circuits. To do so, it needs to |
| 99 | keep track of the information used throughout these steps. This is done |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 100 | by defining a private ``jz4740_glue`` structure:: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 101 | |
| 102 | struct jz4740_glue { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 103 | struct device *dev; |
| 104 | struct platform_device *musb; |
| 105 | struct clk *clk; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 106 | }; |
| 107 | |
| 108 | |
| 109 | The dev and musb members are both device structure variables. The first |
| 110 | one holds generic information about the device, since it's the basic |
| 111 | device structure, and the latter holds information more closely related |
| 112 | to the subsystem the device is registered to. The clk variable keeps |
| 113 | information related to the device clock operation. |
| 114 | |
| 115 | Let's go through the steps of the probe function that leads the glue |
| 116 | layer to register itself to the controller driver. |
| 117 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 118 | .. note:: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 119 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 120 | For the sake of readability each function will be split in logical |
| 121 | parts, each part being shown as if it was independent from the others. |
| 122 | |
| 123 | .. code-block:: c |
| 124 | :emphasize-lines: 8,12,18 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 125 | |
| 126 | static int jz4740_probe(struct platform_device *pdev) |
| 127 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 128 | struct platform_device *musb; |
| 129 | struct jz4740_glue *glue; |
| 130 | struct clk *clk; |
| 131 | int ret; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 132 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 133 | glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL); |
| 134 | if (!glue) |
| 135 | return -ENOMEM; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 136 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 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; |
| 141 | } |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 142 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 143 | clk = devm_clk_get(&pdev->dev, "udc"); |
| 144 | if (IS_ERR(clk)) { |
| 145 | dev_err(&pdev->dev, "failed to get clock\n"); |
| 146 | ret = PTR_ERR(clk); |
| 147 | goto err_platform_device_put; |
| 148 | } |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 149 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 150 | ret = clk_prepare_enable(clk); |
| 151 | if (ret) { |
| 152 | dev_err(&pdev->dev, "failed to enable clock\n"); |
| 153 | goto err_platform_device_put; |
| 154 | } |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 155 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 156 | musb->dev.parent = &pdev->dev; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 157 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 158 | glue->dev = &pdev->dev; |
| 159 | glue->musb = musb; |
| 160 | glue->clk = clk; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 161 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 162 | return 0; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 163 | |
| 164 | err_platform_device_put: |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 165 | platform_device_put(musb); |
| 166 | return ret; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 167 | } |
| 168 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 169 | The first few lines of the probe function allocate and assign the glue, |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 170 | musb and clk variables. The ``GFP_KERNEL`` flag (line 8) allows the |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 171 | allocation process to sleep and wait for memory, thus being usable in a |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 172 | locking situation. The ``PLATFORM_DEVID_AUTO`` flag (line 12) allows |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 173 | automatic allocation and management of device IDs in order to avoid |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 174 | device namespace collisions with explicit IDs. With :c:func:`devm_clk_get` |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 175 | (line 18) the glue layer allocates the clock -- the ``devm_`` prefix |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 176 | indicates that :c:func:`clk_get` is managed: it automatically frees the |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 177 | allocated clock resource data when the device is released -- and enable |
| 178 | it. |
| 179 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 180 | |
| 181 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 182 | Then comes the registration steps: |
| 183 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 184 | .. code-block:: c |
| 185 | :emphasize-lines: 3,5,7,9,16 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 186 | |
| 187 | static int jz4740_probe(struct platform_device *pdev) |
| 188 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 189 | struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 190 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 191 | pdata->platform_ops = &jz4740_musb_ops; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 192 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 193 | platform_set_drvdata(pdev, glue); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 194 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 195 | ret = platform_device_add_resources(musb, pdev->resource, |
| 196 | pdev->num_resources); |
| 197 | if (ret) { |
| 198 | dev_err(&pdev->dev, "failed to add resources\n"); |
| 199 | goto err_clk_disable; |
| 200 | } |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 201 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 202 | ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); |
| 203 | if (ret) { |
| 204 | dev_err(&pdev->dev, "failed to add platform_data\n"); |
| 205 | goto err_clk_disable; |
| 206 | } |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 207 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 208 | return 0; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 209 | |
| 210 | err_clk_disable: |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 211 | clk_disable_unprepare(clk); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 212 | err_platform_device_put: |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 213 | platform_device_put(musb); |
| 214 | return ret; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 215 | } |
| 216 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 217 | The first step is to pass the device data privately held by the glue |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 218 | layer on to the controller driver through :c:func:`platform_set_drvdata` |
| 219 | (line 7). Next is passing on the device resources information, also privately |
| 220 | held at that point, through :c:func:`platform_device_add_resources` (line 9). |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 221 | |
| 222 | Finally comes passing on the platform specific data to the controller |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 223 | driver (line 16). Platform data will be discussed in |
| 224 | :ref:`musb-dev-platform-data`, but here we are looking at the |
| 225 | ``platform_ops`` function pointer (line 5) in ``musb_hdrc_platform_data`` |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 226 | structure (line 3). This function pointer allows the MUSB controller |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 227 | driver to know which function to call for device operation:: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 228 | |
| 229 | static const struct musb_platform_ops jz4740_musb_ops = { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 230 | .init = jz4740_musb_init, |
| 231 | .exit = jz4740_musb_exit, |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 232 | }; |
| 233 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 234 | Here we have the minimal case where only init and exit functions are |
| 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 |
| 237 | controllers, otherwise we may also have pointers to a few other |
| 238 | functions like a power management function or a function to switch |
| 239 | between OTG and non-OTG modes, for instance. |
| 240 | |
| 241 | At that point of the registration process, the controller driver |
| 242 | actually calls the init function: |
| 243 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 244 | .. code-block:: c |
| 245 | :emphasize-lines: 12,14 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 246 | |
| 247 | static int jz4740_musb_init(struct musb *musb) |
| 248 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 249 | musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); |
| 250 | if (!musb->xceiv) { |
| 251 | pr_err("HS UDC: no transceiver configured\n"); |
| 252 | return -ENODEV; |
| 253 | } |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 254 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 255 | /* Silicon does not implement ConfigData register. |
| 256 | * Set dyn_fifo to avoid reading EP config from hardware. |
| 257 | */ |
| 258 | musb->dyn_fifo = true; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 259 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 260 | musb->isr = jz4740_musb_interrupt; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 261 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 262 | return 0; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 263 | } |
| 264 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 265 | The goal of ``jz4740_musb_init()`` is to get hold of the transceiver |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 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. |
| 269 | Since it is an implementation of the physical layer of the OSI model, |
| 270 | the transceiver is also referred to as PHY. |
| 271 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 272 | Getting hold of the ``MUSB PHY`` driver data is done with ``usb_get_phy()`` |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 273 | which returns a pointer to the structure containing the driver instance |
| 274 | data. The next couple of instructions (line 12 and 14) are used as a |
| 275 | quirk and to setup IRQ handling respectively. Quirks and IRQ handling |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 276 | will be discussed later in :ref:`musb-dev-quirks` and |
| 277 | :ref:`musb-handling-irqs`\ :: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 278 | |
| 279 | static int jz4740_musb_exit(struct musb *musb) |
| 280 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 281 | usb_put_phy(musb->xceiv); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 282 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 283 | return 0; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 284 | } |
| 285 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 286 | Acting as the counterpart of init, the exit function releases the MUSB |
| 287 | PHY driver when the controller hardware itself is about to be released. |
| 288 | |
| 289 | Again, note that init and exit are fairly simple in this case due to the |
| 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 |
| 292 | to take care of more processing in those two functions. |
| 293 | |
| 294 | Returning from the init function, the MUSB controller driver jumps back |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 295 | into the probe function:: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 296 | |
| 297 | static int jz4740_probe(struct platform_device *pdev) |
| 298 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 299 | ret = platform_device_add(musb); |
| 300 | if (ret) { |
| 301 | dev_err(&pdev->dev, "failed to register musb device\n"); |
| 302 | goto err_clk_disable; |
| 303 | } |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 304 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 305 | return 0; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 306 | |
| 307 | err_clk_disable: |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 308 | clk_disable_unprepare(clk); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 309 | err_platform_device_put: |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 310 | platform_device_put(musb); |
| 311 | return ret; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 312 | } |
| 313 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 314 | This is the last part of the device registration process where the glue |
| 315 | layer adds the controller hardware device to Linux kernel device |
| 316 | hierarchy: at this stage, all known information about the device is |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 317 | passed on to the Linux USB core stack: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 318 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 319 | .. code-block:: c |
| 320 | :emphasize-lines: 5,6 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 321 | |
| 322 | static int jz4740_remove(struct platform_device *pdev) |
| 323 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 324 | struct jz4740_glue *glue = platform_get_drvdata(pdev); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 325 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 326 | platform_device_unregister(glue->musb); |
| 327 | clk_disable_unprepare(glue->clk); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 328 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 329 | return 0; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 330 | } |
| 331 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 332 | Acting as the counterpart of probe, the remove function unregister the |
| 333 | MUSB controller hardware (line 5) and disable the clock (line 6), |
| 334 | allowing it to be gated. |
| 335 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 336 | .. _musb-handling-irqs: |
| 337 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 338 | Handling IRQs |
| 339 | ============= |
| 340 | |
| 341 | Additionally to the MUSB controller hardware basic setup and |
| 342 | registration, the glue layer is also responsible for handling the IRQs: |
| 343 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 344 | .. code-block:: c |
| 345 | :emphasize-lines: 7,9-11,14,24 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 346 | |
| 347 | static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) |
| 348 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 349 | unsigned long flags; |
| 350 | irqreturn_t retval = IRQ_NONE; |
| 351 | struct musb *musb = __hci; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 352 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 353 | spin_lock_irqsave(&musb->lock, flags); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 354 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 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); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 358 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 359 | /* |
| 360 | * The controller is gadget only, the state of the host mode IRQ bits is |
| 361 | * undefined. Mask them to make sure that the musb driver core will |
| 362 | * never see them set |
| 363 | */ |
| 364 | musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | |
| 365 | MUSB_INTR_RESET | MUSB_INTR_SOF; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 366 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 367 | if (musb->int_usb || musb->int_tx || musb->int_rx) |
| 368 | retval = musb_interrupt(musb); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 369 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 370 | spin_unlock_irqrestore(&musb->lock, flags); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 371 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 372 | return retval; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 373 | } |
| 374 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 375 | Here the glue layer mostly has to read the relevant hardware registers |
| 376 | and pass their values on to the controller driver which will handle the |
| 377 | actual event that triggered the IRQ. |
| 378 | |
| 379 | The interrupt handler critical section is protected by the |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 380 | :c:func:`spin_lock_irqsave` and counterpart :c:func:`spin_unlock_irqrestore` |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 381 | functions (line 7 and 24 respectively), which prevent the interrupt |
| 382 | handler code to be run by two different threads at the same time. |
| 383 | |
| 384 | Then the relevant interrupt registers are read (line 9 to 11): |
| 385 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 386 | - ``MUSB_INTRUSB``: indicates which USB interrupts are currently active, |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 387 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 388 | - ``MUSB_INTRTX``: indicates which of the interrupts for TX endpoints are |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 389 | currently active, |
| 390 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 391 | - ``MUSB_INTRRX``: indicates which of the interrupts for TX endpoints are |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 392 | currently active. |
| 393 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 396 | other functions that can be used depending on the size of your device |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 397 | registers. See ``musb_io.h`` for more information. |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 398 | |
| 399 | Instruction on line 18 is another quirk specific to the JZ4740 USB |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 400 | device controller, which will be discussed later in :ref:`musb-dev-quirks`. |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 401 | |
| 402 | The glue layer still needs to register the IRQ handler though. Remember |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 403 | the instruction on line 14 of the init function:: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 404 | |
| 405 | static int jz4740_musb_init(struct musb *musb) |
| 406 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 407 | musb->isr = jz4740_musb_interrupt; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 408 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 409 | return 0; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 410 | } |
| 411 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 412 | This instruction sets a pointer to the glue layer IRQ handler function, |
| 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 |
| 415 | implemented and registered. |
| 416 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 417 | .. _musb-dev-platform-data: |
| 418 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 419 | Device Platform Data |
| 420 | ==================== |
| 421 | |
| 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. |
| 425 | |
| 426 | Platform data is specific to your hardware, though it may cover a broad |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 427 | range of devices, and is generally found somewhere in the ``arch/`` |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 428 | directory, depending on your device architecture. |
| 429 | |
| 430 | For instance, platform data for the JZ4740 SoC is found in |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 431 | ``arch/mips/jz4740/platform.c``. In the ``platform.c`` file each device of the |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 432 | JZ4740 SoC is described through a set of structures. |
| 433 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 434 | Here is the part of ``arch/mips/jz4740/platform.c`` that covers the USB |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 435 | Device Controller (UDC): |
| 436 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 437 | .. code-block:: c |
| 438 | :emphasize-lines: 2,7,14-17,21,22,25,26,28,29 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 439 | |
| 440 | /* USB Device Controller */ |
| 441 | struct platform_device jz4740_udc_xceiv_device = { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 442 | .name = "usb_phy_gen_xceiv", |
| 443 | .id = 0, |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 444 | }; |
| 445 | |
| 446 | static struct resource jz4740_udc_resources[] = { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 447 | [0] = { |
| 448 | .start = JZ4740_UDC_BASE_ADDR, |
| 449 | .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1, |
| 450 | .flags = IORESOURCE_MEM, |
| 451 | }, |
| 452 | [1] = { |
| 453 | .start = JZ4740_IRQ_UDC, |
| 454 | .end = JZ4740_IRQ_UDC, |
| 455 | .flags = IORESOURCE_IRQ, |
| 456 | .name = "mc", |
| 457 | }, |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 458 | }; |
| 459 | |
| 460 | struct platform_device jz4740_udc_device = { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 461 | .name = "musb-jz4740", |
| 462 | .id = -1, |
| 463 | .dev = { |
| 464 | .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask, |
| 465 | .coherent_dma_mask = DMA_BIT_MASK(32), |
| 466 | }, |
| 467 | .num_resources = ARRAY_SIZE(jz4740_udc_resources), |
| 468 | .resource = jz4740_udc_resources, |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 469 | }; |
| 470 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 471 | The ``jz4740_udc_xceiv_device`` platform device structure (line 2) |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 472 | describes the UDC transceiver with a name and id number. |
| 473 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 474 | At the time of this writing, note that ``usb_phy_gen_xceiv`` is the |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 477 | programming. You will need to set ``CONFIG_NOP_USB_XCEIV=y`` in the |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 478 | kernel configuration to make use of the corresponding transceiver |
| 479 | driver. The id field could be set to -1 (equivalent to |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 480 | ``PLATFORM_DEVID_NONE``), -2 (equivalent to ``PLATFORM_DEVID_AUTO``) or |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 481 | start with 0 for the first device of this kind if we want a specific id |
| 482 | number. |
| 483 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 484 | The ``jz4740_udc_resources`` resource structure (line 7) defines the UDC |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 485 | registers base addresses. |
| 486 | |
| 487 | The first array (line 9 to 11) defines the UDC registers base memory |
| 488 | addresses: start points to the first register memory address, end points |
| 489 | to the last register memory address and the flags member defines the |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 490 | type of resource we are dealing with. So ``IORESOURCE_MEM`` is used to |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 491 | define the registers memory addresses. The second array (line 14 to 17) |
| 492 | defines the UDC IRQ registers addresses. Since there is only one IRQ |
| 493 | register available for the JZ4740 UDC, start and end point at the same |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 494 | address. The ``IORESOURCE_IRQ`` flag tells that we are dealing with IRQ |
| 495 | resources, and the name ``mc`` is in fact hard-coded in the MUSB core in |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 496 | order for the controller driver to retrieve this IRQ resource by |
| 497 | querying it by its name. |
| 498 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 499 | Finally, the ``jz4740_udc_device`` platform device structure (line 21) |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 500 | describes the UDC itself. |
| 501 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 502 | The ``musb-jz4740`` name (line 22) defines the MUSB driver that is used |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 503 | for this device; remember this is in fact the name that we used in the |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 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 |
| 508 | we care for DMA related information here. The ``dma_mask`` field (line 25) |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 509 | defines the width of the DMA mask that is going to be used, and |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 510 | ``coherent_dma_mask`` (line 26) has the same purpose but for the |
| 511 | ``alloc_coherent`` DMA mappings: in both cases we are using a 32 bits mask. |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 512 | Then the resource field (line 29) is simply a pointer to the resource |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 513 | structure defined before, while the ``num_resources`` field (line 28) keeps |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 514 | track of the number of arrays defined in the resource structure (in this |
| 515 | case there were two resource arrays defined before). |
| 516 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 517 | With this quick overview of the UDC platform data at the ``arch/`` level now |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 518 | done, let's get back to the MUSB glue layer specific platform data in |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 519 | ``drivers/usb/musb/jz4740.c``: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 520 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 521 | .. code-block:: c |
| 522 | :emphasize-lines: 3,5,7-9,11 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 523 | |
| 524 | static struct musb_hdrc_config jz4740_musb_config = { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 525 | /* Silicon does not implement USB OTG. */ |
| 526 | .multipoint = 0, |
| 527 | /* Max EPs scanned, driver will decide which EP can be used. */ |
| 528 | .num_eps = 4, |
| 529 | /* RAMbits needed to configure EPs from table */ |
| 530 | .ram_bits = 9, |
| 531 | .fifo_cfg = jz4740_musb_fifo_cfg, |
| 532 | .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg), |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 533 | }; |
| 534 | |
| 535 | static struct musb_hdrc_platform_data jz4740_musb_platform_data = { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 536 | .mode = MUSB_PERIPHERAL, |
| 537 | .config = &jz4740_musb_config, |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 538 | }; |
| 539 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 540 | First the glue layer configures some aspects of the controller driver |
| 541 | operation related to the controller hardware specifics. This is done |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 542 | through the ``jz4740_musb_config`` :c:type:`musb_hdrc_config` structure. |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 543 | |
| 544 | Defining the OTG capability of the controller hardware, the multipoint |
| 545 | member (line 3) is set to 0 (equivalent to false) since the JZ4740 UDC |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 546 | is not OTG compatible. Then ``num_eps`` (line 5) defines the number of USB |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 547 | endpoints of the controller hardware, including endpoint 0: here we have |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 548 | 3 endpoints + endpoint 0. Next is ``ram_bits`` (line 7) which is the width |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 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 |
| 552 | registers. This issue will be discussed when we get to device quirks in |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 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 |
| 555 | table and ``fifo_cfg_size`` keeps track of the size of the number of |
| 556 | entries in that configuration table. More on that later in |
| 557 | :ref:`musb-dev-quirks`. |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 558 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 559 | Then this configuration is embedded inside ``jz4740_musb_platform_data`` |
| 560 | :c:type:`musb_hdrc_platform_data` structure (line 11): config is a pointer to |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 561 | the configuration structure itself, and mode tells the controller driver |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 562 | if the controller hardware may be used as ``MUSB_HOST`` only, |
| 563 | ``MUSB_PERIPHERAL`` only or ``MUSB_OTG`` which is a dual mode. |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 564 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 565 | Remember that ``jz4740_musb_platform_data`` is then used to convey |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 566 | platform data information as we have seen in the probe function in |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 567 | :ref:`musb-basics`. |
| 568 | |
| 569 | .. _musb-dev-quirks: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 570 | |
| 571 | Device Quirks |
| 572 | ============= |
| 573 | |
| 574 | Completing the platform data specific to your device, you may also need |
| 575 | to write some code in the glue layer to work around some device specific |
| 576 | limitations. These quirks may be due to some hardware bugs, or simply be |
| 577 | the result of an incomplete implementation of the USB On-the-Go |
| 578 | specification. |
| 579 | |
| 580 | The JZ4740 UDC exhibits such quirks, some of which we will discuss here |
| 581 | for the sake of insight even though these might not be found in the |
| 582 | controller hardware you are working on. |
| 583 | |
| 584 | Let's get back to the init function first: |
| 585 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 586 | .. code-block:: c |
| 587 | :emphasize-lines: 12 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 588 | |
| 589 | static int jz4740_musb_init(struct musb *musb) |
| 590 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 591 | musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); |
| 592 | if (!musb->xceiv) { |
| 593 | pr_err("HS UDC: no transceiver configured\n"); |
| 594 | return -ENODEV; |
| 595 | } |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 596 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 597 | /* Silicon does not implement ConfigData register. |
| 598 | * Set dyn_fifo to avoid reading EP config from hardware. |
| 599 | */ |
| 600 | musb->dyn_fifo = true; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 601 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 602 | musb->isr = jz4740_musb_interrupt; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 603 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 604 | return 0; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 605 | } |
| 606 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 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 |
| 609 | for USB endpoints configuration. |
| 610 | |
| 611 | Without these registers, the controller driver is unable to read the |
| 612 | endpoints configuration from the hardware, so we use line 12 instruction |
| 613 | to bypass reading the configuration from silicon, and rely on a |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 614 | hard-coded table that describes the endpoints configuration instead:: |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 615 | |
| 616 | static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 617 | { .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, }, |
| 618 | { .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, }, |
| 619 | { .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, }, |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 620 | }; |
| 621 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 622 | Looking at the configuration table above, we see that each endpoints is |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 623 | described by three fields: ``hw_ep_num`` is the endpoint number, style is |
| 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 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 626 | hardware), and maxpacket defines the maximum size of each data packet |
| 627 | that can be transmitted over that endpoint. Reading from the table, the |
| 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 |
| 631 | at once (this is in fact an interrupt endpoint). |
| 632 | |
| 633 | Note that there is no information about endpoint 0 here: that one is |
| 634 | implemented by default in every silicon design, with a predefined |
| 635 | configuration according to the USB specification. For more examples of |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 636 | endpoint configuration tables, see ``musb_core.c``. |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 637 | |
| 638 | Let's now get back to the interrupt handler function: |
| 639 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 640 | .. code-block:: c |
| 641 | :emphasize-lines: 18-19 |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 642 | |
| 643 | static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) |
| 644 | { |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 645 | unsigned long flags; |
| 646 | irqreturn_t retval = IRQ_NONE; |
| 647 | struct musb *musb = __hci; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 648 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 649 | spin_lock_irqsave(&musb->lock, flags); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 650 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 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); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 654 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 655 | /* |
| 656 | * The controller is gadget only, the state of the host mode IRQ bits is |
| 657 | * undefined. Mask them to make sure that the musb driver core will |
| 658 | * never see them set |
| 659 | */ |
| 660 | musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | |
| 661 | MUSB_INTR_RESET | MUSB_INTR_SOF; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 662 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 663 | if (musb->int_usb || musb->int_tx || musb->int_rx) |
| 664 | retval = musb_interrupt(musb); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 665 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 666 | spin_unlock_irqrestore(&musb->lock, flags); |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 667 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 668 | return retval; |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 669 | } |
| 670 | |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 671 | Instruction on line 18 above is a way for the controller driver to work |
| 672 | around the fact that some interrupt bits used for USB host mode |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 673 | operation are missing in the ``MUSB_INTRUSB`` register, thus left in an |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 674 | undefined hardware state, since this MUSB controller hardware is used in |
| 675 | peripheral mode only. As a consequence, the glue layer masks these |
| 676 | missing bits out to avoid parasite interrupts by doing a logical AND |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 677 | operation between the value read from ``MUSB_INTRUSB`` and the bits that |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 678 | are actually implemented in the register. |
| 679 | |
| 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 |
| 682 | the fixes were generic enough to provide a better handling of the issues |
| 683 | for others controller hardware eventually. |
| 684 | |
| 685 | Conclusion |
| 686 | ========== |
| 687 | |
| 688 | Writing a Linux MUSB glue layer should be a more accessible task, as |
| 689 | this documentation tries to show the ins and outs of this exercise. |
| 690 | |
| 691 | The JZ4740 USB device controller being fairly simple, I hope its glue |
| 692 | layer serves as a good example for the curious mind. Used with the |
| 693 | current MUSB glue layers, this documentation should provide enough |
| 694 | guidance to get started; should anything gets out of hand, the linux-usb |
| 695 | mailing list archive is another helpful resource to browse through. |
| 696 | |
| 697 | Acknowledgements |
| 698 | ================ |
| 699 | |
| 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 |
| 702 | me out getting the code in good shape. |
| 703 | |
| 704 | I would also like to thank the Qi-Hardware community at large for its |
| 705 | cheerful guidance and support. |
| 706 | |
| 707 | Resources |
| 708 | ========= |
| 709 | |
| 710 | USB Home Page: http://www.usb.org |
| 711 | |
| 712 | linux-usb Mailing List Archives: http://marc.info/?l=linux-usb |
| 713 | |
| 714 | USB On-the-Go Basics: |
| 715 | http://www.maximintegrated.com/app-notes/index.mvp/id/1822 |
| 716 | |
Mauro Carvalho Chehab | 67cc20e | 2017-04-05 10:23:01 -0300 | [diff] [blame] | 717 | :ref:`Writing USB Device Drivers <writing-usb-driver>` |
Mauro Carvalho Chehab | 4ad4b21 | 2017-04-05 10:22:57 -0300 | [diff] [blame] | 718 | |
| 719 | Texas Instruments USB Configuration Wiki Page: |
| 720 | http://processors.wiki.ti.com/index.php/Usbgeneralpage |
| 721 | |
| 722 | Analog Devices Blackfin MUSB Configuration: |
| 723 | http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb |