This repository explains the structure of a Device Family Pack (DFP) for Open-CMSIS-Pack based projects. It also describes the steps to create a DFP based on an example pack.
A Board Support Pack (BSP) complements a DFP with board support. While it is possible to deliver both (DFP and BSP) as a single pack, it is common practice to separate it.
Content
-
One way to distribute device support into all relevant toolchains as CMSIS and the CMSIS-Toolbox supports Arm Compiler, GCC, and IAR.
-
Connect to users: as a device vendor you control distribution to multiple tools and web portals. For Arm's pack index new releases are scanned once per day, making the pack and the devices defined inside it publicly available. Every device, device group, family or subfamily has a page automatically generated on keil.arm.com that displays all available information about the device(s). Device pages display compatible development boards (based on the mounted device specified for a board) and link back to the parent Pack.
- Once a pack is published, various delivery services may pick up the device. The pack service on www.keil.arm.com scans your pack repository once per day.
- Features that you specify in the packs are enable web search that helps users to identify devices and boards based on project requirements.
- Adding documentation and purchase links lets you connect with your customers.
-
Reduces support efforts as packs make it easier for users to integrate software in projects
- The Product Lifecycle Management capabilities of the pack-enabled tools make it easy to update software packs when required.
-
Access to examples that may be part of packs quick-start user projects.
- Adding one board layer can support many different standardized examples that are based on the Reference Example Framework.
To learn more review the session about Generating CMSIS-Packs for Devices and Boards.
- Defines the properties of a device or a device family.
- Processor core definition (multi-core devices have multiple processor core definitions)
- Processor core configuration of specifies such as FPU, MPU, TrustZone.
- Debug and Trace configuration of the device along with specific sequences. The Debug Setup Tutorial contains further details.
- On-device memory areas with description and Flash algorithms.
- SVD file that describes the peripherals of a device.
- Device startup code, system file, and device header.
Optional pack content that improves the overall usability:
- Data sheet and user manual of the device either directly including as documentation files or via web links.
- Device specific software drivers and in case that the device is supported by a configuration tool the related generator information.
- Standardized CMSIS-Driver that enable standard middleware and software examples.
- Device features that enable search capabilities at web portals.
This repository contains a example DFP of a fictional device family called ACMECM4 from the imaginary device vendor ACME. The device family consists of four members that are separated into two sub-families. The specification of the MVCM3 family is as follows:
| ACME ACMECM4XXX | |||
| The ACMECM4 device family is based on the Arm Cortex-M4 processor with a set of on-chip peripherals. | |||
| Processor | Arm Cortex-M4 (r0p1), little-endian | ||
| MPU | Yes | ||
| FPU | Yes | ||
| External interrupts | 16 | ||
| Operating temperature range | -40 degC ~ +105 degC | ||
| Operating voltage | +2.5 V ~ 3.6 V | ||
| Real-time clock | 32.768 kHz | ||
| Watchdog timer | 1 | ||
| ACMECM4100 | ACMECM4200 | ||
| The ACMECM4100 sub-family runs up to 50 MHz | The ACMECM4100 sub-family runs up to 100 MHz | ||
| I/Os | 26 | I/Os | 38 |
| USART | 4 | USART | 5 |
| Timer/counter | 6 x 32-bit | Timer/counter | 8 x 32-bit |
| PWM | 4 x 16-bit | ||
| Package | 32-pin LQFP | Package | 48-pin LQFP |
| Features ACMECM4110 | Features ACMECM4250 | ||
| RAM | 2 kB SRAM | RAM | 2 kB SRAM |
| Flash | 16 kB | Flash | 16 kB |
| PWM | 2 x 16-bit | ||
| Features ACMECM4120 | Features ACMECM4260 | ||
| RAM | 4 kB SRAM | RAM | 4 kB SRAM |
| Flash | 32 kB | Flash | 32 kB |
| PWM | 4 x 16-bit | ||
The DFP includes the following components that are described in the PDSC file:
- System, startup, and header files
- SVD file
- Flash programming algorithms
- An template source file of a CMSIS-Driver USART.
The pack is generated used the following scripts and workflows:
| Content | Description |
|---|---|
gen_pack.sh |
Script that builds the pack; refer to usage information for configuration details. |
.github/workflows/pack.yaml |
GitHub workflow that generates the pack on every commit. |
This repository may be used to kick start the development of a pack. The following section explains how to create a pack.
- MDK v5.38 with default installation path (C:\Keil_v5)
- CMSIS-Toolbox v1.6.0 or higher (update files in C:\Keil_v5\ARM\ctools)
- VS Code with XML Language Support by Red Hat
- Structure your device family
- First, copy the system and startup files for your selected Arm Cortex-M core from the CMSIS_DFP repository. This is a good starting point for any device based on Arm IP.
- Create one or more SVD files for the device family from your design software. This is the starting point for creating the device header file(s).
- Think about the partitioning of your device family: what do the devices have in common (reduces effort in creating the PRDC file).
- Create Flash programming algorithms for your devices.
- Organize and create the file list that will be delivered as Pack
- Create the PDSC file using your favorite editor (we recommend VS Code with XML extension). A complete list of availble fields used to describe devices is available in the Open-CMSIS-Pack Spec.
- Validate the software pack using the
packchktool. - Create the software pack using the
gen_packlibrary.
-
Clone this repository (as it serves as a getting started example)
-
Register this pack with
cpackgetvia PDSC file using this commands:cpackget update-index // optional to ensure that pack index is up-to-date cpackget add ACME.ACMECM4_DFP.pdsc // pack now appears in toolchains, i.e. in MDK csolution list packs
-
The content of the pack can now be seen in the Manage Component dialog of uVision.
For changing the PDSC file it is recommended to use VS Code with XML extension, but any editor would work.
After modifications to the PDSC file run packchk; include all packs that are required by your software in the validation:
Using Command Prompt:
packchk ACME.ACMECM4_DFP.pdsc -i %CMSIS_PACK_ROOT%/ARM/CMSIS/5.9.0/ARM.CMSIS.pdscUsing Git Bash console:
packchk ACME.ACMECM4_DFP.pdsc -i $CMSIS_PACK_ROOT/ARM/CMSIS/5.9.0/ARM.CMSIS.pdscWith CMSIS-Toolbox v1.7.0 the XML schema check is available with packchk, the command may be then extended to:
packchk ACME.ACMECM4_DFP.pdsc -i $CMSIS_PACK_ROOT/ARM/CMSIS/5.9.0/ARM.CMSIS.pdsc -s /c/Keil_v5/UV4/PACK.xsdThe pack can be created locally in the directory output using Git Bash:
./gen_pack.sh -vTo verify the tools such as the VS Code - Keil Studio Desktop extension, install the pack with:
cpackget add ./output/ACME.ACMECM4_DFP.1.0.0.packNotes:
- VS Code - Keil Studio Desktop does not yet support pack installation from local repositories.
- To continue local pack development, change add a new <release> version. During development semantic version labels to indicate a pre-release may be used as shown below:
<releases>
<release version="1.0.1-rc0">
Further development
</release>
<release version="1.0.0" date="2023-04-22">
Initial version
</release>
</releases>Once changes are committed the GitHub Action creates the pack.
The pack can be hosted on the <url> specified in the *.pdsc file.
Refer to Publish a Pack in the Open-CMSIS-Pack specification for further details.
Use Issues on this GitHub to raise questions or submit problems.
Happy Packing!