39. Как читать документацию ST

Рано или поздно любой справочник заканчивается, а вопрос остаётся. Тогда открывают документацию производителя — а она вся на английском, объёмом в полторы тысячи страниц, и разбита на десяток документов с непрозрачными названиями. Этот раздел о том, как в них ориентироваться и как читать их язык.

Хорошая новость: язык документации ST предельно однообразен. Выучив четыре десятка оборотов, вы будете понимать любой её раздел, даже не владея английским свободно.

Как это называется в документации

Оригинал	Перевод
datasheet (DS)	описание микросхемы: выводы, электрика, корпуса
reference manual (RM)	справочное руководство: периферия и регистры
errata sheet (ES)	перечень известных ошибок кристалла и обходов
application note (AN)	заметка о применении: как решить конкретную задачу
user manual (UM)	руководство пользователя платы или программы
programming manual (PM)	руководство по программированию ядра
reset value	значение регистра после сброса
reserved, must be kept at reset value	зарезервировано, оставлять значение после сброса

39.1 Какие бывают документы

Главное различие, которое экономит часы поиска:

• Reference manual один на всё семейство. RM0008 описывает сразу STM32F101, F102, F103 и F105/107. RM0090 — все F405/407/415/417/427/437/429/439. Регистры внутри семейства в основном совпадают, поэтому документ общий. Различия оговорены прямо в тексте. В RM0008 у RCC линии Connectivity (F105/F107) есть AHBRSTR и CFGR2, которых нет у F103 (раздел 37), а у отдельных битов стоит «available only in connectivity line devices». В RM0090 глава о контроллере дисплея LTDC «applies only to STM32F429xx/439xx devices», а у F42x/F43x вместо FSMC стоит FMC. Встретив оговорку, сверьтесь с даташитом своего камня: есть ли у него этот блок или бит.
• Datasheet свой у каждого набора корпусов и объёмов памяти. У STM32F103 их несколько: отдельно для «средней плотности», отдельно для «высокой». Именно поэтому распиновку ищут в datasheet, а не в reference manual — в общем документе её просто не может быть.

Для наших двух платформ:

39.2 Что где искать

Практический приём. Открыв reference manual, не листайте — пользуйтесь оглавлением в PDF и поиском по имени регистра. Ищите не «GPIO output», а прямо GPIOx_ODR: имена регистров уникальны, и поиск сразу приводит и к описанию бита, и к карте регистров, и к местам, где он упоминается.

39.3 Как устроено описание регистра

Все описания регистров в reference manual построены одинаково. Разобрав одно, вы прочитаете любое. Пример — из RM0008 (STM32F103):

GPIOx_ODR — Port output data register (x = A..G)

Address offset: 0x0C
Reset value: 0x0000 0000

31                            16 15                             0
├─────── Reserved ──────────────┤├──────── ODR15..ODR0 ─────────┤
                                        rw

Bits 31:16  Reserved, must be kept at reset value.
Bits 15:0   ODRy: Port output data (y = 0..15)
            These bits can be read and written by software.

Что читать в первую очередь:

• Address offset — смещение от базового адреса блока. Полный адрес = база порта + смещение. Именно так устроены структуры регистров в заголовках (раздел 3). У F4 перед ODR стоят MODER, OTYPER, OSPEEDR, PUPDR и IDR, поэтому смещение GPIOx_ODR там 0x14. Смещения у семейств разные — их всегда берут из RM своего камня.
• Reset value — что в регистре после сброса. Полезно, чтобы понимать, какие биты уже настроены как надо и трогать их не нужно.
• Обозначение доступа под битовой картой — самое важное и самое недооценённое место.

Обозначения доступа

Отсюда следуют вещи, которые иначе выглядят необъяснимыми:

• EXTI_PR помечен rc_w1 — вот почему флаг прерывания сбрасывается записью единицы, а не нуля (раздел 7). Это не причуда блока EXTI: записью единицы сбрасываются флаги во многих блоках ST. Но не во всех: флаги таймера в TIMx_SR помечены rc_w0 и сбрасываются записью нуля, а флаги DMA в DMA_ISR только читаются (r) — сбрасывают их записью единицы в отдельный регистр DMA_IFCR (у F4 — DMA_LIFCR и DMA_HIFCR). Как сбросить флаг, каждый раз смотрят в обозначении под битом.
• GPIOx_BSRR помечен w — вот почему BSRR |= маска бессмысленно: читать там нечего (раздел 5, где это подтверждено сравнением ассемблера).
• USART_SR у F1 и F4 помечен rc_w0 и r, а не rc_r: флаги ошибок (PE, FE, ORE, флаг шума) и IDLE сбрасываются последовательностью — прочитать SR, затем DR. Окно периферии в отладчике читает все регистры блока, включая DR, — последовательность выполнена, флаг исчез, а принятый байт потерян. Отсюда классическая ошибка: посмотрели регистр в отладчике, флаг исчез, и программа повела себя иначе, чем без отладчика. Настоящий rc_r в STM32 редок: например, флаги WFR и MPR в ETH_MACPMTCSR сбрасываются самим чтением регистра.

