Using regmaps to make Linux drivers more generic

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 toa 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 beforecreating 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 tospot 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.