docs: добавь поясняющие комментарии к модулям и инструментам

2026-10-02 16:45:50 +03:00
parent 6cbce6c360
commit 427fc70100
488 changed files with 2877 additions and 1 deletions
--- a/c/parallel-nand/CMakeLists.txt
+++ b/c/parallel-nand/CMakeLists.txt
@@ -1,3 +1,7 @@
+# Сборка библиотеки parallel_nand, parallel_nand_pcan_gas. Состав исходников и публичные
+# include-пути задают подключение к проекту потребителя. Файл также собирает и регистрирует
+# хостовые проверки; запускать их следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.16)
 project(parallel_nand C)

--- a/c/parallel-nand/include/parallel_nand.h
+++ b/c/parallel-nand/include/parallel_nand.h
@@ -1,3 +1,9 @@
+/*
+ * Команды параллельной NAND x8: идентификация, чтение, программирование, стирание и проверка
+ * bad-block marker. Геометрия страницы и блока определяется профилем микросхемы; операции
+ * записи требуют корректного управления WP#.
+ */
+
 #ifndef PARALLEL_NAND_H
 #define PARALLEL_NAND_H

--- a/c/parallel-nand/include/parallel_nand_gas.h
+++ b/c/parallel-nand/include/parallel_nand_gas.h
@@ -1,3 +1,8 @@
+/*
+ * Банковое окно доступа к NAND через регистры GAS. Пары октетов упаковываются в слова явно;
+ * переключение банка задаёт видимую область памяти и не меняет физическую геометрию NAND.
+ */
+
 #ifndef PARALLEL_NAND_GAS_H
 #define PARALLEL_NAND_GAS_H

--- a/c/parallel-nand/include/parallel_nand_pcan_gas.h
+++ b/c/parallel-nand/include/parallel_nand_pcan_gas.h
@@ -1,3 +1,8 @@
+/*
+ * Связка окна NAND с сервером ProtoCAN GAS. Относительные адреса региона и результаты операций
+ * переводятся в контракт GAS, а выполнение команд памяти остаётся в parallel_nand_gas.
+ */
+
 #ifndef PARALLEL_NAND_PCAN_GAS_H
 #define PARALLEL_NAND_PCAN_GAS_H

--- a/c/parallel-nand/include/parallel_nand_port.h
+++ b/c/parallel-nand/include/parallel_nand_port.h
@@ -1,3 +1,9 @@
+/*
+ * Контракт аппаратного доступа к NAND: команды, адреса, данные и ожидание готовности. Один
+ * octet хранится в целом типе, чтобы восемь значащих бит оставались переносимыми на C28x с
+ * 16-битным char.
+ */
+
 #ifndef PARALLEL_NAND_PORT_H
 #define PARALLEL_NAND_PORT_H

--- a/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.c
+++ b/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.c
@@ -1,3 +1,9 @@
+/*
+ * NAND x8 на STM32F103RC через программное управление GPIO: на этом корпусе нет доступного
+ * FSMC. Передача команды, адреса и данных использует разные управляющие линии; WP# должен
+ * разрешать запись только по контракту порта.
+ */
+
 #include "parallel_nand_port_stm32f103rc.h"
 #include "stm32f1xx_hal.h"

--- a/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.h
+++ b/c/parallel-nand/ports/stm32f103rc/parallel_nand_port_stm32f103rc.h
@@ -1,3 +1,9 @@
+/*
+ * NAND x8 на STM32F103RC через программное управление GPIO: на этом корпусе нет доступного
+ * FSMC. Передача команды, адреса и данных использует разные управляющие линии; WP# должен
+ * разрешать запись только по контракту порта.
+ */
+
 #ifndef PARALLEL_NAND_PORT_STM32F103RC_H
 #define PARALLEL_NAND_PORT_STM32F103RC_H

--- a/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.c
+++ b/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.c
@@ -1,3 +1,9 @@
+/*
+ * NAND x8 на STM32F103ZE через FSMC NAND Bank 3. Отдельные окна команды, адреса и данных
+ * отображаются в пространство процессора; их адреса относятся к шине FSMC, а не к физической
+ * странице NAND.
+ */
+
 #include "parallel_nand_port_stm32f103ze.h"

 #include "stm32f1xx_hal.h"
--- a/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.h
+++ b/c/parallel-nand/ports/stm32f103ze/parallel_nand_port_stm32f103ze.h
@@ -1,3 +1,9 @@
+/*
+ * NAND x8 на STM32F103ZE через FSMC NAND Bank 3. Отдельные окна команды, адреса и данных
+ * отображаются в пространство процессора; их адреса относятся к шине FSMC, а не к физической
+ * странице NAND.
+ */
+
 #ifndef PARALLEL_NAND_PORT_STM32F103ZE_H
 #define PARALLEL_NAND_PORT_STM32F103ZE_H

