We're hiring!
*

Using regmaps to make Linux drivers more generic

Adrian Ratiu avatar

Adrian Ratiu
May 27, 2020

Share this post:

Reading time:

Very few developers enjoy maintaining drivers out of the Linux kernel tree due to a number of reasons like the lack of stable driver APIs, or the possibility that a driver duplicates pre-existing kernel functionalities like, for example, an entire networking stack from scratch.

Factoring out common driver infrastructures into generic, reusable modules is much more desirable to deduplicate code, fix common bugs and have unified interfaces. To no surprise, this has been, and continues to be, a constant Linux kernel development effort. In this article, we will examine a specific instance of this process, namely the effort to make the Synopsys MIPI DSI host controller driver more generic so it can support more device revisions and SoC platforms.

Brief introduction to regmaps

Regmaps are the result of a common infrastructure creation process such as described above. They were added to the kernel starting with v3.1, initially for abstracting common driver register-access logic for non-memory mapped busses, like I2C or SPI, and over time it got extended to also support Memory-Mapped IO starting with v3.5, which we're interested in.

The definition of a regmap starts with a regmap config (this is real code from our example linked below). The header structure documentation contains a lot more useful fields, but we just need the following for a basic definition: register address as value sizes, stride (i.e. total length between start of registers) in bytes and a name.

        #include <linux/regmap.h>
        static const struct regmap_config dw_mipi_dsi_regmap_cfg = {
                .reg_bits = 32,
                .val_bits = 32,
                .reg_stride = 4,
                .name = "dw-mipi-dsi",
        };

This allows us to create a regmap structure from a memory-mapped region like the following. A full real-driver example can be found in the last section of this article.

        base_addr = devm_platform_ioremap_resource(pdev, 0);
        regmap = devm_regmap_init_mmio(dev, base_addr , &dw_mipi_dsi_regmap_cfg);

Much more can be done with just the regmap, like configuring it to enforce maximum address offsets to avoid out-of-bounds reads/writes, or attaching a clock which can be auto-enabled when the regmap is accessed, but for our purposes this is enough. The underlying mechanisms used by regmap to access the memory-region via its regmap_read/write functions are the standard readl/writel functions, so it can be viewed as an abstraction on top of memory-mapped IO.

        #define VERSION_REG_OFFSET 0x00
        u32 hw_version;
        regmap_read(regmap, VERSION_REG_OFFSET, &hw_version);

The regmap is owned by the device which owns the memory region it gets attached to, so there is no need to keep track and manually free it, it gets automatically discarded by the device management code.

Brief introduction to regmap fields

More interesting for us is yet-another abstraction on top of regmaps: regmap fields. While a regmap defines a register set, regmap fields define specific bit-fields inside those registers, at configurable offsets. This will be very useful later on. Fields are configured by defining struct reg_fields, and the kernel provides a convenient macro REG_FIELD(_reg, _lsb, _msb) which we use.

For example, the i.MX 6 Dual/Quad Applications Processor reference manual rev. 2, 06/2014 defines the following register:

The above register fields can be defined like this (again, real code from our example below):

        #include <linux/regmap.h>
        #define DSI_TMR_LINE_CFG 0x28

        struct dw_mipi_dsi_variant {
        	struct reg_field	cfg_vid_hsa_time;
		struct reg_field	cfg_vid_hbp_time;
		struct reg_field	cfg_vid_hline_time;
        };

        struct dw_mipi_dsi_variant dw_mipi_dsi_v101_layout = {
   	   	.cfg_vid_hsa_time =		REG_FIELD(DSI_TMR_LINE_CFG, 0, 8),
		.cfg_vid_hbp_time =		REG_FIELD(DSI_TMR_LINE_CFG, 9, 17),
		.cfg_vid_hline_time =		REG_FIELD(DSI_TMR_LINE_CFG, 18, 31),
        };

Next we just need to associate each struct reg_field configuration with a specific regmapped memory region, thus creating struct regmap_field which can be read/written or polled.

        struct regmap_field *field_vid_hsa_time = devm_regmap_field_alloc(dev,
                                                                          regmap,
                                                                          &dw_mipi_dsi_v101_layout.cfg_vid_hsa_time);
        regmap_field_write(field_vid_hsa_time, 1000);

