drm/tinydrm Driver library¶

This library provides driver helpers for very simple display hardware.

It is based on drm_simple_display_pipe coupled with a drm_connector which has only one fixed drm_display_mode. The framebuffers are backed by the cma helper and have support for framebuffer flushing (dirty). fbdev support is also included.

Core functionality¶

The driver allocates tinydrm_device, initializes it using devm_tinydrm_init(), sets up the pipeline using tinydrm_display_pipe_init() and registers the DRM device using devm_tinydrm_register().

struct tinydrm_device¶: tinydrm device

Definition

struct tinydrm_device {
  struct drm_device *drm;
  struct drm_simple_display_pipe pipe;
  struct mutex dirty_lock;
  const struct drm_framebuffer_funcs *fb_funcs;
  int (*fb_dirty)(struct drm_framebuffer *framebuffer,struct drm_file *file_priv, unsigned flags,unsigned color, struct drm_clip_rect *clips, unsigned num_clips);
};

Members

drm: DRM device
pipe: Display pipe structure
dirty_lock: Serializes framebuffer flushing
fb_funcs: Framebuffer functions used when creating framebuffers
fb_dirty: Framebuffer dirty callback

TINYDRM_GEM_DRIVER_OPS()¶: default tinydrm gem operations

Parameters

Description

This macro provides a shortcut for setting the tinydrm GEM operations in the drm_driver structure.

TINYDRM_MODE(hd, vd, hd_mm, vd_mm)¶: tinydrm display mode

Parameters

hd: Horizontal resolution, width
vd: Vertical resolution, height
hd_mm: Display width in millimeters
vd_mm: Display height in millimeters

Description

This macro creates a drm_display_mode for use with tinydrm.

struct drm_gem_object * tinydrm_gem_cma_prime_import_sg_table(struct drm_device * drm, struct dma_buf_attachment * attach, struct sg_table * sgt)¶: Produce a CMA GEM object from another driver’s scatter/gather table of pinned pages

Parameters

struct drm_device * drm: DRM device to import into
struct dma_buf_attachment * attach: DMA-BUF attachment
struct sg_table * sgt: Scatter/gather table of pinned pages

Description

This function imports a scatter/gather table exported via DMA-BUF by another driver using drm_gem_cma_prime_import_sg_table(). It sets the kernel virtual address on the CMA object. Drivers should use this as their drm_driver->gem_prime_import_sg_table callback if they need the virtual address. tinydrm_gem_cma_free_object() should be used in combination with this function.

Return

A pointer to a newly created GEM object or an ERR_PTR-encoded negative error code on failure.

void tinydrm_gem_cma_free_object(struct drm_gem_object * gem_obj)¶: Free resources associated with a CMA GEM object

Parameters

struct drm_gem_object * gem_obj: GEM object to free

Description

This function frees the backing memory of the CMA GEM object, cleans up the GEM object state and frees the memory used to store the object itself using drm_gem_cma_free_object(). It also handles PRIME buffers which has the kernel virtual address set by tinydrm_gem_cma_prime_import_sg_table(). Drivers can use this as their drm_driver->gem_free_object_unlocked callback.

int devm_tinydrm_init(struct device * parent, struct tinydrm_device * tdev, const struct drm_framebuffer_funcs * fb_funcs, struct drm_driver * driver)¶: Initialize tinydrm device

Parameters

struct device * parent: Parent device object
struct tinydrm_device * tdev: tinydrm device
const struct drm_framebuffer_funcs * fb_funcs: Framebuffer functions
struct drm_driver * driver: DRM driver

Description

This function initializes tdev, the underlying DRM device and it’s mode_config. Resources will be automatically freed on driver detach (devres) using drm_mode_config_cleanup() and drm_dev_put().

Return

Zero on success, negative error code on failure.

int devm_tinydrm_register(struct tinydrm_device * tdev)¶: Register tinydrm device

Parameters

struct tinydrm_device * tdev: tinydrm device

Description

This function registers the underlying DRM device and fbdev. These resources will be automatically unregistered on driver detach (devres) and the display pipeline will be disabled.

Return

Zero on success, negative error code on failure.

void tinydrm_shutdown(struct tinydrm_device * tdev)¶: Shutdown tinydrm

Parameters

struct tinydrm_device * tdev: tinydrm device

Description

This function makes sure that the display pipeline is disabled. Used by drivers in their shutdown callback to turn off the display on machine shutdown and reboot.

void tinydrm_display_pipe_update(struct drm_simple_display_pipe * pipe, struct drm_plane_state * old_state)¶: Display pipe update helper

Parameters

struct drm_simple_display_pipe * pipe: Simple display pipe
struct drm_plane_state * old_state: Old plane state

Description

