BSP porting guide: from a I.mx6q reference Board to a Custom board (in Yocto project)

Document created by Omar Pighi on Mar 24, 2014Last modified by Omar Pighi on Apr 30, 2014
Version 11Show Document
  • View in full screen mode

With last LTIB - BSP release there was an interesting and very usefull document (attached here)


i.MX 6Dual/6Quad BSP Porting Guide

Document Number: IMX6DQBSPPG

Rev. L3.0.35_1.1.0, 01/2013



In this document there were the most used needed steps to port the BSP from a reference board (i will take as example the IMX6q sabresd) to a Custom board. Infact the usual project path , is starting from a reference board , but a t the end i need to use a custom board (for costs , space and any other reason). So the Idea is o make a new document to do the same on the new Yocto enviroment.

Infact the step and the stuff to change are ecxatly the same, but they are to be done in different way.

When you want to make your custom board what can be different from a reference one:

1) DDR memory

2) IO usage

3) on board peripheral

4) boot source

I think these are the main issue that could change from a board to another one (with the same processor Imx6q). Following the "Yocto Project best practice guide" we need to create a new "layer" where we can fit the customized thing: uboot, dts, drivers for pheriperal, maybe customized kernel ....


So this document is intended to be a starting point where customer and freescale expert can work togheter to make this "aplication note " that is really the final step for every project based on imx6Q Yocto Project development.




Following I will try to examine the single step that needs to be configured in every board. First a brief summary then each step will be detailed with files and paths , and example modification.

I will use as example the board IMX6QsabreSD. So all the path will be referred to that board.



I)                                                                                                                Porting Bootloader



1) They first program loaded and executed from your boot source (NAND, emmc, SD etc..) is the bootloader. In our case u-boot. this program perform some basic initialization, those intializations are related to the board. But the very first thing is DDR initialization, this mean to inizialize IOMUX and DDR controller registers (Timing geometry etcc...). This initialization is done in the DCD part of the uboot image. the once we initialized the DDR the bootloader can work, than it will have to configure the IOMUX to match the peripheral used on chip and on board. And then of course it will have to load the driver (at least one UART for consolle and ethernet driver) it needs. So FIRST thing to customize for your board is the bootloader.

Using a base directory the git of u-boot the file that contain the DCD is:


the other important file is the


this second file contain several board related definition, first of all, the IOMUX configuration for the pins of IMX6Q used for soc peripheral

a third important file is the include one here there are several important define such as mem size.



So you need to make a copy of those files (in the new board dir, or in the include/configs for .h files) renaming them of course with the name of your custom board. Then you need also to add the new board to the Makefiles and source tree , as described following:

(take also as a reference he chapter 1.2 and 1.3 of the attached document and this link;a=blob_plain;f=README;hb=HEAD).


1. Add a new configuration option for your board to the toplevel  "boards.cfg" file, using the existing entries as examples.  Follow the instructions there to keep the boards in order.

2. Create a new directory to hold your board specific code. Add any files you need. In your board directory, you will need at least the "Makefile", a "<board>.c"

3. Create a new configuration file "include/configs/<board>.h" for  your board

4. Debug and solve any problems that might arise.


At this point if we did all the modification we need to u-boot we have to create our fsl-myboard layer to add our "patch" to the u-boot tree. those patched u-boot will be compiled and deployed just for the new MACHINE (our custom board).



II)                                                                                                                Creating DTS tree for kernel



1)Then you need to create the DTS files for your board as well, those files are a description of your board (including) SOC , mem etc etc... used by the kernel. those files are in the kernel tree in arch/arm/boot/dts.

Take a look  this is a good starting point.

Another good reference is: Device Tree - , here you can find a lot of link and reference to a more deep understanding.

The official wiki:

And interesting:

In our example the reference dts will be of course the imx6q-sabresd.dts(in the kernel tree source path /arch/arm/boot/dts), this file include and refer other "dts" files that we will see .

Well the starting point of this dts tree is, in this example, the imx6q-sabresd.dts, it recalls other files:


imx6q-sabresd.dts ---------------> imx6qdl-sabresd.dtsi

                          |----------------> imx6q.dtsi

                                                           |--------------------> imx6q-pinfunc.h

                                                           |--------------------> imx6qdl.dtsi

                                                                                                  |-----------------------> skeleton.dtsi

                                                                                                  |-----------------------> dt-bindings/gpio/gpio.h


the file wiht the name that does not contain "sabresd" are not board related but Soc related so we can keep as is even for our custom board, so the only file we need to touch are imx6q-sabresd.dts and imx6qdl-sadresd.dtsi. As we did for u-boot porting, we will copy these files and create new ones with names as imx6q-cutomboard.dts and imx6qdl-customboard.dtsi in the same dir.

Now we will examine them in detail.

11 people found this helpful