drm/tinydrm Tiny DRM drivers

tinydrm is a collection of DRM drivers that are so small they can fit in a single source file.

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.

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.

int tinydrm_display_pipe_init(struct drm_device * drm, struct drm_simple_display_pipe * pipe, 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 drm_device * drm
DRM device
struct drm_simple_display_pipe * pipe
Display pipe
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.

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:

  1. Motorola 6800 type parallel bus
  2. Intel 8080 type parallel bus
  3. 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 drm_device drm;
  struct drm_simple_display_pipe pipe;
  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

drm
DRM device
pipe
Display pipe structure
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_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_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_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 handles framebuffer flushing and vblank events. Drivers can use this as their drm_simple_display_pipe_funcs->update callback.

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.

Note

Drivers which don’t use mipi_dbi_pipe_update() because they have custom framebuffer flushing, can’t use this function since they both use the same flushing code.

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 mipi_dbi * mipi, const struct drm_simple_display_pipe_funcs * funcs, const struct drm_display_mode * mode, unsigned int rotation)

MIPI DBI initialization

Parameters

struct mipi_dbi * mipi
mipi_dbi structure to initialize
const struct drm_simple_display_pipe_funcs * funcs
Display pipe functions
const struct drm_display_mode * mode
Display mode
unsigned int rotation
Initial 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. This mode is used to set the mode config min/max width/height properties. Additionally mipi_dbi.tx_buf is allocated.

Supported formats: Native RGB565 and emulated XRGB8888.

Return

Zero on success, negative error code on failure.

void mipi_dbi_release(struct drm_device * drm)

DRM driver release helper

Parameters

struct drm_device * drm
DRM device

Description

This function finalizes and frees mipi_dbi.

Drivers can use this as their drm_driver->release callback.

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.