From 0046882d48d656b97896eb482e9d538a1ab20fab Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Wed, 14 Oct 2026 22:48:55 +0100 Subject: [PATCH 1/4] feat(stm32): OTG register runtime support and a CubeMX post-generation step USB code generation follows the LibXR OTG register runtime: - The OTG device takes a hardware configuration (PHY, DMA, VBUS sensing, high speed, EP0 OUT DMA buffer) derived from the .ioc mode and parameters instead of the PCD handle. - Endpoint buffers are 32-byte aligned, data endpoints are two slots (512-byte slots at high speed), and a raised OTG buffer size is written back to libxr_config.yaml with a notice. - CubeMX keeps its default settings; only a disabled OTG interrupt in NVIC is an error. When the generated sources define no OTG interrupt handler, app_main.cpp gets the vector function. libxr stm32 sync parses the project, generates app_main.cpp, turns off the CubeMX initialization call and interrupt handler of the OTG instances LibXR takes over, and updates the CMake integration. setup registers cmake/libxr_after_cubemx.cmd, a script that runs under cmd on Windows and under sh elsewhere, as the CubeMX post-generation script, so every code generation in CubeMX runs sync. Its output also goes to .libxr/after_cubemx.log; app_main.cpp records the digest of the .ioc file, and LibXR.CMake fails the configuration with that log and the command to run when the .ioc file changed without the code being generated again. --- README.md | 110 +++++- src/libxr/cli.py | 41 +++ src/libxr/config_cubemx_project.py | 20 +- src/libxr/generator_code_stm32.py | 374 +++++++++++++++++++-- src/libxr/generator_stm32_cmake.py | 47 +++ src/libxr/peripheral_analyzer_stm32.py | 61 +++- src/libxr/stm32_cubemx_sync.py | 423 ++++++++++++++++++++++++ tests/test_config_cubemx_project.py | 9 +- tests/test_generator_code_stm32.py | 153 ++++++++- tests/test_generator_stm32_cmake.py | 3 +- tests/test_peripheral_analyzer_stm32.py | 30 ++ tests/test_stm32_cubemx_sync.py | 224 +++++++++++++ 12 files changed, 1426 insertions(+), 69 deletions(-) create mode 100644 src/libxr/stm32_cubemx_sync.py create mode 100644 tests/test_stm32_cubemx_sync.py diff --git a/README.md b/README.md index 236748b..6697704 100644 --- a/README.md +++ b/README.md @@ -185,6 +185,62 @@ LF in the repository and converted on checkout by platform, so regenerating with Windows or on Linux shows only real changes in the commit. An existing `.gitattributes` only gets the missing lines. +### CubeMX 重新生成之后 / After CubeMX Generates the Code + +setup 把 `cmake/libxr_after_cubemx.cmd` 登记为 CubeMX 的生成后脚本(Project Manager > Code Generator > +User Actions > After Code Generation)。此后每次在 CubeMX 中生成代码,脚本都运行 `libxr stm32 sync`: +解析 `.ioc`、重新生成 `User/app_main.cpp`、更新 CMake 集成。同一个脚本在 Windows 上由 cmd 执行,在 +Linux 上由 sh 执行;它依次使用 `LIBXR_PYTHON` 指定的 Python 和 `PATH` 中的 Python,所用的 Python 需要 +装有 libxr。`.ioc` 中已登记别的生成后脚本时,setup 保留它,并提示在那个脚本末尾调用 +`cmake/libxr_after_cubemx.cmd`。 + +After setup, `cmake/libxr_after_cubemx.cmd` is the post-generation script of CubeMX (Project +Manager > Code Generator > User Actions > After Code Generation). Every time CubeMX generates the +code, the script runs `libxr stm32 sync`: it parses the `.ioc` file, generates +`User/app_main.cpp` again and updates the CMake integration. The same script runs under cmd on +Windows and under sh on Linux; it uses the Python that `LIBXR_PYTHON` names, then the Python on +`PATH`, and that Python needs libxr. When the `.ioc` file already registers another +post-generation script, setup keeps it and asks for a call to `cmake/libxr_after_cubemx.cmd` at +its end. + +CubeMX 只在 Output 窗口显示脚本的输出,脚本失败时照常完成生成。所以输出同时写进 +`.libxr/after_cubemx.log`,`User/app_main.cpp` 记下 `.ioc` 的摘要;LibXR.CMake 在配置时比对摘要, +`.ioc` 改过而代码没有重新生成时让构建失败,报错中给出这份日志和要运行的命令: + +CubeMX shows the output of the script only in its Output window and completes the generation +when the script fails. So the output also goes to `.libxr/after_cubemx.log`, and +`User/app_main.cpp` records the digest of the `.ioc` file; LibXR.CMake compares the digest when it +configures, and when the `.ioc` file changed without the code being generated again the build +fails with this log and the command to run: + +```text +CMake Error at cmake/LibXR.CMake:66 (message): + [LibXR] /DevC.ioc changed after User/app_main.cpp + was generated, so the STM32CubeMX post-generation step failed or did not + run. Run + + python -m libxr stm32 sync + + in , or generate the code in STM32CubeMX again. + + Output of its last run (/.libxr/after_cubemx.log): + + [LibXR] FAILED: no Python with a libxr that has `libxr stm32 sync` was + found (tried LIBXR_PYTHON, python, py -3). Install or update it with `pip + install -U libxr`, or set LIBXR_PYTHON to the python.exe that has it, then + run `python -m libxr stm32 sync` in . +``` + +USB OTG 实例由 LibXR 的驱动初始化并处理中断(见下文 USB 一节)。sync 在 `.ioc` 中关掉这些实例的 +初始化调用和中断函数生成,下次在 CubeMX 中生成代码时生效,之后 CubeMX 的代码不再引用 PCD 句柄, +句柄和 HAL 的 PCD 代码被链接器回收。 + +The LibXR driver initializes the USB OTG instances and handles their interrupts (see the USB +section below). sync turns off the initialization call and the interrupt handler of these +instances in the `.ioc` file; this takes effect the next time CubeMX generates the code, after +which the CubeMX code no longer references the PCD handle, and the linker drops it together +with the PCD code of HAL. + --- ## 🧩 从 .ioc 到代码 / From .ioc to Code @@ -288,15 +344,16 @@ extern "C" void app_main(void) 生成的部分已按 LibXR 的 `.clang-format`(Google 风格、列宽 90、Allman 大括号)排版,clang-format 不会 改动它们。缓冲区的对齐取决于芯片:没有数据 cache 的芯片(F1、F4 等)为 `alignas(4)`;有数据 cache 的 -F7、H7 和 N6 按 32 字节的 cache 行对齐,数组大小向上取整到整行,传给驱动的大小仍是配置的值。 -`libxr_config.yaml` 给出 `dma_section` 时,缓冲区放在这个段: +F7、H7 和 N6 按 32 字节的 cache 行对齐,数组大小向上取整到整行,传给驱动的大小仍是配置的值。USB +端点缓冲区在所有芯片上都按 32 字节对齐,见下文。`libxr_config.yaml` 给出 `dma_section` 时,缓冲区 +放在这个段: The generated parts are laid out by the `.clang-format` of LibXR (Google style, column limit 90, Allman braces), and clang-format leaves them as they are. The alignment of a buffer depends on the chip: a chip without a data cache (F1, F4 and others) gets `alignas(4)`; F7, H7 and N6, which have one, align to the 32-byte cache line and round the array up to a whole line, while the size -a driver is told stays the configured one. With `dma_section` in `libxr_config.yaml`, the buffers -go into that section: +a driver is told stays the configured one. USB endpoint buffers are 32-byte aligned on every +chip, see below. With `dma_section` in `libxr_config.yaml`, the buffers go into that section: ```cpp // DMA buffers (STM32H723VG: D-cache, 32-byte lines) @@ -426,6 +483,50 @@ USB: - {tx_fifo_size: 128, rx_fifo_size: 128, queue_size: 3, interface: Telemetry} ``` +端点缓冲区按 32 字节对齐。EP0 每个方向的缓冲区是一个槽,其余端点的缓冲区平分为两个槽,端点的包长取 +槽放得下的最大合法值:全速时每槽 32 字节用 32 字节的包,64 字节及以上用 64 字节的包;高速批量包只能是 +512 字节,所以高速时每槽至少 512 字节。数据端点取 `tx_buffer_size` 或 `rx_buffer_size`,按两个槽取整, +分配的值与设置不同时写回 `libxr_config.yaml` 并记录一条提示;通知端点为 64 字节。 + +Endpoint buffers are aligned to 32 bytes. The EP0 buffer of each direction is one slot, the +buffer of any other endpoint is split into two slots, and an endpoint takes the largest legal +packet its slot holds: at full speed a 32-byte slot gives 32-byte packets and 64 bytes or more +give 64-byte packets; a high-speed bulk packet is 512 bytes only, so at high speed each slot is +at least 512 bytes. A data endpoint takes `tx_buffer_size` or `rx_buffer_size` rounded to two +slots, and an allocated value that differs from the setting is written back to +`libxr_config.yaml` with a notice; a notification endpoint gets 64 bytes. + +OTG 的设备对象(`usb_otg_fs`、`usb_otg_hs`)由 LibXR 的驱动初始化控制器并处理中断,不使用 CubeMX +生成的 PCD 句柄,CubeMX 保持默认设置即可:LibXR 在链接时包装 `HAL_PCD_Init` 和 +`HAL_PCD_IRQHandler`,`main()` 调用的 `MX_USB_OTG_FS_PCD_Init` 不再初始化控制器,CubeMX 生成的 +`OTG_FS_IRQHandler` 进入驱动。CubeMX 中取消了 `OTG_FS_IRQn` 的 Generate IRQ handler 时,生成器在 +`app_main.cpp` 中写出这个向量函数。`OTG_FS_IRQn` 必须在 NVIC 中开启。设备对象的第一个参数是硬件 +配置,由 `.ioc` 中的模式和参数得出:PHY、DMA、VBUS 检测和是否以高速枚举;开启 DMA 时另生成 64 字节的 +EP0 OUT 缓冲区,例如 `usb_otg_hs_ep0_dma_buf`: + +The OTG device objects (`usb_otg_fs`, `usb_otg_hs`) have the LibXR driver initialize the +controller and handle its interrupts, without the PCD handle CubeMX generates, and CubeMX keeps +its default settings: LibXR wraps `HAL_PCD_Init` and `HAL_PCD_IRQHandler` at link time, so the +`MX_USB_OTG_FS_PCD_Init` that `main()` calls no longer initializes the controller and the +`OTG_FS_IRQHandler` CubeMX generates enters the driver. With Generate IRQ handler unticked for +`OTG_FS_IRQn` in CubeMX, the generator writes that vector function into `app_main.cpp`. +`OTG_FS_IRQn` must be enabled in NVIC. The first argument of the device object is the hardware +configuration, derived from the mode and parameters in the `.ioc` file: the PHY, DMA, VBUS +sensing and whether to enumerate at high speed; with DMA there is also a 64-byte EP0 OUT buffer, +such as `usb_otg_hs_ep0_dma_buf`: + +```cpp + static STM32USBDeviceOtgHS usb_otg_hs( + {STM32USBOtgDevice::Phy::EMBEDDED_FS, true, false, false, usb_otg_hs_ep0_dma_buf}, + 256, {usb_otg_hs_ep0_out_buf, usb_otg_hs_ep1_out_buf}, + {{usb_otg_hs_ep0_in_buf, 8}, + {usb_otg_hs_ep1_in_buf, 128}, + {usb_otg_hs_ep2_in_buf, 16}}, + USB::DeviceDescriptor::PacketSize0::SIZE_8, 0x1D50, 0x6199, 0x100, + {&usb_otg_hs_strings}, {{&usb_otg_hs_cdc}}, + {reinterpret_cast(UID_BASE), 12}); +``` + `database.enable` 为 true 时,`app_main()` 生成 `STM32Flash flash(FLASH_REGIONS, FLASH_REGION_NUMBER)` 和 `DatabaseRaw database(flash)`,数据库以 `database` 注册;`FLASH_REGIONS` 来自 `User/flash_map.hpp`,数据库使用 Flash 末尾的两个扇区。模板参数 `N` 是 Flash 的最小写入单元,单位为 @@ -859,6 +960,7 @@ belong to one platform sit under its name. | `libxr hpm setup` | 为 HPM 工程生成 LibXR 代码 | Generate LibXR code for an HPM project | | `libxr stm32 cubemx-gen` | 以脚本模式运行 STM32CubeMX,由 `.ioc` 重新生成 CubeMX 工程 | Run STM32CubeMX in script mode to regenerate the CubeMX project from the `.ioc` file | | `libxr stm32 cmake` | 把 LibXR 接入 CubeMX 的 CMake 工程 | Integrate LibXR into the CubeMX CMake project | +| `libxr stm32 sync` | CubeMX 生成代码之后更新 LibXR 的代码;CubeMX 的生成后脚本运行它 | Update the LibXR code after CubeMX generated the project; the CubeMX post-generation script runs it | | `libxr stm32 flash-info` | 打印某个型号的 Flash 布局 | Print the flash layout of a model | | `libxr stm32 toolchain` | 切换工具链和 ST Arm Clang 的标准库 | Switch the toolchain and the ST Arm Clang standard library | diff --git a/src/libxr/cli.py b/src/libxr/cli.py index 7b3680c..168a5b7 100644 --- a/src/libxr/cli.py +++ b/src/libxr/cli.py @@ -429,6 +429,19 @@ def cmd_stm32_cmake(args: argparse.Namespace) -> None: integrate(args.directory) +def cmd_stm32_sync(args: argparse.Namespace) -> None: + """libxr stm32 sync:STM32CubeMX 生成代码之后更新 LibXR 的生成结果(见 stm32_cubemx_sync); + 失败时以状态 1 退出。 + libxr stm32 sync: bring the LibXR output up to date after STM32CubeMX generated the code + (see stm32_cubemx_sync); a failure exits with status 1. + """ + from libxr.stm32_cubemx_sync import sync + + code = sync(args.directory, after_cubemx=args.after_cubemx) + if code: + sys.exit(code) + + def cmd_stm32_flash_info(args: argparse.Namespace) -> None: """libxr stm32 flash-info:以 YAML 打印一个 STM32 型号的 Flash 布局。 libxr stm32 flash-info: print the flash layout of an STM32 model as YAML. @@ -883,6 +896,33 @@ def _add_stm32_cmake(commands) -> None: _add_project_directory(parser) +def _add_stm32_sync(commands) -> None: + """加入 stm32 sync 子命令。 + Add the stm32 sync subcommand. + """ + parser = _command( + commands, + "sync", + tr( + "update the LibXR code after STM32CubeMX generated the project: parse, generate, " + "adjust the .ioc file for LibXR and update the CMake integration; STM32CubeMX runs " + "it after each code generation once `libxr stm32 setup` has registered it", + "STM32CubeMX 生成工程之后更新 LibXR 的代码:解析、生成、为 LibXR 调整 .ioc、更新 " + "CMake 集成;`libxr stm32 setup` 登记之后,STM32CubeMX 每次生成代码都会运行它", + ), + cmd_stm32_sync, + ) + _add_project_directory(parser) + parser.add_argument( + "--after-cubemx", + action="store_true", + help=tr( + "called by the STM32CubeMX post-generation script", + "由 STM32CubeMX 的生成后脚本调用", + ), + ) + + def _add_project_directory(parser) -> None: """加入 -d/--directory:CubeMX 工程目录,默认当前目录。 Add -d/--directory: the CubeMX project directory, the current directory by default. @@ -1075,6 +1115,7 @@ def build_parser() -> argparse.ArgumentParser: _add_stm32_setup(stm32_commands) _add_stm32_cubemx_gen(stm32_commands) _add_stm32_cmake(stm32_commands) + _add_stm32_sync(stm32_commands) _add_stm32_flash_info(stm32_commands) _add_stm32_toolchain(stm32_commands) hpm = commands.add_parser( diff --git a/src/libxr/config_cubemx_project.py b/src/libxr/config_cubemx_project.py index c51ab1a..f21b4b5 100644 --- a/src/libxr/config_cubemx_project.py +++ b/src/libxr/config_cubemx_project.py @@ -219,10 +219,11 @@ def config_for(self, recorded_url: str) -> list: def create_gitignore_file(project_dir): - """工程目录没有 .gitignore 时创建一个,忽略 build、.history、.cache、CMakeFiles 和 - .config.yaml;已有的 .gitignore 不改动。 + """工程目录没有 .gitignore 时创建一个,忽略 build、.history、.cache、CMakeFiles、 + .config.yaml 和 .libxr(CubeMX 生成后步骤的日志);已有的 .gitignore 不改动。 Create a .gitignore in the project directory that ignores build, .history, .cache, - CMakeFiles and .config.yaml; an existing .gitignore is left unchanged. + CMakeFiles, .config.yaml and .libxr (the log of the CubeMX post-generation step); an + existing .gitignore is left unchanged. """ gitignore_path = os.path.join(project_dir, ".gitignore") if not os.path.exists(gitignore_path): @@ -233,6 +234,7 @@ def create_gitignore_file(project_dir): .cache/** .config.yaml CMakeFiles/** +.libxr/ """) @@ -664,9 +666,11 @@ def setup_project( its choice: XRobot code is generated again when User/app_main.cpp was generated with --xrobot. At the end it describes what is left to do by hand (see _report_next_steps()). """ + from libxr import generator_code_stm32 from libxr.generator_code_stm32 import generate from libxr.generator_stm32_cmake import integrate, project_uses_xrobot from libxr.peripheral_analyzer_stm32 import parse_project + from libxr.stm32_cubemx_sync import apply_otg_settings, install_hook if shutil.which("git") is None: logging.error( @@ -767,7 +771,17 @@ def setup_project( logging.info(tr("Generating C++ code...", "正在生成 C++ 代码……")) generate(yaml_output, cpp_output, xrobot_enable) + # LibXR 接管的 OTG 实例:在 .ioc 中关掉初始化调用和中断函数生成,再解析和生成一次,使 + # app_main.cpp 记下改后 .ioc 的摘要。 + # The OTG instances LibXR takes over: turn off their initialization call and interrupt + # handler in the .ioc file, then parse and generate once more so that app_main.cpp records + # the digest of the changed .ioc file. + if apply_otg_settings(ioc_file, generator_code_stm32.otg_devices): + parse_project(project_dir, yaml_output, summary=False) + generate(yaml_output, cpp_output, xrobot_enable) + integrate(project_dir) + install_hook(project_dir, ioc_file) logging.info(tr("[Pass] All tasks completed.", "[通过] 全部任务已完成。")) _report_next_steps(project_dir, xrobot_enable) diff --git a/src/libxr/generator_code_stm32.py b/src/libxr/generator_code_stm32.py index 21e5f30..975b623 100644 --- a/src/libxr/generator_code_stm32.py +++ b/src/libxr/generator_code_stm32.py @@ -43,6 +43,18 @@ # 本次生成的 DMA 缓冲区,键为缓冲区名。 # The DMA buffers of this generation, keyed by buffer name. dma_buffers = {} +# 本次生成的中断向量函数(CubeMX 不生成时由生成器补上),每个是若干行。 +# The interrupt vector functions of this generation (written when CubeMX generates none), each +# a list of lines. +interrupt_vectors = [] +# 本次生成了 LibXR 设备对象的 OTG 实例(如 USB_OTG_FS);libxr stm32 sync 据此修改 .ioc。 +# The OTG instances that got a LibXR device object in this generation (such as USB_OTG_FS); +# libxr stm32 sync changes the .ioc file for them. +otg_devices = [] +# 工程 Core/Src 中 CubeMX 生成的中断函数名;没有 Core/Src 时为 None,这时按 .ioc 的设置判断。 +# The interrupt handler names CubeMX generated in Core/Src of the project; None without +# Core/Src, and the .ioc settings decide then. +cubemx_irq_handlers: set[str] | None = None # 本次生成是否带 --xrobot:不带时不被引用的通道引用用 UNUSED 标记。 # Whether this generation has --xrobot: without it, channel references nothing uses are # marked with UNUSED. @@ -122,6 +134,8 @@ def initialize_registry(use_xrobot: bool) -> None: used_headers.clear() used_handles.clear() dma_buffers.clear() + interrupt_vectors.clear() + otg_devices.clear() if use_xrobot: _register_device("power_manager", "PowerManager", tr("power manager", "电源管理器")) @@ -935,6 +949,130 @@ def _pcd_handle(instance: str, config: dict) -> str | None: return config.get("PCDHandle") or f"hpcd_{name}" +# CubeMX 中 OTG_HS 使用外部 ULPI PHY 和内置高速 PHY 的设备模式,取自 CubeMX 数据库中这些模式 +# 的 phy_itface;其余模式(如 Device_Only_FS)使用内置全速 PHY。 +# The OTG_HS device modes in CubeMX that use an external ULPI PHY and the embedded high-speed +# PHY, from the phy_itface of these modes in the CubeMX database; the other modes (such as +# Device_Only_FS) use the embedded full-speed PHY. +_OTG_ULPI_MODES = {"Device_HS", "OTG/Dual_Role_Device_HS", "External_Phy_Device"} +_OTG_EMBEDDED_HS_MODES = { + "Internal_Phy_Device", + "Dual_Role_Device", + "Dual-Role-Device", + "OTG/Dual_Role_Device", + "OTG/Dual-Role-Device-HS", +} +# 显式写在 .ioc 中的 phy_itface 到 STM32USBOtgDevice::Phy。 +# An explicit phy_itface in the .ioc file to STM32USBOtgDevice::Phy. +_OTG_PHY_PARAMETERS = { + "PCD_PHY_EMBEDDED": "EMBEDDED_FS", + "USB_OTG_EMBEDDED_PHY": "EMBEDDED_FS", + "USB_OTG_ULPI_PHY": "ULPI", + "PCD_PHY_ULPI": "ULPI", + "USB_OTG_HS_EMBEDDED_PHY": "EMBEDDED_HS", + "PCD_PHY_UTMI": "EMBEDDED_HS", +} + + +def _otg_hardware(name: str, config: dict) -> dict: + """OTG 实例的硬件配置,对应 LibXR 的 STM32USBOtgDevice::HardwareConfig:phy(Phy 的枚举名)、 + dma、vbus_sensing 和 high_speed。 + The hardware configuration of an OTG instance, matching STM32USBOtgDevice::HardwareConfig of + LibXR: phy (the enumerator name of Phy), dma, vbus_sensing and high_speed. + + 参数取实例的全局参数和设备模式 profile 中的参数。.ioc 只写出与默认值不同的参数,CubeMX 中 + dma_enable 和 vbus_sensing_enable 默认为 DISABLE。PHY 取显式的 phy_itface,否则按模式: + USB_OTG_HS 的 _OTG_ULPI_MODES 为 ULPI,_OTG_EMBEDDED_HS_MODES 为内置高速 PHY,其余为内置全速 + PHY。高速 PHY 默认以高速枚举,speed 为 *_HIGH_IN_FULL 或 *_FULL 时以全速枚举。 + The parameters are the global ones of the instance and those of its device-mode profile. + The .ioc file lists only parameters that differ from their defaults; in CubeMX dma_enable + and vbus_sensing_enable default to DISABLE. The PHY is the explicit phy_itface, otherwise + by mode: on USB_OTG_HS, _OTG_ULPI_MODES use ULPI and _OTG_EMBEDDED_HS_MODES the embedded + high-speed PHY; anything else uses the embedded full-speed PHY. A high-speed PHY + enumerates at high speed by default and at full speed when speed is *_HIGH_IN_FULL or + *_FULL. + """ + params = {key: value for key, value in config.items() if key != "profiles"} + for profile in (config.get("profiles") or {}).values(): + if "Device" in str(profile.get("VirtualMode", "")): + params.update(profile) + mode = str(params.get("VirtualMode", "")) + phy = _OTG_PHY_PARAMETERS.get(str(params.get("phy_itface", ""))) + if phy is None: + phy = "EMBEDDED_FS" + if name == "USB_OTG_HS" and mode in _OTG_ULPI_MODES: + phy = "ULPI" + elif name == "USB_OTG_HS" and mode in _OTG_EMBEDDED_HS_MODES: + phy = "EMBEDDED_HS" + speed = str(params.get("speed", "")) + return { + "phy": phy, + "dma": params.get("dma_enable") == "ENABLE", + "vbus_sensing": params.get("vbus_sensing_enable") == "ENABLE", + "high_speed": phy != "EMBEDDED_FS" and not speed.endswith("FULL"), + } + + +def _otg_vector(name: str, config: dict) -> list[str]: + """OTG 实例的中断向量函数:CubeMX 生成了中断函数时为空列表,否则是调用驱动 Dispatch() 的 + 向量函数定义。 + The interrupt vector function of an OTG instance: an empty list when CubeMX generates the + interrupt handler, otherwise the definition of a vector function that calls the driver's + Dispatch(). + + CubeMX 保持默认设置即可:LibXR 在链接时包装 HAL_PCD_Init() 和 HAL_PCD_IRQHandler(),main() + 调用的 MX_<实例>_PCD_Init() 不再初始化控制器,CubeMX 生成的 <实例>_IRQHandler() 进入驱动。 + 取消了 Generate IRQ handler 时向量函数由这里生成。设置取自解析器记下的 InitCalled、 + InitStatic 和 Vectors(见 USBParser);旧的解析结果没有这些键时按 CubeMX 默认处理。初始化 + 函数没有调用且为 static 时记录警告:没有调用的 static 函数会产生编译警告。 + CubeMX can keep its default settings: LibXR wraps HAL_PCD_Init() and HAL_PCD_IRQHandler() + at link time, so MX__PCD_Init() called from main() no longer initializes the + controller and the _IRQHandler() CubeMX generates enters the driver. With + Generate IRQ handler unticked, the vector function is generated here. The settings come + from InitCalled, InitStatic and Vectors that the parser records (see USBParser); an older + parse result without these keys is treated as the CubeMX default. An initialization + function that is not called and static gets a warning: an uncalled static function draws + a compiler warning. + + Raises: + LibXRConfigError: NVIC 中没有开启 <实例>_IRQn;没有它 USB 不会有任何中断。 + _IRQn is not enabled in NVIC; without it USB gets no interrupt at all. + """ + stem = name[len("USB_") :] + main_irq = f"{stem}_IRQn" + vectors = config.get("Vectors") + main = dict((vectors or {}).get(main_irq, {"Enabled": True, "Handler": True})) + if cubemx_irq_handlers is not None: + # The generated sources decide: the .ioc file may already be changed while the code + # in Core/Src still comes from the earlier settings. + main["Handler"] = f"{stem}_IRQHandler" in cubemx_irq_handlers + if not main.get("Enabled"): + raise LibXRConfigError( + tr( + f"{name}: {main_irq} is not enabled; enable it in STM32CubeMX NVIC", + f"{name}:没有开启 {main_irq};请在 STM32CubeMX 的 NVIC 中开启", + ) + ) + function = f"MX_{name}_PCD_Init" + if config.get("InitStatic") and not config.get("InitCalled", True): + logging.warning( + tr( + f"{name}: {function} is static and not called; untick its Visibility (Static) " + "in Project Manager > Advanced Settings to avoid an unused-function warning", + f"{name}:{function} 是 static 且没有调用;请在 Project Manager > Advanced " + "Settings 中取消它的 Visibility (Static),以免产生未使用函数的警告", + ) + ) + if main.get("Handler"): + return [] + return [ + f'extern "C" void {stem}_IRQHandler(void)', + "{", + f"{INDENT}STM32USBOtgDevice::Dispatch({name});", + "}", + ] + + def _invalid_setting(key: str, value, english: str, chinese: str) -> LibXRConfigError: """设置 key 的值 value 无效时的错误;信息写出 libxr_config_origin、key、value 和应有的值。 The error for the invalid value of the setting key; the message names libxr_config_origin, @@ -1433,9 +1571,11 @@ def _mcu_label(project_data: dict) -> str: @dataclass(frozen=True) class DmaBuffer: - """一个 DMA 缓冲区:名字、元素类型、驱动使用的元素数、所在段和实际存储的元素数。 - One DMA buffer: its name, element type, the number of elements the driver uses, its section - and the number of elements actually stored. + """一个 DMA 缓冲区:名字、元素类型、驱动使用的元素数、所在段、实际存储的元素数和驱动要求的 + 最小对齐字节数(0 表示没有要求)。 + One DMA buffer: its name, element type, the number of elements the driver uses, its section, + the number of elements actually stored and the minimum alignment in bytes the driver needs + (0 for none). 有数据 cache 时存储的元素数向上取整到 cache 行的整数倍,使缓冲区两端不与其他数据共用 cache 行;驱动使用的元素数不变。 @@ -1449,6 +1589,7 @@ class DmaBuffer: count: int section: str stored: int + alignment: int = 0 def argument(self) -> "str | Braces": """传给驱动的参数:存储的元素数与驱动使用的相同时为缓冲区名,否则为 {名字, 字节数}。 @@ -1485,27 +1626,109 @@ def dma_argument(name: str) -> "str | Braces": return buffer.argument() if buffer else name -def _usb_buffer_plan(is_otg: bool, cdc_count: int, ep0: int, tx: int, rx: int) -> list: +# LibXR 端点槽的对齐:32 位 MCU 上的 HW_CACHE_LINE_SIZE。端点缓冲区的地址和长度都必须是它的 +# 整数倍,与 MCU 有没有数据 cache 无关。 +# The alignment of LibXR endpoint slots: HW_CACHE_LINE_SIZE on a 32-bit MCU. The address and +# length of an endpoint buffer must both be multiples of it, whether or not the MCU has a data +# cache. +_USB_SLOT_ALIGN = 32 +# OTG 驱动在 DMA 模式下 EP0 OUT 使用的缓冲区字节数(容一个 EP0 最大包或 3 个背靠背 SETUP)。 +# The bytes of the buffer the OTG driver uses for EP0 OUT in DMA mode (one EP0 packet of the +# largest size, or three back-to-back SETUP packets). +_USB_EP0_DMA_SIZE = 64 + + +def _usb_slots(count: int, size: int) -> int: + """count 个槽、每槽至少 size 字节时端点缓冲区的字节数;每槽向上取整到 _USB_SLOT_ALIGN。 + The bytes of an endpoint buffer with count slots of at least size bytes each; each slot is + rounded up to _USB_SLOT_ALIGN. + """ + return count * (-(-size // _USB_SLOT_ALIGN) * _USB_SLOT_ALIGN) + + +def _usb_data_buffer(size: int, high_speed: bool) -> int: + """数据端点缓冲区的字节数:两个槽,每槽取 size 的一半,按 _USB_SLOT_ALIGN 取整;高速时每槽 + 至少 512(高速批量包只能是 512)。全速时 CDC 取槽放得下的最大合法包长:每槽 32 字节为 32, + 64 字节及以上为 64。 + The bytes of a data endpoint buffer: two slots of half of size each, rounded to + _USB_SLOT_ALIGN; at high speed each slot is at least 512 (a high-speed bulk packet is 512 + only). At full speed CDC takes the largest legal packet the slot holds: 32 for a 32-byte + slot, 64 from 64 bytes up. + """ + return _usb_slots(2, max(-(-size // 2), 512 if high_speed else _USB_SLOT_ALIGN)) + + +def _usb_buffer_plan( + is_otg: bool, + cdc_count: int, + ep0: int, + tx: int, + rx: int, + high_speed: bool = False, + ep0_dma: bool = False, +) -> list: """USB 设备的端点缓冲区:(名字后缀, 字节数) 的列表。 The endpoint buffers of a USB device: a list of (name suffix, bytes). CDC 按顺序分配端点:第 i 个 CDC(从 0 起)的数据 IN 端点为 EP(2i+1),通知端点为 EP(2i+2); OTG 的数据 OUT 端点为 EP(i+1),IN 和 OUT 的端点号各自编号;FSDEV 的数据 OUT 与数据 IN - 使用同一个端点号。通知端点的缓冲区为 16 字节。 + 使用同一个端点号。 CDCs take endpoints in order: the data IN endpoint of CDC i (from 0) is EP(2i+1) and its notification endpoint EP(2i+2); on OTG the data OUT endpoint is EP(i+1), IN and OUT endpoints being numbered separately, while FSDEV uses one endpoint number for data OUT and - data IN. The notification buffer is 16 bytes. - """ - plan = [("ep0_in_buf", ep0), ("ep0_out_buf", ep0)] + data IN. + + LibXR 把 EP0 的缓冲区当作一个槽,其余端点的缓冲区平分为两个槽,每个槽按 _USB_SLOT_ALIGN + 对齐;端点的包长取槽放得下的最大合法值。所以 EP0 每个方向至少 ep0 字节;数据端点见 + _usb_data_buffer();通知端点每槽 32 字节。ep0_dma 时另有 OTG 驱动在 DMA 模式下使用的 EP0 + OUT 缓冲区 ep0_dma_buf。 + LibXR treats the EP0 buffer as one slot and splits the buffer of any other endpoint into + two slots, each aligned to _USB_SLOT_ALIGN; an endpoint takes the largest legal packet its + slot holds. So EP0 gets at least ep0 bytes per direction; data endpoints follow + _usb_data_buffer(); the notification endpoint gets 32 bytes per slot. With ep0_dma there is + also ep0_dma_buf, the EP0 OUT buffer the OTG driver uses in DMA mode. + """ + plan = [("ep0_in_buf", _usb_slots(1, ep0)), ("ep0_out_buf", _usb_slots(1, ep0))] + if ep0_dma: + plan.append(("ep0_dma_buf", _USB_EP0_DMA_SIZE)) for index in range(cdc_count): data, notify = 2 * index + 1, 2 * index + 2 - plan.append((f"ep{data}_in_buf", tx)) - plan.append((f"ep{notify}_in_buf", 16)) - plan.append((f"ep{data if not is_otg else index + 1}_out_buf", rx)) + plan.append((f"ep{data}_in_buf", _usb_data_buffer(tx, high_speed))) + plan.append((f"ep{notify}_in_buf", _usb_slots(2, 16))) + plan.append( + (f"ep{data if not is_otg else index + 1}_out_buf", _usb_data_buffer(rx, high_speed)) + ) return plan +def _settle_usb_buffer(name: str, usb_cfg: dict, key: str, hardware: dict) -> int: + """OTG 实例的数据端点缓冲区设置 key(tx_buffer_size 或 rx_buffer_size)实际分配的字节数; + 与设置不同时写回 usb_cfg 并记录一条提示,libxr_config.yaml 随之写出分配的值。FSDEV 的 + rx_buffer_size 同时是 PMA 的大小,不写回。 + The bytes actually allocated for the data endpoint buffer setting key (tx_buffer_size or + rx_buffer_size) of an OTG instance; when they differ from the setting they are written back + to usb_cfg with a notice, so libxr_config.yaml shows the allocated value. The + rx_buffer_size of FSDEV is also the PMA size and is not written back. + """ + configured = _integer(key, usb_cfg[key]) + allocated = _usb_data_buffer(configured, hardware.get("high_speed", False)) + if allocated != configured: + if hardware.get("high_speed", False): + reason_en = "two slots of at least one 512-byte high-speed bulk packet each" + reason_zh = "两个槽,每槽至少放得下一个 512 字节的高速批量包" + else: + reason_en = "two slots in 32-byte steps" + reason_zh = "两个槽,每槽按 32 字节取整" + logging.info( + tr( + f"USB.{name.lower()}.{key} {configured} -> {allocated}: {reason_en}", + f"USB.{name.lower()}.{key} {configured} -> {allocated}:{reason_zh}", + ) + ) + usb_cfg[key] = allocated + return allocated + + def _cdc_items(cfg: dict) -> list[dict]: """USB 设备的 CDC 串口设置列表:每个 CDC 一个映射,含整数 tx_fifo_size、rx_fifo_size 和 queue_size,以及接口名 interface(未设置时为空字符串)。 @@ -1541,11 +1764,13 @@ def generate_dma_resources(project_data: dict) -> list[str]: 没有数据 cache 的 MCU 按 4 字节对齐;有数据 cache 的 MCU 按 cache 行对齐,数组长度向上取整到 cache 行的整数倍,缓冲区两端不与其他数据共用 cache 行;驱动被告知的大小不变,见 - DmaBuffer.argument()。 + DmaBuffer.argument()。USB 端点缓冲区总是按 _USB_SLOT_ALIGN 对齐,大小见 + _usb_buffer_plan()。 An MCU without a data cache aligns to 4 bytes; one with a data cache aligns to the cache line and rounds the array length up to a whole number of cache lines, so no other data shares a cache line with either end of a buffer; the size a driver is told stays, see - DmaBuffer.argument(). + DmaBuffer.argument(). USB endpoint buffers are always aligned to _USB_SLOT_ALIGN, with the + sizes _usb_buffer_plan() gives. _DTCM_BSS_FAMILIES 中的系列上有 DMA 访问的缓冲区而 dma_section 为空的实例记录一条警告,见 _warn_dtcm_buffers();不用 DMA 的 SPI 的缓冲区只由 CPU 访问,不计入。 @@ -1561,12 +1786,15 @@ def generate_dma_resources(project_data: dict) -> list[str]: # The keys of the instance settings with buffers and an empty dma_section, such as SPI.spi1. unplaced: list[str] = [] - def add(key: str, element: str, name: str, count: int, section: str) -> None: - """登记实例设置 key 的一个缓冲区:count 个 element 类型的元素,位于 section 段。 + def add( + key: str, element: str, name: str, count: int, section: str, alignment: int = 0 + ) -> None: + """登记实例设置 key 的一个缓冲区:count 个 element 类型的元素,位于 section 段,至少按 + alignment 字节对齐。 Register one buffer of the instance settings key: count elements of the type element in - the section section. + the section section, aligned to at least alignment bytes. """ - dma_buffers[name] = DmaBuffer(name, element, count, section, count) + dma_buffers[name] = DmaBuffer(name, element, count, section, count, alignment) if not section and key not in unplaced: unplaced.append(key) @@ -1689,12 +1917,30 @@ def section_of(key: str, instance_config: dict) -> str: ep0 = _integer("ep0_packet_size", usb_cfg["ep0_packet_size"]) tx_sz = _integer("tx_buffer_size", usb_cfg["tx_buffer_size"]) rx_sz = _integer("rx_buffer_size", usb_cfg["rx_buffer_size"]) + is_otg = name.startswith("USB_OTG_") + hardware = _otg_hardware(name, instances[instance]) if is_otg else {} + if is_otg: + tx_sz = _settle_usb_buffer(name, usb_cfg, "tx_buffer_size", hardware) + rx_sz = _settle_usb_buffer(name, usb_cfg, "rx_buffer_size", hardware) plan = _usb_buffer_plan( - name.startswith("USB_OTG_"), len(_cdc_items(usb_cfg)), ep0, tx_sz, rx_sz + is_otg, + len(_cdc_items(usb_cfg)), + ep0, + tx_sz, + rx_sz, + hardware.get("high_speed", False), + hardware.get("dma", False), ) for suffix, size in plan: section = usb_cfg["dma_section"] - add(f"USB.{name.lower()}", "uint8_t", f"{name.lower()}_{suffix}", size, section) + add( + f"USB.{name.lower()}", + "uint8_t", + f"{name.lower()}_{suffix}", + size, + section, + _USB_SLOT_ALIGN, + ) if not dma_buffers: return [] @@ -1712,7 +1958,8 @@ def section_of(key: str, instance_config: dict) -> str: lines = [f"// DMA buffers ({_mcu_label(project_data)}: {note})"] alignment = line or 4 for name in sorted(dma_buffers, key=_natural_key): - lines.extend(_dma_declaration(dma_buffers[name], alignment)) + buffer = dma_buffers[name] + lines.extend(_dma_declaration(buffer, max(alignment, buffer.alignment))) return lines @@ -2087,20 +2334,25 @@ def _generate_usb(instance: str, config: dict) -> tuple: 实例名和设置来自 _usb_settings();其他实例名(如 USB_DEVICE 中间件)和未启用的实例不生成 代码,启用了但在 CubeMX 中是主机模式的实例记录警告后不生成。设备对象以实例名命名(如 - usb_otg_fs),使用 _pcd_handle() 给出的句柄,引用 generate_dma_resources() 定义的端点 - 缓冲区,本方法不定义缓冲区。CDC 串口 <实例>_cdc、<实例>_cdc2 …… 按顺序分配端点,规则见 - _usb_buffer_plan(),各登记为 UART。 + usb_otg_fs),引用 generate_dma_resources() 定义的端点缓冲区,本方法不定义缓冲区。OTG + 设备的第一个参数是 _otg_hardware() 给出的硬件配置,CubeMX 不生成中断函数时由 + _otg_vector() 补上向量函数;FSDEV 设备使用 _pcd_handle() 给出的句柄。CDC 串口 <实例>_cdc、<实例>_cdc2 + …… 按顺序分配端点,规则见 _usb_buffer_plan(),各登记为 UART。 The instance name and settings come from _usb_settings(); other instance names, such as the USB_DEVICE middleware, and disabled instances produce no code, and an enabled instance in host mode in CubeMX is skipped with a warning. The device object is named - after the instance, for example usb_otg_fs, uses the handle _pcd_handle() gives and - references the endpoint buffers that generate_dma_resources() defines; this method - defines no buffer. The CDC serial ports _cdc, _cdc2 ... take + after the instance, for example usb_otg_fs, and references the endpoint buffers that + generate_dma_resources() defines; this method defines no buffer. The first argument of + an OTG device is the hardware configuration _otg_hardware() gives, and _otg_vector() + writes the vector function when CubeMX generates no interrupt handler; an FSDEV device + uses the handle _pcd_handle() gives. The CDC serial ports _cdc, _cdc2 ... take endpoints in order, see _usb_buffer_plan(), and are each registered as UART. Raises: - LibXRConfigError: 设置了 cdc_count,或某个设置无效(见 _usb_settings())。 - cdc_count is set, or a setting is invalid (see _usb_settings()). + LibXRConfigError: 设置了 cdc_count,某个设置无效(见 _usb_settings()),或 OTG 的 + 中断没有在 NVIC 中开启(见 _otg_vector())。 + cdc_count is set, a setting is invalid (see _usb_settings()), or the interrupt + of an OTG instance is not enabled in NVIC (see _otg_vector()). """ usb = _usb_settings(instance) if usb is None: @@ -2165,7 +2417,14 @@ def _generate_usb(instance: str, config: dict) -> tuple: _use_header("stm32_usb_dev.hpp") _use_header("cdc_uart.hpp") - _use_handle("PCD_HandleTypeDef", pcd_handle) + if is_otg: + vector = _otg_vector(name, config) + if vector: + interrupt_vectors.append(vector) + otg_devices.append(name) + hardware = _otg_hardware(name, config) + else: + _use_handle("PCD_HandleTypeDef", pcd_handle) def endpoint(number: int) -> str: """端点号 number 对应的 USB::Endpoint::EPNumber 枚举值。 @@ -2222,7 +2481,19 @@ def buffer(suffix: str) -> "str | Braces": out_buffers.append(buffer(f"ep{index + 1}_out_buf")) in_configs.append(Braces(buffer(f"ep{2 * index + 1}_in_buf"), str(tx_fifo_size))) in_configs.append(Braces(buffer(f"ep{2 * index + 2}_in_buf"), "16")) - endpoints = [str(rx_fifo_size), Braces(*out_buffers), Braces(*in_configs)] + # STM32USBOtgDevice::HardwareConfig 的聚合初始化:PHY、DMA、VBUS 检测、高速,DMA 时 + # 再加 EP0 OUT 缓冲区。 + # Aggregate initialization of STM32USBOtgDevice::HardwareConfig: PHY, DMA, VBUS + # sensing and high speed, plus the EP0 OUT buffer with DMA. + first = Braces( + f"STM32USBOtgDevice::Phy::{hardware['phy']}", + *( + "true" if hardware[key] else "false" + for key in ("dma", "vbus_sensing", "high_speed") + ), + *([buffer("ep0_dma_buf")] if hardware["dma"] else []), + ) + endpoints = [first, str(rx_fifo_size), Braces(*out_buffers), Braces(*in_configs)] else: configs = [ Braces(buffer("ep0_in_buf"), buffer("ep0_out_buf"), str(ep0_sz), str(ep0_sz)) @@ -2238,11 +2509,10 @@ def buffer(suffix: str) -> "str | Braces": ) ) configs.append(Braces(buffer(f"ep{data + 1}_in_buf"), "16", "true")) - endpoints = [Braces(*configs)] + endpoints = [f"&{pcd_handle}", Braces(*configs)] lines += layout_statement( f"static {instance_type} {inst_lower}", - [f"&{pcd_handle}"] - + endpoints + endpoints + [ f"USB::DeviceDescriptor::PacketSize0::{size_enum}", f"0x{vid:X}", @@ -2278,7 +2548,12 @@ def buffer(suffix: str) -> "str | Braces": "stm32_pwm.hpp": ("STM32PWM",), "stm32_spi.hpp": ("STM32SPI",), "stm32_uart.hpp": ("STM32UART",), - "stm32_usb_dev.hpp": ("STM32USBDeviceDevFs", "STM32USBDeviceOtgFS", "STM32USBDeviceOtgHS"), + "stm32_usb_dev.hpp": ( + "STM32USBDeviceDevFs", + "STM32USBDeviceOtgFS", + "STM32USBDeviceOtgHS", + "STM32USBOtgDevice", + ), "stm32_watchdog.hpp": ("STM32Watchdog",), } # Peripherals 中的段与它们的 HAL 句柄类型;句柄名是 h 加小写的实例名。 @@ -3248,10 +3523,14 @@ def _app_main_notice(project_data: dict) -> list[str]: written, otherwise the CubeMX project. """ source = project_data.get("Ioc") or "the CubeMX project" - return [ + lines = [ f"// Generated by `libxr gen` from {source} and {libxr_config_label}.", '// Edit only between "User Code Begin" and "User Code End"; the rest is regenerated.', ] + if project_data.get("IocDigest"): + # LibXR.CMake compares it with the .ioc file (see stm32_cubemx_sync.ioc_digest()). + lines.append(f"// {source} digest: {project_data['IocDigest']}") + return lines # 不带 --xrobot 生成时 User Code 3 的默认循环,去掉全部空白;5.x 版本写成 while(true) { ... }, @@ -3364,6 +3643,8 @@ def generate_full_code( lines += [""] + externs if dma: lines += [""] + dma + for vector in interrupt_vectors: + lines += [""] + vector lines += ["", 'extern "C" void app_main(void)', "{"] lines += [f"{INDENT}/* User Code Begin 2 */", f"{INDENT}/* User Code End 2 */", ""] lines += join_blocks([section for section in sections if section]) @@ -3640,6 +3921,8 @@ def generate( ) load_libxr_config(output_dir, libxr_config) _name_libxr_config(output_dir, libxr_config) + global cubemx_irq_handlers + cubemx_irq_handlers = _cubemx_irq_handlers(os.path.dirname(os.path.abspath(output_dir))) check_generator_pin() initialize_registry(use_xrobot) @@ -3689,6 +3972,27 @@ def generate( sys.exit(1) +# CubeMX 生成的中断函数定义,例如 void OTG_FS_IRQHandler(void)。 +# An interrupt handler definition CubeMX generates, such as void OTG_FS_IRQHandler(void). +_IRQ_HANDLER_DEFINITION = re.compile(r"^\s*void\s+(\w+_IRQHandler)\s*\(\s*void\s*\)\s*$", re.M) + + +def _cubemx_irq_handlers(project_root: str) -> set[str] | None: + """project_root/Core/Src 的 .c 文件中定义的中断函数名;没有这个目录时为 None。 + The interrupt handler names defined in the .c files of project_root/Core/Src; None without + that directory. + """ + source_dir = os.path.join(project_root, "Core", "Src") + if not os.path.isdir(source_dir): + return None + names = set() + for entry in sorted(os.listdir(source_dir)): + if entry.endswith(".c"): + with open(os.path.join(source_dir, entry), encoding="utf-8", errors="replace") as f: + names.update(_IRQ_HANDLER_DEFINITION.findall(f.read())) + return names + + def _report_files(output_dir: str, written: list, unchanged: list, removed: list) -> None: """用一行日志列出 output_dir 中写入、未变化和删除的文件。 Log in one line which files of output_dir were written, unchanged or deleted. diff --git a/src/libxr/generator_stm32_cmake.py b/src/libxr/generator_stm32_cmake.py index 75b83a8..2605b6a 100644 --- a/src/libxr/generator_stm32_cmake.py +++ b/src/libxr/generator_stm32_cmake.py @@ -60,6 +60,7 @@ COMPILE_OPTIONS_TITLE = "Compile options" LIBXR_TITLE = "LibXR" APPLICATION_TITLE = "Application" +CUBEMX_TITLE = "CubeMX" OPTIMIZATION_TITLE = "Library optimization" FIRMWARE_TITLE = "Firmware images" KEPT_TITLE = "Kept from the earlier LibXR.CMake" @@ -143,6 +144,49 @@ $ ${CMAKE_PROJECT_NAME}.bin VERBATIM)""" +# User/app_main.cpp 记下生成它的 .ioc 的摘要(见 stm32_cubemx_sync.ioc_digest());配置时比对, +# .ioc 改过而 LibXR 的代码没有重新生成时让配置失败,并附上生成后步骤的输出。CMake 在 .ioc 或 +# app_main.cpp 变化后重新配置。 +# User/app_main.cpp records the digest of the .ioc file it was generated from (see +# stm32_cubemx_sync.ioc_digest()); configuring compares it, and fails with the output of the +# post-generation step when the .ioc file changed without the LibXR code being generated again. +# CMake configures again after the .ioc file or app_main.cpp changes. +CUBEMX_BLOCK = r"""# User/app_main.cpp records the digest of the .ioc file it was generated from. Another digest +# means that STM32CubeMX changed the project and the LibXR code was not generated again: the +# post-generation step (cmake/libxr_after_cubemx.cmd, `libxr stm32 sync`) failed or did not run. +file(GLOB LIBXR_IOC "${CMAKE_CURRENT_SOURCE_DIR}/*.ioc") +set(LIBXR_APP_MAIN "${CMAKE_CURRENT_SOURCE_DIR}/User/app_main.cpp") +list(LENGTH LIBXR_IOC LIBXR_IOC_COUNT) +if(LIBXR_IOC_COUNT EQUAL 1 AND EXISTS "${LIBXR_APP_MAIN}") + set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS + "${LIBXR_IOC}" "${LIBXR_APP_MAIN}") + file(STRINGS "${LIBXR_APP_MAIN}" LIBXR_IOC_RECORD + REGEX "^// .* digest: [0-9a-f]+$" LIMIT_COUNT 1) + if(LIBXR_IOC_RECORD) + string(REGEX REPLACE "^.* digest: " "" LIBXR_IOC_RECORDED "${LIBXR_IOC_RECORD}") + file(READ "${LIBXR_IOC}" LIBXR_IOC_TEXT) + string(REPLACE "\r" "" LIBXR_IOC_TEXT "${LIBXR_IOC_TEXT}") + string(SHA256 LIBXR_IOC_DIGEST "${LIBXR_IOC_TEXT}") + string(SUBSTRING "${LIBXR_IOC_DIGEST}" 0 16 LIBXR_IOC_DIGEST) + if(NOT LIBXR_IOC_DIGEST STREQUAL LIBXR_IOC_RECORDED) + set(LIBXR_SYNC_LOG "${CMAKE_CURRENT_SOURCE_DIR}/.libxr/after_cubemx.log") + if(EXISTS "${LIBXR_SYNC_LOG}") + file(READ "${LIBXR_SYNC_LOG}" LIBXR_SYNC_OUTPUT) + string(CONCAT LIBXR_SYNC_OUTPUT "Output of its last run (${LIBXR_SYNC_LOG}):\n" + "${LIBXR_SYNC_OUTPUT}") + else() + set(LIBXR_SYNC_OUTPUT "It has not run in this checkout (no ${LIBXR_SYNC_LOG}).") + endif() + message(FATAL_ERROR + "[LibXR] ${LIBXR_IOC} changed after User/app_main.cpp was generated, so the " + "STM32CubeMX post-generation step failed or did not run. Run\n" + " python -m libxr stm32 sync\n" + "in ${CMAKE_CURRENT_SOURCE_DIR}, or generate the code in STM32CubeMX again.\n" + "${LIBXR_SYNC_OUTPUT}") + endif() + endif() +endif()""" + include_cmake_cmd = "include(${CMAKE_CURRENT_LIST_DIR}/cmake/LibXR.CMake)\n" # 被 include 的文件的写法,与 CMakeLists.txt 中实际写的大小写无关。 @@ -258,6 +302,9 @@ def render_libxr_cmake( builder.raw(_rule(APPLICATION_TITLE)) builder.raw(APPLICATION_BLOCK) builder.raw("") + builder.raw(_rule(CUBEMX_TITLE)) + builder.raw(CUBEMX_BLOCK) + builder.raw("") builder.raw(_rule(OPTIMIZATION_TITLE)) builder.raw(OPTIMIZATION_BLOCK) builder.raw("") diff --git a/src/libxr/peripheral_analyzer_stm32.py b/src/libxr/peripheral_analyzer_stm32.py index e2448fc..8957e6a 100644 --- a/src/libxr/peripheral_analyzer_stm32.py +++ b/src/libxr/peripheral_analyzer_stm32.py @@ -1180,12 +1180,14 @@ def parse(self, p_type: str) -> None: "-" 形式的参数存入 profiles[profile][param],其余存在实例下; IPParameters 拆成列表。VirtualMode(含各 profile 中的)含 Device 时 Role 为 Device, 含 Host 时为 Host,主机模式下 CubeMX 生成的是 HCD 句柄。_DRD_FAMILIES 系列的 USB 实例和 - IP 名为 USB_DRD_FS 的实例记下 PCDHandle hpcd_USB_DRD_FS。 + IP 名为 USB_DRD_FS 的实例记下 PCDHandle hpcd_USB_DRD_FS。OTG 实例另记下代码生成设置, + 见 _record_otg_code_generation()。 A "-" parameter is stored in profiles[profile][param] and any other under the instance; IPParameters is split into a list. Role is Device when a VirtualMode, profiles included, contains Device and Host when one contains Host; in host mode CubeMX generates an HCD handle. The USB instance of the _DRD_FAMILIES and an - instance with the IP name USB_DRD_FS get PCDHandle hpcd_USB_DRD_FS. + instance with the IP name USB_DRD_FS get PCDHandle hpcd_USB_DRD_FS. OTG instances also + get their code generation settings, see _record_otg_code_generation(). """ # 1. 按 .ioc 中的顺序找出 raw_map 里的全部 USB 外设名。 # 1. Find all USB peripheral names in the raw_map, in .ioc order @@ -1252,6 +1254,39 @@ def parse(self, p_type: str) -> None: cfg["Role"] = "Host" if usb_name == "USB_DRD_FS" or (usb_name == "USB" and family in self._DRD_FAMILIES): cfg["PCDHandle"] = "hpcd_USB_DRD_FS" + if usb_name.startswith("USB_OTG_"): + self._record_otg_code_generation(usb_name, cfg) + + def _record_otg_code_generation(self, usb_name: str, cfg: dict) -> None: + """记下 OTG 实例在 CubeMX 中的代码生成设置,供生成器检查。 + Record the code generation settings of an OTG instance in CubeMX for the generator to + check. + + InitCalled:main() 是否调用 MX_USB_OTG_*_PCD_Init()(Project Manager 中没有勾选 Do Not + Generate Function Call);InitStatic:该函数是否为 static。Vectors:该实例的每个 NVIC + 中断(如 OTG_FS_IRQn、OTG_HS_EP1_OUT_IRQn)是否开启、是否生成 IRQ 处理函数;NVIC. + 的第 1 项是开启,第 6 项是生成处理函数。 + InitCalled: whether main() calls MX_USB_OTG_*_PCD_Init() (Do Not Generate Function Call + is not set in the Project Manager); InitStatic: whether that function is static. + Vectors: for each NVIC interrupt of the instance (such as OTG_FS_IRQn or + OTG_HS_EP1_OUT_IRQn), whether it is enabled and whether its IRQ handler is generated; + field 1 of NVIC. is the enable and field 6 the handler generation. + """ + entries = [e for e in _init_functions(self.raw_map).get(usb_name, []) if e["generate"]] + cfg["InitCalled"] = any(e["called"] for e in entries) + cfg["InitStatic"] = any(e["static"] for e in entries) + stem = usb_name[len("USB_") :] # OTG_FS / OTG_HS + vectors = {} + for key, value in self.raw_map.items(): + root, _, irq = key.partition(".") + if root != "NVIC" or not re.fullmatch(rf"{stem}(_\w+)?_IRQn", irq): + continue + fields = str(value).replace("\\:", ":").split(":") + vectors[irq] = { + "Enabled": fields[0] == "true", + "Handler": len(fields) > 5 and fields[5] == "true", + } + cfg["Vectors"] = vectors def _ensure_usb_instance(self, usb_name: str) -> None: """USB 实例不存在时创建空字典。 @@ -1752,11 +1787,12 @@ def _init_functions(raw_map: dict[str, str]) -> dict[str, list[dict[str, Any]]]: 条目形如 [false-]<序号>-<函数>--<不调用>-<驱动>-<静态>[-<上下文>]:开头的 false 表示取消了 Generate Code,<不调用> 为 true 表示勾选了 Do Not Generate Function Call,<驱动> 为 HAL 或 - LL。每个 IP 对应一个列表,多核或 TrustZone 工程的每个上下文各一项。 + LL,<静态> 为 true 表示函数是 static。每个 IP 对应一个列表,多核或 TrustZone 工程的每个上下文 + 各一项。 An entry reads [false-]-----[-]: a leading false means Generate Code is off, true means Do Not Generate Function - Call is set, and is HAL or LL. Each IP maps to a list with one item per context - of a multi-core or TrustZone project. + Call is set, is HAL or LL, and true means the function is static. Each + IP maps to a list with one item per context of a multi-core or TrustZone project. """ functions: defaultdict[str, list[dict[str, Any]]] = defaultdict(list) for entry in raw_map.get("ProjectManager.functionlistsort", "").split(","): @@ -1772,6 +1808,7 @@ def _init_functions(raw_map: dict[str, str]) -> dict[str, list[dict[str, Any]]]: "generate": generate, "called": parts[3] != "true", "driver": parts[4], + "static": len(parts) > 5 and parts[5] == "true", } ) return functions @@ -2117,9 +2154,17 @@ def parse_project(directory: str, output: str | None = None, summary: bool = Tru logging.info(tr(f"Processing {ioc_file}...", f"正在处理 {ioc_file}……")) config_data = parse_ioc_file(os.path.join(directory, ioc_file)) if config_data: - # libxr gen 在生成文件的说明中写出 .ioc 文件名。 - # libxr gen names the .ioc file in the notice of the files it generates. - config_data = {"Platform": config_data["Platform"], "Ioc": ioc_file, **config_data} + # libxr gen 在生成文件的说明中写出 .ioc 文件名和摘要;LibXR.CMake 比对摘要。 + # libxr gen names the .ioc file and its digest in the notice of the files it generates; + # LibXR.CMake compares the digest. + from libxr.stm32_cubemx_sync import ioc_digest + + config_data = { + "Platform": config_data["Platform"], + "Ioc": ioc_file, + "IocDigest": ioc_digest(os.path.join(directory, ioc_file)), + **config_data, + } output_path = output or os.path.join(directory, ".config.yaml") if not config_data or not save_to_yaml(config_data, output_path): sys.exit(1) diff --git a/src/libxr/stm32_cubemx_sync.py b/src/libxr/stm32_cubemx_sync.py new file mode 100644 index 0000000..ea11e3b --- /dev/null +++ b/src/libxr/stm32_cubemx_sync.py @@ -0,0 +1,423 @@ +"""libxr stm32 sync:STM32CubeMX 生成代码之后更新 LibXR 的生成结果。 +libxr stm32 sync: bring the LibXR output up to date after STM32CubeMX generated the code. + +sync 依次解析 .ioc、生成 User/app_main.cpp、在 .ioc 中关掉 LibXR 接管的 OTG 实例的初始化调用 +和中断函数生成(见 otg_ioc_edits())、更新 CMake 集成。setup 把 cmake/libxr_after_cubemx.cmd +登记为 CubeMX 的生成后脚本(Project Manager > Code Generator > User Actions > After Code +Generation),此后每次在 CubeMX 中生成代码都会自动运行 sync。 +sync parses the .ioc file, generates User/app_main.cpp, turns off in the .ioc file the +initialization call and the interrupt handler of the OTG instances LibXR takes over (see +otg_ioc_edits()) and updates the CMake integration. setup registers +cmake/libxr_after_cubemx.cmd as the post-generation script of CubeMX (Project Manager > Code +Generator > User Actions > After Code Generation), so every code generation in CubeMX runs +sync. + +CubeMX 只把脚本的输出显示在 Output 窗口,脚本失败时照常完成生成。所以 sync 的输出同时写进 +.libxr/after_cubemx.log,生成的 User/app_main.cpp 记下 .ioc 的摘要;LibXR.CMake 在配置时比对 +摘要,.ioc 改过而代码没有重新生成时让构建失败,并给出日志的内容和要运行的命令。 +CubeMX shows the output of the script only in its Output window and completes the generation +when the script fails. So the output of sync also goes to .libxr/after_cubemx.log, and the +generated User/app_main.cpp records the digest of the .ioc file; LibXR.CMake compares the +digest when it configures and fails the build when the .ioc file changed without the code being +generated again, with the content of the log and the command to run. +""" + +from __future__ import annotations + +import hashlib +import logging +import os +import re +import stat +import subprocess +import sys +from collections.abc import Iterable + +from xr_syntax.i18n import tr + +from libxr.output import _Formatter + +# 生成后脚本:同一个文件在 Windows 上由 cmd 执行,在 Linux 和 macOS 上由 sh 执行(第一行以 : +# 开头,对 cmd 是标号,对 sh 是空命令)。sh 部分交给 HOOK_SH。 +# The post-generation script: the same file runs under cmd on Windows and under sh on Linux and +# macOS (its first line starts with :, a label for cmd and an empty command for sh). The sh part +# hands over to HOOK_SH. +HOOK_CMD = "cmake/libxr_after_cubemx.cmd" +HOOK_SH = "cmake/libxr_after_cubemx.sh" +# sync 的输出,LibXR.CMake 报错时附上它。 +# The output of sync, which LibXR.CMake shows when it fails the build. +SYNC_LOG = ".libxr/after_cubemx.log" +# .ioc 中生成后脚本的键。 +# The key of the post-generation script in the .ioc file. +AFTER_SCRIPT_KEY = "ProjectManager.UAScriptAfterPath" + +# 第一行:sh 执行到这里为止(# 之后是注释,吞掉 Windows 签出时行尾的 \r);cmd 把它当标号。 +# The first line: sh stops here (what follows # is a comment and absorbs the \r of a Windows +# checkout); cmd takes it for a label. +HOOK_CMD_TEXT = """:; exec sh "$(dirname "$0")/libxr_after_cubemx.sh" "$@"; exit 1 # +@echo off +rem STM32CubeMX runs this after it generates the code (Project Manager > Code Generator > +rem User Actions > After Code Generation). It runs `libxr stm32 sync` for this project; +rem the output also goes to .libxr\\after_cubemx.log. Written by `libxr stm32 setup`. +setlocal +cd /d "%~dp0.." +if not exist .libxr mkdir .libxr +if defined LIBXR_PYTHON ( + "%LIBXR_PYTHON%" -c "import libxr.stm32_cubemx_sync" >nul 2>&1 && ( + "%LIBXR_PYTHON%" -m libxr stm32 sync --after-cubemx -d . + exit /b + ) +) +python -c "import libxr.stm32_cubemx_sync" >nul 2>&1 && ( + python -m libxr stm32 sync --after-cubemx -d . + exit /b +) +py -3 -c "import libxr.stm32_cubemx_sync" >nul 2>&1 && ( + py -3 -m libxr stm32 sync --after-cubemx -d . + exit /b +) +> .libxr\\after_cubemx.log echo [LibXR] FAILED: no Python with a libxr that has `libxr stm32 sync` was found (tried LIBXR_PYTHON, python, py -3). Install or update it with `pip install -U libxr`, or set LIBXR_PYTHON to the python.exe that has it, then run `python -m libxr stm32 sync` in %CD%. +type .libxr\\after_cubemx.log +exit /b 1 +""" + +HOOK_SH_TEXT = """#!/bin/sh +# STM32CubeMX runs this through libxr_after_cubemx.cmd after it generates the code (Project +# Manager > Code Generator > User Actions > After Code Generation). It runs +# `libxr stm32 sync` for this project; the output also goes to .libxr/after_cubemx.log. +# Written by `libxr stm32 setup`. +cd "$(dirname "$0")/.." || exit 1 +mkdir -p .libxr +for py in ${LIBXR_PYTHON:-} python3 python; do + if command -v "$py" >/dev/null 2>&1 && "$py" -c "import libxr.stm32_cubemx_sync" >/dev/null 2>&1; then + exec "$py" -m libxr stm32 sync --after-cubemx -d . + fi +done +echo "[LibXR] FAILED: no Python with a libxr that has \\`libxr stm32 sync\\` was found (tried ${LIBXR_PYTHON:+$LIBXR_PYTHON, }python3, python). Install or update it with \\`pip install -U libxr\\`, or set LIBXR_PYTHON to the python that has it, then run \\`python3 -m libxr stm32 sync\\` in $(pwd)." > .libxr/after_cubemx.log +cat .libxr/after_cubemx.log +exit 1 +""" + + +def ioc_digest(ioc_path: str) -> str: + """.ioc 文件的摘要:去掉回车后的 SHA-256 的前 16 个十六进制字符,与签出时的换行方式无关; + LibXR.CMake 用同样的方法计算。 + The digest of an .ioc file: the first 16 hex characters of the SHA-256 without carriage + returns, independent of the line endings of the checkout; LibXR.CMake computes it the same + way. + """ + with open(ioc_path, "rb") as f: + data = f.read().replace(b"\r", b"") + return hashlib.sha256(data).hexdigest()[:16] + + +def _read_ioc(ioc_path: str) -> str: + """原样读出 .ioc 文本,换行不转换。 + Read the .ioc text as it is, without newline translation. + """ + with open(ioc_path, encoding="utf-8", newline="") as f: + return f.read() + + +def _write_ioc(ioc_path: str, text: str) -> None: + """原样写回 .ioc 文本。 + Write the .ioc text back as it is. + """ + with open(ioc_path, "w", encoding="utf-8", newline="") as f: + f.write(text) + + +def _line_pattern(key: str) -> re.Pattern: + """匹配 .ioc 中 key=值 一行(值不含行尾的回车)。 + Match the key=value line of key in the .ioc text (the value without the trailing carriage + return). + """ + return re.compile(rf"^{re.escape(key)}=([^\r\n]*)", re.MULTILINE) + + +def otg_ioc_edits(text: str, instances: Iterable[str]) -> tuple[str, list[str]]: + """在 .ioc 文本 text 中关掉 OTG 实例 instances(如 USB_OTG_FS)的初始化调用和中断函数生成, + 返回新文本和改动的说明。 + Turn off in the .ioc text text the initialization call and the interrupt handler of the OTG + instances (such as USB_OTG_FS), returning the new text and descriptions of the changes. + + ProjectManager.functionlistsort 中 MX_<实例>_PCD_Init 一项的 <不调用> 设为 true、<静态> 设为 + false(没有调用的 static 函数会产生编译警告);NVIC._IRQn 的第 6 项(Generate IRQ + handler)设为 false,中断本身保持开启。之后 CubeMX 生成的代码不再引用 PCD 句柄,它和 HAL 的 + PCD 代码被链接器回收。 + In ProjectManager.functionlistsort the field of MX__PCD_Init becomes true + and its field false (an uncalled static function draws a compiler warning); field 6 + of NVIC._IRQn (Generate IRQ handler) becomes false while the interrupt stays enabled. + The code CubeMX generates afterwards no longer references the PCD handle, and the linker + drops it with the PCD code of HAL. + """ + changes = [] + for name in instances: + function = f"MX_{name}_PCD_Init" + pattern = _line_pattern("ProjectManager.functionlistsort") + match = pattern.search(text) + if match: + entries = match.group(1).split(",") + for index, entry in enumerate(entries): + parts = entry.split("-") + offset = 1 if parts and parts[0] in ("true", "false") else 0 + if len(parts) < offset + 6 or parts[offset + 1] != function: + continue + wanted = parts[:] + wanted[offset + 3] = "true" + wanted[offset + 5] = "false" + if wanted != parts: + entries[index] = "-".join(wanted) + changes.append( + tr( + f"{function}: not called from main(), not static", + f"{function}:main() 不调用,非 static", + ) + ) + text = text[: match.start(1)] + ",".join(entries) + text[match.end(1) :] + irq = f"{name[len('USB_') :]}_IRQn" + nvic = _line_pattern(f"NVIC.{irq}").search(text) + if nvic: + fields = nvic.group(1).split("\\:") + if len(fields) > 5 and fields[5] != "false": + fields[5] = "false" + text = text[: nvic.start(1)] + "\\:".join(fields) + text[nvic.end(1) :] + changes.append( + tr( + f"{irq}: the IRQ handler is not generated", + f"{irq}:不生成中断函数", + ) + ) + return text, changes + + +def set_after_script(text: str, path: str) -> tuple[str, str | None]: + """把 .ioc 文本 text 中的生成后脚本设为 path,返回新文本和原来的脚本(没有或为空时为 None)。 + 原来已是别的脚本时不改动。 + Set the post-generation script in the .ioc text text to path, returning the new text and the + earlier script (None when there was none or it was empty). An earlier, different script is + left in place. + """ + match = _line_pattern(AFTER_SCRIPT_KEY).search(text) + if match: + current = match.group(1).strip() + if current and current != path: + return text, current + if current == path: + return text, None + return text[: match.start(1)] + path + text[match.end(1) :], None + # 没有这个键时,按键名的顺序插入到 ProjectManager 段中。 + # Without the key, it goes into the ProjectManager section in key order. + newline = "\r\n" if "\r\n" in text else "\n" + lines = text.split(newline) + line = f"{AFTER_SCRIPT_KEY}={path}" + for index, existing in enumerate(lines): + if existing.startswith("ProjectManager.") and existing > line: + lines.insert(index, line) + break + else: + lines.insert(len(lines) - 1 if lines and not lines[-1] else len(lines), line) + return newline.join(lines), None + + +def _write_if_changed(path: str, text: str) -> bool: + """内容不同时写出 path(LF 换行),返回是否写了。 + Write path (LF newlines) when its content differs, returning whether it was written. + """ + try: + with open(path, encoding="utf-8", newline="") as f: + if f.read() == text: + return False + except OSError: + pass + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, "w", encoding="utf-8", newline="\n") as f: + f.write(text) + return True + + +def _make_executable(project_dir: str, relative: str) -> None: + """给脚本加上可执行权限;它已由 Git 跟踪时,同时在索引中记下可执行位,使 Linux 上的签出也能 + 直接执行它(Windows 的文件系统不保存这一位)。 + Make the script executable; when Git tracks it, also record the executable bit in the + index, so that a Linux checkout can run it directly (Windows file systems do not keep that + bit). + """ + path = os.path.join(project_dir, relative) + mode = os.stat(path).st_mode + os.chmod(path, mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH) + try: + tracked = subprocess.run( + ["git", "ls-files", "--error-unmatch", relative], + cwd=project_dir, + capture_output=True, + ) + if tracked.returncode == 0: + subprocess.run( + ["git", "update-index", "--chmod=+x", relative], + cwd=project_dir, + capture_output=True, + ) + except OSError: + pass + + +def _ignore_log(project_dir: str) -> None: + """工程的 .gitignore 不忽略 .libxr/ 时加上这一行。 + Add .libxr/ to the .gitignore of the project when it does not ignore it yet. + """ + path = os.path.join(project_dir, ".gitignore") + if not os.path.exists(path): + return + with open(path, encoding="utf-8", newline="") as f: + content = f.read() + if any(line.strip() in (".libxr/", ".libxr", ".libxr/**") for line in content.splitlines()): + return + newline = "\r\n" if "\r\n" in content else "\n" + if content and not content.endswith(("\n", "\r")): + content += newline + with open(path, "w", encoding="utf-8", newline="") as f: + f.write(content + ".libxr/" + newline) + + +def install_hook(project_dir: str, ioc_path: str) -> None: + """写出生成后脚本并在 .ioc 中登记它;.ioc 已登记别的脚本时保留它,记录警告说明怎样从那个脚本 + 调用 HOOK_CMD。 + Write the post-generation script and register it in the .ioc file; an .ioc file that + already registers another script keeps it, with a warning that tells how to call HOOK_CMD + from that script. + """ + for relative, text in ((HOOK_CMD, HOOK_CMD_TEXT), (HOOK_SH, HOOK_SH_TEXT)): + if _write_if_changed(os.path.join(project_dir, relative), text): + logging.info(tr(f"Wrote {relative}", f"已写入 {relative}")) + _make_executable(project_dir, HOOK_CMD) + _ignore_log(project_dir) + text = _read_ioc(ioc_path) + new_text, other = set_after_script(text, HOOK_CMD) + name = os.path.basename(ioc_path) + if other: + logging.warning( + tr( + f"{name} already runs {other} after code generation; LibXR does not replace " + f"it. Call {HOOK_CMD} at the end of that script so that every CubeMX code " + "generation also runs `libxr stm32 sync`", + f"{name} 已登记生成后脚本 {other};LibXR 不替换它。请在该脚本末尾调用 " + f"{HOOK_CMD},使每次在 CubeMX 中生成代码时也运行 `libxr stm32 sync`", + ) + ) + elif new_text != text: + _write_ioc(ioc_path, new_text) + logging.info( + tr( + f"{name}: STM32CubeMX now runs {HOOK_CMD} after each code generation", + f"{name}:STM32CubeMX 此后每次生成代码都会运行 {HOOK_CMD}", + ) + ) + + +def apply_otg_settings(ioc_path: str, instances: Iterable[str]) -> bool: + """在 .ioc 中关掉 instances 的初始化调用和中断函数生成(见 otg_ioc_edits()),返回是否改动。 + Turn off the initialization call and the interrupt handler of instances in the .ioc file + (see otg_ioc_edits()), returning whether anything changed. + """ + instances = list(instances) + if not instances: + return False + text = _read_ioc(ioc_path) + new_text, changes = otg_ioc_edits(text, instances) + if new_text == text: + return False + _write_ioc(ioc_path, new_text) + name = os.path.basename(ioc_path) + logging.info( + tr( + f"{name}: {'; '.join(changes)}. They take effect when STM32CubeMX generates the " + "code next time (reopen the .ioc file if it is open in STM32CubeMX); until then " + "LibXR takes over the generated calls", + f"{name}:{';'.join(changes)}。下次在 STM32CubeMX 中生成代码时生效(.ioc 正在 " + "STM32CubeMX 中打开时需重新打开);在此之前由 LibXR 接管生成的调用", + ) + ) + return True + + +def sync(project_dir: str, after_cubemx: bool = False) -> int: + """更新 project_dir 中 LibXR 的生成结果,返回退出码(0 成功,1 失败)。 + Bring the LibXR output of project_dir up to date and return the exit code (0 on success, 1 + on failure). + + 依次:检查工程(见 check_project());解析 .ioc 并生成 User/app_main.cpp(沿用工程是否使用 + XRobot);在 .ioc 中关掉 LibXR 接管的 OTG 实例的初始化调用和中断函数生成,有改动时再解析和 + 生成一次,使 app_main.cpp 记下改后 .ioc 的摘要;更新 CMake 集成;更新已安装的生成后脚本。 + 输出同时写进 SYNC_LOG,最后一行是结果。after_cubemx 表示由 CubeMX 的生成后脚本调用,结果行 + 这时说明怎样手动重试。 + In order: check the project (see check_project()); parse the .ioc file and generate + User/app_main.cpp, keeping whether the project uses XRobot; turn off in the .ioc file the + initialization call and the interrupt handler of the OTG instances LibXR takes over, and + parse and generate once more after a change, so that app_main.cpp records the digest of the + changed .ioc file; update the CMake integration; update an installed post-generation + script. The output also goes to SYNC_LOG, whose last line is the result. after_cubemx means + the post-generation script of CubeMX called it; the result line then tells how to retry by + hand. + """ + from libxr import generator_code_stm32 + from libxr.config_cubemx_project import check_project + from libxr.generator_stm32_cmake import integrate, project_uses_xrobot + from libxr.peripheral_analyzer_stm32 import parse_project + + project_dir = os.path.abspath(project_dir) + log_path = os.path.join(project_dir, SYNC_LOG) + os.makedirs(os.path.dirname(log_path), exist_ok=True) + handler = logging.FileHandler(log_path, mode="w", encoding="utf-8") + handler.setFormatter(_Formatter("%(message)s")) + root = logging.getLogger() + root.addHandler(handler) + ok = False + try: + if after_cubemx: + logging.info( + tr( + "LibXR: updating the generated code after STM32CubeMX", + "LibXR:在 STM32CubeMX 生成代码之后更新 LibXR 的生成结果", + ) + ) + ioc_path = check_project(project_dir) + yaml_path = os.path.join(project_dir, ".config.yaml") + cpp_path = os.path.join(project_dir, "User", "app_main.cpp") + use_xrobot = project_uses_xrobot(project_dir) + for _ in range(2): + parse_project(project_dir, yaml_path, summary=False) + generator_code_stm32.generate(yaml_path, cpp_path, use_xrobot) + if not apply_otg_settings(ioc_path, generator_code_stm32.otg_devices): + break + integrate(project_dir) + if os.path.exists(os.path.join(project_dir, HOOK_CMD)): + for relative, text in ((HOOK_CMD, HOOK_CMD_TEXT), (HOOK_SH, HOOK_SH_TEXT)): + _write_if_changed(os.path.join(project_dir, relative), text) + _make_executable(project_dir, HOOK_CMD) + ok = True + except SystemExit as error: + # The steps log their own error before they exit. + ok = not error.code + except Exception as error: # noqa: BLE001 - every failure must reach the log + logging.error(str(error)) + logging.debug(tr("Traceback:", "调用栈:"), exc_info=True) + finally: + if ok: + logging.info(tr("[LibXR] OK", "[LibXR] 完成")) + else: + logging.error( + tr( + f"[LibXR] FAILED. Fix the error above, then run `python -m libxr stm32 " + f"sync` in {project_dir}, or generate the code in STM32CubeMX again", + f"[LibXR] 失败。修正上面的错误后,在 {project_dir} 中运行 `python -m libxr " + "stm32 sync`,或在 STM32CubeMX 中重新生成代码", + ) + ) + root.removeHandler(handler) + handler.close() + return 0 if ok else 1 + + +if __name__ == "__main__": + sys.exit(sync(os.curdir)) diff --git a/tests/test_config_cubemx_project.py b/tests/test_config_cubemx_project.py index 2f46892..c75f35f 100644 --- a/tests/test_config_cubemx_project.py +++ b/tests/test_config_cubemx_project.py @@ -648,8 +648,15 @@ def test_a_cubemx_project_is_set_up(self): self.assertEqual(git("rev-parse", "HEAD", cwd=checkout), self.default) self.assertEqual( (project / ".gitignore").read_text(encoding="utf-8"), - "build/**\n.history/**\n.cache/**\n.config.yaml\nCMakeFiles/**\n", + "build/**\n.history/**\n.cache/**\n.config.yaml\nCMakeFiles/**\n.libxr/\n", ) + # STM32CubeMX runs the post-generation script after every code generation. + self.assertIn( + "ProjectManager.UAScriptAfterPath=cmake/libxr_after_cubemx.cmd", + next(project.glob("*.ioc")).read_text(encoding="utf-8"), + ) + self.assertTrue((project / "cmake" / "libxr_after_cubemx.cmd").is_file()) + self.assertTrue((project / "cmake" / "libxr_after_cubemx.sh").is_file()) self.assertIn( "* text=auto\n*.sh text eol=lf\n*.bat text eol=crlf\n", (project / ".gitattributes").read_text(encoding="utf-8"), diff --git a/tests/test_generator_code_stm32.py b/tests/test_generator_code_stm32.py index c2c04e0..5ff7387 100644 --- a/tests/test_generator_code_stm32.py +++ b/tests/test_generator_code_stm32.py @@ -346,12 +346,122 @@ class PeripheralObjects(GeneratorTestCase): Static objects of peripherals, channels, USB devices, the terminal and DMA buffers. """ - def usb_otg_hs(self, **settings): - """启用 USB_OTG_HS 的工程数据,USB 设置按给出的值。 - Project data with USB_OTG_HS enabled and the given USB settings. + def usb_otg_hs(self, ioc=None, **settings): + """启用 USB_OTG_HS 的工程数据,USB 设置按给出的值;ioc 是解析器记下的实例配置。 + Project data with USB_OTG_HS enabled and the given USB settings; ioc is the instance + configuration the parser records. """ generator.libxr_settings.setdefault("USB", {})["usb_otg_hs"] = {"enable": True, **settings} - return self.project(peripherals={"USB": {"USB_OTG_HS": {"enable": True}}}) + return self.project(peripherals={"USB": {"USB_OTG_HS": {"enable": True, **(ioc or {})}}}) + + def test_an_otg_device_with_dma_gets_the_ep0_out_buffer(self): + # MC02 的 OTG_HS:内置全速 PHY,开启 DMA。 + # The OTG_HS of MC02: embedded full-speed PHY with DMA. + project = self.usb_otg_hs( + { + "Role": "Device", + "profiles": { + "Device_Only_FS": {"VirtualMode": "Device_Only_FS", "dma_enable": "ENABLE"} + }, + } + ) + code = self.generate(project) + self.assertIn("alignas(32) static uint8_t usb_otg_hs_ep0_dma_buf[64];\n", code) + self.assertIn( + " static STM32USBDeviceOtgHS usb_otg_hs(\n" + " {STM32USBOtgDevice::Phy::EMBEDDED_FS, true, false, false, usb_otg_hs_ep0_dma_buf},\n" + " 256, {usb_otg_hs_ep0_out_buf, usb_otg_hs_ep1_out_buf},\n", + code, + ) + + def test_an_otg_device_on_ulpi_runs_at_high_speed(self): + # 高速时数据端点每个槽至少 512 字节;speed 为 *_HIGH_IN_FULL 时以全速枚举。 + # At high speed each slot of a data endpoint is at least 512 bytes; with speed + # *_HIGH_IN_FULL the device enumerates at full speed. + for speed, high, size in (("", "true", 1024), ("PCD_SPEED_HIGH_IN_FULL", "false", 128)): + with self.subTest(speed=speed): + ioc = {"Role": "Device", "VirtualMode": "Device_HS"} + if speed: + ioc["speed"] = speed + code = self.generate(self.usb_otg_hs(ioc)) + self.assertIn(f"usb_otg_hs_ep1_in_buf[{size}];\n", code) + self.assertIn(f"usb_otg_hs_ep1_out_buf[{size}];\n", code) + self.assertIn(f"{{STM32USBOtgDevice::Phy::ULPI, false, false, {high}}}", code) + + def test_the_embedded_high_speed_phy_runs_at_high_speed(self): + # STM32F723 这类芯片的 OTG_HS 内置高速 PHY,CubeMX 的模式为 Internal_Phy_Device。 + # The OTG_HS of chips such as the STM32F723 has an embedded high-speed PHY; the CubeMX + # mode is Internal_Phy_Device. + code = self.generate( + self.usb_otg_hs({"Role": "Device", "VirtualMode": "Internal_Phy_Device"}) + ) + self.assertIn("{STM32USBOtgDevice::Phy::EMBEDDED_HS, false, false, true}", code) + self.assertIn("usb_otg_hs_ep1_in_buf[1024];\n", code) + + def test_an_otg_device_works_with_the_cubemx_defaults(self): + # CubeMX 默认调用初始化函数并生成中断函数:LibXR 在链接时包装 HAL_PCD_Init() 和 + # HAL_PCD_IRQHandler(),生成器不加向量函数,也不要求改 CubeMX。 + # By default CubeMX calls the initialization function and generates the interrupt + # handler: LibXR wraps HAL_PCD_Init() and HAL_PCD_IRQHandler() at link time, so the + # generator adds no vector function and asks for no CubeMX change. + project = self.usb_otg_hs( + { + "Role": "Device", + "InitCalled": True, + "InitStatic": True, + "Vectors": { + "OTG_HS_IRQn": {"Enabled": True, "Handler": True}, + "OTG_HS_EP1_OUT_IRQn": {"Enabled": True, "Handler": True}, + }, + } + ) + code = self.generate(project) + self.assertIn("static STM32USBDeviceOtgHS usb_otg_hs(", code) + self.assertNotIn("IRQHandler", code) + + def test_an_otg_vector_is_written_when_cubemx_generates_none(self): + project = self.usb_otg_hs( + { + "Role": "Device", + "InitCalled": True, + "Vectors": {"OTG_HS_IRQn": {"Enabled": True, "Handler": False}}, + } + ) + code = self.generate(project) + self.assertIn( + 'extern "C" void OTG_HS_IRQHandler(void)\n' + "{\n" + " STM32USBOtgDevice::Dispatch(USB_OTG_HS);\n" + "}\n" + "\n" + 'extern "C" void app_main(void)\n', + code, + ) + + def test_an_otg_interrupt_must_be_enabled(self): + project = self.usb_otg_hs( + {"Role": "Device", "Vectors": {"OTG_HS_IRQn": {"Enabled": False, "Handler": True}}} + ) + with self.assertRaisesMessage( + ValueError, "USB_OTG_HS: OTG_HS_IRQn is not enabled; enable it in STM32CubeMX NVIC" + ): + self.generate(project) + + def test_a_static_otg_init_function_is_warned_about(self): + project = self.usb_otg_hs( + { + "Role": "Device", + "InitCalled": False, + "InitStatic": True, + "Vectors": {"OTG_HS_IRQn": {"Enabled": True, "Handler": False}}, + } + ) + with self.assertLogs(level="WARNING") as logs: + code = self.generate(project) + self.assertIn("static STM32USBDeviceOtgHS usb_otg_hs(", code) + self.assertTrue( + any("MX_USB_OTG_HS_PCD_Init is static and not called" in line for line in logs.output) + ) def test_an_otg_device_takes_its_settings(self): # 参数顺序与 LibXR 的 STM32USBDeviceOtgHS 和 CDCUart 构造函数一致。 @@ -359,7 +469,7 @@ def test_an_otg_device_takes_its_settings(self): # LibXR. project = self.usb_otg_hs( ep0_packet_size=64, - tx_buffer_size=64, + tx_buffer_size=100, rx_buffer_size=256, tx_fifo_size=192, rx_fifo_size=512, @@ -373,19 +483,27 @@ def test_an_otg_device_takes_its_settings(self): dma_section=".dma", ) code = self.generate(project, use_xrobot=False) + # 端点缓冲区按 32 字节对齐,数据端点分为两个槽、每槽按 32 字节取整,所以 tx_buffer_size + # 100 变为 128;通知端点两个槽各 32 字节。 + # Endpoint buffers are 32-byte aligned and a data endpoint is two slots in 32-byte + # steps, so tx_buffer_size 100 becomes 128; the notification endpoint gets 32 bytes per + # slot. self.assertEqual( - [line for line in code.splitlines() if line.startswith("alignas(4) static uint8_t")], + [line for line in code.splitlines() if line.startswith("alignas(32) static uint8_t")], [ - f'alignas(4) static uint8_t usb_otg_hs_{name}[{size}] __attribute__((section(".dma")));' + f'alignas(32) static uint8_t usb_otg_hs_{name}[{size}] __attribute__((section(".dma")));' for name, size in ( ("ep0_in_buf", 64), ("ep0_out_buf", 64), - ("ep1_in_buf", 64), + ("ep1_in_buf", 128), ("ep1_out_buf", 256), - ("ep2_in_buf", 16), + ("ep2_in_buf", 64), ) ], ) + # The raised size is written back; the other one was already a valid size. + settings = generator.libxr_settings["USB"]["usb_otg_hs"] + self.assertEqual((settings["tx_buffer_size"], settings["rx_buffer_size"]), (128, 256)) self.assertIn( " // USB OTG HS: 1 CDC\n" " static constexpr auto usb_otg_hs_strings = USB::DescriptorStrings::MakeLanguagePack(\n" @@ -394,7 +512,8 @@ def test_an_otg_device_takes_its_settings(self): " USB::Endpoint::EPNumber::EP1,\n" " USB::Endpoint::EPNumber::EP2, 80, 96, 4);\n" " static STM32USBDeviceOtgHS usb_otg_hs(\n" - " &hpcd_USB_OTG_HS, 512, {usb_otg_hs_ep0_out_buf, usb_otg_hs_ep1_out_buf},\n" + " {STM32USBOtgDevice::Phy::EMBEDDED_FS, false, false, false}, 512,\n" + " {usb_otg_hs_ep0_out_buf, usb_otg_hs_ep1_out_buf},\n" " {{usb_otg_hs_ep0_in_buf, 64},\n" " {usb_otg_hs_ep1_in_buf, 192},\n" " {usb_otg_hs_ep2_in_buf, 16}},\n" @@ -430,7 +549,7 @@ def test_several_cdcs_take_endpoints_in_order(self): " USB::Endpoint::EPNumber::EP2,\n" " USB::Endpoint::EPNumber::EP4, 128, 128, 3);\n" " static STM32USBDeviceOtgHS usb_otg_hs(\n" - " &hpcd_USB_OTG_HS, 256,\n" + " {STM32USBOtgDevice::Phy::EMBEDDED_FS, false, false, false}, 256,\n" " {usb_otg_hs_ep0_out_buf, usb_otg_hs_ep1_out_buf, usb_otg_hs_ep2_out_buf},\n" " {{usb_otg_hs_ep0_in_buf, 8},\n" " {usb_otg_hs_ep1_in_buf, 128},\n" @@ -444,19 +563,19 @@ def test_several_cdcs_take_endpoints_in_order(self): ) self.assertEqual( [ - line.removeprefix("alignas(4) static uint8_t ") + line.removeprefix("alignas(32) static uint8_t ") for line in code.splitlines() - if line.startswith("alignas(4) static uint8_t") + if line.startswith("alignas(32) static uint8_t") ], [ - "usb_otg_hs_ep0_in_buf[8];", - "usb_otg_hs_ep0_out_buf[8];", + "usb_otg_hs_ep0_in_buf[32];", + "usb_otg_hs_ep0_out_buf[32];", "usb_otg_hs_ep1_in_buf[128];", "usb_otg_hs_ep1_out_buf[128];", - "usb_otg_hs_ep2_in_buf[16];", + "usb_otg_hs_ep2_in_buf[64];", "usb_otg_hs_ep2_out_buf[128];", "usb_otg_hs_ep3_in_buf[128];", - "usb_otg_hs_ep4_in_buf[16];", + "usb_otg_hs_ep4_in_buf[64];", ], ) for name in ("usb_otg_hs_cdc", "usb_otg_hs_cdc2"): diff --git a/tests/test_generator_stm32_cmake.py b/tests/test_generator_stm32_cmake.py index 82592f7..570d13f 100644 --- a/tests/test_generator_stm32_cmake.py +++ b/tests/test_generator_stm32_cmake.py @@ -228,6 +228,7 @@ def test_a_new_file_has_the_fixed_structure(self): "Compile options", "LibXR", "Application", + "CubeMX", "Library optimization", "Firmware images", "Application settings", @@ -548,7 +549,7 @@ def test_devc_keeps_its_settings_and_warning_options(self): ) # 其余块与新文件相同。 # The other blocks equal those of a new file. - for title in ("LibXR", "Application", "Library optimization", "Firmware images"): + for title in ("LibXR", "Application", "CubeMX", "Library optimization", "Firmware images"): self.assertEqual( blocks[title], stm32_cmake.split_blocks(stm32_cmake.render_libxr_cmake(""))[title] ) diff --git a/tests/test_peripheral_analyzer_stm32.py b/tests/test_peripheral_analyzer_stm32.py index 259ab33..ccf4259 100644 --- a/tests/test_peripheral_analyzer_stm32.py +++ b/tests/test_peripheral_analyzer_stm32.py @@ -555,10 +555,40 @@ def test_the_mode_of_a_profile_gives_the_role(self): "IPParameters": ["VirtualMode-Device_Only_FS"], "Role": "Device", "profiles": {"Device_Only_FS": {"VirtualMode": "Device_Only_FS"}}, + "InitCalled": False, + "InitStatic": False, }, ) self.assertEqual(usb["USB_OTG_FS"]["Role"], "Device") + def test_an_otg_instance_records_its_code_generation_settings(self): + # NVIC. 的第 6 项是 Generate IRQ handler;functionlistsort 中 USB_OTG_FS 后的 true + # 是 Do Not Generate Function Call,HAL 后的 false 是非 static。 + # Field 6 of NVIC. is Generate IRQ handler; in functionlistsort the true after + # USB_OTG_FS is Do Not Generate Function Call and the false after HAL is non-static. + ioc = ( + "Mcu.Family=STM32F4\n" + "Mcu.CPN=STM32F407IGH6\n" + "Mcu.IP0=USB_OTG_FS\n" + "USB_OTG_FS.IPParameters=VirtualMode\n" + "USB_OTG_FS.VirtualMode=Device_Only\n" + "NVIC.OTG_FS_IRQn=true\\:5\\:0\\:false\\:false\\:false\\:true\\:true\\:true\\:true\n" + "NVIC.OTG_FS_WKUP_IRQn=true\\:5\\:0\\:false\\:false\\:true\\:true\\:true\\:true\\:true\n" + "ProjectManager.functionlistsort=1-SystemClock_Config-RCC-false-HAL-false," + "2-MX_USB_OTG_FS_PCD_Init-USB_OTG_FS-true-HAL-false\n" + ) + with self.assertLogs(level="WARNING"): + usb = self.parse("", ioc)["Peripherals"]["USB"]["USB_OTG_FS"] + self.assertFalse(usb["InitCalled"]) + self.assertFalse(usb["InitStatic"]) + self.assertEqual( + usb["Vectors"], + { + "OTG_FS_IRQn": {"Enabled": True, "Handler": False}, + "OTG_FS_WKUP_IRQn": {"Enabled": True, "Handler": True}, + }, + ) + class Rtos(TestCase): """FreeRTOS 和 ThreadX 的不同来源都写出对应的段,libxr gen 据此选择 LibXR 的系统。 diff --git a/tests/test_stm32_cubemx_sync.py b/tests/test_stm32_cubemx_sync.py new file mode 100644 index 0000000..8edf2db --- /dev/null +++ b/tests/test_stm32_cubemx_sync.py @@ -0,0 +1,224 @@ +"""STM32CubeMX 生成后步骤(libxr.stm32_cubemx_sync):.ioc 的修改、生成后脚本的登记、.ioc 摘要和 +LibXR.CMake 中的摘要检查,以及 sync 失败时的日志。 +The STM32CubeMX post-generation step (libxr.stm32_cubemx_sync): the changes to the .ioc file, +the registration of the post-generation script, the .ioc digest and its check in LibXR.CMake, +and the log of a failed sync. +""" + +import os +import shutil +import subprocess +import tempfile +import unittest +from pathlib import Path + +from fixtures import GeneratorTestCase, TestCase + +from libxr import generator_code_stm32 as generator +from libxr import generator_stm32_cmake as stm32_cmake +from libxr import stm32_cubemx_sync as cubemx_sync + +# CubeMX 默认设置下 OTG_FS 的相关行:main() 调用 MX_USB_OTG_FS_PCD_Init(static),NVIC 生成 +# OTG_FS_IRQHandler。CubeMX 在 Windows 上写 CRLF。 +# The OTG_FS lines with the CubeMX defaults: main() calls MX_USB_OTG_FS_PCD_Init (static) and +# NVIC generates OTG_FS_IRQHandler. CubeMX writes CRLF on Windows. +IOC = ( + "#MicroXplorer Configuration settings - do not modify\r\n" + "NVIC.OTG_FS_IRQn=true\\:5\\:0\\:false\\:false\\:true\\:true\\:true\\:true\\:true\r\n" + "NVIC.TIM6_DAC_IRQn=true\\:0\\:0\\:false\\:false\\:true\\:true\\:true\\:true\\:true\r\n" + "ProjectManager.UAScriptAfterPath=\r\n" + "ProjectManager.UAScriptBeforePath=\r\n" + "ProjectManager.functionlistsort=1-SystemClock_Config-RCC-false-HAL-false," + "2-MX_GPIO_Init-GPIO-false-HAL-true,3-MX_USB_OTG_FS_PCD_Init-USB_OTG_FS-false-HAL-true\r\n" +) + + +class IocChanges(TestCase): + """.ioc 的修改只动目标字段,换行保持原样。 + The changes to the .ioc file touch only the target fields and keep the line endings. + """ + + def test_the_otg_instance_is_neither_called_nor_handled_by_cubemx(self): + text, changes = cubemx_sync.otg_ioc_edits(IOC, ["USB_OTG_FS"]) + self.assertEqual(len(changes), 2) + self.assertIn("3-MX_USB_OTG_FS_PCD_Init-USB_OTG_FS-true-HAL-false\r\n", text) + self.assertIn( + "NVIC.OTG_FS_IRQn=true\\:5\\:0\\:false\\:false\\:false\\:true\\:true\\:true\\:true\r\n", + text, + ) + # Other entries and interrupts stay as they were. + self.assertIn("2-MX_GPIO_Init-GPIO-false-HAL-true", text) + self.assertIn("NVIC.TIM6_DAC_IRQn=true\\:0\\:0\\:false\\:false\\:true\\:", text) + self.assertEqual(text.count("\r\n"), IOC.count("\r\n")) + # A second run changes nothing. + self.assertEqual(cubemx_sync.otg_ioc_edits(text, ["USB_OTG_FS"]), (text, [])) + + def test_the_post_generation_script_is_registered_once(self): + text, other = cubemx_sync.set_after_script(IOC, cubemx_sync.HOOK_CMD) + self.assertIsNone(other) + self.assertIn("ProjectManager.UAScriptAfterPath=cmake/libxr_after_cubemx.cmd\r\n", text) + self.assertEqual(cubemx_sync.set_after_script(text, cubemx_sync.HOOK_CMD), (text, None)) + + def test_a_script_of_the_user_is_kept(self): + mine = IOC.replace("UAScriptAfterPath=", "UAScriptAfterPath=tools/mine.cmd") + self.assertEqual( + cubemx_sync.set_after_script(mine, cubemx_sync.HOOK_CMD), (mine, "tools/mine.cmd") + ) + + def test_a_missing_key_is_inserted_in_key_order(self): + text = IOC.replace("ProjectManager.UAScriptAfterPath=\r\n", "") + text, _ = cubemx_sync.set_after_script(text, cubemx_sync.HOOK_CMD) + self.assertIn( + "ProjectManager.UAScriptAfterPath=cmake/libxr_after_cubemx.cmd\r\n" + "ProjectManager.UAScriptBeforePath=\r\n", + text, + ) + + def test_the_digest_ignores_line_endings(self): + with tempfile.TemporaryDirectory() as directory: + crlf = Path(directory, "crlf.ioc") + lf = Path(directory, "lf.ioc") + crlf.write_bytes(IOC.encode()) + lf.write_bytes(IOC.replace("\r\n", "\n").encode()) + self.assertEqual(cubemx_sync.ioc_digest(crlf), cubemx_sync.ioc_digest(lf)) + self.assertRegex(cubemx_sync.ioc_digest(crlf), "^[0-9a-f]{16}$") + + +class HookScripts(TestCase): + """生成后脚本:同一个文件对 cmd 和 sh 都成立。 + The post-generation script: one file valid for both cmd and sh. + """ + + def test_the_first_line_hands_over_to_sh_and_is_a_label_for_cmd(self): + first = cubemx_sync.HOOK_CMD_TEXT.split("\n")[0] + # A colon starts a label in cmd; in sh it is the empty command. + self.assertTrue(first.startswith(":;")) + # The comment at the end absorbs the carriage return of a CRLF checkout. + self.assertTrue(first.endswith(" #")) + + @unittest.skipUnless(shutil.which("sh"), "sh is not available") + def test_sh_reports_a_missing_libxr_in_the_log(self): + with tempfile.TemporaryDirectory() as directory: + os.makedirs(os.path.join(directory, "cmake")) + for relative, text in ( + (cubemx_sync.HOOK_CMD, cubemx_sync.HOOK_CMD_TEXT), + (cubemx_sync.HOOK_SH, cubemx_sync.HOOK_SH_TEXT), + ): + Path(directory, relative).write_text(text, encoding="utf-8", newline="\n") + # A PATH without any python: the script must say so instead of failing silently. + result = subprocess.run( + ["sh", cubemx_sync.HOOK_CMD], + cwd=directory, + capture_output=True, + text=True, + env={"PATH": os.path.dirname(shutil.which("sh")), "LIBXR_PYTHON": ""}, + ) + self.assertEqual(result.returncode, 1) + log = Path(directory, cubemx_sync.SYNC_LOG).read_text(encoding="utf-8") + self.assertIn("[LibXR] FAILED: no Python with a libxr that has", log) + self.assertIn("pip install -U libxr", log) + self.assertIn(log.strip(), result.stdout) + + +class GeneratedRecords(GeneratorTestCase): + """生成器记下 .ioc 摘要,并按 Core/Src 中实际生成的中断函数决定是否补向量函数。 + The generator records the .ioc digest and writes a vector function according to the + interrupt handlers actually generated in Core/Src. + """ + + def test_the_notice_names_the_ioc_digest(self): + project = self.project() + project["Ioc"] = "Board.ioc" + project["IocDigest"] = "0123456789abcdef" + code = self.generate(project) + self.assertIn("// Board.ioc digest: 0123456789abcdef\n", code) + + def test_the_generated_sources_decide_the_vector(self): + settings = { + "Role": "Device", + "Vectors": {"OTG_HS_IRQn": {"Enabled": True, "Handler": False}}, + } + generator.libxr_settings.setdefault("USB", {})["usb_otg_hs"] = {"enable": True} + project = self.project(peripherals={"USB": {"USB_OTG_HS": {"enable": True, **settings}}}) + # The .ioc file already turns the handler off, but Core/Src still defines it: no second + # definition. + generator.cubemx_irq_handlers = {"OTG_HS_IRQHandler"} + try: + self.assertNotIn("void OTG_HS_IRQHandler", self.generate(project)) + generator.cubemx_irq_handlers = set() + self.assertIn('extern "C" void OTG_HS_IRQHandler(void)', self.generate(project)) + finally: + generator.cubemx_irq_handlers = None + self.assertEqual(generator.otg_devices, ["USB_OTG_HS"]) + + +@unittest.skipUnless(shutil.which("cmake"), "cmake is not available") +class CMakeDigestCheck(TestCase): + """LibXR.CMake 的 CubeMX 块:摘要一致时配置通过,不一致时失败并附上生成后步骤的日志。 + The CubeMX block of LibXR.CMake: configuring passes with a matching digest and fails with the + log of the post-generation step otherwise. + """ + + def configure(self, directory, digest, log=None): + """在 directory 中写出 Board.ioc、记下 digest 的 app_main.cpp、可选的日志和只含 CubeMX 块的 + CMakeLists.txt,运行 CMake 配置并返回结果。 + Write Board.ioc, an app_main.cpp recording digest, the optional log and a CMakeLists.txt + with only the CubeMX block into directory, run the CMake configuration and return the + result. + """ + Path(directory, "Board.ioc").write_bytes(IOC.encode()) + Path(directory, "User").mkdir(exist_ok=True) + Path(directory, "User", "app_main.cpp").write_text( + f"// Board.ioc digest: {digest}\n", encoding="utf-8" + ) + if log is not None: + Path(directory, ".libxr").mkdir(exist_ok=True) + Path(directory, cubemx_sync.SYNC_LOG).write_text(log, encoding="utf-8") + Path(directory, "CMakeLists.txt").write_text( + "cmake_minimum_required(VERSION 3.22)\nproject(t NONE)\n" + + stm32_cmake.CUBEMX_BLOCK + + "\n", + encoding="utf-8", + ) + return subprocess.run( + ["cmake", "-S", directory, "-B", os.path.join(directory, "build")], + capture_output=True, + text=True, + ) + + def test_a_matching_digest_configures(self): + with tempfile.TemporaryDirectory() as directory: + Path(directory, "Board.ioc").write_bytes(IOC.encode()) + digest = cubemx_sync.ioc_digest(os.path.join(directory, "Board.ioc")) + result = self.configure(directory, digest) + self.assertEqual(result.returncode, 0, result.stderr) + + def test_another_digest_fails_with_the_log(self): + with tempfile.TemporaryDirectory() as directory: + result = self.configure( + directory, "0000000000000000", log="[ERROR] something; with a semicolon\n" + ) + self.assertNotEqual(result.returncode, 0) + # CMake wraps the message; compare the words. + message = " ".join(result.stderr.split()) + self.assertIn("changed after User/app_main.cpp was generated", message) + self.assertIn("python -m libxr stm32 sync", message) + self.assertIn("[ERROR] something; with a semicolon", message) + + +class FailedSync(TestCase): + """sync 失败时,日志的最后一行说明怎样手动重试。 + When sync fails, the last line of the log tells how to retry by hand. + """ + + def test_the_log_ends_with_the_command_to_retry(self): + with tempfile.TemporaryDirectory() as directory: + with self.assertLogs(level="ERROR"): + self.assertEqual(cubemx_sync.sync(directory, after_cubemx=True), 1) + log = Path(directory, cubemx_sync.SYNC_LOG).read_text(encoding="utf-8") + self.assertIn("missing Core/ directory", log) + self.assertIn("python -m libxr stm32 sync", log.strip().splitlines()[-1]) + + +if __name__ == "__main__": + unittest.main() From 818989e03f71d1c5607028c8fa26767266f3613a Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Thu, 15 Oct 2026 22:49:19 +0100 Subject: [PATCH 2/4] feat(stm32): FSDEV device support for the register runtime Emit the RX/TX list device constructor without any hpcd, generate the FSDEV/DRD vector function when CubeMX provides no IRQ handler, and number the data OUT endpoints EP(i+1) on both OTG and FSDEV. --- src/libxr/generator_code_stm32.py | 121 ++++++++++++++++++++++------- tests/test_generator_code_stm32.py | 39 ++++++---- 2 files changed, 113 insertions(+), 47 deletions(-) diff --git a/src/libxr/generator_code_stm32.py b/src/libxr/generator_code_stm32.py index 975b623..b326d4b 100644 --- a/src/libxr/generator_code_stm32.py +++ b/src/libxr/generator_code_stm32.py @@ -1246,6 +1246,59 @@ def _default_usb_enables(peripherals: dict) -> None: ) +def _fsdev_vector(name: str, config: dict) -> list[str]: + """FSDEV/DRD 实例的中断向量函数:CubeMX 生成了中断函数时为空列表,否则是调用驱动 + Dispatch() 的向量函数定义。 + The interrupt vector function of an FSDEV or DRD instance: an empty list when CubeMX + generates the interrupt handler, otherwise the definition of a vector function that + calls the driver's Dispatch(). + + CubeMX 保持默认设置即可:LibXR 在链接时包装 HAL_PCD_Init() 和 HAL_PCD_IRQHandler(), + CubeMX 生成的中断函数进入驱动。经典型(F1/F3)的主中断是 USB_LP_CAN1_RX0_IRQn + (USB_HP_CAN1_TX_IRQn 只承载 CTR,同一入口处理),DRD 与其余经典型是 USB_IRQn, + G0B1 与 UCPD 共用 USB_UCPD1_2_IRQn。NVIC 未开启主中断时报错。 + CubeMX can keep its default settings: LibXR wraps HAL_PCD_Init() and + HAL_PCD_IRQHandler() at link time, so the interrupt handler CubeMX generates enters + the driver. The main interrupt of the classic parts (F1/F3) is USB_LP_CAN1_RX0_IRQn + (USB_HP_CAN1_TX_IRQn carries only CTR, handled by the same entry), DRD and the other + classic parts use USB_IRQn, and G0B1 shares USB_UCPD1_2_IRQn with UCPD. A missing + NVIC entry for the main interrupt raises an error. + """ + vectors = config.get("Vectors") + main_irq = None + if vectors: + for preferred in ("USB_LP_CAN1_RX0_IRQn", "USB_UCPD1_2_IRQn", "USB_IRQn"): + if preferred in vectors: + main_irq = preferred + break + if main_irq is None: + # 老解析结果没有向量信息:按 CubeMX 默认处理。 + # An older parse result has no vector data: treat it as the CubeMX default. + return [] + entry = dict(vectors.get(main_irq, {"Enabled": True, "Handler": True})) + handler = main_irq[: -len("_IRQn")] + "_IRQHandler" + if cubemx_irq_handlers is not None: + # 生成的源码决定:.ioc 可能已改而 Core/Src 里的代码还是旧的。 + # The generated sources decide: the .ioc file may already be changed while the + # code in Core/Src still comes from the earlier settings. + entry["Handler"] = handler in cubemx_irq_handlers + if not entry.get("Enabled"): + raise LibXRConfigError( + tr( + f"{name}: {main_irq} is not enabled; enable it in STM32CubeMX NVIC", + f"{name}:没有开启 {main_irq};请在 STM32CubeMX 的 NVIC 中开启", + ) + ) + if entry.get("Handler"): + return [] + return [ + f'extern "C" void {handler}(void)', + "{", + f"{INDENT}LibXR::STM32USBDeviceDevFs::Dispatch();", + "}", + ] + + def _usb_settings(instance: str) -> tuple[str, dict] | None: """USB 实例的规范名和它在 libxr_settings["USB"] 中的设置;其他实例名(如 USB_DEVICE 中间件) 为 None。 @@ -1659,7 +1712,6 @@ def _usb_data_buffer(size: int, high_speed: bool) -> int: def _usb_buffer_plan( - is_otg: bool, cdc_count: int, ep0: int, tx: int, @@ -1671,12 +1723,10 @@ def _usb_buffer_plan( The endpoint buffers of a USB device: a list of (name suffix, bytes). CDC 按顺序分配端点:第 i 个 CDC(从 0 起)的数据 IN 端点为 EP(2i+1),通知端点为 EP(2i+2); - OTG 的数据 OUT 端点为 EP(i+1),IN 和 OUT 的端点号各自编号;FSDEV 的数据 OUT 与数据 IN - 使用同一个端点号。 - CDCs take endpoints in order: the data IN endpoint of CDC i (from 0) is EP(2i+1) and its - notification endpoint EP(2i+2); on OTG the data OUT endpoint is EP(i+1), IN and OUT - endpoints being numbered separately, while FSDEV uses one endpoint number for data OUT and - data IN. + 数据 OUT 端点为 EP(i+1)(OTG 上与数据 IN 各自编号,FSDEV/DRD 上与数据 IN 同号)。 + CDCs take endpoints in order: the data IN endpoint of CDC i (from 0) is EP(2i+1), its + notification endpoint EP(2i+2), and its data OUT endpoint EP(i+1) (numbered independently + from the data IN endpoint on OTG, sharing the number on FSDEV/DRD). LibXR 把 EP0 的缓冲区当作一个槽,其余端点的缓冲区平分为两个槽,每个槽按 _USB_SLOT_ALIGN 对齐;端点的包长取槽放得下的最大合法值。所以 EP0 每个方向至少 ep0 字节;数据端点见 @@ -1695,9 +1745,12 @@ def _usb_buffer_plan( data, notify = 2 * index + 1, 2 * index + 2 plan.append((f"ep{data}_in_buf", _usb_data_buffer(tx, high_speed))) plan.append((f"ep{notify}_in_buf", _usb_slots(2, 16))) - plan.append( - (f"ep{data if not is_otg else index + 1}_out_buf", _usb_data_buffer(rx, high_speed)) - ) + # 数据 OUT 端点:OTG 与 FSDEV/DRD 都是 EP(i+1)(FSDEV 的数据 IN 与 OUT 同号, + # 但 OUT 侧按自己的顺序占号)。 + # The data OUT endpoint: on OTG and on FSDEV/DRD alike it is EP(i+1); on FSDEV + # the data IN and OUT endpoints share a number, yet the OUT side numbers its + # own endpoints in order. + plan.append((f"ep{index + 1}_out_buf", _usb_data_buffer(rx, high_speed))) return plan @@ -1923,7 +1976,6 @@ def section_of(key: str, instance_config: dict) -> str: tx_sz = _settle_usb_buffer(name, usb_cfg, "tx_buffer_size", hardware) rx_sz = _settle_usb_buffer(name, usb_cfg, "rx_buffer_size", hardware) plan = _usb_buffer_plan( - is_otg, len(_cdc_items(usb_cfg)), ep0, tx_sz, @@ -2336,7 +2388,8 @@ def _generate_usb(instance: str, config: dict) -> tuple: 代码,启用了但在 CubeMX 中是主机模式的实例记录警告后不生成。设备对象以实例名命名(如 usb_otg_fs),引用 generate_dma_resources() 定义的端点缓冲区,本方法不定义缓冲区。OTG 设备的第一个参数是 _otg_hardware() 给出的硬件配置,CubeMX 不生成中断函数时由 - _otg_vector() 补上向量函数;FSDEV 设备使用 _pcd_handle() 给出的句柄。CDC 串口 <实例>_cdc、<实例>_cdc2 + _otg_vector() 补上向量函数;FSDEV/DRD 设备的 RX/TX 列表按端点号从 EP0 起,CubeMX 不生成 + 中断函数时由 _fsdev_vector() 补上向量函数。CDC 串口 <实例>_cdc、<实例>_cdc2 …… 按顺序分配端点,规则见 _usb_buffer_plan(),各登记为 UART。 The instance name and settings come from _usb_settings(); other instance names, such as the USB_DEVICE middleware, and disabled instances produce no code, and an enabled @@ -2344,9 +2397,11 @@ def _generate_usb(instance: str, config: dict) -> tuple: after the instance, for example usb_otg_fs, and references the endpoint buffers that generate_dma_resources() defines; this method defines no buffer. The first argument of an OTG device is the hardware configuration _otg_hardware() gives, and _otg_vector() - writes the vector function when CubeMX generates no interrupt handler; an FSDEV device - uses the handle _pcd_handle() gives. The CDC serial ports _cdc, _cdc2 ... take - endpoints in order, see _usb_buffer_plan(), and are each registered as UART. + writes the vector function when CubeMX generates no interrupt handler; an FSDEV or DRD + device takes the RX and TX lists running from EP0, and _fsdev_vector() writes the vector + function when CubeMX generates no interrupt handler. The CDC serial ports _cdc, + _cdc2 ... take endpoints in order, see _usb_buffer_plan(), and are each + registered as UART. Raises: LibXRConfigError: 设置了 cdc_count,某个设置无效(见 _usb_settings()),或 OTG 的 @@ -2424,7 +2479,9 @@ def _generate_usb(instance: str, config: dict) -> tuple: otg_devices.append(name) hardware = _otg_hardware(name, config) else: - _use_handle("PCD_HandleTypeDef", pcd_handle) + vector = _fsdev_vector(name, config) + if vector: + interrupt_vectors.append(vector) def endpoint(number: int) -> str: """端点号 number 对应的 USB::Endpoint::EPNumber 枚举值。 @@ -2449,7 +2506,12 @@ def endpoint(number: int) -> str: cdc_name = f"{inst_lower}_cdc" + (str(index + 1) if index else "") cdc_names.append(cdc_name) data_in = 2 * index + 1 - data_out = index + 1 if is_otg else data_in + # 数据 OUT 与数据 IN 在 OTG 上各自编号,在 FSDEV/DRD 上共用一个端点号;两种 + # 控制器上 OUT 侧都按自己的顺序占号,数据 OUT 为 EP(i+1)。 + # The data OUT endpoints number themselves in order on both controllers, so + # the data OUT endpoint is EP(i+1); on FSDEV/DRD it shares the data IN + # number, on OTG the IN and OUT numbers are independent. + data_out = index + 1 # 设置了 interface 时它同时作为控制接口和数据接口的名字;主机按它区分 VID:PID 相同的 # 各路 CDC。 # A set interface names both the control and the data interface; the host tells the @@ -2495,21 +2557,20 @@ def buffer(suffix: str) -> "str | Braces": ) endpoints = [first, str(rx_fifo_size), Braces(*out_buffers), Braces(*in_configs)] else: - configs = [ - Braces(buffer("ep0_in_buf"), buffer("ep0_out_buf"), str(ep0_sz), str(ep0_sz)) - ] + # FSDEV/DRD:RX 与 TX 列表按端点号从 EP0 起,每项是 {槽内存, PMA 字节数}。 + # FSDEV/DRD: the RX and TX lists run from EP0, each entry {slot memory, PMA + # bytes}. + out_configs = [Braces(buffer("ep0_out_buf"), str(ep0_sz))] + in_configs = [Braces(buffer("ep0_in_buf"), str(ep0_sz))] for index in range(len(cdcs)): - data = 2 * index + 1 - configs.append( - Braces( - buffer(f"ep{data}_in_buf"), - buffer(f"ep{data}_out_buf"), - str(tx_fifo_size), - str(rx_buf_sz), - ) + out_configs.append( + Braces(buffer(f"ep{index + 1}_out_buf"), str(rx_buf_sz)) + ) + in_configs.append( + Braces(buffer(f"ep{2 * index + 1}_in_buf"), str(tx_fifo_size)) ) - configs.append(Braces(buffer(f"ep{data + 1}_in_buf"), "16", "true")) - endpoints = [f"&{pcd_handle}", Braces(*configs)] + in_configs.append(Braces(buffer(f"ep{2 * index + 2}_in_buf"), "16")) + endpoints = [Braces(*out_configs), Braces(*in_configs)] lines += layout_statement( f"static {instance_type} {inst_lower}", endpoints diff --git a/tests/test_generator_code_stm32.py b/tests/test_generator_code_stm32.py index 5ff7387..b5a30ff 100644 --- a/tests/test_generator_code_stm32.py +++ b/tests/test_generator_code_stm32.py @@ -634,10 +634,13 @@ def test_a_cdc_interface_must_be_a_string(self): def test_on_fsdev_each_cdc_has_a_data_endpoint_and_a_notification_endpoint( self, ): - # FSDEV 的数据 OUT 端点与数据 IN 端点同号:第 i 路 CDC 的数据端点是 EP(2i+1),通知端点 - # 是 EP(2i+2)。 - # On FSDEV the data OUT endpoint has the number of the data IN endpoint: CDC i has its - # data endpoint on EP(2i+1) and its notification endpoint on EP(2i+2). + # FSDEV/DRD 的 RX/TX 列表按端点号从 EP0 起,每项 {槽内存, PMA 字节数}:第 i 路 CDC + # 的数据端点是 EP(2i+1)(IN 与 OUT 同号)、通知端点是 EP(2i+2),数据 OUT 在 OUT 侧按 + # 顺序占号为 EP(i+1)。 + # On FSDEV/DRD the RX/TX lists run from EP0 with {slot memory, PMA bytes} each: CDC + # i has its data endpoints on EP(2i+1) (IN and OUT sharing the number), its + # notification endpoint on EP(2i+2), and the data OUT endpoints number themselves in + # order as EP(i+1). generator.libxr_settings.setdefault("USB", {})["usb_fs"] = { "enable": True, "cdc": [{}, {"queue_size": 5}], @@ -650,14 +653,15 @@ def test_on_fsdev_each_cdc_has_a_data_endpoint_and_a_notification_endpoint( code = self.generate(project) self.assertIn( " static USB::CDCUart usb_fs_cdc2(USB::Endpoint::EPNumber::EP3,\n" - " USB::Endpoint::EPNumber::EP3,\n" + " USB::Endpoint::EPNumber::EP2,\n" " USB::Endpoint::EPNumber::EP4, 128, 128, 5);\n" - " static STM32USBDeviceDevFs usb_fs(&hpcd_USB_DRD_FS,\n" - " {{usb_fs_ep0_in_buf, usb_fs_ep0_out_buf, 8, 8},\n" - " {usb_fs_ep1_in_buf, usb_fs_ep1_out_buf, 128, 128},\n" - " {usb_fs_ep2_in_buf, 16, true},\n" - " {usb_fs_ep3_in_buf, usb_fs_ep3_out_buf, 128, 128},\n" - " {usb_fs_ep4_in_buf, 16, true}},\n", + " static STM32USBDeviceDevFs usb_fs(\n" + " {{usb_fs_ep0_out_buf, 8}, {usb_fs_ep1_out_buf, 128}, {usb_fs_ep2_out_buf, 128}},\n" + " {{usb_fs_ep0_in_buf, 8},\n" + " {usb_fs_ep1_in_buf, 128},\n" + " {usb_fs_ep2_in_buf, 16},\n" + " {usb_fs_ep3_in_buf, 128},\n" + " {usb_fs_ep4_in_buf, 16}},\n", code, ) @@ -797,12 +801,13 @@ def usb_fs(self, role): def test_the_usb_device_uses_the_handle_parse_recorded(self): # STM32CubeH5 的 USBX 设备例程都定义 PCD_HandleTypeDef hpcd_USB_DRD_FS;以前生成的是 - # hpcd_USB_FS,链接失败。 + # hpcd_USB_FS,链接失败。现在设备没有句柄参数,解析出的句柄名不再进入生成代码。 # The USBX device examples of STM32CubeH5 all define PCD_HandleTypeDef hpcd_USB_DRD_FS; - # hpcd_USB_FS used to be generated and failed to link. + # hpcd_USB_FS used to be generated and failed to link. The device takes no handle + # argument any more, and the parsed handle name no longer enters the generated code. code = self.generate(self.usb_fs("Device"), use_xrobot=False) - self.assertIn("extern PCD_HandleTypeDef hpcd_USB_DRD_FS;", code) - self.assertIn("static STM32USBDeviceDevFs usb_fs(&hpcd_USB_DRD_FS,", code) + self.assertNotIn("hpcd_", code) + self.assertIn("static STM32USBDeviceDevFs usb_fs(", code) def test_the_usb_drd_fs_instance_is_the_usb_fs_device(self): # STM32G0B1 的 .ioc 中 USB 的 IP 名是 USB_DRD_FS,参数全为默认值时没有 VirtualMode;以前 @@ -816,8 +821,8 @@ def test_the_usb_drd_fs_instance_is_the_usb_fs_device(self): family="STM32G0", ) code = self.generate(project, use_xrobot=False) - self.assertIn("extern PCD_HandleTypeDef hpcd_USB_DRD_FS;", code) - self.assertIn("static STM32USBDeviceDevFs usb_fs(&hpcd_USB_DRD_FS,", code) + self.assertNotIn("hpcd_", code) + self.assertIn("static STM32USBDeviceDevFs usb_fs(", code) self.assertTrue(generator.libxr_settings["USB"]["usb_fs"]["enable"]) def test_a_usb_in_host_mode_generates_no_device(self): From 458083008d585bc5f457508e966611b9d23f6274 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Fri, 13 Nov 2026 02:03:34 +0000 Subject: [PATCH 3/4] style(stm32): format the FSDEV endpoint list --- src/libxr/generator_code_stm32.py | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/libxr/generator_code_stm32.py b/src/libxr/generator_code_stm32.py index b326d4b..34d6d5b 100644 --- a/src/libxr/generator_code_stm32.py +++ b/src/libxr/generator_code_stm32.py @@ -2563,12 +2563,8 @@ def buffer(suffix: str) -> "str | Braces": out_configs = [Braces(buffer("ep0_out_buf"), str(ep0_sz))] in_configs = [Braces(buffer("ep0_in_buf"), str(ep0_sz))] for index in range(len(cdcs)): - out_configs.append( - Braces(buffer(f"ep{index + 1}_out_buf"), str(rx_buf_sz)) - ) - in_configs.append( - Braces(buffer(f"ep{2 * index + 1}_in_buf"), str(tx_fifo_size)) - ) + out_configs.append(Braces(buffer(f"ep{index + 1}_out_buf"), str(rx_buf_sz))) + in_configs.append(Braces(buffer(f"ep{2 * index + 1}_in_buf"), str(tx_fifo_size))) in_configs.append(Braces(buffer(f"ep{2 * index + 2}_in_buf"), "16")) endpoints = [Braces(*out_configs), Braces(*in_configs)] lines += layout_statement( From 339b6857429dc5a41d656c265970c6c328679830 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Fri, 13 Nov 2026 03:05:29 +0000 Subject: [PATCH 4/4] fix(stm32): setup registers the post-generation script before generating setup wrote the script name into the .ioc file after app_main.cpp had recorded the digest of the .ioc file, so a project failed to configure right after setup until STM32CubeMX generated the code again. --- src/libxr/config_cubemx_project.py | 8 +++++++- tests/test_config_cubemx_project.py | 8 ++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/src/libxr/config_cubemx_project.py b/src/libxr/config_cubemx_project.py index f21b4b5..b4c9ff6 100644 --- a/src/libxr/config_cubemx_project.py +++ b/src/libxr/config_cubemx_project.py @@ -765,6 +765,13 @@ def setup_project( if terminal_source: set_terminal_source(user_path, terminal_source) + # 生成后脚本要登记进 .ioc,所以先于解析和生成:app_main.cpp 记下的摘要必须是 setup 结束 + # 时的 .ioc 的摘要,否则工程在再次运行 STM32CubeMX 之前无法配置。 + # The post-generation script is registered in the .ioc file, so it comes before parsing + # and generating: app_main.cpp has to record the digest of the .ioc file as setup leaves + # it, or the project would not configure until STM32CubeMX runs again. + install_hook(project_dir, ioc_file) + logging.info(tr("Parsing .ioc file...", "正在解析 .ioc 文件……")) parse_project(project_dir, yaml_output, summary=False) @@ -781,7 +788,6 @@ def setup_project( generate(yaml_output, cpp_output, xrobot_enable) integrate(project_dir) - install_hook(project_dir, ioc_file) logging.info(tr("[Pass] All tasks completed.", "[通过] 全部任务已完成。")) _report_next_steps(project_dir, xrobot_enable) diff --git a/tests/test_config_cubemx_project.py b/tests/test_config_cubemx_project.py index c75f35f..51903e3 100644 --- a/tests/test_config_cubemx_project.py +++ b/tests/test_config_cubemx_project.py @@ -657,6 +657,14 @@ def test_a_cubemx_project_is_set_up(self): ) self.assertTrue((project / "cmake" / "libxr_after_cubemx.cmd").is_file()) self.assertTrue((project / "cmake" / "libxr_after_cubemx.sh").is_file()) + # app_main.cpp records the digest of the .ioc file as setup leaves it, so the project + # configures without another run of STM32CubeMX. + from libxr.stm32_cubemx_sync import ioc_digest + + self.assertIn( + f" digest: {ioc_digest(str(next(project.glob('*.ioc'))))}\n", + (project / "User" / "app_main.cpp").read_text(encoding="utf-8"), + ) self.assertIn( "* text=auto\n*.sh text eol=lf\n*.bat text eol=crlf\n", (project / ".gitattributes").read_text(encoding="utf-8"),