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() .
Definition
Members
drm DRM device pipe Display pipe structure dirty_lock Serializes framebuffer flushing fb_funcs Framebuffer functions used when creating framebuffers 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 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 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 ) В¶
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_prepare_fb ( struct drm_simple_display_pipe * pipe, struct drm_plane_state * plane_state ) В¶
Display pipe prepare_fb helper
Parameters
struct drm_simple_display_pipe * pipe Simple display pipe struct drm_plane_state * plane_state Plane state
Description
This function uses drm_gem_fb_prepare_fb() to check if the plane FB has an dma-buf attached, extracts the exclusive fence and attaches it to plane state for the atomic helper to wait on. Drivers can use this as their drm_simple_display_pipe_funcs->prepare_fb 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¶
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.
struct backlight_device * tinydrm_of_find_backlight ( struct device * dev ) В¶
Find backlight device in device-tree
Parameters
struct device * dev Device
Description
This function looks for a DT node pointed to by a property named ‘backlight’ and uses of_find_backlight_by_node() to get the backlight device. Additionally if the brightness property is zero, it is set to max_brightness.
Return
NULL if there’s no backlight property. Error pointer -EPROBE_DEFER if the DT node is found, but no backlight device is found. If the backlight device is found, a pointer to the structure is returned.
int tinydrm_enable_backlight ( struct backlight_device * backlight ) В¶
Enable backlight helper
Parameters
struct backlight_device * backlight Backlight device
Return
Zero on success, negative error code on failure.
int tinydrm_disable_backlight ( struct backlight_device * backlight ) В¶
Disable backlight helper
Parameters
struct backlight_device * backlight Backlight device
Return
Zero on success, negative error code on failure.
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() .
MIPI DBI controller
Definition
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_pipe_enable ( struct drm_simple_display_pipe * pipe, struct drm_crtc_state * crtc_state ) В¶
MIPI DBI pipe enable helper
Parameters
struct drm_simple_display_pipe * pipe Display pipe struct drm_crtc_state * crtc_state CRTC state
Description
This function enables backlight. Drivers can use this as 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 or if not the display memory is blanked. 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.
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.
Источник
