Modbus/docs/superpowers/plans/2026-08-02-modbus-runtime-cleanup.md

Modbus Runtime Cleanup Implementation Plan

For agentic workers: Execute this plan inline. Do not create a worktree
because the current working directory contains the user’s uncommitted project
changes and is the only complete current project state.

Goal: Remove unused IAR build inputs and IAR-only Modbus snapshots while
preserving the PLC protocol behavior and the two requested live-watch arrays.

Architecture: The target remains an STM32F407/uC-OS-II Modbus RTU slave.
Only the IAR project source list and application-level diagnostic path change;
the protocol core, backup module, interrupt behavior, public data storage, and
TouchWin contract remain intact. The final project design is generated after
the source edits so every locator reflects the finished code.

Tech Stack: IAR EWARM 8.3, STM32F4 HAL, uC/OS-II, C99 host tests,
PowerShell static checks, Markdown.

Global Constraints

• Preserve holdingRegisters, coilStorage, and extendedHoldingRegister.
• Preserve standard function codes 0x01/0x03/0x05/0x06/0x0F/0x10, private
  functions 0x41/0x42/0x43, and the 0x00010000 RTC retention path.
• Do not edit vendor sources under Drivers/ or RTOS sources under Core/OS/.
• Retain EWARM/Modbus/Exe/Modbus.hex, document/, uC-OS2_temp/, and IAR
  settings files.
• Do not stage or commit because the worktree contains unrelated user changes.

---

Task 1: Remove unused HAL compilation entries

Files:

• Modify: EWARM/Modbus.ewp:1140-1173
• Verify: EWARM/Modbus/List/Modbus.map

Interfaces:

• Consumes: the current link map, which records zero linked sections for the
  eight listed HAL translation units.

• Produces: an IAR source list that compiles only the HAL modules used by the
  current target.

• Delete the complete <file> XML blocks for these source entries, and no
  other HAL entries:
  stm32f4xx_hal_dma_ex.c, stm32f4xx_hal_exti.c,
  stm32f4xx_hal_flash.c, stm32f4xx_hal_flash_ex.c,
  stm32f4xx_hal_flash_ramfunc.c, stm32f4xx_hal_pwr_ex.c,
  stm32f4xx_hal_tim.c, and stm32f4xx_hal_tim_ex.c.

• Confirm that the remaining target source list still includes
  stm32f4xx_hal.c, _cortex.c, _dma.c, _gpio.c, _pwr.c, _rcc.c,
  _rcc_ex.c, and _uart.c.

• Build EWARM/Modbus.ewp configuration Modbus with
  E:\IAR\common\bin\IarBuild.exe EWARM\Modbus.ewp -build Modbus -log warnings.
  Expected result: 0 errors, 0 warnings.

Task 2: Remove IAR-only Modbus snapshots while retaining live-watch data

Files:

• Modify: Core/Src/main.c:30-41, 107-116, 630-710, 730-780, 818, 890-940
• Modify: Core/Inc/main.h:37-51
• Modify: Core/OS/Cfg/app_cfg.h:45-47
• Modify: Core/Modbus/app_runtime_test.c:78-106

Interfaces:

• Consumes: holdingRegisters, coilStorage, and extendedHoldingRegister
  as the only IAR Live Watch data interface.

• Produces: the same UART recovery and RTU behavior without exported snapshots
  or their RAM buffers.

• In app_runtime_test.c, remove assertions that require
  AppModbusDebugRecoveryStatus and AppModbusDebugUartErrorCode; retain the
  behavioral assertions for retry, abort, deferred recovery flagging, semaphore
  posting, and no receive re-arm inside the error callback.

• Delete the three APP_MODBUS_DEBUG_* capacity macros from app_cfg.h.

• Delete all AppModbusDebug* global definitions and all matching extern
  declarations. Do not change the three retained data storage declarations.

• Delete AppCopyDebugFrame, AppCaptureDebugDataModel, and
  AppCaptureDebugSnapshot, their prototypes, and every call or assignment
  that exists solely to update their state.