39.4 Язык документации

Около сорока оборотов покрывают почти весь текст. Они повторяются дословно из раздела в раздел.

Про биты и регистры

Про поведение

⚠️ Разница между must, should и may в технической документации не стилистическая. must — нарушение приведёт к неработоспособности, should — нарушение допустимо, но чревато, may — просто возможность. В переводах эту разницу часто стирают, и рекомендация превращается в требование или наоборот.

Слова, которые переводят неправильно

Скважность в строгом смысле — обратная величина T/τ: при заполнении 25 % скважность равна 4. В разговоре, и в этом справочнике тоже, «скважностью» часто называют само заполнение (раздел 82.2) — в расчётах их различайте.

39.5 Errata: читать до, а не после

Errata sheet — официальный список того, что в кристалле работает не так, как написано в reference manual. Документ короткий, читается за полчаса, и эти полчаса окупаются многократно.

Типичная запись выглядит так:

2.1.5  I2C analog filter may provide wrong value, locking BUSY flag

Description: ...
Workaround:  ...

То есть: что сломано, при каких условиях проявляется и как обойти.

Классические примеры, на которых теряют дни:

• у F1 известно залипание флага BUSY в I²C, из-за чего шина «зависает» после сбоя — обход требует ручного дёргания линий (у F405/F407 такого пункта нет — свой перечень надо читать свой, 39б);
• у некоторых семейств первый отсчёт АЦП после включения недостоверен;
• у отдельных ревизий кристалла отличается поведение при пробуждении из Stop.

Перечень разбит по ревизиям кристалла, и у многих пунктов сказано, в какой ревизии их исправили, — значит, сначала надо знать свою. Её узнают по букве ревизии в маркировке корпуса или по полю REV_ID — старшим 16 битам DBGMCU_IDCODE по адресу 0xE0042000 (у F1 и у F4 адрес один). Какой код какой букве соответствует — в начале перечня и в описании DBGMCU_IDCODE в справочном руководстве: у F405/F407 0x1000 — ревизия A, 0x1001 — Z. У F103 подвох: без отладчика DBGMCU_IDCODE читается нулём, и программа свою ревизию сама не узнает — это тоже пункт перечня ошибок (раздел 2а).

Симптом всегда один и тот же: код написан строго по документации, а работает не так. Прежде чем искать ошибку у себя третий час — откройте errata.

39.6 Application notes

Отдельный жанр: не описание железа, а решение задачи целиком, с формулами, схемами и кодом. Часто это готовый ответ на вопрос, который иначе пришлось бы собирать из десятка мест.

Если задача выглядит типовой — почти наверняка по ней есть application note. Поиск: STM32 <тема> application note или прямо AN с номером на сайте ST.

39.7 Как искать

Правильные ключевые слова экономят больше времени, чем беглый английский.

Приём с таблицами регистров. В конце каждого раздела reference manual есть сводная таблица <блок> register map and reset values — на одной странице все регистры блока со смещениями и значениями после сброса. Обычно это единственное, что нужно, когда механизм уже понятен и требуется лишь уточнить бит.

39.8 Грабли

Сделано строго по документации, а работает не так. Первым делом — перечень ошибок кристалла: там может быть ровно этот случай (39.5).

Рекомендация прочитана как требование — или наоборот. must, should и may различаются по смыслу, в переводах эту разницу стирают (39.4).

Распиновки нет в справочном руководстве. Она в даташите конкретного кристалла; регистры — в справочном руководстве, ядро — в руководстве по ядру (39.1–39.2).

39.9 Итоги

• Reference manual один на семейство, datasheet — свой на каждый корпус. Распиновка живёт в datasheet, регистры — в reference manual, ядро — в programming manual.
• Обозначения доступа под битовой картой объясняют то, что иначе кажется произволом: rc_w1 — сброс записью единицы, w — читать нечего, rc_r — флаг исчезает от самого чтения.
• Язык документации однообразен: четыре десятка оборотов покрывают почти весь текст. must, should и may различаются по смыслу, а не по стилю.
• Errata читают до разработки. Симптом «сделал по документации, работает не так» — повод открыть её первым делом.
• По типовой задаче почти всегда есть application note с готовым решением.
• Искать в документе стоит по имени регистра, а не по описанию — имена уникальны и ведут сразу во все нужные места.

Дальше: раздел 39а «Официальные документы: что и где взять».