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
drmDRM device
pipeDisplay pipe structure
dirty_lockSerializes framebuffer flushing
fb_funcsFramebuffer functions used when creating framebuffers
fb_dirtyFramebuffer 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
hdHorizontal resolution, width
vdVertical resolution, height
hd_mmDisplay width in millimeters
vd_mmDisplay 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 * drmDRM device to import into
struct dma_buf_attachment * attachDMA-BUF attachment
struct sg_table * sgtScatter/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_objGEM 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 * parentParent device object
struct tinydrm_device * tdevtinydrm device
const struct drm_framebuffer_funcs * fb_funcsFramebuffer functions
struct drm_driver * driverDRM 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 * tdevtinydrm 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 * tdevtinydrm 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 * pipeSimple display pipe
struct drm_plane_state * old_stateOld 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 * tdevtinydrm device
const struct drm_simple_display_pipe_funcs * funcsDisplay pipe functions
int connector_typeConnector type
const uint32_t * formatsArray of supported formats (DRM_FORMAT_*)
unsigned int format_countNumber of elements in formats
const struct drm_display_mode * modeSupported mode
unsigned int rotationInitial 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
voidno 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 * spiSPI device
struct spi_message * mSPI 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 * dstDestination clip rectangle
struct drm_clip_rect * srcSource clip rectangle(s)
unsigned int num_clipsNumber of src clip rectangles
unsigned int flagsDirty fb ioctl flags
u32 max_widthMaximum width of dst
u32 max_heightMaximum 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 * dstDestination buffer
void * vaddrSource buffer
struct drm_framebuffer * fbDRM framebuffer
struct drm_clip_rect * clipClip 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 * dstRGB565 destination buffer
void * vaddrRGB565 source buffer
struct drm_framebuffer * fbDRM framebuffer
struct drm_clip_rect * clipClip 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 * dstRGB565 destination buffer
void * vaddrXRGB8888 source buffer
struct drm_framebuffer * fbDRM framebuffer
struct drm_clip_rect * clipClip rectangle area to copy
bool swapSwap 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 * dst8-bit grayscale destination buffer
void * vaddrXRGB8888 source buffer
struct drm_framebuffer * fbDRM framebuffer
struct drm_clip_rect * clipClip 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 * spiSPI device
size_t max_lenMaximum 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 * spiSPI device
u8 bpwBits 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 * spiSPI device
u32 speed_hzOverride speed (optional)
struct spi_transfer * headerOptional header transfer
u8 bpwBits per word
const void * bufBuffer to transfer
size_t lenBuffer 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
tinydrmtinydrm base
spiSPI device
enabledPipeline is enabled
cmdlockCommand lock
commandBus specific callback executing commands.
read_commandsArray of read commands terminated by a zero entry. Reading is disabled if this is NULL.
dcOptional D/C gpio.
tx_bufBuffer used for transfer (copy clip rect area)
tx_buf9Buffer used for Option 1 9-bit conversion
tx_buf9_lenSize of tx_buf9.
swap_bytesSwap bytes in buffer before transfer
resetOptional reset gpio
rotationinitial rotation in degrees Counter Clock Wise
backlightbacklight device (optional)
regulatorpower regulator (optional)
-
mipi_dbi_command(mipi, cmd, seq…)¶ MIPI DCS command with optional parameter(s)
Parameters
mipiMIPI structure
cmdCommand
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 * mipiMIPI structure
u8 cmdCommand
u8 * valValue 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 * mipiMIPI structure
u8 cmdCommand
u8 * dataParameter buffer
size_t lenBuffer 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 * dstThe destination buffer
struct drm_framebuffer * fbThe source framebuffer
struct drm_clip_rect * clipClipping rectangle of the area to be copied
bool swapWhen 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 * mipiMIPI DBI structure
struct drm_crtc_state * crtc_stateCRTC state
struct drm_plane_state * plane_statePlane 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 * pipeDisplay 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 * devParent device
struct mipi_dbi * mipimipi_dbistructure to initializeconst struct drm_simple_display_pipe_funcs * pipe_funcsDisplay pipe functions
struct drm_driver * driverDRM driver
const struct drm_display_mode * modeDisplay mode
unsigned int rotationInitial 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 * mipiMIPI DBI structure
Description
Reset controller if the mipi_dbi->reset gpio is set.
Parameters
struct mipi_dbi * mipiMIPI 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 * mipiMIPI 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 * mipiMIPI 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 * spiSPI device
size_t lenThe 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 * spiSPI device
struct mipi_dbi * mipimipi_dbistructure to initializestruct gpio_desc * dcD/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 * minorDRM 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.