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_unref()
.
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:
9-bit with the Data/Command signal as the ninth bit
Same as above except it’s sent as 16 bits
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.
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 initializeconst 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.
Parameters
struct mipi_dbi * mipi
MIPI DBI structure
Description
Reset controller if the mipi_dbi->reset
gpio is set.
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.
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 initializestruct 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.
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.