Chapter 12: Abstracting Memory Access – Introduction to the Regmap API: a Register Map Abstraction

Before the Regmap API was developed, there was redundant code for the device drivers dealing with SPI, I2C, or memory-mapped devices. Many of these drivers contained some very similar code for accessing hardware device registers.

The following figure shows how SPI, I2C, and memory-mapped related APIs were used standalone before Regmap was introduced:

Figure 12.1 – I2C, SPI, and memory-mapped access before Regmap

The Regmap API was introduced in version v3.1 of the Linux kernel and proposes a solution that factors out and unifies these similar register access codes, saving code and making it much easier to share infrastructure. It is then just a matter of how to initialize and to configure a regmap structure, and process any read/write/modify operations fluently, whether it is SPI, I2C, or memory-mapped.

The following diagram depicts this API...

Introduction to the Regmap data structures

The Regmap framework, which is enabled via the CONFIG_REGMAP kernel configuration option, is made of a few data structures, among which the most important are struct regmap_config, which represents the Regmap configuration, and struct regmap, which is the Regmap instance itself. That said, all of the Regmap data structures are defined in include/linux/regmap.h. It then goes without saying that this header must be included in all Regmap-based drivers:

#include <linux/regmap.h>

Including the preceding header is sufficient to make the most out of the Regmap framework. With this header, a lot of data structures will be made available, among which, struct regmap_config is the most important, which we will describe in the next section.

Understanding the struct regmap_config structure

struct regmap_config stores the configuration of the register map during the driver's lifetime. What you set there affects the memory read/write...

Handling Regmap initialization

As we said earlier, the Regmap API supports SPI, I2C, and memory-mapped register access. Their respective support can be enabled in the kernel thanks to the CONFIG_REGMAP_SPI, CONFIG_REGMAP_I2C, and CONFIG_REGMAP_MMIO kernel configuration options. It can go far beyond that and managing IRQs as well, but this is out of the scope of this book. Depending on the memory access method you need to support in the driver, you will have to call either devm_regmap_init_i2c(), devm_regmap_init_spi(), or devm_ regmap_init_mmio() in the probe function. To write generic drivers, Regmap is the best choice you can make.

The Regmap API is generic and homogenous, and initialization only changes between bus types. Other functions are the same. It is a good practice to always initialize the register map in the probe function, and you must always fill the regmap_config elements prior to initializing the register map using one of the following APIs:

struct regmap *devm_regmap_init_spi...

Using Regmap register access functions

Remap register access methods handle data parsing, formatting, and transmission. In most cases, device accesses are performed with regmap_read(), regmap_write(), and regmap_update_bits(), which are the three important APIs when it comes to writing/reading data into/from the device. Their respective prototypes are the following:

int regmap_read(struct regmap *map, unsigned int reg,
                 unsigned int *val);
int regmap_write(struct regmap *map, unsigned int reg,
                 unsigned int val);
int regmap_update_bits(struct regmap *map,
                 unsigned int reg, unsigned int mask,
               ...

Regmap-based SPI driver example – putting it all together

All the steps involved in setting up Regmap, from configuration to device register access, can be enumerated as follows:

• Setting up a struct regmap_config object according to the device characteristics. Defining the register range if needed, default values if any, cache_type if needed, and so on. If custom read/write functions are needed, pass them to the reg_read/reg_write fields.
• In the probe function, allocating a register map using devm_regmap_init_i2c(), devm_regmap_init_spi(), or devm_regmap_init_mmio() depending on the connection with the underlying device – I2C, SPI, or memory-mapped.
• Whenever you need to read/write from/into registers, calling remap_[read|write] functions.
• When done with the register map, assuming you used resource-managed APIs, you have nothing else to do as devres core will take care of releasing the Regmap resources; otherwise, you'll have to call regmap_exit...

Leveraging Regmap from the user space

Register maps can be monitored from the user space via the debugfs file system. First, debugfs needs to be enabled via the CONFIG_DEBUG_FS kernel configuration option. Then, debugfs can be mounted using the following command:

mount -t debugfs none /sys/kernel/debug

After that, the debugfs register map implementation can be found under /sys/kernel/debug/regmap/. This debugfs view implemented by drivers/base/regmap/regmap-debugfs.c in kernel sources contains a register cache (mirror) for drivers/peripherals based on the Regmap API.

From the Regmap main debugfs directory, we can get the list of devices whose drivers are based on the Regmap API using the following command:

root@jetson-nano-devkit:~# ls -l /sys/kernel/debug/regmap/
drwxr-xr-x   2 root  root   0 Jan  1  1970 4-003c-power-slave
drwxr-xr-x   2 root  root   0 Jan  1...

Summary

This chapter is all about register access related Regmap APIs. Its simplicity should give you an idea of how useful and widely used it is. This chapter has shown everything you need to know about the Regmap API. Now you should be able to convert any standard SPI/I2C/memory-mapped driver into Regmap.

The next chapter will cover IRQ management under Linux, however, two chapters after, we will cover IIO devices, a framework for analog-to-digital converters. Those kinds of devices always sit on top of SPI/I2C buses. It could be a challenge for us, at the end of that chapter, to write an IIO driver using the Regmap API.