source: rtems-docs/user/bsps/arm/imxrt.rst @ 929d0a9

Last change on this file since 929d0a9 was 929d0a9, checked in by Christian Mauderer <christian.mauderer@…>, on 05/04/23 at 12:39:04

user/bsps/imxrt: Add new BSP variant

Add information about the new i.MXRT1166 BSP. Rework some parts that
have been changed during or as preparation for that variant:

  • The BSP now adapts to the Chip variant. It's no longer necessary to overwrite the PLL settings in an application.
  • Improve documentation on how to adapt to different boards.
  • Add Update the i.MXRT chapter so that it represents the new i.MXRT1166 BSP.
  • Add information about mcux-sdk and how to handle it.
  • Property mode set to 100644
File size: 10.5 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2020 embedded brains GmbH & Co. KG
4.. Copyright (C) 2020 Christian Mauderer
5
6imxrt (NXP i.MXRT)
7==================
8
9This BSP offers multiple variants. The `imxrt1052` supports the i.MXRT 1052
10processor on a IMXRT1050-EVKB (tested with rev A1). Some possibilities to adapt
11it to a custom board are described below.
12
13NOTE: The IMXRT1050-EVKB has an backlight controller that must not be enabled
14without load. Make sure to either attach a load, disable it by software or
15disable it by removing the 0-Ohm resistor on it's input.
16
17The `imxrt1166-cm7-saltshaker` supports an application specific board. Adapting
18it to another i.MXRT1166 based board works similar like for the `imxrt1052` BSP.
19
20Build Configuration Options
21---------------------------
22
23Please see the documentation of the `IMXRT_*` and `BSP_*` configuration options
24for that. You can generate a default set of options with::
25
26  ./waf bspdefaults --rtems-bsps=arm/imxrt1052 > config.ini
27
28Adapting to a different board
29-----------------------------
30
31This is only a short overview for the most important steps to adapt the BSP to
32another board. Details for most steps follow further below.
33
34#. The device tree has to be adapted to fit the target hardware.
35#. A matching clock configuration is necessary (simplest method is to generate
36   it with the NXP PinMux tool)
37#. The `dcd_data` has to be adapted. That is used for example to initialize
38   SDRAM.
39#. `imxrt_flexspi_config` has to be adapted to match the Flash connected to
40   FlexSPI (if that is used).
41#. `BOARD_InitDEBUG_UARTPins` should be adapted to match the used system
42   console.
43
44Boot Process of IMXRT1050-EVKB
45------------------------------
46
47There are two possible boot processes supported:
48
491) The ROM code loads a configuration from HyperFlash (connected to FlexSPI),
50   does some initialization (based on device configuration data (DCD)) and then
51   starts the application. This is the default case. `linkcmds.flexspi` is used
52   for this case.
53
542) Some custom bootloader does the basic initialization, loads the application
55   to SDRAM and starts it from there. Select the `linkcmds.sdram` for this.
56
57For programming the HyperFlash in case 1, you can use the on board debugger
58integrated into the IMXRT1050-EVKB. You can generate a flash image out of a
59compiled RTEMS application with for example::
60
61  arm-rtems@rtems-ver-major@-objcopy -O binary build/arm/imxrt1052/testsuites/samples/hello.exe hello.bin
62
63Then just copy the generated binary to the mass storage provided by the
64debugger. Wait a bit till the mass storage vanishes and re-appears. After that,
65reset the board and the newly programmed application will start.
66
67NOTE: It seems that there is a bug on at least some of the on board debuggers.
68They can't write more than 1MB to the HyperFlash. If your application is bigger
69than that (like quite some of the applications in libbsd), you should use an
70external debugger or find some alternative programming method.
71
72For debugging: Create a special application with a `while(true)` loop at end of
73`bsp_start_hook_1`. Load that application into flash. Then remove the loop
74again, build your BSP for SDRAM and use a debugger to load the application into
75SDRAM after the BSP started from flash did the basic initialization.
76
77Flash Image
78-----------
79
80For booting from a HyperFlash (or other storage connected to FlexSPI), the ROM
81code of the i.MXRT first reads some special flash header information from a
82fixed location of the connected flash device. This consists of the Image vector
83table (IVT), Boot data and Device configuration data (DCD).
84
85In RTEMS, these flash headers are generated using some C-structures. If you use
86a board other than the IMXRT1050-EVKB, those structures have to be adapted. To
87do that re-define the following variables in your application (you only need the
88ones that need different values):
89
90.. code-block:: c
91
92  #include <bsp/flash-headers.h>
93  const uint8_t imxrt_dcd_data[] =
94      { /* Your DCD data here */ };
95  const ivt imxrt_image_vector_table =
96      { /* Your IVT here */ };
97  const BOOT_DATA_T imxrt_boot_data =
98      { /* Your boot data here */ };
99  const flexspi_nor_config_t imxrt_flexspi_config =
100      { /* Your FlexSPI config here */ };
101
102You can find the default definitions in `bsps/arm/imxrt/start/flash-*.c`. Take a
103look at the `i.MX RT1050 Processor Reference Manual, Rev. 4, 12/2019` chapter
104`9.7 Program image` or `i.MX RT1166 Processor Reference Manual, Rev. 0, 05/2021`
105chapter `10.7 Program image` for details about the contents.
106
107FDT
108---
109
110The BSP uses a FDT based initialization. The FDT is linked into the application.
111You can find the default FDT used in the BSPs in `bsps/arm/imxrt/dts`. The FDT
112is split up into two parts. The controller specific part is put into an `dtsi`
113file. The board specific one is in the dts file. Both are installed together
114with normal headers into
115`${PREFIX}/arm-rtems@rtems-ver-major@/${BSP}/lib/include`. You can use that to
116create your own device tree based on that. Basically use something like::
117
118  /dts-v1/;
119
120  #include <imxrt/imxrt1050-pinfunc.h>
121  #include <imxrt/imxrt1050.dtsi>
122
123  &lpuart1 {
124          pinctrl-0 = <&pinctrl_lpuart1>;
125          status = "okay";
126  };
127
128  &chosen {
129          stdout-path = &lpuart1;
130  };
131
132  /* put your further devices here */
133
134  &iomuxc {
135          pinctrl_lpuart1: lpuart1grp {
136                  fsl,pins = <
137                          IMXRT_PAD_GPIO_AD_B0_12__LPUART1_TX     0x8
138                          IMXRT_PAD_GPIO_AD_B0_13__LPUART1_RX     0x13000
139                  >;
140          };
141
142          /* put your further pinctrl groups here */
143  };
144
145You can then convert your FDT into a C file with (replace `YOUR.dts` and similar
146with your FDT source names):
147
148.. code-block:: none
149
150  sh> arm-rtems@rtems-ver-major@-cpp -P -x assembler-with-cpp \
151             -I ${PREFIX}/arm-rtems@rtems-ver-major@/imxrt1052/lib/include \
152             -include "YOUR.dts" /dev/null | \
153         dtc -O dtb -o "YOUR.dtb" -b 0 -p 64
154  sh> rtems-bin2c -A 8 -C -N imxrt_dtb "YOUR.dtb" "YOUR.c"
155
156You'll get a C file which defines the `imxrt_dtb` array. Make sure that your new
157C file is compiled and linked into the application. It will overwrite the
158existing definition of the `imxrt_dtb` in RTEMS.
159
160Clock Driver
161------------
162
163The clock driver uses the generic `ARMv7-M Clock`.
164
165IOMUX
166-----
167
168The i.MXRT IOMUXC is initialized based on the FDT. For that, the `pinctrl-0`
169fields of all devices with a status of `ok` or `okay` will be parsed.
170
171Console Driver
172--------------
173
174LPUART drivers are registered based on the FDT. The special `rtems,path`
175attribute defines where the device file for the console is created.
176
177The `stdout-path` in the `chosen` node determines which LPUART is used for the
178console.
179
180I2C Driver
181----------
182
183I2C drivers are registered based on the FDT. The special `rtems,path` attribute
184defines where the device file for the I2C bus is created.
185
186Limitations:
187
188* Only basic I2C is implemented. This is mostly a driver limitation and not a
189  hardware one.
190
191SPI Driver
192----------
193
194SPI drivers are registered based on the FDT. The special `rtems,path` attribute
195defines where the device file for the SPI bus is created.
196
197Note that the SPI-pins on the evaluation board are shared with the SD card.
198Populate R278, R279, R280, R281 on the IMXRT1050-EVKB (Rev A) to use the SPI
199pins on the Arduino connector.
200
201Limitations:
202
203* Only a basic SPI driver is implemented. This is mostly a driver limitation and
204  not a hardware one.
205
206Network Interface Driver
207------------------------
208
209The network interface driver is provided by the `libbsd`. It is initialized
210according to the device tree.
211
212Note on the hardware: The i.MXRT1050 EVKB maybe has a wrong termination of the
213RXP, RXN, TXP and TXN lines. The resistors R126 through R129 maybe shouldn't be
214populated because the used KSZ8081RNB already has an internal termination.
215Ethernet does work on short distance anyway. But keep it in mind in case you
216have problems. Source:
217https://community.nxp.com/t5/i-MX-RT/Error-in-IMXRT1050-EVKB-and-1060-schematic-ethernet/m-p/835540#M1587
218
219NXP SDK files
220-------------
221
222A lot of peripherals are currently not yet supported by RTEMS drivers. The NXP
223SDK offers drivers for these. For convenience, the BSP compiles the drivers from
224the SDK. But please note that they are not tested and maybe won't work out of
225the box. Everything that works with interrupts most likely needs some special
226treatment.
227
228The SDK files are imported to RTEMS from the NXP mcux-sdk git repository that
229you can find here: https://github.com/nxp-mcuxpresso/mcux-sdk/
230
231The directory structure has been preserved and all files are in a
232`bsps/arm/imxrt/mcux-sdk` directory. All patches to the files are marked with
233`#ifdef __rtems__` markers.
234
235The suggested method to import new or updated files is to apply all RTEMS
236patches to the mcux-sdk repository, rebase them to the latest mcux-sdk release
237and re-import the files. The new base revision should be mentioned in the commit
238description to make future updates simpler.
239
240A import helper script (that might or might not work on newer releases of the
241mcux-sdk) can be found here:
242https://raw.githubusercontent.com/c-mauderer/nxp-mcux-sdk/d21c3e61eb8602b2cf8f45fed0afa50c6aee932f/export_to_RTEMS.py
243
244Clocks and SDRAM
245----------------
246
247The clock configuration support is quite rudimentary. The same is true for
248SDRAM. It mostly relies on the DCD and on a static clock configuration that is
249taken from the NXP SDK example projects.
250
251If you need to adapt the DCD or clock config to support a different hardware,
252you should generate these files using the NXP MCUXpresso Configuration Tools.
253You can add the generated files to your application to overwrite the default
254RTEMS ones or you can add them to RTEMS in a new BSP variant.
255
256As a special case, the imxrt1052 BSP will adapt it's PLL setting based on the
257chip variant. The commercial variant of the i.MXRT1052 will use a core clock of
258600MHz for the ARM core. The industrial variants only uses 528MHz. For other
259chip or BSP variants, you should adapt the files generated with the MCUXpresso
260Configuration Tools.
261
262Caveats
263-------
264
265* The MPU settings are currently quite permissive.
266
267* There is no power management support.
268
269* On the i.MXRT1166, sleeping of the Cortex M7 can't be disabled even for
270  debugging purposes. That makes it hard for a debugger to access the
271  controller. To make debugging a bit easier, it's possible to overwrite the
272  idle thread with the following one in the application:
273
274    .. code-block:: c
275
276      void * _CPU_Thread_Idle_body(uintptr_t ignored)
277      {
278        (void)ignored;
279        while (true) {
280          /* void */
281        }
282      }
Note: See TracBrowser for help on using the repository browser.