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..b4c9ff6 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( @@ -761,12 +765,28 @@ 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) 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) logging.info(tr("[Pass] All tasks completed.", "[通过] 全部任务已完成。")) diff --git a/src/libxr/generator_code_stm32.py b/src/libxr/generator_code_stm32.py index 21e5f30..34d6d5b 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, @@ -1108,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。 @@ -1433,9 +1624,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 +1642,7 @@ class DmaBuffer: count: int section: str stored: int + alignment: int = 0 def argument(self) -> "str | Braces": """传给驱动的参数:存储的元素数与驱动使用的相同时为缓冲区名,否则为 {名字, 字节数}。 @@ -1485,27 +1679,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( + 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)] + 数据 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 字节;数据端点见 + _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))) + # 数据 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 +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 +1817,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 +1839,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 +1970,29 @@ 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 + 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 +2010,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 +2386,28 @@ 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/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 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 - endpoints in order, see _usb_buffer_plan(), and are each registered as UART. + 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 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())。 - 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 +2472,16 @@ 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: + vector = _fsdev_vector(name, config) + if vector: + interrupt_vectors.append(vector) def endpoint(number: int) -> str: """端点号 number 对应的 USB::Endpoint::EPNumber 枚举值。 @@ -2190,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 @@ -2222,27 +2543,33 @@ 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)) - ] + # 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), - ) - ) - configs.append(Braces(buffer(f"ep{data + 1}_in_buf"), "16", "true")) - endpoints = [Braces(*configs)] + 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( f"static {instance_type} {inst_lower}", - [f"&{pcd_handle}"] - + endpoints + endpoints + [ f"USB::DeviceDescriptor::PacketSize0::{size_enum}", f"0x{vid:X}", @@ -2278,7 +2605,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 +3580,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 +3700,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 +3978,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 +4029,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..51903e3 100644 --- a/tests/test_config_cubemx_project.py +++ b/tests/test_config_cubemx_project.py @@ -648,7 +648,22 @@ 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()) + # 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", diff --git a/tests/test_generator_code_stm32.py b/tests/test_generator_code_stm32.py index c2c04e0..b5a30ff 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"): @@ -515,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}], @@ -531,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, ) @@ -678,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;以前 @@ -697,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): 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()