This function does a full framebuffer flush if the plane framebuffer has changed. It also handles vblank events. Drivers can use this as their drm_simple_display_pipe_funcs->update callback.

int tinydrm_display_pipe_init(struct tinydrm_device * tdev, const struct drm_simple_display_pipe_funcs * funcs, int connector_type, const uint32_t * formats, unsigned int format_count, const struct drm_display_mode * mode, unsigned int rotation)¶: Initialize display pipe

Parameters

struct tinydrm_device * tdev: tinydrm device
const struct drm_simple_display_pipe_funcs * funcs: Display pipe functions
int connector_type: Connector type
const uint32_t * formats: Array of supported formats (DRM_FORMAT_*)
unsigned int format_count: Number of elements in formats
const struct drm_display_mode * mode: Supported mode
unsigned int rotation: Initial mode rotation in degrees Counter Clock Wise

Description

This function sets up a drm_simple_display_pipe with a drm_connector that has one fixed drm_display_mode which is rotated according to rotation.

Return

Zero on success, negative error code on failure.

Additional helpers¶

bool tinydrm_machine_little_endian(void)¶: Machine is little endian

Parameters

void: no arguments

Return

true if defined(__LITTLE_ENDIAN), false otherwise

void tinydrm_dbg_spi_message(struct spi_device * spi, struct spi_message * m)¶: Dump SPI message

Parameters

struct spi_device * spi: SPI device
struct spi_message * m: SPI message

Description

Dumps info about the transfers in a SPI message including buffer content. DEBUG has to be defined for this function to be enabled alongside setting the DRM_UT_DRIVER bit of drm_debug.

bool tinydrm_merge_clips(struct drm_clip_rect * dst, struct drm_clip_rect * src, unsigned int num_clips, unsigned int flags, u32 max_width, u32 max_height)¶: Merge clip rectangles

Parameters

struct drm_clip_rect * dst: Destination clip rectangle
struct drm_clip_rect * src: Source clip rectangle(s)
unsigned int num_clips: Number of src clip rectangles
unsigned int flags: Dirty fb ioctl flags
u32 max_width: Maximum width of dst
u32 max_height: Maximum height of dst

Description

This function merges src clip rectangle(s) into dst. If src is NULL, max_width and min_width is used to set a full dst clip rectangle.

Return

true if it’s a full clip, false otherwise

void tinydrm_memcpy(void * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_clip_rect * clip)¶: Copy clip buffer

Parameters

void * dst: Destination buffer
void * vaddr: Source buffer
struct drm_framebuffer * fb: DRM framebuffer
struct drm_clip_rect * clip: Clip rectangle area to copy

void tinydrm_swab16(u16 * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_clip_rect * clip)¶: Swap bytes into clip buffer

Parameters

u16 * dst: RGB565 destination buffer
void * vaddr: RGB565 source buffer
struct drm_framebuffer * fb: DRM framebuffer
struct drm_clip_rect * clip: Clip rectangle area to copy

void tinydrm_xrgb8888_to_rgb565(u16 * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_clip_rect * clip, bool swap)¶: Convert XRGB8888 to RGB565 clip buffer

Parameters

u16 * dst: RGB565 destination buffer
void * vaddr: XRGB8888 source buffer
struct drm_framebuffer * fb: DRM framebuffer
struct drm_clip_rect * clip: Clip rectangle area to copy
bool swap: Swap bytes

Description

Drivers can use this function for RGB565 devices that don’t natively support XRGB8888.

void tinydrm_xrgb8888_to_gray8(u8 * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_clip_rect * clip)¶: Convert XRGB8888 to grayscale

Parameters

u8 * dst: 8-bit grayscale destination buffer
void * vaddr: XRGB8888 source buffer
struct drm_framebuffer * fb: DRM framebuffer
struct drm_clip_rect * clip: Clip rectangle area to copy

Description

Drm doesn’t have native monochrome or grayscale support. Such drivers can announce the commonly supported XR24 format to userspace and use this function to convert to the native format.

Monochrome drivers will use the most significant bit, where 1 means foreground color and 0 background color.

ITU BT.601 is used for the RGB -> luma (brightness) conversion.

size_t tinydrm_spi_max_transfer_size(struct spi_device * spi, size_t max_len)¶: Determine max SPI transfer size

Parameters

struct spi_device * spi: SPI device
size_t max_len: Maximum buffer size needed (optional)

Description

This function returns the maximum size to use for SPI transfers. It checks the SPI master, the optional max_len and the module parameter spi_max and returns the smallest.

Return

Maximum size for SPI transfers

bool tinydrm_spi_bpw_supported(struct spi_device * spi, u8 bpw)¶: Check if bits per word is supported

Parameters

