From 31e3237b066c6a29b666cf7b5ebe3a2fd531cf52 Mon Sep 17 00:00:00 2001 From: Dmitry Akimov Date: Tue, 7 Jul 2026 12:07:15 +0300 Subject: [PATCH] # Refactoring: source code docstrings --- README.md | 2 -- bsp/can/src/can.c | 14 -------------- bsp/mqs/src/mqs.c | 5 ----- bsp/opto/include/bsp/opto.h | 1 - bsp/uart_host/include/bsp/uart_host.h | 2 +- bsp/uart_host/src/uart_host.c | 4 ---- bsp/usb_cdc/include/bsp/usb_cdc.h | 2 +- bsp/usb_cdc/src/usb_cdc.c | 2 -- firmware/test/src/cli.c | 4 +--- firmware/test/src/protocol.c | 1 - firmware/test/src/test_runner.c | 2 +- tools/host/flash_swd.py | 4 ---- tools/host/flash_usb.py | 4 ---- tools/production/README.md | 3 +-- tools/production/app/app.py | 3 --- tools/production/app/firmware_client.py | 4 +--- tools/production/app/m5_client.py | 1 - tools/production/app/orchestrator.py | 11 ++++------- tools/production/app/screens/diag/test_list.py | 1 - tools/production/app/screens/flash.py | 5 ++--- tools/production/tests/test_flash_backend.py | 1 - 21 files changed, 12 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 0ef62d4..e713fb7 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,6 @@ | Загрузчик (⏳ запланирован) | `firmware/bootloader/` | A/B обновление через uSD. Обновляется только через USB ROM + blhost / SWD | | Production прошивка (⏳ запланирован) | `firmware/tft_app/` | Приложение с реализацией логики лифтового индикатора. Обновляется загрузчиком | -`bootloader`/`tft_app` пока не реализованы. - --- ## Инструменты (`tools/`) diff --git a/bsp/can/src/can.c b/bsp/can/src/can.c index 57fb3e6..e0bac61 100644 --- a/bsp/can/src/can.c +++ b/bsp/can/src/can.c @@ -161,18 +161,15 @@ static uint32_t poll_rx_mailboxes(void) uint8_t mb_idx = RX_MB_FIRST + i; - /* Проверяем флаг готовности MB. */ uint64_t mb_flag = (uint64_t) 1U << mb_idx; if (FLEXCAN_GetMbStatusFlags(BSP_CAN_BASE, mb_flag) == 0U) { continue; } - /* Читаем фрейм из MB. */ flexcan_frame_t sdk_frame; status_t sdk_status = FLEXCAN_ReadRxMb(BSP_CAN_BASE, mb_idx, &sdk_frame); - /* Очищаем флаг. */ FLEXCAN_ClearMbStatusFlags(BSP_CAN_BASE, mb_flag); if ((sdk_status == kStatus_Success) || (sdk_status == kStatus_FLEXCAN_RxOverflow)) @@ -180,7 +177,6 @@ static uint32_t poll_rx_mailboxes(void) bsp_can_frame_t bsp_frame; frame_from_sdk(&sdk_frame, &bsp_frame); - /* Сериализуем фрейм побайтово в ring buffer. */ ring_buffer_write(&g_s_rx_ring, (const uint8_t *) &bsp_frame, sizeof(bsp_frame)); received++; } @@ -222,16 +218,13 @@ bsp_status_t bsp_can_init(const bsp_can_config_t *p_config) return BSP_ERR_PARAM; } - /* Если уже инициализирован — сначала деинициализируем. */ if (g_s_initialized) { bsp_can_deinit(); } - /* Инициализация ring buffer. */ ring_buffer_init(&g_s_rx_ring, g_s_rx_ring_storage, RX_RING_SIZE); - /* Конфигурация FlexCAN. */ flexcan_config_t flexcan_cfg; FLEXCAN_GetDefaultConfig(&flexcan_cfg); @@ -306,7 +299,6 @@ bsp_status_t bsp_can_set_filter(uint8_t index, uint32_t can_id, uint32_t mask, b uint8_t mb_idx = RX_MB_FIRST + index; - /* Конфигурация RX MB. */ flexcan_rx_mb_config_t rx_mb_cfg; rx_mb_cfg.type = kFLEXCAN_FrameTypeData; @@ -422,14 +414,12 @@ bsp_status_t bsp_can_send(const bsp_can_frame_t *p_frame, uint32_t timeout_ms) flexcan_frame_t sdk_frame; frame_to_sdk(p_frame, &sdk_frame); - /* Записать фрейм в TX MB. */ status_t wr_status = FLEXCAN_WriteTxMb(BSP_CAN_BASE, TX_MB_IDX, &sdk_frame); if (wr_status != kStatus_Success) { return BSP_ERR_BUSY; } - /* Ждать завершения передачи с таймаутом. */ uint64_t tx_flag = (uint64_t) 1U << TX_MB_IDX; uint32_t start_ms = bsp_tick_get_ms(); @@ -442,7 +432,6 @@ bsp_status_t bsp_can_send(const bsp_can_frame_t *p_frame, uint32_t timeout_ms) } } - /* Очистить флаг завершения. */ FLEXCAN_ClearMbStatusFlags(BSP_CAN_BASE, tx_flag); return BSP_OK; @@ -471,16 +460,13 @@ bsp_status_t bsp_can_receive(bsp_can_frame_t *p_frame, uint32_t timeout_ms) for (;;) { - /* Опросить все активные MB, сложить в ring buffer. */ poll_rx_mailboxes(); - /* Попробовать извлечь фрейм. */ if (try_dequeue_frame(p_frame)) { return BSP_OK; } - /* Проверить таймаут. */ uint32_t elapsed = bsp_tick_get_ms() - start_ms; if (elapsed >= timeout_ms) { diff --git a/bsp/mqs/src/mqs.c b/bsp/mqs/src/mqs.c index f6ddf77..e3ff324 100644 --- a/bsp/mqs/src/mqs.c +++ b/bsp/mqs/src/mqs.c @@ -110,11 +110,6 @@ static void mqs_edma_callback(I2S_Type *p_base, sai_edma_handle_t *p_handle, sta /* -------------------------------------------------------------------------- * Публичный API * ----------------------------------------------------------------------- */ -/* - * AUDIO PLL setting: Frequency = Fref * (DIV_SELECT + NUM / DENOM) - * = 24 * (32 + 768/1000) - * = 786.432 MHz - */ bsp_status_t bsp_mqs_init(void) { diff --git a/bsp/opto/include/bsp/opto.h b/bsp/opto/include/bsp/opto.h index d671a1f..a663b4f 100644 --- a/bsp/opto/include/bsp/opto.h +++ b/bsp/opto/include/bsp/opto.h @@ -12,7 +12,6 @@ * Пин LOW (тока нет) → BSP_OPTO_STATE_INACTIVE * * Режимы каналов (bsp_opto_ch_mode_t): - * ы * BSP_OPTO_MODE_LEVEL — IN1, IN2 * Детектирование уровня с программным дебаунсом. * ISR переключает направление прерывания (RISING↔FALLING) после каждого фронта, diff --git a/bsp/uart_host/include/bsp/uart_host.h b/bsp/uart_host/include/bsp/uart_host.h index 7ad62dd..5a66e74 100644 --- a/bsp/uart_host/include/bsp/uart_host.h +++ b/bsp/uart_host/include/bsp/uart_host.h @@ -26,7 +26,7 @@ /* -------------------------------------------------------------------------- */ /* Константы */ -/* -------------------------------------------------s------------------------- */ +/* -------------------------------------------------------------------------- */ /** Передать в timeout_ms чтобы ждать данные бесконечно. */ #define BSP_UART_HOST_WAIT_FOREVER (UINT32_MAX) diff --git a/bsp/uart_host/src/uart_host.c b/bsp/uart_host/src/uart_host.c index de8e245..0dcab89 100644 --- a/bsp/uart_host/src/uart_host.c +++ b/bsp/uart_host/src/uart_host.c @@ -84,17 +84,14 @@ bsp_status_t bsp_uart_host_init(uint32_t baud_rate) return BSP_ERR_INIT; } - /* Инициализация кольцевого буфера. */ if (!ring_buffer_init(&g_s_rx_ring, g_s_rx_buf, BSP_UART_HOST_RX_BUFFER_SIZE)) { /* Размер не степень двойки — ошибка конфигурации. */ return BSP_ERR_INIT; } - /* Тактирование LPUART1. */ CLOCK_EnableClock(kCLOCK_Lpuart1); - /* Настройка периферии. */ lpuart_config_t config; LPUART_GetDefaultConfig(&config); config.baudRate_Bps = baud_rate; @@ -191,7 +188,6 @@ size_t bsp_uart_host_read(uint8_t *p_buf, size_t len, uint32_t timeout_ms) continue; } - /* Буфер пуст — проверяем таймаут. */ if (timeout_ms == 0U) { break; diff --git a/bsp/usb_cdc/include/bsp/usb_cdc.h b/bsp/usb_cdc/include/bsp/usb_cdc.h index e7c0d11..0257cba 100644 --- a/bsp/usb_cdc/include/bsp/usb_cdc.h +++ b/bsp/usb_cdc/include/bsp/usb_cdc.h @@ -36,7 +36,7 @@ extern "C" * * @pre board_hw_init() вызван (MPU настроен, NonCacheable регион активен). * - * @return BSP_OK при успехе, BSP_ERR_HW при ошибке инициализациистека. + * @return BSP_OK при успехе, BSP_ERR_HW при ошибке инициализации стека. */ bsp_status_t bsp_usb_cdc_init(void); diff --git a/bsp/usb_cdc/src/usb_cdc.c b/bsp/usb_cdc/src/usb_cdc.c index e634677..7036929 100644 --- a/bsp/usb_cdc/src/usb_cdc.c +++ b/bsp/usb_cdc/src/usb_cdc.c @@ -566,8 +566,6 @@ bsp_status_t bsp_usb_cdc_init(void) USB_DeviceIsrEnable(); - /* FIXME:Задержка для стабилизации DP pull-down. */ - //SDK_DelayAtLeastUs(USB_ATTACH_DELAY_US, SDK_DEVICE_MAXIMUM_CPU_CLOCK_FREQUENCY); bsp_delay(USB_ATTACH_DELAY_US / 1000); USB_DeviceRun(g_usbDeviceHandle); diff --git a/firmware/test/src/cli.c b/firmware/test/src/cli.c index fc12a60..c3372b4 100644 --- a/firmware/test/src/cli.c +++ b/firmware/test/src/cli.c @@ -191,7 +191,7 @@ static size_t parse_string_array(const char *p_array_start, char (*p_out_bufs)[T { return 0U; } - p++; /* пропустить '[' */ + p++; size_t count = 0U; while (count < max_items) @@ -285,8 +285,6 @@ static void handle_cmd_run_selected(const char *p_line) /** * @brief Обработать сообщение {"type":"cmd",...}. - * - * Команды: ping → pong, run_all → test_runner, run → test_runner. */ static void handle_cmd(const char *p_line) { diff --git a/firmware/test/src/protocol.c b/firmware/test/src/protocol.c index 4fc3b62..37e0d5a 100644 --- a/firmware/test/src/protocol.c +++ b/firmware/test/src/protocol.c @@ -115,7 +115,6 @@ void protocol_send_confirm_request(const confirm_params_t *p_params) void protocol_send_test_list(const test_module_t *const *p_pp_registry, size_t count) { - /* Заголовок массива */ cli_send("{\"type\":\"test_list\",\"tests\":["); for (size_t i = 0U; i < count; i++) diff --git a/firmware/test/src/test_runner.c b/firmware/test/src/test_runner.c index cf53770..e9674a4 100644 --- a/firmware/test/src/test_runner.c +++ b/firmware/test/src/test_runner.c @@ -91,7 +91,7 @@ static volatile bool g_s_confirm_value; static char g_s_pending_confirm_id[RUNNER_CONFIRM_ID_SIZE]; static uint32_t g_s_confirm_deadline_ms; -/* Счётчики итога (используются только в RUNNER_MODE_ALL) */ +/* Счётчики итога (ALL и SELECTED; в SINGLE не используются) */ static uint8_t g_s_passed; static uint8_t g_s_failed; static uint8_t g_s_skipped; diff --git a/tools/host/flash_swd.py b/tools/host/flash_swd.py index 81213ac..c2eb833 100644 --- a/tools/host/flash_swd.py +++ b/tools/host/flash_swd.py @@ -163,7 +163,6 @@ def main() -> int: ) args = parser.parse_args() - # ── Проверить FCB ───────────────────────────────────────────────────────── if not args.fcb.exists(): print(f" ❌ FCB not found: {args.fcb}", file=sys.stderr) print( @@ -174,7 +173,6 @@ def main() -> int: ) return 1 - # ── Найти HAB-образ ─────────────────────────────────────────────────────── hab_name = HAB_NAMES[args.firmware] hab_path = BUILD_DIR / args.build_type / hab_name @@ -195,7 +193,6 @@ def main() -> int: print(f" Target : {args.target}") print(f" Frequency : {args.frequency} Hz\n") - # ── Собрать объединённый образ ──────────────────────────────────────────── image = build_full_image(args.fcb, hab_path) if args.dry_run: @@ -205,7 +202,6 @@ def main() -> int: print(f"\n Dry run — image saved to {out}") return 0 - # ── Записать во Flash через pyOCD ───────────────────────────────────────── with tempfile.NamedTemporaryFile( suffix=f"_{args.firmware}_full.bin", delete=False ) as tmp: diff --git a/tools/host/flash_usb.py b/tools/host/flash_usb.py index 76e8b6a..cd02696 100644 --- a/tools/host/flash_usb.py +++ b/tools/host/flash_usb.py @@ -387,7 +387,6 @@ def main() -> None: ), ) - # Группа: что прошивать (взаимоисключающие варианты) target_group = parser.add_mutually_exclusive_group() target_group.add_argument( "--firmware", @@ -420,9 +419,6 @@ def main() -> None: args = parser.parse_args() - # Валидация: --firmware требует --build-type (уже есть default, но запомним) - # --bin-path: build-type игнорируется - # --erase-chip: несовместим с --ram-only if args.erase_chip and args.ram_only: parser.error("--erase-chip несовместим с --ram-only") diff --git a/tools/production/README.md b/tools/production/README.md index 05d04c2..e310f2d 100644 --- a/tools/production/README.md +++ b/tools/production/README.md @@ -4,8 +4,7 @@ TUI-приложение для диагностики и прошивки пл Написано на Python + [Textual](https://textual.textualize.io/). Работает на Linux, macOS, Windows. > Внутреннее устройство, диаграммы архитектуры и заметки для разработчиков — -> в [DEV_ARCH.md](DEV_ARCH.md). Этот документ — только про то, как приложением -> пользоваться. +> в [DEV_ARCH.md](DEV_ARCH.md). --- diff --git a/tools/production/app/app.py b/tools/production/app/app.py index 1319d5b..80b44ed 100644 --- a/tools/production/app/app.py +++ b/tools/production/app/app.py @@ -50,8 +50,6 @@ class ServiceApp(App): self.push_screen(WaitingScreen()) # ── Переходы между экранами ─────────────────────────────────────────────── - - @on(WaitingScreen.DeviceDetected) @on(WaitingScreen.DeviceDetected) def _on_device_detected(self, event: WaitingScreen.DeviceDetected) -> None: if event.mode == AppMode.FLASHING: @@ -97,7 +95,6 @@ class ServiceApp(App): @on(DiagScreen.DiagDone) def _on_diag_done(self, event: DiagScreen.DiagDone) -> None: - """После диагностики — отключиться, вернуться в Waiting.""" self._disconnect() self.switch_screen(WaitingScreen(disconnect_reason=event.reason)) diff --git a/tools/production/app/firmware_client.py b/tools/production/app/firmware_client.py index aa01df0..e5a6613 100644 --- a/tools/production/app/firmware_client.py +++ b/tools/production/app/firmware_client.py @@ -33,11 +33,9 @@ from .models import TestInfo logger = logging.getLogger(__name__) -# Таймаут чтения одной строки (сек) _READLINE_TIMEOUT_S = 0.1 -# Таймаут ping→pong при подключении (сек) _PING_TIMEOUT_S = 5.0 -# Таймаут ожидания событий теста (сек) — длиннее самого долгого теста (SDRAM ~15 с) +# Длиннее самого долгого теста (SDRAM ~15 с) _TEST_EVENT_TIMEOUT_S = 120.0 diff --git a/tools/production/app/m5_client.py b/tools/production/app/m5_client.py index cd0c4fe..8ffe395 100644 --- a/tools/production/app/m5_client.py +++ b/tools/production/app/m5_client.py @@ -30,7 +30,6 @@ import serial.tools.list_ports logger = logging.getLogger(__name__) -# VID/PID M5StampPLC _M5_VID = int(os.environ.get("SERVICE_M5_VID", "0x303A"), 16) _M5_PID = int(os.environ.get("SERVICE_M5_PID", "0x4001"), 16) diff --git a/tools/production/app/orchestrator.py b/tools/production/app/orchestrator.py index 95a1d06..a65e07a 100644 --- a/tools/production/app/orchestrator.py +++ b/tools/production/app/orchestrator.py @@ -51,12 +51,10 @@ from .models import ConfirmRequest, TestResult, TestStatus logger = logging.getLogger(__name__) -# Задержки для HIL _RELAY_ON_S = 0.15 _RELAY_OFF_S = 0.50 -# Карта confirm_id → реле M5 для opto-теста -# Формат: confirm_id → (relay_num, target_state) +# confirm_id → (relay_num, target_state) _OPTO_RELAY_MAP: dict[str, tuple[int, bool]] = { "opto_in1_active": (3, True), "opto_in1_inactive": (3, False), @@ -66,7 +64,6 @@ _OPTO_RELAY_MAP: dict[str, tuple[int, bool]] = { "opto_rs_inactive": (2, False), } -# CAN параметры _CAN_RX_ID = 0x100 _CAN_RX_DATA = [0xDE, 0xAD, 0xBE, 0xEF] _CAN_TX_ID = 0x200 @@ -80,13 +77,13 @@ _TIMEOUT_EVENT_TYPE = "_timeout" class OrchestratorEventType(Enum): - TEST_BEGIN = auto() # тест начался - TEST_RESULT = auto() # тест завершился + TEST_BEGIN = auto() + TEST_RESULT = auto() TEST_PROGRESS = auto() # внутришаговый прогресс долгого теста (usd и т.п.) CONFIRM_NEEDED = auto() # нужен ответ оператора (standalone) CONFIRM_RESOLVED = auto() # HIL confirm выполнен автоматически BUTTONS_PROMPT = auto() # показать инструкцию для buttons (без confirm) - SUMMARY = auto() # итог всей сессии + SUMMARY = auto() ERROR = auto() # ошибка протокола, M5, или обрыв по таймауту diff --git a/tools/production/app/screens/diag/test_list.py b/tools/production/app/screens/diag/test_list.py index 068f8f9..ff1da21 100644 --- a/tools/production/app/screens/diag/test_list.py +++ b/tools/production/app/screens/diag/test_list.py @@ -24,7 +24,6 @@ class TestListPanel(Widget): def __init__(self, **kwargs) -> None: super().__init__(**kwargs) - # test_id → Checkbox для быстрого доступа self._checkboxes: dict[str, Checkbox] = {} # test_id → True если HIL-тест недоступен без M5 (постоянное состояние, # не зависящее от прогона). Отдельно от Checkbox.disabled, который diff --git a/tools/production/app/screens/flash.py b/tools/production/app/screens/flash.py index 45608d4..c4e0b32 100644 --- a/tools/production/app/screens/flash.py +++ b/tools/production/app/screens/flash.py @@ -173,9 +173,8 @@ class FlashScreen(Screen, ConnectionWatcherMixin): self._stop_connection_watch() def _check_sdp_present(self) -> bool: - # Не считаем потерей соединения, если идёт активная операция — - # flash_usb.py сам обработает реальный обрыв через subprocess. - # обрыв в этом случае обнаружит и обработает сам flash_backend + # Не считаем потерей соединения, если идёт активная операция — обрыв + # в этом случае обнаружит и обработает сам flash_backend # (ConnectionLostError, см. Фазу 4), не watcher. if self._flashing: return True diff --git a/tools/production/tests/test_flash_backend.py b/tools/production/tests/test_flash_backend.py index f9674f8..820c536 100644 --- a/tools/production/tests/test_flash_backend.py +++ b/tools/production/tests/test_flash_backend.py @@ -329,7 +329,6 @@ def test_flash_write_memory_fails(monkeypatch, events, tmp_path): with pytest.raises(fb.FlashBackendError, match="write_memory"): fb.flash(hab_bin, progress_cb=_collector(events)) - # reset/done не должны наступить после ошибки записи assert "reset" not in _phases(events) assert "done" not in _phases(events)