Skip to content

Latest commit

 

History

History
297 lines (242 loc) · 13.1 KB

README.md

File metadata and controls

297 lines (242 loc) · 13.1 KB
Raw

Create a Device Family Pack - Hands-On Example

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

Benefits of Packs to deliver device and board support

  • 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.

    Example of a device page generated from PDSC data

  • 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.

DFP Content

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.

Example DFP

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.

Pack Development

This repository may be used to kick start the development of a pack. The following section explains how to create a pack.

Tool-Environment (Recommended)

Steps to Create a Device Family Pack

  • Structure your device family
    • First, copy the system and startup files for your selected Arm Cortex-M core from the Cortex_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 packchk tool.
  • Create the software pack using the gen_pack library.

Local Pack Development

  1. Clone this repository (as it serves as a getting started example)

  2. Register this pack with cpackget via 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

  3. 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.pdsc

Using Git Bash console:

packchk ACME.ACMECM4_DFP.pdsc -i $CMSIS_PACK_ROOT/ARM/CMSIS/5.9.0/ARM.CMSIS.pdsc

With 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.xsd

The pack can be created locally in the directory output using Git Bash:

./gen_pack.sh -v

Verify Pack in Tools

To 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.pack

Notes:

  • 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>

Pack Creation on GitHub

Once changes are committed the GitHub Action creates the pack.

Publish 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.

Issues and Questions

Use Issues on this GitHub to raise questions or submit problems.

Happy Packing!