NXP released a new OLED panel (MX8-DSI-OLED1A) during the first half of 2021. However, at the moment of writing this document, the panel lacks of the documentation that an user would need.
The OLED1A panel has a similar name to its predecessor (MX8-DSI-OLED1). Making an user to think that both parts might work with similar driver and device tree. However, the new panel requires a device tree fix necessary to make it work properly.
This document provides a fix for the OLED1A using the 5.4.70.2.3.0 Linux BSP for the i.MX 8M Nano EVK (LPDDR4-board). In addition, a called kernel-source method for compiling a device tree is presented.
Both device tree source (dts) and its compiled code (dtb) are provided as attachments to this project.
Hardware used in this project- MX8-DSI-OLED1A panel with its Molex Connector
- i.MX 8M Nano EVK ( 8MNANOLPD4-EVK )
- An Ubuntu 18.04 workstation
The OLED1 panel works with a NXP Linux BSP when the rm67191 device tree is provided to the kernel. So, I started testing the OLED1A with the same device tree. However, the result is not what we expect.
The panel shows an image that its halved; one part has a greenish tone and the other its normal, and touch response was not enabled. I used the file named imx8mn-ddr4-evk-rm67191.dtb. See result below:
The following section presents the steps I followed to fix the panel using a new device tree that makes a couple of changes to the rm67199 original device tree.
Setting up the EVKStart downloading a pre-built LInux BSP image with 5.4.70.2.3.0 kernel from NXP. It is available from here:
https://www.nxp.com/webapp/Download?colCode=L5.4.70_2.3.0_MX8MN&appType=license
Following steps are meant to followed using BSP image that was burned onto an SD card (preferably a 32 GB one). Please download the image from the above link, decompress it and load onto the card using the dd command.
Open a serial terminal within the decompressed image folder. Then, copy the BSP image using the dd command. Make sure to replace the sdx name from the below command with the name of your SD card.
$ sudo dd if=imx-image-full-imx8mnevk.wic of=/dev/sdx bs=1M && syncAfter this process is complete. Make sure that your EVK is not powered (SW101 is off) and plug the MX8-DSI-OLED1A to its Molex cable. Then, attach the latter to the J801 (DSI MIPI) connector of the i.MX 8M Nano EVK. Also, attach an USB cable to the debug port of the board (J901).
Now, identify the EVK debug port as an FTDI USB Serial Device converter. We will read the kernel ring buffer of our workstation just to make sure that the debug port was properly attached.
$ dmesg | grep ttySince we are interest on the the Cortex A cluster of the 8M Nano, we will be using the ttyUSB1 device for serial communication with the EVK.
[ 2678.073748] usb 3-1.4: FTDI USB Serial Device converter now attached to ttyUSB1Now, set appropriate read and write permissions for ttyUSB1 within the workstation.
$ sudo chmod 666 /dev/ttyUSB1I like to use tio at my workstation as a virtual terminal for i.MX 8M Nano. If you haven't installed it, follow this step:
$ sudo apt install tioStart a tio session for the EVK. Then power it.
$ tio /dev/ttyUSB1NOTE
I put this section at here so you can turn on your EVK, and make sure that is working. So, it is possible that you don't see anything on the screen of the OLED1A panel. Please have in mind that the last section of the document needs the board to be rebooted and be logged into an U-boot shell for choosing the appropriate device tree for panel.
Setting up a Yocto environment Prior Device Tree FixAlbeit there are other methods for working with device trees, I will present one that I consider handy. This is a process that builds a kernel for the i.MX 8M Nano using Yocto, and works with its device tree sources. I prefer this method as it allows a developer to perform and test changes to the BSP efficiently.
I setup a Yocto build environment for the i.MX 8M Nano. Although there is no need to build a complete BSP to make the changes that I will describe, you can absolutely build your own image and go on with the project. Documentation can be downloaded from the NXP website:
https://www.nxp.com/webapp/Download?colCode=L5.4.70_2.3.0_LINUX_DOCS
Just for your convenience, I put below the Yocto setup commands from above guide. Note that I didn't issue any bibtake compile of a full BSP.
Install essential Yocto project host packages:
$ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \
pylint3 xtermSetting up the repo utility:
$ mkdir ~/bin (this step may not be needed if the bin folder already exists)
$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod a+x ~/bin/repo
$ export PATH=~/bin:$PATHSetting up git:
$ git config --global user.name "Your Name"
$ git config --global user.email "Your Email"
$ git config --listFirst, make sure that git is set up properly with the commands below:
$ git config --global user.name "Your Name"
$ git config --global user.email "Your Email"
$ git config --listRepo init and sync:
$ mkdir imx-yocto-bsp
$ cd imx-yocto-bsp
$ repo init -u https://source.codeaurora.org/external/imx/imx-manifest
-b imx-linux-zeus -m imx-5.4.70-2.3.0.xml
$ repo syncSet up the distro, machine and a build directory. Then accept the EULA
$ DISTRO=fsl-imx-wayland MACHINE=imx8mnevk source imx-setup-release.sh -b build-quick-nanoNote:
If you decide to build an image for the i.MX 8M Mini and work with kernel sources, you can skip the next command an jump into the launch of the Yocto devshell in the next section.
Use bitbake for compiling the kernel. We will use it contains the necessary device trees and Makefiles required for in the next section.
$ bitbake linux-imx -f -c deployThis process may take a while depending on your workstation setup. But for me, it took approximately 25 minutes (HP Zbook with 32 GB of RAM).
Building the device tree for the OLED1A - the kernel-source methodAfter we compiled a kernel image. We are ready to start working on a new device tree for the panel. First, launch the Yocto's devshell, which prepares all the scripts and configurations needed to perform any change to a Yocto recipe without any setup issues.
$ bitbake -c devhsell linux-imxThe devshell will take you to the kernel-source directory:
/tmp/work-shared/imx8mnevk/kernel-sourceContinue on that directory and move to the folder where the .dts files are stored:
build-quick-nano/tmp/work-shared/imx8mnevk/kernel-source/arch/arm64/boot/dts/freescaleYou will see a lot of other dts (device tree sources) when you issue the list command (ls). See image below:
Create the your new dts file using your preferred editor. Mine is going to be called imx8mn-ddr4-evk-rm67199.dts
$ nano imx8mn-ddr4-evk-rm67199.dtsPaste this code onto it and save it:
// SPDX-License-Identifier: GPL-2.0+
/*
* Copyright 2021 NXP
*/
#include "imx8mn-ddr4-evk.dts"
&adv_bridge {
status = "disabled";
};
&mipi_dsi {
panel@0 {
compatible = "raydium,rm67199";
reg = <0>;
pinctrl-0 = <&pinctrl_mipi_dsi_en>;
reset-gpio = <&gpio1 8 GPIO_ACTIVE_LOW>;
dsi-lanes = <4>;
video-mode = <2>; /* 0: burst mode
* 1: non-burst mode with sync event
* 2: non-burst mode with sync pulse
*/
panel-width-mm = <68>;
panel-height-mm = <121>;
status = "okay";
};
};
&i2c2 {
touchscreen@14 {
compatible = "goodix,gt1151";
reg = <0x14>;
pinctrl-names = "default";
pinctrl-0 = <&pinctrl_i2c2_synaptics_dsx_io>;interrupt-parent = <&gpio1>;
interrupts = <9 IRQ_TYPE_EDGE_FALLING>;
irq-gpios = <&gpio1 9 GPIO_ACTIVE_HIGH>;
edge-failling-trigger;
touchscreen-size-x = <720>;
touchscreen-size-y = <1440>;
};
};Now, focus on adding the device tree to the Makefile that lives on the same directory. This file will instruc the device tree compiler to generate a device trer binary file that can be loaded onto the SD card.
Append the following line to end of the the Makefile:
dtb-$(CONFIG_ARCH_MXC) += imx8mn-ddr4-evk-rm67199.dtbThen, navigate to the build folder, which is located outside of the kernel-source directory, in the work directory. This is where output files are stored whenever a kernel is compiled. It is located here:
/yocto-quick/build-quick-nano/tmp/work/imx8mnevk-poky-linux/linux-imx/5.4-r0/buildNow, compile the rm67199 dtb that we just created in the kernel-source directory. This will call another Makefile that invokes the one that we edited on the previous step.
# make dtbsAs we are inside the devshell the make dtbs command end up calling scripts that contain our architecture configuration. Then, the device tree compiler its excuted to build our device tree including SOC-dependent .dtsi (include) files. Thus, generating a full device tree (dtb) that we can now test.
To find the new dtb, navigate to this directory:
/yocto-quick/build-quick-nano/tmp/work/imx8mnevk-poky-linux/linux-imx/5.4-r0/build/arch/arm64/boot/dts/freescaleNOTE:
A good practice is to make a copy in a backup directory of your liking just in case any problem occurs with the devshell. Please have also in mind that Yocto is not meant to be a compilation or build rather than a development environment. So all changes made between compilations need to be appended to a relevant recipe.
Updating the SD card with our new device tree for OLED1A panelMake sure that your EVK is already powered off in case that you previously plugged in the SD card onto it. Now plug in the card onto your workstation an paste the new dtb on the boot directory (you should already see other dtbs within it).
Plug in the SD card to your EVK an turn it ON with a tio session already set up. Just a couple of seconds after the first kernel-boot message, you will see a prompt with a timer. Press any key to launch an U-boot session.
Hit any key to stop autoboot: 3Now that you are logged into U-boot, issue the following command just to make sure that your new dtb is present. In my case, the imx8mn-ddr4-evk-rm67199.dtb is present with size of 40608 bytes.
u-boot=> fatls mmc 1:1
28013056 Image
40187 imx8mn-ddr3l-evk-ak5558.dtb
40155 imx8mn-ddr3l-evk.dtb
41563 imx8mn-ddr3l-evk-rpmsg.dtb
40089 imx8mn-ddr4-evk-ak5558.dtb
40057 imx8mn-ddr4-evk.dtb
3071 imx8mn-ddr4-evk-inmate.dtb
40608 imx8mn-ddr4-evk-rm67199.dtb
40658 imx8mn-ddr4-evk-root.dtb
41317 imx8mn-ddr4-evk-rpmsg.dtb
40072 imx8mn-ddr4-evk-usd-wifi.dtb
43504 imx8mn-evk-8mic-revE.dtb
42018 imx8mn-evk-ak5558.dtb
41986 imx8mn-evk.dtb
3071 imx8mn-evk-inmate.dtb .Trash-1000/
42591 imx8mn-evk-root.dtb
43182 imx8mn-evk-rpmsg.dtb
6528 imx8mn_m7_TCM_hello_world.bin
17456 imx8mn_m7_TCM_rpmsg_lite_pingpong_rtos_linux_remote.bin
16848 imx8mn_m7_TCM_rpmsg_lite_str_echo_rtos.bin
36608 imx8mn_m7_TCM_sai_low_power_audio.bin
2113136 tee.bin
22 file(s), 1 dir(s)Now, set the device tree to memory so it is loaded in subsequent power on and off cycles of the EVK. Use the set environment and save environment commands for this. Then, just instruct U-boot to boot the EVK.
setenv ftd_file imx8mn-ddr4-evk-rm67199-2.dtb
saveenv
bootThis is how the panel image should like after the completion of the process.
I realized that the panel is responding to touch after I pressed the NXP and terminal icons that appear on the desktop environment of the BSP ( left-down corner of the above image). However, the cursor cannot be dragged across the screen with bare fingers. Moreover, some menus of the NXP demos that I was able to launch were not clickable unless I used a mouse. believe this problem might be explained as the touch support needs further calibrated. Or that is the problem or my hands are too big :-)
Further debug notesI was not able to make the panel to work with a newest NXP BSP (5.10.35) as the panel driver fails to load with this device tree workaround.
[ 2.305382] imx-drm 32c00000.bus:display-subsystem: bound imx-lcdif-crtc.0 (ops lcdif_crtc_ops)
[ 2.314226] imx_sec_dsim_drv 32e10000.dsi_controller: version number is 0x1060200
[ 2.321746] imx_sec_dsim_drv 32e10000.dsi_controller: Failed to attach bridge: 32e10000.dsi_controller
[ 2.331058] imx_sec_dsim_drv 32e10000.dsi_controller: failed to bind sec dsim bridge: -19I am making this comment hoping that a more experienced reader may provide his insight on what might be the workaround. But I am suspecting that another device tree must be provided by NXP so this can be fixed. Hopefully, this will happen on future releases.
I am also attaching the modetest output of the panel working with the 5.4.70.2.3.0 BSP working with the OLED1A panel. As nothing was shown with 5.10 release.
root@imx8mnevk:/sys/class/drm# modetest imx-drm
trying to open device 'i915'...failed
trying to open device 'amdgpu'...failed
trying to open device 'radeon'...failed
trying to open device 'nouveau'...failed
trying to open device 'vmwgfx'...failed
trying to open device 'omapdrm'...failed
trying to open device 'exynos'...failed
trying to open device 'tilcdc'...failed
trying to open device 'msm'...failed
trying to open device 'sti'...failed
trying to open device 'tegra'...failed
trying to open device 'imx-drm'...done
Encoders:
id crtc type possible crtcs possible clones
34 33 DSI 0x00000001 0xffffffff
Connectors:
id encoder status name size (mm) modes encoders
35 34 connected DSI-1 68x121 1 34
modes:
index name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
#0 1080x1920 60.02 1080 1100 1102 1136 1920 1930 1932 1936 132000 flags: nhsync, nvsync; type: preferred, driver
props:
1 EDID:
flags: immutable blob
blobs:
value:
2 DPMS:
flags: enum
enums: On=0 Standby=1 Suspend=2 Off=3
value: 0
5 link-status:
flags: enum
enums: Good=0 Bad=1
value: 0
6 non-desktop:
flags: immutable range
values: 0 1
value: 0
4 TILE:
flags: immutable blob
blobs:
value:
CRTCs:
id fb pos size
33 38 (0,0) (1080x1920)
#0 1080x1920 60.02 1080 1100 1102 1136 1920 1930 1932 1936 132000 flags: nhsync, nvsync; type: preferred, driver
props:
24 VRR_ENABLED:
flags: range
values: 0 1
value: 0
Planes:
id crtc fb CRTC x,y x,y gamma size possible crtcs
31 33 38 0,0 0,0 0 0x00000001
formats: XR24 AR24 RG16 XB24 AB24 RX24 RA24 AR15 XR15 AB15 XB15 BG16
props:
8 type:
flags: immutable enum
enums: Overlay=0 Primary=1 Cursor=2
value: 1
32 zpos:
flags: immutable range
values: 0 0
value: 0
Frame buffers:
id size pitchFinally, just for helping other readers that might experience issues while loading the device tree for the OLED1A, I am including this snapshot. It shows that panel dtb was parsed by the kernel and named card1-DSI-1:
root@imx8mnevk:/sys/class/drm# ls
card0 card1 card1-DSI-1 renderD128 versionThe MX8-DSI-OLED1A presents the same problem that motivated this project while I test it on other NXP's Android Release (11 and below). Hopefully, the device tree provided snippet provided would work for creating a dtb for that operating system. Stay tuned for a latter project on this topic!
Suggested materialThis post on Yocto project community elaborates how a kernel patch can be created for a new device tree.
https://www.yoctoproject.org/pipermail/yocto/2019-May/045115.html
Official device tree specification:
https://www.yoctoproject.org/pipermail/yocto/2019-May/045115.html
Device tree made easy (NXP):
https://community.nxp.com/t5/NXP-Training-Content/Device-Tree-Made-Easy/ta-p/1114330
Introduction to device trees (NXP):
https://www.nxp.com/docs/en/application-note/AN5125.pdf
A cool introduction for device trees by Thomas Pettazzoni (Bootlin):
Comments