struct spi_device * spi: SPI device
u8 bpw: Bits per word

Description

This function checks to see if the SPI master driver supports bpw.

Return

True if bpw is supported, false otherwise.

int tinydrm_spi_transfer(struct spi_device * spi, u32 speed_hz, struct spi_transfer * header, u8 bpw, const void * buf, size_t len)¶: SPI transfer helper

Parameters

struct spi_device * spi: SPI device
u32 speed_hz: Override speed (optional)
struct spi_transfer * header: Optional header transfer
u8 bpw: Bits per word
const void * buf: Buffer to transfer
size_t len: Buffer length

Description

This SPI transfer helper breaks up the transfer of buf into chunks which the SPI master driver can handle. If the machine is Little Endian and the SPI master driver doesn’t support 16 bits per word, it swaps the bytes and does a 8-bit transfer. If header is set, it is prepended to each SPI message.

Return

Zero on success, negative error code on failure.

MIPI DBI Compatible Controllers¶

This library provides helpers for MIPI Display Bus Interface (DBI) compatible display controllers.

Many controllers for tiny lcd displays are MIPI compliant and can use this library. If a controller uses registers 0x2A and 0x2B to set the area to update and uses register 0x2C to write to frame memory, it is most likely MIPI compliant.

Only MIPI Type 1 displays are supported since a full frame memory is needed.

There are 3 MIPI DBI implementation types:

Motorola 6800 type parallel bus
Intel 8080 type parallel bus
SPI type with 3 options:
1. 9-bit with the Data/Command signal as the ninth bit
2. Same as above except it’s sent as 16 bits
3. 8-bit with the Data/Command signal as a separate D/CX pin

Currently mipi_dbi only supports Type C options 1 and 3 with mipi_dbi_spi_init().

struct mipi_dbi¶: MIPI DBI controller

Definition

struct mipi_dbi {
  struct tinydrm_device tinydrm;
  struct spi_device *spi;
  bool enabled;
  struct mutex cmdlock;
  int (*command)(struct mipi_dbi *mipi, u8 cmd, u8 *param, size_t num);
  const u8 *read_commands;
  struct gpio_desc *dc;
  u16 *tx_buf;
  void *tx_buf9;
  size_t tx_buf9_len;
  bool swap_bytes;
  struct gpio_desc *reset;
  unsigned int rotation;
  struct backlight_device *backlight;
  struct regulator *regulator;
};

Members

tinydrm: tinydrm base
spi: SPI device
enabled: Pipeline is enabled
cmdlock: Command lock
command: Bus specific callback executing commands.
read_commands: Array of read commands terminated by a zero entry. Reading is disabled if this is NULL.
dc: Optional D/C gpio.
tx_buf: Buffer used for transfer (copy clip rect area)
tx_buf9: Buffer used for Option 1 9-bit conversion
tx_buf9_len: Size of tx_buf9.
swap_bytes: Swap bytes in buffer before transfer
reset: Optional reset gpio
rotation: initial rotation in degrees Counter Clock Wise
backlight: backlight device (optional)
regulator: power regulator (optional)

mipi_dbi_command(mipi, cmd, seq...)¶: MIPI DCS command with optional parameter(s)

Parameters

mipi: MIPI structure
cmd: Command
seq...: Optional parameter(s)

Description

Send MIPI DCS command to the controller. Use mipi_dbi_command_read() for get/read.

Return

Zero on success, negative error code on failure.

int mipi_dbi_command_read(struct mipi_dbi * mipi, u8 cmd, u8 * val)¶: MIPI DCS read command

Parameters

struct mipi_dbi * mipi: MIPI structure
u8 cmd: Command
u8 * val: Value read

Description

Send MIPI DCS read command to the controller.

Return

Zero on success, negative error code on failure.

int mipi_dbi_command_buf(struct mipi_dbi * mipi, u8 cmd, u8 * data, size_t len)¶: MIPI DCS command with parameter(s) in an array

Parameters

struct mipi_dbi * mipi: MIPI structure
u8 cmd: Command
u8 * data: Parameter buffer
size_t len: Buffer length

Return

Zero on success, negative error code on failure.

int mipi_dbi_buf_copy(void * dst, struct drm_framebuffer * fb, struct drm_clip_rect * clip, bool swap)¶: Copy a framebuffer, transforming it if necessary

Parameters

void * dst: The destination buffer
struct drm_framebuffer * fb: The source framebuffer
struct drm_clip_rect * clip: Clipping rectangle of the area to be copied
bool swap: When true, swap MSB/LSB of 16-bit values

Return

Zero on success, negative error code on failure.

void mipi_dbi_enable_flush(struct mipi_dbi * mipi, struct drm_crtc_state * crtc_state, struct drm_plane_state * plane_state)¶: MIPI DBI enable helper

