Структура репозитория на GitHub

Репозиторий состоит из 2-х директорий:

• PACK_Gen - здесь происходит сборка Pack
• SVD_Files - здесь собираются SVD файлы описания регистров микроконтроллера.

Pack файл - это всего лишь zip архив. Т.е. можно смело поменять расширение *.pack на *.zip, залезть внутрь и что-то исправить. При двойном клике на PACK_Gen/Milandr.MDR1986VExx.2.x.pack запускается Keil - PackInstaller, который разархивирует пак в директорию C:\Keil_v5\ARM\PACK, сам же пак копируется в директорию C:\Keil_v5\ARM\PACK\.Download и может обновляться по сети, если это правильно прописать. В этой директории лежат все паки, которые когда-либо устанавливались, так что, в принципе, всегда есть возможность откатиться.

Сборка Пака производится батником PACK_Gen\gen_pack.bat. В состав Пака попадает все, что лежит в директории PACK_Gen\Files. Сборка может закончится с ошибками, тогда следует запустить PACK_Gen\_CheckPack.bat, который обновляет файл log.txt. В этом файле можно прочитать, какие были выявлены проблемы при сборке, либо о том, что проблем нет. Выходной файл появляется здесь же, например, PACK_Gen\Milandr.MDR1986VExx.2.x.pack, с версией, заданной в файле PACK_Gen\Milandr.MDR1986VExx.pdsc.

Файл PACK_Gen\Milandr.MDR1986VExx.pdsc является основным для сборки Пака, в нем описаны микроконтроллеры, драйвера и все прочее. Подробно об этом лучше читать у производителя - CMSIS-Pack Documentation.

Файл PACK_Gen\Files\Milandr.MDR1986VExx.pdsc изменять не надо, он создается при сборке Пака! Все остальное - это то, что мы хотим предложить в Паке. Структура в нашем паке такая:

• Books - здесь лежат pdf файлы с кратким описанием регистров и флагов периферийных блоков. Подробнее ниже в SVD_Files.
• Examples - здесь представлены примеры работы с периферийными модулями микроконтроллеров.
• Keil - здесь лежат файлы необходимые для работы с микроконтроллерами в среде Keil.
  • FLM - файлы для прошивки МК.
  • SVD - описание периферии для отображения в отладчике. Подробнее ниже.
  • CMSIS_Core - Библиотека ядра Cortex.
  • _Scatter - Скаттер файлы для линкера, но подключить их не удалось. Вероятно будут удалены.
• SPL - Библиотека для управления микроконтроллерами
  • Boards - Описание ресурсов демоплат и функции работы с ними - кнопки, светодиоды, LCD экран и т.д.
  • Config - Настройки поведения функций библиотеки, значения по умолчанию.
  • Devices - Описание микроконтроллеров
    • Defines - Описание периферийных блоков общее для нескольких микроконтроллеров.
      • MDR_ADC_defs.h - Общее описание блока АЦП
      • MDR_ADC_VE1VE3_def.h - Расширение общего описания до полного описания блока АЦП для 1986ВЕ1Т и 1986ВЕ3Т.
      • …
    • MDR1901VC1 - Заголовочный файл и описание периферийных блоков под конкретный МК.
      • MDR_1901VC1.h
      • startup_MDR1901VC1.s
      • system_MDR1901VC1.c
      • system_MDR1901VC1.h
    • MDR1986VE1
    • …
  • Drivers - Драйверы работы с периферией
    • MDR_GPIO.c
    • MDR_GPIO.h
    • …

Подробнее про некоторые пункты:

Минимальный набор файлов поддержки ядра, необходимый для библиотеки. По умолчанию в Keil есть своя директория под эти файлы - C:\Keil_v5\ARM\CMSIS\Include. Но иногда они не подключаются - это проблема старой версий Keil или чего-то еще. Кроме этого, иногда Keil обновляет эти файлы, например, переносит функции в другие файлы. В итоге чтобы не было несовместимости с будущими обновлениями Keil в данной директории зафиксированы необходимые файлы поддержки ядра для нашего пака.

Здесь лежат файлы для прошивки микроконтроллеров. Сами проекты по созданию этих FLM находятся в примерах - Examples\All_Boards\EEPROM_FLM.

