readme.md
1# MCUX SDK and Zephyr Integration
2
3This document describes how NXP MCUX SDK code integrates with Zephyr.
4Currently, MCUX SDK NG (Next Generation) is primarily used.
5Some SOCs supported by Zephyr are not supported by MCUX SDK NG,
6these SOCs still use MCUX SDK NG drivers. MCUX SDK provides source code,
7and this glue layer provides Kconfig and CMake files to select and
8configure MCUX source code.
9
10## Folder Structure
11
12```
13mcux
14├── CMakeLists.txt # CMake entry point for MCUX SDK glue layer
15├── Kconfig.mcux # Kconfig options for configuring MCUX SDK
16├── mcux-sdk
17│ └── CMakeLists.txt # CMake entry for SOCs not supported by SDK NG
18└── mcux-sdk-ng
19 ├── basic.cmake # Basic settings and functions for MCUX SDK NG
20 ├── fixup.cmake # Fixes to ensure MCUX SDK NG works with Zephyr
21 ├── CMakeLists.txt # CMake entry for MCUX SDK NG supported SOCs
22 ├── components # Files for MCUX SDK NG components
23 ├── device # Files for MCUX SDK NG device
24 ├── drivers # Files for MCUX SDK NG drivers
25 └── middleware # Files for MCUX SDK NG middleware
26```
27
28## Architecture
29
30### MCUX SDK NG CMake Architecture
31
32MCUX SDK NG code is located in the folder:
33*<zephyr_workspace>/modules/hal/nxp/mcux/mcux-sdk-ng*.
34
35#### Adding Contents to Project
36
37MCUX SDK's code is modularized and controlled by separate CMake files.
38A typical MCUX SDK NG driver CMake file looks like this:
39
40```cmake
41if(CONFIG_MCUX_COMPONENT_driver.acmp)
42
43 mcux_add_source(SOURCES fsl_acmp.c fsl_acmp.h)
44
45 mcux_add_include(INCLUDES .)
46
47endif()
48```
49
50When the variable `CONFIG_MCUX_COMPONENT_driver.acmp` is enabled, the driver source
51files `fsl_acmp.c` and `fsl_acmp.h` are added to the project, along with
52their include path.
53
54The functions `mcux_add_source` and `mcux_add_include` are defined in MCUX SDK NG
55CMake extensions, located in the folder
56*<zephyr_workspace>/modules/hal/nxp/mcux/mcux-sdk-ng/cmake*.
57
58These functions provide additional features, such as adding contents
59based on specific conditions.
60
61Here's an example:
62
63```cmake
64if (CONFIG_MCUX_COMPONENT_driver.fro_calib)
65 mcux_add_source( SOURCES fsl_fro_calib.h )
66 mcux_add_library(
67 LIBS ../iar/iar_lib_fro_calib_cm33_core0.a
68 TOOLCHAINS iar)
69 mcux_add_library(
70 LIBS ../arm/keil_lib_fro_calib_cm33_core0.lib
71 TOOLCHAINS mdk)
72 mcux_add_library(
73 LIBS ../gcc/libfro_calib_hardabi.a
74 TOOLCHAINS armgcc)
75 mcux_add_include( INCLUDES . )
76endif()
77```
78
79In this example, different libraries are added to the project based on
80the selected toolchain.
81
82#### Device Level CMake Files
83
84Here are example folder structures for two SOCs: MIMXRT633S (single-core) and
85MIMXRT685S (dual-core with 'cm33' and 'hifi4' cores).
86
87```
88RT600/
89├── MIMXRT633S
90│ ├── CMakeLists.txt # CMake entry for MIMXRT633S
91│ ├── variable.cmake
92│ ├── drivers/ # SOC specific drivers
93│ ├── arm/ # Files for ARM toolchains (MDK)
94│ ├── gcc/ # Files for armgcc
95│ ├── iar/ # Files for IAR
96│ ├── MIMXRT633S.h # SOC header
97│ ├── system_MIMXRT633S.c
98│ └── system_MIMXRT633S.h
99└── MIMXRT685S
100 ├── CMakeLists.txt
101 ├── variable.cmake
102 ├── drivers/
103 ├── arm/
104 ├── gcc/
105 ├── iar/
106 ├── xtensa/
107 ├── cm33 # CMake files for cm33 core
108 │ ├── CMakeLists.txt
109 │ └── variable.cmake
110 ├── hifi4 # CMake files for hifi4 core
111 │ ├── CMakeLists.txt
112 │ └── variable.cmake
113 ├── MIMXRT685S_cm33.h
114 ├── MIMXRT685S_dsp.h
115 ├── system_MIMXRT685S_cm33.c
116 ├── system_MIMXRT685S_cm33.h
117 ├── system_MIMXRT685S_dsp.c
118 └── system_MIMXRT685S_dsp.h
119```
120
121Key differences between single-core and dual-core SOC folders:
1221. Dual-core SOCs have separate folders for each core (cm33, hifi4)
1232. Dual-core SOCs have separate header and system files for
124 each core with distinct suffixes (MIMXRT685S_cm33.h, MIMXRT685S_dsp.h)
125
126Each SOC provides a "variable.cmake" file allowing upper layer CMake files
127to determine appropriate names for different SOCs or cores. Upper layer
128CMake files only need to provide `DEVICE` (SOC name, e.g., `MIMXRT685S`)
129and `core_id` (subfolder name like `cm33`, `hifi4`; empty for single-core SOCs).
130
131**NOTE**:
132In MCUX SDK NG, `core_id` and `core_id_suffix_name` are distinct concepts.
133Take RT685S as an example:
134- `core_id`: matches subfolder names (`cm33`, `hifi4`)
135- `core_id_suffix_name`: matches header file suffixes (`cm33`, `dsp`)
136
137While these are typically identical, some exceptions exist due to
138historical reasons (e.g., RT685 HIFI4). Future SOCs will maintain
139consistency between these names.
140
141### Integration with Zephyr
142
143#### MCUX SDK NG Glue Layer
144
145- [basic.cmake](./mcux-sdk-ng/basic.cmake): Provides basic settings and functions for MCUX SDK NG,
146 including necessary CMake extensions and additional function definitions.
147
148- CMake Files for MCUX SDK NG code selection:
149 - [device.cmake](./mcux-sdk-ng/device/device.cmake)
150 - [components.cmake](./mcux-sdk-ng/components/components.cmake)
151 - [drivers.cmake](./mcux-sdk-ng/drivers/drivers.cmake)
152 - [middleware.cmake](./mcux-sdk-ng/middleware/middleware.cmake)
153
154 Each file manages its corresponding MCUX SDK NG code. Example content:
155
156 ```cmake
157 set_variable_ifdef(CONFIG_SENSOR_MCUX_ACMP CONFIG_MCUX_COMPONENT_driver.acmp)
158 ```
159 When `CONFIG_SENSOR_MCUX_ACMP` is enabled, the ACMP driver is added to the project.
160
161- [fixup.cmake](./mcux-sdk-ng/fixup.cmake): Contains fixes for MCUX SDK NG
162 compatibility with Zephyr.
163
164To use MCUX SDK NG code, include these files in the top-level CMakeLists.txt:
165
166```cmake
167include(basic.cmake)
168
169include(middleware/middleware.cmake)
170include(components/components.cmake)
171include(drivers/drivers.cmake)
172include(device/device.cmake)
173
174include(fixup.cmake)
175```
176
177#### MCUX SDK NG Device Level Code
178
179MCUX SDK NG device CMake files require `DEVICE` and `core_id`.
180Zephyr's `CONFIG_SOC` corresponds to MCUX SDK's `DEVICE`, while
181`CONFIG_MCUX_CORE_SUFFIX` corresponds to MCUX SDK's `core_id_suffix_name`.
182Since these are typically identical, the glue layer converts
183`CONFIG_MCUX_CORE_SUFFIX` to `core_id` before passing it to
184MCUX SDK NG CMake. Exceptions are handled through hard-coding
185in the glue layer.
186
187This functionality is implemented in
188[device/device.cmake](./mcux-sdk-ng/device/device.cmake).
189
190#### MCUX SDK NG Unsupported SOCs
191
192These SOCs utilize MCUX SDK NG code for latest features and bug fixes,
193along with device-specific code like header files.
194
195Their [CMakeLists.txt](./mcux-sdk/CMakeLists.txt) typically follows this pattern:
196
197```cmake
198include(basic.cmake)
199
200include(middleware/middleware.cmake)
201include(components/components.cmake)
202include(drivers/drivers.cmake)
203
204# ...
205# Device specific settings
206# ...
207
208include(fixup.cmake)
209```
210
211For these SOCs, `basic.cmake` and `fixup.cmake` are required,
212while other CMake files (`middleware.cmake`, `components.cmake`, `drivers.cmake`)
213are optional.