On 04/05/2014 11:42 AM, Apelete Seketeli wrote: > Document the process of writing an musb glue layer by taking the > Ingenic JZ4740 glue layer as an example, as it seems more simple than > most glue layers due to the basic feature set of the JZ4740 USB device > controller. > > Signed-off-by: Apelete Seketeli <apelete@xxxxxxxxxxxx> Hi, You should be cc-ing the musb maintainer and the USB mailing list (so now done). Felipe should probably be the person to merge this unless he wants me to do it... Thanks. > --- > Documentation/DocBook/Makefile | 3 +- > Documentation/DocBook/writing_musb_glue_layer.tmpl | 873 ++++++++++++++++++++ > 2 files changed, 875 insertions(+), 1 deletion(-) > create mode 100644 Documentation/DocBook/writing_musb_glue_layer.tmpl > > diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile > index 8d96ebf..e274743 100644 > --- a/Documentation/DocBook/Makefile > +++ b/Documentation/DocBook/Makefile > @@ -14,7 +14,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \ > genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ > 80211.xml debugobjects.xml sh.xml regulator.xml \ > alsa-driver-api.xml writing-an-alsa-driver.xml \ > - tracepoint.xml drm.xml media_api.xml w1.xml > + tracepoint.xml drm.xml media_api.xml w1.xml \ > + writing_musb_glue_layer.xml > > include $(srctree)/Documentation/DocBook/media/Makefile > > diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl > new file mode 100644 > index 0000000..837eca7 > --- /dev/null > +++ b/Documentation/DocBook/writing_musb_glue_layer.tmpl > @@ -0,0 +1,873 @@ > +<?xml version="1.0" encoding="UTF-8"?> > +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" > + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []> > + > +<book id="Writing-MUSB-Glue-Layer"> > + <bookinfo> > + <title>Writing an MUSB Glue Layer</title> > + > + <authorgroup> > + <author> > + <firstname>Apelete</firstname> > + <surname>Seketeli</surname> > + <affiliation> > + <address> > + <email>apelete at seketeli.net</email> > + </address> > + </affiliation> > + </author> > + </authorgroup> > + > + <copyright> > + <year>2014</year> > + <holder>Apelete Seketeli</holder> > + </copyright> > + > + <legalnotice> > + <para> > + This documentation is free software; you can redistribute it > + and/or modify it under the terms of the GNU General Public > + License as published by the Free Software Foundation; either > + version 2 of the License, or (at your option) any later version. > + </para> > + > + <para> > + This documentation is distributed in the hope that it will be > + useful, but WITHOUT ANY WARRANTY; without even the implied > + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. > + See the GNU General Public License for more details. > + </para> > + > + <para> > + You should have received a copy of the GNU General Public License > + along with this documentation; if not, write to the Free Software > + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA > + 02111-1307 USA > + </para> > + > + <para> > + For more details see the file COPYING in the Linux kernel source > + tree. > + </para> > + </legalnotice> > + </bookinfo> > + > +<toc></toc> > + > + <chapter id="introduction"> > + <title>Introduction</title> > + <para> > + The Linux MUSB subsystem is part of the larger Linux USB > + subsystem. It provides support for embedded USB Device Controllers > + (UDC) that do not use Universal Host Controller Interface (UHCI) > + or Open Host Controller Interface (OHCI). > + </para> > + <para> > + Instead, these embedded UDC rely on the USB On-the-Go (OTG) > + specification which they implement at least partially. The silicon > + reference design used in most cases is the Multipoint USB > + Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor > + Graphics Inventra™ design. > + </para> > + <para> > + As a self-taught exercise I have written an MUSB glue layer for > + the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers > + in the kernel source tree. This layer can be found at > + drivers/usb/musb/jz4740.c. In this documentation I will walk > + through the basics of the jz4740.c glue layer, explaining the > + different pieces and what needs to be done in order to write your > + own device glue layer. > + </para> > + </chapter> > + > + <chapter id="linux-musb-basics"> > + <title>Linux MUSB Basics</title> > + <para> > + To get started on the topic, please read USB On-the-Go Basics (see > + Resources) which provides an introduction of USB OTG operation at > + the hardware level. A couple of wiki pages by Texas Instruments > + and Analog Devices also provide an overview of the Linux kernel > + MUSB configuration, albeit focused on some specific devices > + provided by these companies. Finally, getting acquainted with the > + USB specification at USB home page may come in handy, with > + practical instance provided through the Writing USB Device Drivers > + documentation (again, see Resources). > + </para> > + <para> > + Linux USB stack is a layered architecture in which the MUSB > + controller hardware sits at the lowest. The MUSB controller driver > + abstract the MUSB controller hardware to the Linux USB stack. > + </para> > + <programlisting> > + ------------------------ > + | | <------- drivers/usb/gadget > + | Linux USB Core Stack | <------- drivers/usb/host > + | | <------- drivers/usb/core > + ------------------------ > + ⬍ > + -------------------------- > + | | <------ drivers/usb/musb/musb_gadget.c > + | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c > + | | <------ drivers/usb/musb/musb_core.c > + -------------------------- > + ⬍ > + --------------------------------- > + | MUSB Platform Specific Driver | > + | | <-- drivers/usb/musb/jz4740.c > + | aka "Glue Layer" | > + --------------------------------- > + ⬍ > + --------------------------------- > + | MUSB Controller Hardware | > + --------------------------------- > + </programlisting> > + <para> > + As outlined above, the glue layer is actually the platform > + specific code sitting in between the controller driver and the > + controller hardware. > + </para> > + <para> > + Just like a Linux USB driver needs to register itself with the > + Linux USB subsystem, the MUSB glue layer needs first to register > + itself with the MUSB controller driver. This will allow the > + controller driver to know about which device the glue layer > + supports and which functions to call when a supported device is > + detected or released; remember we are talking about an embedded > + controller chip here, so no insertion or removal at run-time. > + </para> > + <para> > + All of this information is passed to the MUSB controller driver > + through a platform_driver structure defined in the glue layer as: > + </para> > + <programlisting linenumbering="numbered"> > +static struct platform_driver jz4740_driver = { > + .probe = jz4740_probe, > + .remove = jz4740_remove, > + .driver = { > + .name = "musb-jz4740", > + }, > +}; > + </programlisting> > + <para> > + The probe and remove function pointers are called when a matching > + device is detected and, respectively, released. The name string > + describes the device supported by this glue layer. In the current > + case it matches a platform_device structure declared in > + arch/mips/jz4740/platform.c. Note that we are not using device > + tree bindings here. > + </para> > + <para> > + In order to register itself to the controller driver, the glue > + layer goes through a few steps, basically allocating the > + controller hardware resources and initialising a couple of > + circuits. To do so, it needs to keep track of the information used > + throughout these steps. This is done by defining a private > + jz4740_glue structure: > + </para> > + <programlisting linenumbering="numbered"> > +struct jz4740_glue { > + struct device *dev; > + struct platform_device *musb; > + struct clk *clk; > +}; > + </programlisting> > + <para> > + The dev and musb members are both device structure variables. The > + first one holds generic information about the device, since it's > + the basic device structure, and the latter holds information more > + closely related to the subsystem the device is registered to. The > + clk variable keeps information related to the device clock > + operation. > + </para> > + <para> > + Let's go through the steps of the probe function that leads the > + glue layer to register itself to the controller driver. > + </para> > + <para> > + N.B.: For the sake of readability each function will be split in > + logical parts, each part being shown as if it was independent from > + the others. > + </para> > + <programlisting linenumbering="numbered"> > +static int jz4740_probe(struct platform_device *pdev) > +{ > + struct platform_device *musb; > + struct jz4740_glue *glue; > + struct clk *clk; > + int ret; > + > + glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL); > + if (!glue) > + return -ENOMEM; > + > + musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO); > + if (!musb) { > + dev_err(&pdev->dev, "failed to allocate musb device\n"); > + return -ENOMEM; > + } > + > + clk = devm_clk_get(&pdev->dev, "udc"); > + if (IS_ERR(clk)) { > + dev_err(&pdev->dev, "failed to get clock\n"); > + ret = PTR_ERR(clk); > + goto err_platform_device_put; > + } > + > + ret = clk_prepare_enable(clk); > + if (ret) { > + dev_err(&pdev->dev, "failed to enable clock\n"); > + goto err_platform_device_put; > + } > + > + musb->dev.parent = &pdev->dev; > + > + glue->dev = &pdev->dev; > + glue->musb = musb; > + glue->clk = clk; > + > + return 0; > + > +err_platform_device_put: > + platform_device_put(musb); > + return ret; > +} > + </programlisting> > + <para> > + The first few lines of the probe function allocate and assign the > + glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows > + the allocation process to sleep and wait for memory, thus being > + usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line > + 12) allows automatic allocation and management of device IDs in > + order to avoid device namespace collisions with explicit IDs. With > + devm_clk_get() (line 18) the glue layer allocates the clock -- the > + <literal>devm_</literal> prefix indicates that clk_get() is > + managed: it automatically frees the allocated clock resource data > + when the device is released -- and enable it. > + </para> > + <para> > + Then comes the registration steps: > + </para> > + <programlisting linenumbering="numbered"> > +static int jz4740_probe(struct platform_device *pdev) > +{ > + struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data; > + > + pdata->platform_ops = &jz4740_musb_ops; > + > + platform_set_drvdata(pdev, glue); > + > + ret = platform_device_add_resources(musb, pdev->resource, > + pdev->num_resources); > + if (ret) { > + dev_err(&pdev->dev, "failed to add resources\n"); > + goto err_clk_disable; > + } > + > + ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); > + if (ret) { > + dev_err(&pdev->dev, "failed to add platform_data\n"); > + goto err_clk_disable; > + } > + > + return 0; > + > +err_clk_disable: > + clk_disable_unprepare(clk); > +err_platform_device_put: > + platform_device_put(musb); > + return ret; > +} > + </programlisting> > + <para> > + The first step is to pass the device data privately held by the > + glue layer on to the controller driver through > + platform_set_drvdata() (line 7). Next is passing on the device > + resources information, also privately held at that point, through > + platform_device_add_resources() (line 9). > + </para> > + <para> > + Finally comes passing on the platform specific data to the > + controller driver (line 16). Platform data will be discussed in > + <link linkend="device-platform-data">Chapter 4</link>, but here > + we are looking at the platform_ops function pointer (line 5) in > + musb_hdrc_platform_data structure (line 3). This function > + pointer allows the MUSB controller driver to know which function > + to call for device operation: > + </para> > + <programlisting linenumbering="numbered"> > +static const struct musb_platform_ops jz4740_musb_ops = { > + .init = jz4740_musb_init, > + .exit = jz4740_musb_exit, > +}; > + </programlisting> > + <para> > + Here we have the minimal case where only init and exit functions > + are called by the controller driver when needed. Fact is the > + JZ4740 MUSB controller is a basic controller, lacking some > + features found in other controllers, otherwise we may also have > + pointers to a few other functions like a power management function > + or a function to switch between OTG and non-OTG modes, for > + instance. > + </para> > + <para> > + At that point of the registration process, the controller driver > + actually calls the init function: > + </para> > + <programlisting linenumbering="numbered"> > +static int jz4740_musb_init(struct musb *musb) > +{ > + musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); > + if (!musb->xceiv) { > + pr_err("HS UDC: no transceiver configured\n"); > + return -ENODEV; > + } > + > + /* Silicon does not implement ConfigData register. > + * Set dyn_fifo to avoid reading EP config from hardware. > + */ > + musb->dyn_fifo = true; > + > + musb->isr = jz4740_musb_interrupt; > + > + return 0; > +} > + </programlisting> > + <para> > + The goal of jz4740_musb_init() is to get hold of the transceiver > + driver data of the MUSB controller hardware and pass it on to the > + MUSB controller driver, as usual. The transceiver is the circuitry > + inside the controller hardware responsible for sending/receiving > + the USB data. Since it is an implementation of the physical layer > + of the OSI model, the transceiver is also referred to as PHY. > + </para> > + <para> > + Getting hold of the MUSB PHY driver data is done with > + usb_get_phy() which returns a pointer to the structure > + containing the driver instance data. The next couple of > + instructions (line 12 and 14) are used as a quirk and to setup > + IRQ handling respectively. Quirks and IRQ handling will be > + discussed later in <link linkend="device-quirks">Chapter > + 5</link> and <link linkend="handling-irqs">Chapter 3</link>. > + </para> > + <programlisting linenumbering="numbered"> > +static int jz4740_musb_exit(struct musb *musb) > +{ > + usb_put_phy(musb->xceiv); > + > + return 0; > +} > + </programlisting> > + <para> > + Acting as the counterpart of init, the exit function releases the > + MUSB PHY driver when the controller hardware itself is about to be > + released. > + </para> > + <para> > + Again, note that init and exit are fairly simple in this case due > + to the basic set of features of the JZ4740 controller hardware. > + When writing an musb glue layer for a more complex controller > + hardware, you might need to take care of more processing in those > + two functions. > + </para> > + <para> > + Returning from the init function, the MUSB controller driver jumps > + back into the probe function: > + </para> > + <programlisting linenumbering="numbered"> > +static int jz4740_probe(struct platform_device *pdev) > +{ > + ret = platform_device_add(musb); > + if (ret) { > + dev_err(&pdev->dev, "failed to register musb device\n"); > + goto err_clk_disable; > + } > + > + return 0; > + > +err_clk_disable: > + clk_disable_unprepare(clk); > +err_platform_device_put: > + platform_device_put(musb); > + return ret; > +} > + </programlisting> > + <para> > + This is the last part of the device registration process where the > + glue layer adds the controller hardware device to Linux kernel > + device hierarchy: at this stage, all known information about the > + device is passed on to the Linux USB core stack. > + </para> > + <programlisting linenumbering="numbered"> > +static int jz4740_remove(struct platform_device *pdev) > +{ > + struct jz4740_glue *glue = platform_get_drvdata(pdev); > + > + platform_device_unregister(glue->musb); > + clk_disable_unprepare(glue->clk); > + > + return 0; > +} > + </programlisting> > + <para> > + Acting as the counterpart of probe, the remove function unregister > + the MUSB controller hardware (line 5) and disable the clock (line > + 6), allowing it to be gated. > + </para> > + </chapter> > + > + <chapter id="handling-irqs"> > + <title>Handling IRQs</title> > + <para> > + Additionally to the MUSB controller hardware basic setup and > + registration, the glue layer is also responsible for handling the > + IRQs: > + </para> > + <programlisting linenumbering="numbered"> > +static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) > +{ > + unsigned long flags; > + irqreturn_t retval = IRQ_NONE; > + struct musb *musb = __hci; > + > + spin_lock_irqsave(&musb->lock, flags); > + > + musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); > + musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); > + musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); > + > + /* > + * The controller is gadget only, the state of the host mode IRQ bits is > + * undefined. Mask them to make sure that the musb driver core will > + * never see them set > + */ > + musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | > + MUSB_INTR_RESET | MUSB_INTR_SOF; > + > + if (musb->int_usb || musb->int_tx || musb->int_rx) > + retval = musb_interrupt(musb); > + > + spin_unlock_irqrestore(&musb->lock, flags); > + > + return retval; > +} > + </programlisting> > + <para> > + Here the glue layer mostly has to read the relevant hardware > + registers and pass their values on to the controller driver which > + will handle the actual event that triggered the IRQ. > + </para> > + <para> > + The interrupt handler critical section is protected by the > + spin_lock_irqsave() and counterpart spin_unlock_irqrestore() > + functions (line 7 and 24 respectively), which prevent the > + interrupt handler code to be run by two different threads at the > + same time. > + </para> > + <para> > + Then the relevant interrupt registers are read (line 9 to 11): > + </para> > + <itemizedlist> > + <listitem> > + <para> > + MUSB_INTRUSB: indicates which USB interrupts are currently > + active, > + </para> > + </listitem> > + <listitem> > + <para> > + MUSB_INTRTX: indicates which of the interrupts for TX > + endpoints are currently active, > + </para> > + </listitem> > + <listitem> > + <para> > + MUSB_INTRRX: indicates which of the interrupts for TX > + endpoints are currently active. > + </para> > + </listitem> > + </itemizedlist> > + <para> > + Note that musb_readb() is used to read 8-bit registers at most, > + while musb_readw() allows us to read at most 16-bit registers. > + There are other functions that can be used depending on the size > + of your device registers. See musb_io.h for more information. > + </para> > + <para> > + Instruction on line 18 is another quirk specific to the JZ4740 > + USB device controller, which will be discussed later in <link > + linkend="device-quirks">Chapter 5</link>. > + </para> > + <para> > + The glue layer still needs to register the IRQ handler though. > + Remember the instruction on line 14 of the init function: > + </para> > + <programlisting linenumbering="numbered"> > +static int jz4740_musb_init(struct musb *musb) > +{ > + musb->isr = jz4740_musb_interrupt; > + > + return 0; > +} > + </programlisting> > + <para> > + This instruction sets a pointer to the glue layer IRQ handler > + function, in order for the controller hardware to call the handler > + back when an IRQ comes from the controller hardware. The interrupt > + handler is now implemented and registered. > + </para> > + </chapter> > + > + <chapter id="device-platform-data"> > + <title>Device Platform Data</title> > + <para> > + In order to write an MUSB glue layer, you need to have some data > + describing the hardware capabilities of your controller hardware, > + which is called the platform data. > + </para> > + <para> > + Platform data is specific to your hardware, though it may cover a > + broad range of devices, and is generally found somewhere in the > + arch/ directory, depending on your device architecture. > + </para> > + <para> > + For instance, platform data for the JZ4740 SoC is found in > + arch/mips/jz4740/platform.c. In the platform.c file each device of > + the JZ4740 SoC is described through a set of structures. > + </para> > + <para> > + Here is the part of arch/mips/jz4740/platform.c that covers the > + USB Device Controller (UDC): > + </para> > + <programlisting linenumbering="numbered"> > +/* USB Device Controller */ > +struct platform_device jz4740_udc_xceiv_device = { > + .name = "usb_phy_gen_xceiv", > + .id = 0, > +}; > + > +static struct resource jz4740_udc_resources[] = { > + [0] = { > + .start = JZ4740_UDC_BASE_ADDR, > + .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1, > + .flags = IORESOURCE_MEM, > + }, > + [1] = { > + .start = JZ4740_IRQ_UDC, > + .end = JZ4740_IRQ_UDC, > + .flags = IORESOURCE_IRQ, > + .name = "mc", > + }, > +}; > + > +struct platform_device jz4740_udc_device = { > + .name = "musb-jz4740", > + .id = -1, > + .dev = { > + .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask, > + .coherent_dma_mask = DMA_BIT_MASK(32), > + }, > + .num_resources = ARRAY_SIZE(jz4740_udc_resources), > + .resource = jz4740_udc_resources, > +}; > + </programlisting> > + <para> > + The jz4740_udc_xceiv_device platform device structure (line 2) > + describes the UDC transceiver with a name and id number. > + </para> > + <para> > + At the time of this writing, note that > + "usb_phy_gen_xceiv" is the specific name to be used for > + all transceivers that are either built-in with reference USB IP or > + autonomous and doesn't require any PHY programming. You will need > + to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make > + use of the corresponding transceiver driver. The id field could be > + set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to > + PLATFORM_DEVID_AUTO) or start with 0 for the first device of this > + kind if we want a specific id number. > + </para> > + <para> > + The jz4740_udc_resources resource structure (line 7) defines the > + UDC registers base addresses. > + </para> > + <para> > + The first array (line 9 to 11) defines the UDC registers base > + memory addresses: start points to the first register memory > + address, end points to the last register memory address and the > + flags member defines the type of resource we are dealing with. So > + IORESOURCE_MEM is used to define the registers memory addresses. > + The second array (line 14 to 17) defines the UDC IRQ registers > + addresses. Since there is only one IRQ register available for the > + JZ4740 UDC, start and end point at the same address. The > + IORESOURCE_IRQ flag tells that we are dealing with IRQ resources, > + and the name "mc" is in fact hard-coded in the MUSB core > + in order for the controller driver to retrieve this IRQ resource > + by querying it by its name. > + </para> > + <para> > + Finally, the jz4740_udc_device platform device structure (line 21) > + describes the UDC itself. > + </para> > + <para> > + The "musb-jz4740" name (line 22) defines the MUSB > + driver that is used for this device; remember this is in fact > + the name that we used in the jz4740_driver platform driver > + structure in <link linkend="linux-musb-basics">Chapter > + 2</link>. The id field (line 23) is set to -1 (equivalent to > + PLATFORM_DEVID_NONE) since we do not need an id for the device: > + the MUSB controller driver was already set to allocate an > + automatic id in <link linkend="linux-musb-basics">Chapter > + 2</link>. In the dev field we care for DMA related information > + here. The dma_mask field (line 25) defines the width of the DMA > + mask that is going to be used, and coherent_dma_mask (line 26) > + has the same purpose but for the alloc_coherent DMA mappings: in > + both cases we are using a 32 bits mask. Then the resource field > + (line 29) is simply a pointer to the resource structure defined > + before, while the num_resources field (line 28) keeps track of > + the number of arrays defined in the resource structure (in this > + case there were two resource arrays defined before). > + </para> > + <para> > + With this quick overview of the UDC platform data at the arch/ > + level now done, let's get back to the MUSB glue layer specific > + platform data in drivers/usb/musb/jz4740.c: > + </para> > + <programlisting linenumbering="numbered"> > +static struct musb_hdrc_config jz4740_musb_config = { > + /* Silicon does not implement USB OTG. */ > + .multipoint = 0, > + /* Max EPs scanned, driver will decide which EP can be used. */ > + .num_eps = 4, > + /* RAMbits needed to configure EPs from table */ > + .ram_bits = 9, > + .fifo_cfg = jz4740_musb_fifo_cfg, > + .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg), > +}; > + > +static struct musb_hdrc_platform_data jz4740_musb_platform_data = { > + .mode = MUSB_PERIPHERAL, > + .config = &jz4740_musb_config, > +}; > + </programlisting> > + <para> > + First the glue layer configures some aspects of the controller > + driver operation related to the controller hardware specifics. > + This is done through the jz4740_musb_config musb_hdrc_config > + structure. > + </para> > + <para> > + Defining the OTG capability of the controller hardware, the > + multipoint member (line 3) is set to 0 (equivalent to false) > + since the JZ4740 UDC is not OTG compatible. Then num_eps (line > + 5) defines the number of USB endpoints of the controller > + hardware, including endpoint 0: here we have 3 endpoints + > + endpoint 0. Next is ram_bits (line 7) which is the width of the > + RAM address bus for the MUSB controller hardware. This > + information is needed when the controller driver cannot > + automatically configure endpoints by reading the relevant > + controller hardware registers. This issue will be discussed when > + we get to device quirks in <link linkend="device-quirks">Chapter > + 5</link>. Last two fields (line 8 and 9) are also about device > + quirks: fifo_cfg points to the USB endpoints configuration table > + and fifo_cfg_size keeps track of the size of the number of > + entries in that configuration table. More on that later in <link > + linkend="device-quirks">Chapter 5</link>. > + </para> > + <para> > + Then this configuration is embedded inside > + jz4740_musb_platform_data musb_hdrc_platform_data structure (line > + 11): config is a pointer to the configuration structure itself, > + and mode tells the controller driver if the controller hardware > + may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG > + which is a dual mode. > + </para> > + <para> > + Remember that jz4740_musb_platform_data is then used to convey > + platform data information as we have seen in the probe function > + in <link linkend="linux-musb-basics">Chapter 2</link> > + </para> > + </chapter> > + > + <chapter id="device-quirks"> > + <title>Device Quirks</title> > + <para> > + Completing the platform data specific to your device, you may also > + need to write some code in the glue layer to work around some > + device specific limitations. These quirks may be due to some > + hardware bugs, or simply be the result of an incomplete > + implementation of the USB On-the-Go specification. > + </para> > + <para> > + The JZ4740 UDC exhibits such quirks, some of which we will discuss > + here for the sake of insight even though these might not be found > + in the controller hardware you are working on. > + </para> > + <para> > + Let's get back to the init function first: > + </para> > + <programlisting linenumbering="numbered"> > +static int jz4740_musb_init(struct musb *musb) > +{ > + musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); > + if (!musb->xceiv) { > + pr_err("HS UDC: no transceiver configured\n"); > + return -ENODEV; > + } > + > + /* Silicon does not implement ConfigData register. > + * Set dyn_fifo to avoid reading EP config from hardware. > + */ > + musb->dyn_fifo = true; > + > + musb->isr = jz4740_musb_interrupt; > + > + return 0; > +} > + </programlisting> > + <para> > + Instruction on line 12 helps the MUSB controller driver to work > + around the fact that the controller hardware is missing registers > + that are used for USB endpoints configuration. > + </para> > + <para> > + Without these registers, the controller driver is unable to read > + the endpoints configuration from the hardware, so we use line 12 > + instruction to bypass reading the configuration from silicon, and > + rely on a hard-coded table that describes the endpoints > + configuration instead: > + </para> > + <programlisting linenumbering="numbered"> > +static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = { > +{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, }, > +{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, }, > +{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, }, > +}; > + </programlisting> > + <para> > + Looking at the configuration table above, we see that each > + endpoints is described by three fields: hw_ep_num is the endpoint > + number, style is its direction (either FIFO_TX for the controller > + driver to send packets in the controller hardware, or FIFO_RX to > + receive packets from hardware), and maxpacket defines the maximum > + size of each data packet that can be transmitted over that > + endpoint. Reading from the table, the controller driver knows that > + endpoint 1 can be used to send and receive USB data packets of 512 > + bytes at once (this is in fact a bulk in/out endpoint), and > + endpoint 2 can be used to send data packets of 64 bytes at once > + (this is in fact an interrupt endpoint). > + </para> > + <para> > + Note that there is no information about endpoint 0 here: that one > + is implemented by default in every silicon design, with a > + predefined configuration according to the USB specification. For > + more examples of endpoint configuration tables, see musb_core.c. > + </para> > + <para> > + Let's now get back to the interrupt handler function: > + </para> > + <programlisting linenumbering="numbered"> > +static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) > +{ > + unsigned long flags; > + irqreturn_t retval = IRQ_NONE; > + struct musb *musb = __hci; > + > + spin_lock_irqsave(&musb->lock, flags); > + > + musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); > + musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); > + musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); > + > + /* > + * The controller is gadget only, the state of the host mode IRQ bits is > + * undefined. Mask them to make sure that the musb driver core will > + * never see them set > + */ > + musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | > + MUSB_INTR_RESET | MUSB_INTR_SOF; > + > + if (musb->int_usb || musb->int_tx || musb->int_rx) > + retval = musb_interrupt(musb); > + > + spin_unlock_irqrestore(&musb->lock, flags); > + > + return retval; > +} > + </programlisting> > + <para> > + Instruction on line 18 above is a way for the controller driver to > + work around the fact that some interrupt bits used for USB host > + mode operation are missing in the MUSB_INTRUSB register, thus left > + in an undefined hardware state, since this MUSB controller > + hardware is used in peripheral mode only. As a consequence, the > + glue layer masks these missing bits out to avoid parasite > + interrupts by doing a logical AND operation between the value read > + from MUSB_INTRUSB and the bits that are actually implemented in > + the register. > + </para> > + <para> > + These are only a couple of the quirks found in the JZ4740 USB > + device controller. Some others were directly addressed in the MUSB > + core since the fixes were generic enough to provide a better > + handling of the issues for others controller hardware eventually. > + </para> > + </chapter> > + > + <chapter id="conclusion"> > + <title>Conclusion</title> > + <para> > + Writing a Linux MUSB glue layer should be a more accessible task, > + as this documentation tries to show the ins and outs of this > + exercise. > + </para> > + <para> > + The JZ4740 USB device controller being fairly simple, I hope its > + glue layer serves as a good example for the curious mind. Used > + with the current MUSB glue layers, this documentation should > + provide enough guidance to get started; should anything gets out > + of hand, the linux-usb mailing list archive is another helpful > + resource to browse through. > + </para> > + </chapter> > + > + <chapter id="acknowledgements"> > + <title>Acknowledgements</title> > + <para> > + Many thanks to Lars-Peter Clausen and Maarten ter Huurne for > + answering my questions while I was writing the JZ4740 glue layer > + and for helping me out getting the code in good shape. > + </para> > + <para> > + I would also like to thank the Qi-Hardware community at large for > + its cheerful guidance and support. > + </para> > + </chapter> > + > + <chapter id="resources"> > + <title>Resources</title> > + <para> > + USB Home Page: > + <ulink url="http://www.usb.org";>http://www.usb.org</ulink> > + </para> > + <para> > + linux-usb Mailing List Archives: > + <ulink url="http://marc.info/?l=linux-usb";>http://marc.info/?l=linux-usb</ulink> > + </para> > + <para> > + USB On-the-Go Basics: > + <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822";>http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink> > + </para> > + <para> > + Writing USB Device Drivers: > + <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html";>https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink> > + </para> > + <para> > + Texas Instruments USB Configuration Wiki Page: > + <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage";>http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink> > + </para> > + <para> > + Analog Devices Blackfin MUSB Configuration: > + <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb";>http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink> > + </para> > + </chapter> > + > +</book> > -- ~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
