Skip to content

Commit ede6186

Browse files
zejiang0jasondanieldegrasse
zejiang0jason
authored and
danieldegrasse
committed
modules: hal_nxp: mcux: Add MCUX SDK NG glue layer readme
Add the readme to show the implementation. Signed-off-by: Jason Yu <zejiang.yu@nxp.com>
1 parent f8871d5 commit ede6186

File tree

2 files changed

+216
-1
lines changed

2 files changed

+216
-1
lines changed

‎modules/hal_nxp/mcux/mcux-sdk-ng/fixup.cmake

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22
#
33
# SPDX-License-Identifier: Apache-2.0
44

5-
# Expose the driver header include path, so that the shim driver can use them.
5+
# SDK driver headers are also used out of hal_nxp module, for example
6+
# <zephyr>/soc/nxp/imxrt/imxrt118x/soc.c includes fsl_clock.h, fsl_pmu.h.
7+
# So expose the driver header include path, make the shim driver can use them.
68
get_target_property(MCUXSDK_INCLUDE_DIRS ${MCUX_SDK_PROJECT_NAME} INTERFACE_INCLUDE_DIRECTORIES)
79
if(NOT MCUXSDK_INCLUDE_DIRS STREQUAL MCUXSDK_INCLUDE_DIRS-NOTFOUND)
810
zephyr_include_directories(${MCUXSDK_INCLUDE_DIRS})

‎modules/hal_nxp/mcux/readme.md

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# MCUX SDK and Zephyr Integration
2+
3+
This document describes how NXP MCUX SDK code integrates with Zephyr.
4+
Currently, MCUX SDK NG (Next Generation) is primarily used.
5+
Some SOCs supported by Zephyr are not supported by MCUX SDK NG,
6+
these SOCs still use MCUX SDK NG drivers. MCUX SDK provides source code,
7+
and this glue layer provides Kconfig and CMake files to select and
8+
configure MCUX source code.
9+
10+
## Folder Structure
11+
12+
```
13+
mcux
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+
32+
MCUX 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+
37+
MCUX SDK's code is modularized and controlled by separate CMake files.
38+
A typical MCUX SDK NG driver CMake file looks like this:
39+
40+
```cmake
41+
if(CONFIG_MCUX_COMPONENT_driver.acmp)
42+
43+
mcux_add_source(SOURCES fsl_acmp.c fsl_acmp.h)
44+
45+
mcux_add_include(INCLUDES .)
46+
47+
endif()
48+
```
49+
50+
When the variable `CONFIG_MCUX_COMPONENT_driver.acmp` is enabled, the driver source
51+
files `fsl_acmp.c` and `fsl_acmp.h` are added to the project, along with
52+
their include path.
53+
54+
The functions `mcux_add_source` and `mcux_add_include` are defined in MCUX SDK NG
55+
CMake extensions, located in the folder
56+
*<zephyr_workspace>/modules/hal/nxp/mcux/mcux-sdk-ng/cmake*.
57+
58+
These functions provide additional features, such as adding contents
59+
based on specific conditions.
60+
61+
Here's an example:
62+
63+
```cmake
64+
if (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 . )
76+
endif()
77+
```
78+
79+
In this example, different libraries are added to the project based on
80+
the selected toolchain.
81+
82+
#### Device Level CMake Files
83+
84+
Here are example folder structures for two SOCs: MIMXRT633S (single-core) and
85+
MIMXRT685S (dual-core with 'cm33' and 'hifi4' cores).
86+
87+
```
88+
RT600/
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+
121+
Key differences between single-core and dual-core SOC folders:
122+
1. Dual-core SOCs have separate folders for each core (cm33, hifi4)
123+
2. Dual-core SOCs have separate header and system files for
124+
each core with distinct suffixes (MIMXRT685S_cm33.h, MIMXRT685S_dsp.h)
125+
126+
Each SOC provides a "variable.cmake" file allowing upper layer CMake files
127+
to determine appropriate names for different SOCs or cores. Upper layer
128+
CMake files only need to provide `DEVICE` (SOC name, e.g., `MIMXRT685S`)
129+
and `core_id` (subfolder name like `cm33`, `hifi4`; empty for single-core SOCs).
130+
131+
**NOTE**:
132+
In MCUX SDK NG, `core_id` and `core_id_suffix_name` are distinct concepts.
133+
Take RT685S as an example:
134+
- `core_id`: matches subfolder names (`cm33`, `hifi4`)
135+
- `core_id_suffix_name`: matches header file suffixes (`cm33`, `dsp`)
136+
137+
While these are typically identical, some exceptions exist due to
138+
historical reasons (e.g., RT685 HIFI4). Future SOCs will maintain
139+
consistency 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+
164+
To use MCUX SDK NG code, include these files in the top-level CMakeLists.txt:
165+
166+
```cmake
167+
include(basic.cmake)
168+
169+
include(middleware/middleware.cmake)
170+
include(components/components.cmake)
171+
include(drivers/drivers.cmake)
172+
include(device/device.cmake)
173+
174+
include(fixup.cmake)
175+
```
176+
177+
#### MCUX SDK NG Device Level Code
178+
179+
MCUX SDK NG device CMake files require `DEVICE` and `core_id`.
180+
Zephyr's `CONFIG_SOC` corresponds to MCUX SDK's `DEVICE`, while
181+
`CONFIG_MCUX_CORE_SUFFIX` corresponds to MCUX SDK's `core_id_suffix_name`.
182+
Since these are typically identical, the glue layer converts
183+
`CONFIG_MCUX_CORE_SUFFIX` to `core_id` before passing it to
184+
MCUX SDK NG CMake. Exceptions are handled through hard-coding
185+
in the glue layer.
186+
187+
This functionality is implemented in
188+
[device/device.cmake](./mcux-sdk-ng/device/device.cmake).
189+
190+
#### MCUX SDK NG Unsupported SOCs
191+
192+
These SOCs utilize MCUX SDK NG code for latest features and bug fixes,
193+
along with device-specific code like header files.
194+
195+
Their [CMakeLists.txt](./mcux-sdk/CMakeLists.txt) typically follows this pattern:
196+
197+
```cmake
198+
include(basic.cmake)
199+
200+
include(middleware/middleware.cmake)
201+
include(components/components.cmake)
202+
include(drivers/drivers.cmake)
203+
204+
# ...
205+
# Device specific settings
206+
# ...
207+
208+
include(fixup.cmake)
209+
```
210+
211+
For these SOCs, `basic.cmake` and `fixup.cmake` are required,
212+
while other CMake files (`middleware.cmake`, `components.cmake`, `drivers.cmake`)
213+
are optional.

0 commit comments

Comments
 (0)