Parameters

struct mipi_dbi * mipi: MIPI DBI structure
struct drm_crtc_state * crtc_state: CRTC state
struct drm_plane_state * plane_state: Plane state

Description

This function sets mipi_dbi->enabled, flushes the whole framebuffer and enables the backlight. Drivers can use this in their drm_simple_display_pipe_funcs->enable callback.

void mipi_dbi_pipe_disable(struct drm_simple_display_pipe * pipe)¶: MIPI DBI pipe disable helper

Parameters

struct drm_simple_display_pipe * pipe: Display pipe

Description

This function disables backlight if present, if not the display memory is blanked. The regulator is disabled if in use. Drivers can use this as their drm_simple_display_pipe_funcs->disable callback.

int mipi_dbi_init(struct device * dev, struct mipi_dbi * mipi, const struct drm_simple_display_pipe_funcs * pipe_funcs, struct drm_driver * driver, const struct drm_display_mode * mode, unsigned int rotation)¶: MIPI DBI initialization

Parameters

struct device * dev: Parent device
struct mipi_dbi * mipi: mipi_dbi structure to initialize
const struct drm_simple_display_pipe_funcs * pipe_funcs: Display pipe functions
struct drm_driver * driver: DRM driver
const struct drm_display_mode * mode: Display mode
unsigned int rotation: Initial rotation in degrees Counter Clock Wise

Description

This function initializes a mipi_dbi structure and it’s underlying tinydrm_device. It also sets up the display pipeline.

Supported formats: Native RGB565 and emulated XRGB8888.

Objects created by this function will be automatically freed on driver detach (devres).

Return

Zero on success, negative error code on failure.

void mipi_dbi_hw_reset(struct mipi_dbi * mipi)¶: Hardware reset of controller

Parameters

struct mipi_dbi * mipi: MIPI DBI structure

Description

Reset controller if the mipi_dbi->reset gpio is set.

bool mipi_dbi_display_is_on(struct mipi_dbi * mipi)¶: Check if display is on

Parameters

struct mipi_dbi * mipi: MIPI DBI structure

Description

This function checks the Power Mode register (if readable) to see if display output is turned on. This can be used to see if the bootloader has already turned on the display avoiding flicker when the pipeline is enabled.

Return

true if the display can be verified to be on, false otherwise.

int mipi_dbi_poweron_reset(struct mipi_dbi * mipi)¶: MIPI DBI poweron and reset

Parameters

struct mipi_dbi * mipi: MIPI DBI structure

Description

This function enables the regulator if used and does a hardware and software reset.

Return

Zero on success, or a negative error code.

int mipi_dbi_poweron_conditional_reset(struct mipi_dbi * mipi)¶: MIPI DBI poweron and conditional reset

Parameters

struct mipi_dbi * mipi: MIPI DBI structure

Description

This function enables the regulator if used and if the display is off, it does a hardware and software reset. If mipi_dbi_display_is_on() determines that the display is on, no reset is performed.

Return

Zero if the controller was reset, 1 if the display was already on, or a negative error code.

u32 mipi_dbi_spi_cmd_max_speed(struct spi_device * spi, size_t len)¶: get the maximum SPI bus speed

Parameters

struct spi_device * spi: SPI device
size_t len: The transfer buffer length.

Description

Many controllers have a max speed of 10MHz, but can be pushed way beyond that. Increase reliability by running pixel data at max speed and the rest at 10MHz, preventing transfer glitches from messing up the init settings.

int mipi_dbi_spi_init(struct spi_device * spi, struct mipi_dbi * mipi, struct gpio_desc * dc)¶: Initialize MIPI DBI SPI interfaced controller

Parameters

struct spi_device * spi: SPI device
struct mipi_dbi * mipi: mipi_dbi structure to initialize
struct gpio_desc * dc: D/C gpio (optional)

Description

This function sets mipi_dbi->command, enables mipi->read_commands for the usual read commands. It should be followed by a call to mipi_dbi_init() or a driver-specific init.

If dc is set, a Type C Option 3 interface is assumed, if not Type C Option 1.

If the SPI master driver doesn’t support the necessary bits per word, the following transformation is used:

9-bit: reorder buffer as 9x 8-bit words, padded with no-op command.
16-bit: if big endian send as 8-bit, if little endian swap bytes

Return

Zero on success, negative error code on failure.

int mipi_dbi_debugfs_init(struct drm_minor * minor)¶: Create debugfs entries

Parameters

struct drm_minor * minor: DRM minor

Description

This function creates a ‘command’ debugfs file for sending commands to the controller or getting the read command values. Drivers can use this as their drm_driver->debugfs_init callback.

Return

Zero on success, negative error code on failure.