--- a/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.c
+++ b/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.c
@@ -1,3 +1,9 @@
+/*
+ * NAND x8 на STM32F407VE через FSMC Bank 2. Область данных начинается с 0x70000000, а
+ * управляющие адресные биты выбирают команду и адрес; геометрией памяти управляет переносимое
+ * ядро.
+ */
+
 #include "parallel_nand_port_stm32f407ve.h"
 #include "stm32f4xx_hal.h"
 #include "stm32f4xx_hal_nand.h"
--- a/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.h
+++ b/c/parallel-nand/ports/stm32f407ve/parallel_nand_port_stm32f407ve.h
@@ -1,3 +1,9 @@
+/*
+ * NAND x8 на STM32F407VE через FSMC Bank 2. Область данных начинается с 0x70000000, а
+ * управляющие адресные биты выбирают команду и адрес; геометрией памяти управляет переносимое
+ * ядро.
+ */
+
 #ifndef PARALLEL_NAND_PORT_STM32F407VE_H
 #define PARALLEL_NAND_PORT_STM32F407VE_H

--- a/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.c
+++ b/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.c
@@ -1,3 +1,9 @@
+/*
+ * NAND x8 на STM32G474CE через GPIO, где PB0..PB7 образуют шину данных. Порт формирует
+ * управляющие импульсы программно; переключение направления данных необходимо для чтения и
+ * записи одной двунаправленной шиной.
+ */
+
 #include "parallel_nand_port_stm32g474ce.h"
 #include "stm32g4xx_hal.h"

--- a/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.h
+++ b/c/parallel-nand/ports/stm32g474ce/parallel_nand_port_stm32g474ce.h
@@ -1,3 +1,9 @@
+/*
+ * NAND x8 на STM32G474CE через GPIO, где PB0..PB7 образуют шину данных. Порт формирует
+ * управляющие импульсы программно; переключение направления данных необходимо для чтения и
+ * записи одной двунаправленной шиной.
+ */
+
 #ifndef PARALLEL_NAND_PORT_STM32G474CE_H
 #define PARALLEL_NAND_PORT_STM32G474CE_H

--- a/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.c
+++ b/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.c
@@ -1,3 +1,8 @@
+/*
+ * NAND через XINTF TMS320F2812 с адресными линиями XA0/XA1 для CLE/ALE. Адреса C28x измеряются
+ * 16-битными словами, но полезные данные NAND остаются восьмибитными октетами.
+ */
+
 #include "parallel_nand_port_tms320f2812.h"
 #include "DSP281x_Device.h"

--- a/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.h
+++ b/c/parallel-nand/ports/tms320f2812/parallel_nand_port_tms320f2812.h
@@ -1,3 +1,8 @@
+/*
+ * NAND через XINTF TMS320F2812 с адресными линиями XA0/XA1 для CLE/ALE. Адреса C28x измеряются
+ * 16-битными словами, но полезные данные NAND остаются восьмибитными октетами.
+ */
+
 #ifndef PARALLEL_NAND_PORT_TMS320F2812_H
 #define PARALLEL_NAND_PORT_TMS320F2812_H

--- a/c/parallel-nand/src/parallel_nand.c
+++ b/c/parallel-nand/src/parallel_nand.c
@@ -1,3 +1,9 @@
+/*
+ * Команды параллельной NAND x8: идентификация, чтение, программирование, стирание и проверка
+ * bad-block marker. Геометрия страницы и блока определяется профилем микросхемы; операции
+ * записи требуют корректного управления WP#.
+ */
+
 #include "parallel_nand.h"

 #define PNAND_CMD_READ_1       0x00U
--- a/c/parallel-nand/src/parallel_nand_gas.c
+++ b/c/parallel-nand/src/parallel_nand_gas.c
@@ -1,3 +1,8 @@
+/*
+ * Банковое окно доступа к NAND через регистры GAS. Пары октетов упаковываются в слова явно;
+ * переключение банка задаёт видимую область памяти и не меняет физическую геометрию NAND.
+ */
+
 #include "parallel_nand_gas.h"

 static unsigned int pack_pair(const pnand_octet_t *data, unsigned int index)
--- a/c/parallel-nand/src/parallel_nand_pcan_gas.c
+++ b/c/parallel-nand/src/parallel_nand_pcan_gas.c
@@ -1,3 +1,8 @@
+/*
+ * Связка окна NAND с сервером ProtoCAN GAS. Относительные адреса региона и результаты операций
+ * переводятся в контракт GAS, а выполнение команд памяти остаётся в parallel_nand_gas.
+ */
+
 #include "parallel_nand_pcan_gas.h"

 static pcan_gas_status_t convert(parallel_nand_gas_result_t result)
--- a/c/parallel-nand/tests/test_parallel_nand.c
+++ b/c/parallel-nand/tests/test_parallel_nand.c
@@ -1,3 +1,9 @@
+/*
+ * Проверки parallel_nand: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include <assert.h>
 #include <stddef.h>
 #include <stdio.h>