1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 2. Linux MUSB Basics</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Writing an MUSB Glue Layer"><link rel="up" href="index.html" title="Writing an MUSB Glue Layer"><link rel="prev" href="introduction.html" title="Chapter 1. Introduction"><link rel="next" href="handling-irqs.html" title="Chapter 3. Handling IRQs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Linux MUSB Basics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="handling-irqs.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="linux-musb-basics"></a>Chapter 2. Linux MUSB Basics</h1></div></div></div><p> 2 To get started on the topic, please read USB On-the-Go Basics (see 3 Resources) which provides an introduction of USB OTG operation at 4 the hardware level. A couple of wiki pages by Texas Instruments 5 and Analog Devices also provide an overview of the Linux kernel 6 MUSB configuration, albeit focused on some specific devices 7 provided by these companies. Finally, getting acquainted with the 8 USB specification at USB home page may come in handy, with 9 practical instance provided through the Writing USB Device Drivers 10 documentation (again, see Resources). 11 </p><p> 12 Linux USB stack is a layered architecture in which the MUSB 13 controller hardware sits at the lowest. The MUSB controller driver 14 abstract the MUSB controller hardware to the Linux USB stack. 15 </p><pre class="programlisting"> 16 ------------------------ 17 | | <------- drivers/usb/gadget 18 | Linux USB Core Stack | <------- drivers/usb/host 19 | | <------- drivers/usb/core 20 ------------------------ 21 ⬍ 22 -------------------------- 23 | | <------ drivers/usb/musb/musb_gadget.c 24 | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c 25 | | <------ drivers/usb/musb/musb_core.c 26 -------------------------- 27 ⬍ 28 --------------------------------- 29 | MUSB Platform Specific Driver | 30 | | <-- drivers/usb/musb/jz4740.c 31 | aka "Glue Layer" | 32 --------------------------------- 33 ⬍ 34 --------------------------------- 35 | MUSB Controller Hardware | 36 --------------------------------- 37 </pre><p> 38 As outlined above, the glue layer is actually the platform 39 specific code sitting in between the controller driver and the 40 controller hardware. 41 </p><p> 42 Just like a Linux USB driver needs to register itself with the 43 Linux USB subsystem, the MUSB glue layer needs first to register 44 itself with the MUSB controller driver. This will allow the 45 controller driver to know about which device the glue layer 46 supports and which functions to call when a supported device is 47 detected or released; remember we are talking about an embedded 48 controller chip here, so no insertion or removal at run-time. 49 </p><p> 50 All of this information is passed to the MUSB controller driver 51 through a platform_driver structure defined in the glue layer as: 52 </p><pre class="programlisting"> 53static struct platform_driver jz4740_driver = { 54 .probe = jz4740_probe, 55 .remove = jz4740_remove, 56 .driver = { 57 .name = "musb-jz4740", 58 }, 59}; 60 </pre><p> 61 The probe and remove function pointers are called when a matching 62 device is detected and, respectively, released. The name string 63 describes the device supported by this glue layer. In the current 64 case it matches a platform_device structure declared in 65 arch/mips/jz4740/platform.c. Note that we are not using device 66 tree bindings here. 67 </p><p> 68 In order to register itself to the controller driver, the glue 69 layer goes through a few steps, basically allocating the 70 controller hardware resources and initialising a couple of 71 circuits. To do so, it needs to keep track of the information used 72 throughout these steps. This is done by defining a private 73 jz4740_glue structure: 74 </p><pre class="programlisting"> 75struct jz4740_glue { 76 struct device *dev; 77 struct platform_device *musb; 78 struct clk *clk; 79}; 80 </pre><p> 81 The dev and musb members are both device structure variables. The 82 first one holds generic information about the device, since it's 83 the basic device structure, and the latter holds information more 84 closely related to the subsystem the device is registered to. The 85 clk variable keeps information related to the device clock 86 operation. 87 </p><p> 88 Let's go through the steps of the probe function that leads the 89 glue layer to register itself to the controller driver. 90 </p><p> 91 N.B.: For the sake of readability each function will be split in 92 logical parts, each part being shown as if it was independent from 93 the others. 94 </p><pre class="programlisting"> 95static int jz4740_probe(struct platform_device *pdev) 96{ 97 struct platform_device *musb; 98 struct jz4740_glue *glue; 99 struct clk *clk; 100 int ret; 101 102 glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL); 103 if (!glue) 104 return -ENOMEM; 105 106 musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO); 107 if (!musb) { 108 dev_err(&pdev->dev, "failed to allocate musb device\n"); 109 return -ENOMEM; 110 } 111 112 clk = devm_clk_get(&pdev->dev, "udc"); 113 if (IS_ERR(clk)) { 114 dev_err(&pdev->dev, "failed to get clock\n"); 115 ret = PTR_ERR(clk); 116 goto err_platform_device_put; 117 } 118 119 ret = clk_prepare_enable(clk); 120 if (ret) { 121 dev_err(&pdev->dev, "failed to enable clock\n"); 122 goto err_platform_device_put; 123 } 124 125 musb->dev.parent = &pdev->dev; 126 127 glue->dev = &pdev->dev; 128 glue->musb = musb; 129 glue->clk = clk; 130 131 return 0; 132 133err_platform_device_put: 134 platform_device_put(musb); 135 return ret; 136} 137 </pre><p> 138 The first few lines of the probe function allocate and assign the 139 glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows 140 the allocation process to sleep and wait for memory, thus being 141 usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line 142 12) allows automatic allocation and management of device IDs in 143 order to avoid device namespace collisions with explicit IDs. With 144 devm_clk_get() (line 18) the glue layer allocates the clock -- the 145 <code class="literal">devm_</code> prefix indicates that clk_get() is 146 managed: it automatically frees the allocated clock resource data 147 when the device is released -- and enable it. 148 </p><p> 149 Then comes the registration steps: 150 </p><pre class="programlisting"> 151static int jz4740_probe(struct platform_device *pdev) 152{ 153 struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data; 154 155 pdata->platform_ops = &jz4740_musb_ops; 156 157 platform_set_drvdata(pdev, glue); 158 159 ret = platform_device_add_resources(musb, pdev->resource, 160 pdev->num_resources); 161 if (ret) { 162 dev_err(&pdev->dev, "failed to add resources\n"); 163 goto err_clk_disable; 164 } 165 166 ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); 167 if (ret) { 168 dev_err(&pdev->dev, "failed to add platform_data\n"); 169 goto err_clk_disable; 170 } 171 172 return 0; 173 174err_clk_disable: 175 clk_disable_unprepare(clk); 176err_platform_device_put: 177 platform_device_put(musb); 178 return ret; 179} 180 </pre><p> 181 The first step is to pass the device data privately held by the 182 glue layer on to the controller driver through 183 platform_set_drvdata() (line 7). Next is passing on the device 184 resources information, also privately held at that point, through 185 platform_device_add_resources() (line 9). 186 </p><p> 187 Finally comes passing on the platform specific data to the 188 controller driver (line 16). Platform data will be discussed in 189 <a class="link" href="device-platform-data.html" title="Chapter 4. Device Platform Data">Chapter 4</a>, but here 190 we are looking at the platform_ops function pointer (line 5) in 191 musb_hdrc_platform_data structure (line 3). This function 192 pointer allows the MUSB controller driver to know which function 193 to call for device operation: 194 </p><pre class="programlisting"> 195static const struct musb_platform_ops jz4740_musb_ops = { 196 .init = jz4740_musb_init, 197 .exit = jz4740_musb_exit, 198}; 199 </pre><p> 200 Here we have the minimal case where only init and exit functions 201 are called by the controller driver when needed. Fact is the 202 JZ4740 MUSB controller is a basic controller, lacking some 203 features found in other controllers, otherwise we may also have 204 pointers to a few other functions like a power management function 205 or a function to switch between OTG and non-OTG modes, for 206 instance. 207 </p><p> 208 At that point of the registration process, the controller driver 209 actually calls the init function: 210 </p><pre class="programlisting"> 211static int jz4740_musb_init(struct musb *musb) 212{ 213 musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); 214 if (!musb->xceiv) { 215 pr_err("HS UDC: no transceiver configured\n"); 216 return -ENODEV; 217 } 218 219 /* Silicon does not implement ConfigData register. 220 * Set dyn_fifo to avoid reading EP config from hardware. 221 */ 222 musb->dyn_fifo = true; 223 224 musb->isr = jz4740_musb_interrupt; 225 226 return 0; 227} 228 </pre><p> 229 The goal of jz4740_musb_init() is to get hold of the transceiver 230 driver data of the MUSB controller hardware and pass it on to the 231 MUSB controller driver, as usual. The transceiver is the circuitry 232 inside the controller hardware responsible for sending/receiving 233 the USB data. Since it is an implementation of the physical layer 234 of the OSI model, the transceiver is also referred to as PHY. 235 </p><p> 236 Getting hold of the MUSB PHY driver data is done with 237 usb_get_phy() which returns a pointer to the structure 238 containing the driver instance data. The next couple of 239 instructions (line 12 and 14) are used as a quirk and to setup 240 IRQ handling respectively. Quirks and IRQ handling will be 241 discussed later in <a class="link" href="device-quirks.html" title="Chapter 5. Device Quirks">Chapter 242 5</a> and <a class="link" href="handling-irqs.html" title="Chapter 3. Handling IRQs">Chapter 3</a>. 243 </p><pre class="programlisting"> 244static int jz4740_musb_exit(struct musb *musb) 245{ 246 usb_put_phy(musb->xceiv); 247 248 return 0; 249} 250 </pre><p> 251 Acting as the counterpart of init, the exit function releases the 252 MUSB PHY driver when the controller hardware itself is about to be 253 released. 254 </p><p> 255 Again, note that init and exit are fairly simple in this case due 256 to the basic set of features of the JZ4740 controller hardware. 257 When writing an musb glue layer for a more complex controller 258 hardware, you might need to take care of more processing in those 259 two functions. 260 </p><p> 261 Returning from the init function, the MUSB controller driver jumps 262 back into the probe function: 263 </p><pre class="programlisting"> 264static int jz4740_probe(struct platform_device *pdev) 265{ 266 ret = platform_device_add(musb); 267 if (ret) { 268 dev_err(&pdev->dev, "failed to register musb device\n"); 269 goto err_clk_disable; 270 } 271 272 return 0; 273 274err_clk_disable: 275 clk_disable_unprepare(clk); 276err_platform_device_put: 277 platform_device_put(musb); 278 return ret; 279} 280 </pre><p> 281 This is the last part of the device registration process where the 282 glue layer adds the controller hardware device to Linux kernel 283 device hierarchy: at this stage, all known information about the 284 device is passed on to the Linux USB core stack. 285 </p><pre class="programlisting"> 286static int jz4740_remove(struct platform_device *pdev) 287{ 288 struct jz4740_glue *glue = platform_get_drvdata(pdev); 289 290 platform_device_unregister(glue->musb); 291 clk_disable_unprepare(glue->clk); 292 293 return 0; 294} 295 </pre><p> 296 Acting as the counterpart of probe, the remove function unregister 297 the MUSB controller hardware (line 5) and disable the clock (line 298 6), allowing it to be gated. 299 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="handling-irqs.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Handling IRQs</td></tr></table></div></body></html> 300