diff --git a/modules/hal_nxp/mcux/mcux-sdk-ng/fixup.cmake b/modules/hal_nxp/mcux/mcux-sdk-ng/fixup.cmake index 4f19089626f..7bd51e297a0 100644 --- a/modules/hal_nxp/mcux/mcux-sdk-ng/fixup.cmake +++ b/modules/hal_nxp/mcux/mcux-sdk-ng/fixup.cmake @@ -2,7 +2,9 @@ # # SPDX-License-Identifier: Apache-2.0 -# Expose the driver header include path, so that the shim driver can use them. +# SDK driver headers are also used out of hal_nxp module, for example +# /soc/nxp/imxrt/imxrt118x/soc.c includes fsl_clock.h, fsl_pmu.h. +# So expose the driver header include path, make the shim driver can use them. get_target_property(MCUXSDK_INCLUDE_DIRS ${MCUX_SDK_PROJECT_NAME} INTERFACE_INCLUDE_DIRECTORIES) if(NOT MCUXSDK_INCLUDE_DIRS STREQUAL MCUXSDK_INCLUDE_DIRS-NOTFOUND) zephyr_include_directories(${MCUXSDK_INCLUDE_DIRS}) diff --git a/modules/hal_nxp/mcux/readme.md b/modules/hal_nxp/mcux/readme.md new file mode 100644 index 00000000000..dd6896b455d --- /dev/null +++ b/modules/hal_nxp/mcux/readme.md @@ -0,0 +1,213 @@ +# MCUX SDK and Zephyr Integration + +This document describes how NXP MCUX SDK code integrates with Zephyr. +Currently, MCUX SDK NG (Next Generation) is primarily used. +Some SOCs supported by Zephyr are not supported by MCUX SDK NG, +these SOCs still use MCUX SDK NG drivers. MCUX SDK provides source code, +and this glue layer provides Kconfig and CMake files to select and +configure MCUX source code. + +## Folder Structure + +``` +mcux +├── CMakeLists.txt # CMake entry point for MCUX SDK glue layer +├── Kconfig.mcux # Kconfig options for configuring MCUX SDK +├── mcux-sdk +│ └── CMakeLists.txt # CMake entry for SOCs not supported by SDK NG +└── mcux-sdk-ng + ├── basic.cmake # Basic settings and functions for MCUX SDK NG + ├── fixup.cmake # Fixes to ensure MCUX SDK NG works with Zephyr + ├── CMakeLists.txt # CMake entry for MCUX SDK NG supported SOCs + ├── components # Files for MCUX SDK NG components + ├── device # Files for MCUX SDK NG device + ├── drivers # Files for MCUX SDK NG drivers + └── middleware # Files for MCUX SDK NG middleware +``` + +## Architecture + +### MCUX SDK NG CMake Architecture + +MCUX SDK NG code is located in the folder: +*/modules/hal/nxp/mcux/mcux-sdk-ng*. + +#### Adding Contents to Project + +MCUX SDK's code is modularized and controlled by separate CMake files. +A typical MCUX SDK NG driver CMake file looks like this: + +```cmake +if(CONFIG_MCUX_COMPONENT_driver.acmp) + + mcux_add_source(SOURCES fsl_acmp.c fsl_acmp.h) + + mcux_add_include(INCLUDES .) + +endif() +``` + +When the variable `CONFIG_MCUX_COMPONENT_driver.acmp` is enabled, the driver source +files `fsl_acmp.c` and `fsl_acmp.h` are added to the project, along with +their include path. + +The functions `mcux_add_source` and `mcux_add_include` are defined in MCUX SDK NG +CMake extensions, located in the folder +*/modules/hal/nxp/mcux/mcux-sdk-ng/cmake*. + +These functions provide additional features, such as adding contents +based on specific conditions. + +Here's an example: + +```cmake +if (CONFIG_MCUX_COMPONENT_driver.fro_calib) + mcux_add_source( SOURCES fsl_fro_calib.h ) + mcux_add_library( + LIBS ../iar/iar_lib_fro_calib_cm33_core0.a + TOOLCHAINS iar) + mcux_add_library( + LIBS ../arm/keil_lib_fro_calib_cm33_core0.lib + TOOLCHAINS mdk) + mcux_add_library( + LIBS ../gcc/libfro_calib_hardabi.a + TOOLCHAINS armgcc) + mcux_add_include( INCLUDES . ) +endif() +``` + +In this example, different libraries are added to the project based on +the selected toolchain. + +#### Device Level CMake Files + +Here are example folder structures for two SOCs: MIMXRT633S (single-core) and +MIMXRT685S (dual-core with 'cm33' and 'hifi4' cores). + +``` +RT600/ +├── MIMXRT633S +│ ├── CMakeLists.txt # CMake entry for MIMXRT633S +│ ├── variable.cmake +│ ├── drivers/ # SOC specific drivers +│ ├── arm/ # Files for ARM toolchains (MDK) +│ ├── gcc/ # Files for armgcc +│ ├── iar/ # Files for IAR +│ ├── MIMXRT633S.h # SOC header +│ ├── system_MIMXRT633S.c +│ └── system_MIMXRT633S.h +└── MIMXRT685S + ├── CMakeLists.txt + ├── variable.cmake + ├── drivers/ + ├── arm/ + ├── gcc/ + ├── iar/ + ├── xtensa/ + ├── cm33 # CMake files for cm33 core + │ ├── CMakeLists.txt + │ └── variable.cmake + ├── hifi4 # CMake files for hifi4 core + │ ├── CMakeLists.txt + │ └── variable.cmake + ├── MIMXRT685S_cm33.h + ├── MIMXRT685S_dsp.h + ├── system_MIMXRT685S_cm33.c + ├── system_MIMXRT685S_cm33.h + ├── system_MIMXRT685S_dsp.c + └── system_MIMXRT685S_dsp.h +``` + +Key differences between single-core and dual-core SOC folders: +1. Dual-core SOCs have separate folders for each core (cm33, hifi4) +2. Dual-core SOCs have separate header and system files for + each core with distinct suffixes (MIMXRT685S_cm33.h, MIMXRT685S_dsp.h) + +Each SOC provides a "variable.cmake" file allowing upper layer CMake files +to determine appropriate names for different SOCs or cores. Upper layer +CMake files only need to provide `DEVICE` (SOC name, e.g., `MIMXRT685S`) +and `core_id` (subfolder name like `cm33`, `hifi4`; empty for single-core SOCs). + +**NOTE**: +In MCUX SDK NG, `core_id` and `core_id_suffix_name` are distinct concepts. +Take RT685S as an example: +- `core_id`: matches subfolder names (`cm33`, `hifi4`) +- `core_id_suffix_name`: matches header file suffixes (`cm33`, `dsp`) + +While these are typically identical, some exceptions exist due to +historical reasons (e.g., RT685 HIFI4). Future SOCs will maintain +consistency between these names. + +### Integration with Zephyr + +#### MCUX SDK NG Glue Layer + +- [basic.cmake](./mcux-sdk-ng/basic.cmake): Provides basic settings and functions for MCUX SDK NG, + including necessary CMake extensions and additional function definitions. + +- CMake Files for MCUX SDK NG code selection: + - [device.cmake](./mcux-sdk-ng/device/device.cmake) + - [components.cmake](./mcux-sdk-ng/components/components.cmake) + - [drivers.cmake](./mcux-sdk-ng/drivers/drivers.cmake) + - [middleware.cmake](./mcux-sdk-ng/middleware/middleware.cmake) + + Each file manages its corresponding MCUX SDK NG code. Example content: + + ```cmake + set_variable_ifdef(CONFIG_SENSOR_MCUX_ACMP CONFIG_MCUX_COMPONENT_driver.acmp) + ``` + When `CONFIG_SENSOR_MCUX_ACMP` is enabled, the ACMP driver is added to the project. + +- [fixup.cmake](./mcux-sdk-ng/fixup.cmake): Contains fixes for MCUX SDK NG + compatibility with Zephyr. + +To use MCUX SDK NG code, include these files in the top-level CMakeLists.txt: + +```cmake +include(basic.cmake) + +include(middleware/middleware.cmake) +include(components/components.cmake) +include(drivers/drivers.cmake) +include(device/device.cmake) + +include(fixup.cmake) +``` + +#### MCUX SDK NG Device Level Code + +MCUX SDK NG device CMake files require `DEVICE` and `core_id`. +Zephyr's `CONFIG_SOC` corresponds to MCUX SDK's `DEVICE`, while +`CONFIG_MCUX_CORE_SUFFIX` corresponds to MCUX SDK's `core_id_suffix_name`. +Since these are typically identical, the glue layer converts +`CONFIG_MCUX_CORE_SUFFIX` to `core_id` before passing it to +MCUX SDK NG CMake. Exceptions are handled through hard-coding +in the glue layer. + +This functionality is implemented in +[device/device.cmake](./mcux-sdk-ng/device/device.cmake). + +#### MCUX SDK NG Unsupported SOCs + +These SOCs utilize MCUX SDK NG code for latest features and bug fixes, +along with device-specific code like header files. + +Their [CMakeLists.txt](./mcux-sdk/CMakeLists.txt) typically follows this pattern: + +```cmake +include(basic.cmake) + +include(middleware/middleware.cmake) +include(components/components.cmake) +include(drivers/drivers.cmake) + +# ... +# Device specific settings +# ... + +include(fixup.cmake) +``` + +For these SOCs, `basic.cmake` and `fixup.cmake` are required, +while other CMake files (`middleware.cmake`, `components.cmake`, `drivers.cmake`) +are optional. \ No newline at end of file