One advantage of using register fields like this is that the code is cleaner because field ranges are explicitly defined and error-prone preprocessor #define bit manipulation hacks are avoided, thus the mental effort required to keep track of the fields is significantly lowered. Another bigger advantage is that multiple field layouts can be specified in parallel so a driver, for example, can chose the correct register field locations based on the detected HW revision. We'll see a specific example of this next.

MIPI Display Serial Interface on Linux

In their quest to optimize the usage of kilometers of copper wire, to make devices smaller, more powerful or cheaper, hardware vendors came up with lots of cool technologies and revisions, such as is MIPI DSI.

It is a fully serial display interface, easy to implement in hardware because it requires just one high speed clock lane (typically set to 27 Mhz on i.MX 6) and one data lane (in practice up to 4 lanes are encountered), which makes it very popular in embedded, smartphone / tablet and automotive markets.

It has 4 main revisions (1.0-1.3, ignoring DSI 2 for now) which are used in various combinations by SoC vendors such as NXP, STMicroelectronics or Rockchip, which add to their boards Synopsys-created DSI host controllers to send data to DSI-compatible display panels. The problem is writing drivers for these revisions: as can be observed from SoC vendor provided reference manuals, register layouts are very different between revisions, even if the core HW protocols are similar if not almost identical.

This situation has lead to a proliferation of Linux MIPI-DSI drivers, usually one for each SoC vendor / DSI revision. The drivers which were merged in the mainline tree, for STM and Rockchip, created a common bridge driver module to share code, which unfortunately at this time is limited to only the DSI 1.30-1.31 layouts which these platforms use. Making these drivers or the common bridge module more generic to share more code, add new platforms or DSI revisions is hard without introducing an abstraction layer, so this sounds like a good use case to apply regmaps to make the existing upstream host controller driver more generic.

Making the Synopsys MIPI DSI driver more generic with regmaps

Toward this purpose a Genericize DW MIPI DSI bridge and add i.MX 6 driver patch series was created, at the time of this writing at version v6, which will eventually make its way in the mainline kernel and decrease a little the out-of-tree driver proliferation. For convenience v6 was also pushed to a gitlab branch, based on the latest Linux release v5.6 at the time of writing.

The idea underlying these patches is to do a gradual conversion of the bridge module to regmaps, to make it aware of different register layouts without significantly modifying the platform drivers using it, thus granting drivers the ability to transparently handle multiple layouts corresponding to HW revisions. The same MMIO interface is used by both the bridge regmap backend and the platform drivers. The register memory is mapped only once either by the drivers via their plat_data->base pointer or by the bridge before creating the regmap.

The patches should be self-explanatory and easy to understand given the context in this post. In a nutshell the steps taken are:

  1. Convert bridge MMIO read/writes to equivalent regmap read/writes.
  2. Abstract the bridge register accesses into regmap fields corresponding to the existing v1.3x layout.
  3. Add support to the bridge for an alternate v1.01 layout.
  4. Add an i.MX 6 platform driver using the new v1.01 bridge layout.
  5. Misc fixes for various issues uncovered during the regmap conversion.

An example of added benefit of having register fields explicitly defined is that bit field read/write bugs are easier to spot and fix due to not having them hidden behind cryptic preprocessor bit manipulations macros.

Conclusion

As can be observed, the same regmap and field configs as in the beginning of this post are used in the above MIPI-DSI patch series and the logic implementing different layouts should be generic enough to make it reusable by more drivers accessing MMIO-exposed registers, so hopefully this can also be useful to other driver writers having to deal with these problems. Hardware designers and vendors should take this into consideration to try to avoid any unnecessary interface breakages, and make the lives of software developers easier.