• Preserve the return paths, ModbusReceptionNeedsRecovery, and UART error
  callback behavior after snapshot calls are removed.

• Compile and run the runtime host test with:
  gcc -std=c99 -Wall -Wextra -Werror -ICore/Modbus/test_support/app_runtime -ICore/Modbus Core/Modbus/app_runtime_test.c Core/Modbus/modbus.c -o tmp/document_work/verification_bin/app_runtime_test.exe.
  Expected result: exit code 0.

Task 3: Improve comments in project-owned runtime and protocol modules

Files:

• Modify: Core/Src/main.c
• Modify: Core/Inc/main.h
• Modify: Core/OS/Cfg/app_cfg.h
• Modify: Core/Modbus/modbus.c
• Modify: Core/Modbus/modbus.h
• Modify: Core/Modbus/modbus_backup.c
• Modify: Core/Modbus/modbus_backup.h
• Modify: Core/Src/stm32f4xx_it.c
• Modify: Core/Inc/stm32f4xx_it.h

Interfaces:

• Consumes: existing APIs and symbol names.

• Produces: Doxygen comments that explain ownership, protocol constraints,
  concurrency boundaries, parameter units, side effects, and error behavior.

• Add or revise comments only where they explain non-obvious intent:
  RTU timer phases, ISR-to-task ownership transfer, UART recovery deferral,
  coil-to-GPIO polarity, private-function address rules, CRC byte order, and
  RTC metadata validation.

• Ensure every public Modbus and backup API documents parameter ownership,
  return status, and state change; do not add comments that merely restate a
  variable assignment or modify third-party HAL/uC-OS-II code.

• Keep indentation at four spaces, braces on separate lines, macro values
  parenthesized, and existing identifier conventions intact.

• Re-run all host tests with -Wall -Wextra -Werror after comment changes.

Task 4: Remove reproducible artifacts and prevent regeneration

Files:

• Modify: .gitignore
• Delete: root app_runtime_test.exe, modbus_backup_test.exe,
  modbus_protocol_test.exe, and all root *.stackdump
• Delete: EWARM/Modbus/Obj/, EWARM/Modbus/List/Modbus.map,
  EWARM/Modbus/Exe/Modbus.out, EWARM/Modbus/Exe/Modbus.sim, and
  EWARM/Modbus.dep

Interfaces:

• Consumes: Modbus.hex as the retained downloadable firmware artifact.

• Produces: a source workspace without host-test binaries or IAR intermediate
  outputs.

• Add project-specific ignore rules for IAR Obj/, generated map files,
  .out, .sim, .dep, and *.stackdump; keep Modbus.hex unignored.

• Verify each deletion target is an exact generated artifact before removal.

• Delete only the named artifact paths. Do not remove EWARM/settings/,
  document/, docs/, tmp/, or uC-OS2_temp/.

Task 5: Generate the source-aligned project design and run regression gates

Files:

• Create: docs/项目设计.md
• Verify: Core/Modbus/modbus_test.c, Core/Modbus/modbus_backup_test.c,
  Core/Modbus/app_runtime_test.c, Core/Modbus/check_rtu_runtime_invariants.ps1,
  Core/Modbus/check_no_communication_counters.ps1, EWARM/Modbus.ewp

Interfaces:

• Consumes: final source line numbers after Tasks 1-4.

• Produces: a maintainable design document whose code references can be opened
  directly in the source tree.

• Document the system boundary, initialization order, RTU receive state,
  T1.5/T3.5 timing, task/interrupt handoff, Modbus data model, standard and
  private function routing, coil GPIO mapping, RTC retention, error recovery,
  and test strategy.

• Add a source index mapping each design responsibility to final
  relative/path:line locations. Include only application-owned modules and
  identify HAL/uC-OS-II as third-party dependencies rather than duplicating
  their implementation explanation.

• Build and run protocol, RTC backup, and runtime host tests with
  -std=c99 -Wall -Wextra -Werror; run both PowerShell static checks; build the
  IAR Modbus target and verify 0 errors and 0 warnings.

• Check git diff --check and git status --short; report only the files
  touched by this cleanup and any pre-existing unrelated modifications.