• Defines - Здесь собраны заголовочники, описывающие ресурсы демоплат. Файлы и функции, относящиеся к платам, имеют префикс MDRB_, дополнительная буква обозначает Board. Например, MDRB_1986VE1.h - в этом файле описано, какие пины подключены к светодиодам на плате, к кнопкам, к экрану LCD, к SPI, к UART и т.д.

Драйверы для работы с устройствами на платах находятся в этой же директории SPL/Boards. Например,

• драйвер MDRB_LEDs.c (MDRB_LEDs.h) предоставляет функции по настройке выводов GPIO, подключенных к светодиодам в функцию Port OUT.
• драйвер MDRB_Buttons.c (MDRB_Buttons.h) предоставляет функции для настройки пинов и для опроса кнопок.
• драйвер MDRB_LCD_MT_12864x.c (MDRB_LCD.h) позволяет работать с LCD экраном на тех демоплатах, на которых он есть.
• драйвер MDRB_UART_Debug.c (MDRB_UART_Debug.h) реализует вывод printf в Uart. Достаточно лишь подключить этот драйвер в проект и вызвать MDR_UART_DBG_Init(), тогда printf будет выводить данные наружу.
• драйвера MDRB_XXX_PinSelect.с содержат настройки пинов для работы с UART, SSP, каналами Timer. Эти пины используются в некоторых демо-проектах для быстрой настройки выводов.

Все что нужно для работы этих драйверов с отладочными платами, например 1986ВЕ1Т, уже задано в MDRB_1986VE1.h. Чтобы использовать эти драйверы в своих проектах достаточно их подключить.

Как видно из картинки, драйвера для LED и Buttons реализованы по стандартному API СMSIS и Keil признал их родными - CMSIS-Driver. Остальные драйвера такими не являются. В будущем планируется реализовать драйвера SPI и UART по стандартному API, как это сделал на форуме RMax.

Эти драйвера можно использовать и в своих платах, для этого необходимо сформировать свой файл описания аналогичный MDRB_1986VE1.h, а в файле MDRB_BoardSelect.h подключить этот свой новый файл. Файл MDRB_BoardSelect.h копируется в каждый новый проект в директорию RTE\Board_Support\MDR1986VE1\MDRB_BoardSelect.h и доступен для редактирования.

Это удобно, поскольку для новой платы достаточно лишь описать ресурсы, а драйвера уже готовы.

Здесь лежат конфигурационные файлы для каждого МК. Файл MDR_Config_XX.h автоматически копируется в директорию проекта RTE\Device\ и доступен для настройки пользователем под свою плату. Подробнее описано здесь - Настройки Config.

В этой директории собраны определения на все микроконтроллеры. Обычно файл описания МК содержит описание всей содержащейся на борту периферии, регистры, маски, флаги, адреса и т.д. В случае когда периферия повторяется в нескольких МК неудобно вносить одно и то-же исправление в разные файлы описания микроконтроллеров. Объем таких файлов большой и есть шанс наплодить невынужденных ошибок, где-то исправить, где-то забыть, где-то не туда воткнуть копипасту. Чтобы этого избежать одинаковые куски определений вынесены отдельные файлы и расположены они в SPL/Devices/Defines. Например, файл MDR_BKP_defs.h содержит определения общие для всех МК с данным блоком. А файл MDR_BKP_VE1_defs.h добавляет лишь определения специфичные для 1986ВЕ1Т. Итого, в файле описания МК

• SPL\Devices\MDR1986VE1\MDR_1986VE1.h "инклудится" файл
• SPL\Devices\MDR1986VE1\MDR_BKP_VE1_defs.h, который в свою очередь "унклудит" файл
• SPL\Devices\Defines\MDR_BKP_defs.h.

По остальным периферийным блокам схема аналогичная. Файл заголовочник для МК подключает необходимые версии описания периферии, вместо того чтобы содержать их непосредственно в своем теле.

MDR_1986VE1.h:

...
/*===============  RST_Clock ===================*/
#include "MDR_RST_VE1_defs.h"

/*===============  Backup and RST ==============*/
#include "MDR_BKP_VE1_defs.h"

/*===============  EEPROM Controller=============*/
#include "MDR_EEPROM_defs.h"
...

В небольших файлах проще ориентироваться и перемещаться по содержимому, чем в "большой простыне" содержащей все на свете. Поэтому изучение содержимого и внесение исправлений должно происходить проще. Необходимо лишь понимать иерархию вложенности.