Comments (8)

  1. Wade Mealing:
    May 28, 2020 at 01:29 AM

    I can imagine this being very useful. I don't think that existing drivers could be 'auto converted' with a tool like Coccinelle, but at least it has a clear and simple interface so that conversions should be relatively straight forward.

    Reply to this comment

    Reply to this comment

    1. Adrian:
      May 28, 2020 at 12:28 PM

      Indeed regmap conversions are a bit more than what Coccinelle can handle, but they're fairly straightforward, hence the reason for writing this article to try and popularize them. The real problem in this context is in understanding the HW interface breakages which need to be compensated by the regmaps. Vendors have so many reasons for breaking HW interfaces between revisions and the breakages might be more than just registers shuffling :) Thankfully usually the changes are small enough that regmap can compensate so there is no need for a new driver from scratch (i.e. the new HW revision / core is not so different that it could be considered a "new" HW IP block).

      Reply to this comment

      Reply to this comment

  2. Jeffrey Hugo:
    May 29, 2020 at 03:07 PM

    I'm curious, is the synopsis bridge only configured via direct MMIO, or can it be configured via I2C/DSI/etc as well?

    Reply to this comment

    Reply to this comment

  3. Adrian:
    Jun 08, 2020 at 11:26 AM

    Hi Jeffrey,

    DSI is used to communicate with the external panel to send image data or do panel configuration, usually in low-power mode, but the registers which configure the host controller itself are only available via MMIO according to the documentation I have available.

    Reply to this comment

    Reply to this comment

    1. Jeffrey Hugo:
      Jun 08, 2020 at 03:09 PM

      Ok. There is a TI bridge that gets used in a lot of products I am interested in. The TI bridge can be configured either "out of band" via a dedicated I2C connection, or "inband" via DSI commands which target the bridge rather than the panel. I'm looking at extending regmap to support this, and was wondering if that work was possibly applicable to your bridge as well.

      Reply to this comment

      Reply to this comment

      1. Adrian:
        Jun 08, 2020 at 06:06 PM

        I'd have to say "maybe", but I'm not sure because I'm not familiar with TI HW to give an answer what's possible to share between the different IP blocks. Based on your description the bridge configuration is quite different, the Synopsis one is done only via MMIO, but I'm not even 100% sure of the capabilities of the Synopsis bridge because the only documentation I have access to is what SoC vendors like STM, Rockchip and NXP have released publicly via their ref manuals. In any case, good luck with your regmap! Makes me very happy to know others are doing similar work! :)

        Reply to this comment

        Reply to this comment

  4. Max:
    Jun 12, 2020 at 06:36 PM

    Retrieving the register's values is helpful for debugging. Is there automated support for debugfs?

    Reply to this comment

    Reply to this comment

    1. Adrian:
      Jun 15, 2020 at 03:50 PM

      Yes, there is the possibility to inspect regmap registers via debugfs if the regmap config meets certain criteria, basically having an upper and lower memory bound (the mmio address + a max_register offset in our case), though in practice I've found it more useful to iterate over the regmap and print all the values with a for loop in certain locations within the kernel (for eg right before starting an image decoding/encoding operation).

      Reply to this comment

      Reply to this comment


Add a Comment






Allowed tags: <b><i><br>Add a new comment:


Search the newsroom

Latest Blog Posts

Automatic regression handling and reporting for the Linux Kernel

14/03/2024

In continuation with our series about Kernel Integration we'll go into more detail about how regression detection, processing, and tracking…

Almost a fully open-source boot chain for Rockchip's RK3588!

21/02/2024

Now included in our Debian images & available via our GitLab, you can build a complete, working BL31 (Boot Loader stage 3.1), and replace…

What's the latest with WirePlumber?

19/02/2024

Back in 2022, after a series of issues were found in its design, I made the call to rework some of WirePlumber's fundamentals in order to…

DRM-CI: A GitLab-CI pipeline for Linux kernel testing

08/02/2024

Continuing our Kernel Integration series, we're excited to introduce DRM-CI, a groundbreaking solution that enables developers to test their…

Persian Rug, Part 4 - The limitations of proxies

23/01/2024

This is the fourth and final part in a series on persian-rug, a Rust crate for interconnected objects. We've touched on the two big limitations:…

How to share code between Vulkan and Gallium

16/01/2024

One of the key high-level challenges of building Mesa drivers these days is figuring out how to best share code between a Vulkan driver…

Open Since 2005 logo

We use cookies on this website to ensure that you get the best experience. By continuing to use this website you are consenting to the use of these cookies. To find out more please follow this link.

Collabora Ltd © 2005-2024. All rights reserved. Privacy Notice. Sitemap.