В данной директории собраны файлы реализующие API управления периферией микроконтроллеров. Здесь все аналогично официальной библиотеке. Но на мой взгляд, нет особой пользы в разнесении заголовочный файлов и файлов кода по разным директориям. Часто приходится открывать те или иные файлы, и скачка между директориям INC и SRC изрядно утомляет. Файлов в SPL/Drivers не так много чтобы разносить их по разным директориям.

(Данная информация относится к внутренней кухне по сборке Pack и полезной информации для пользователя не несет. Это скорее памятка для потомков, если отойду от дел.)

SVD (System View Description) файл - это файл описания периферии, которая отображается в окне отладчика при просмотре периферии - картинка. Из этого файла с помощью утилиты Keil SVDConv.exe можно получить заголовочный файл описания микроконтроллера. Мы используем эту утилиту для генерации заголовочного файла и потом его перерабатываем. Подробнее про SVD file можно почитать по указанной ссылке, это обычный xml файл, необходимо лишь его написать.

Поскольку по большей части периферийные блоки наследуются из микроконтроллера в микроконтроллер, то описание одного блока с некоторыми модификациями используется в разных svd файлах под разные микроконтроллеры. Чтобы не заниматься копированием xml-текста описания блока вручную была написана простейшая утилита по вставке текста в места отмеченные tag-ами. В каждой тиректории внутри SVD_Files с помощью этой утилиты собирается описание отдельного периферийного блока для разных МК. Как правило в директории есть один файл-заготовка, содержащая общие части текста и таги начинающиеся со знака #. Под этими тагами наша утилита EXE/TextInsert.exe вставит текст уникальный для каждого МК. Что куда вставлять под тагом задается для каждого МК отдельным файлом, например BKP/TAGS_VE1.txt. Запуск вставки текста осуществляется батником, например BKP/Run.bat.

В директории _src все описания периферийный блоков собираются в единый svd файл. Батник _src/Update.bat запускает все батники Run.bat в директориях описания периферии, чтобы обновить эти описания. Батник _src/Run.bat запускает TextInsert.exe чтобы куски описания вставить в blank_MDR19хх.svd и получить готовый svd файл.

В директории _out происходит проверка полученного svd на валидность, а так-же утилитой SVDConv.exe формируются h-файл описания микроконтроллера. Запуск всего этого происходит батником _out/makeAll.bat, лог в _out/out/logVEхх.txt показывает какие ошибки есть в SVD файле. Тут же формируются заголовочники под МК, например MDR1986VE1.h. Мы не используем напрямую эти заголовочные файлы, а лишь копируем из них описания регистров и полей. Дело в том, что под каждое поле в этих заголовочниках создается отдельный enum, что является избыточным. Некоторые поля, такие как биты On/Off нет смысла дублировать. Достаточно завести один тип и использовать во всех подобных полях прочих регистров.

Батник CopyToPack.bat копирует полученные svd файлы внутрь Пака - PACK_Gen\Files\Keil\SVD\. При установке Keil компилирует эти svd файлы в более удобный для машины формат SRF.

Перед началом описания регистров и флагов каждого блока, описание этих регистров из спецификаций на микроконтроллеры сводится в один blockХХХ.xml файл. Это позволяет увидеть различие в регистрах и полях. Например, если открыть файл BKP.xlsx то видно, что этот блок в микроконтроллерах отличается мало - у него отличается адрес блока по сравнению с остальными МК и различается только один регистр REG_0E. В этих же файлах указаны некоторые комментарии по назначению флагов в регистрах. Эти файлы можно использовать как быструю справку. Для этого они экспортированы в *.pdf формат и входят в состав Pack - PACK_Gen\Files\Books. Из Keil их можно открыть двойным кликом в закладке Books.

Делать из этих файлов документацию не планировалось, поэтому описание крайне скудное и на ломаном английском. XLM файлы нужны были лишь для анализа различий. Но иногда возникает необходимость вспомнить за что отвечает какой-то бит, поэтому даже такое неказистое описание показалось полезным. Надеюсь, что в перспективе мы сможем исправить описание на русский и описать биты более подробно. По крайней мере в спецификации перемещаться по описанию регистров менее удобно, поскольку приходится пролистывать много текста, а описание регистров - это и есть самое главное. Оно показывает, что собственно может периферийный блок, а что нет.