 |
Open-CMSIS-Pack
Version 1.7.45
Delivery Mechanism for Software Packs
|
|
Open-CMSIS-Pack
Version 1.7.45
Delivery Mechanism for Software Packs
|
Before you start distributing a software pack, make sure that it does not contain errors. Use the tools described in the Checking CMSIS-Packs section for verification. Once you have validated that the PDSC file and the pack contain no errors, you have basically two options for distributing a software pack:
The following sections assume that you are familiar with the CMSIS-Toolbox and especially with cpackget.
Software packs are ZIP files that contain a PDSC file and other content. The ZIP file needs to be consistent and the PDSC file within has to be validated against the XML schema file (PACK.xsd). An open-source checking tool is available that helps you with both tasks: a Bash library for gen-pack scripts. Make sure that you have used it to validate your PDSC file and the pack contents before submitting it to any pack indexing service. The library can be used on all major host operating systems and can also be run in GitHub actions.
The easiest way to distribute a software pack is attaching it to an email or using other means of electronic distribution (for example using a file server). Install the software pack on a PC using cpackget, the pack management tool that comes with the CMSIS-Toolbox:
If the PDSC file does not contain a valid <url> element, a manual installation is required to update a software pack. Otherwise, cpackget can check for updates on the server or the local machine that is specified by <url>.
<url> using the file URI scheme.If you want to make your packs publicly available, you need to host them on the web. For publishing packs, these options are available:
The following diagram shows how you can publish your packs when using a pack indexing service:
When you run the command cpackget update-index, the tool queries the package index file (index.pidx) from the pack index server. This file is generated using the vidx2pidx tool from the vendor index file (index.vidx) which points to all known <vendor>.pidx and stand-alone PDSC files.
The PIDX file allows you to change pack versions and add packs to your distribution list. All packs that are referenced in the PIDX file will be processed and validated. Only error-free packs will become available via web pages and development tools.
Any web server can be used to host a software pack (specified by the <url> element in the PDSC file). At this location, the following files should be present:
All previous versions listed in the <releases> section of the PDSC file should be present at the <url> as well. This allows users to revert updates or to download a previous version of a software pack (for maintenance purposes).
The <vendor>.pidx allows you to publish multiple packs to a Pack Index Service at once.
If you develop your packs publicly on GitHub, you can use the infrastructure to host your packs. The recommended way to do this is as follows (note that in this example, <orgname> is equal to <vendor> in the other examples. We use <orgname> here as this is the nomenclature on GitHub):
github.com/orgname/indexrepo. The PIDX file should be named <orgname>.pidx.github.com/orgname/name1 github.com/orgname/name2 main branch, you need have a <orgname>.<nameX>.pdsc file.This diagram shows an exemplary set up on GitHub with pack versions 1.0.0 and 1.3.0:
The vendor (orgname) PIDX file would look like the following:
A PDSC file for one of the repositories would look like this:
When updating a pack, you need to:
main branch can be used to host the PDSC file, additional confidence against unwanted changes can be made if you use a dedicated branch for hosting the PDSC file. This avoids breaking unintentionally the pack location when accepting a pull request (PR).Tool, software, or silicon vendors may provide a web infra-structure that lists packs that are available from multiple vendors. Companies like Arm or IAR provide such a service for making CMSIS-Packs available to a wider audience of developers. The packs are then found by pack management tools and their contents are listed on web sites, such as Arm's list of CMSIS-Packs.
Once you are ready to publish your packs, please send the URL of the <vendor>.<name>.pdsc or <vendor>.pidx file to the following email addresses:
Arm uses the pack information to generate a list of available software packs. The following content will be processed in order to generate the web site (https://www.keil.arm.com/packs/):
Furthermore, the data is used to create lists of boards and devices.
Please allow up to seven working days for the process. If the files contain any errors, you will be notified. Otherwise, the information is added to the index server. We strongly recommend using a Package index file (PIDX) for better maintainability.
If you want to check the content of you Package index file (PIDX), you can use the vidx2pidx utility to create your own index.pidx file. Once created, you can use it with cpackget to install the packs listed in the PIDX file.
Follow these steps to run the conversion and installatin:
Create you <vendor>.vidx file just listing the <vendor.pidx> file. Code example
index.pidx.index.pidx.Sometimes, it is necessary to rehost a pack (moving a pack from one URL to another). Rehosting implies changing the <url> element in the PDSC file. To ensure that the pack is found by a Pack Index Service, follow this procedure:
Sometimes, it is necessary to rename a pack (because the pack vendor and/or its name have changed for example). To ensure that the pack is found by a Pack Index Service and the tools, follow this procedure:
CMSIS-Pack is designed as a web-based distribution network. Each provider of a CMSIS-Pack (also referred to as vendor) is responsible for hosting, maintaining and publishing unique versions of a CMSIS-Pack.
A CMSIS-Pack is uniquely identified by <vendor>.<pack name>.<version>.pack. All published versions of a pack and the PDSC file need to be available in the same web folder specified by <url>. Multiple different packs may be located in the same web folder.
The package index file lists all CMSIS-Packs hosted and maintained by a vendor. The file is hosted by the vendor and has the name <vendor>.pidx. The <vendor> tag needs to match the file name. The file also contains the <url> to it's origin, as well as a <timestamp> of it's last update.
It is the vendor's obligation to update this file whenever:
MyVendor.pidx example
Each individual pack is referenced by the attributes:
The package index file for the CMSIS-Pack compliant packs, hosted on www.keil.com can be found here: https://www.keil.com/pack/Keil.pidx.
The benefit of a single package index file is, that this file only needs to be exchanged once and can be polled for updates and additions of packs by a vendor. To add a vendor's packs to the public list maintained on www.keil.com, send an email to CMSIS@arm.com attaching a version of the <vendor>.pidx file.
A vendor index file lists package index files from different vendors. This information can be used to compile a list of known packs.
MyVendor.vidx example
The latest index file of CMSIS-Packs belonging to vendor="ARM" and vendor="Keil" that are hosted and maintained here: https://www.keil.com/pack/Keil.pidx
Arm also maintains a flat list of all CMSIS-Pack compliant packs reported to Arm here: https://www.keil.com/pack/index.pidx
The vendor index file containing references to the package index files (or optionally PDSC files) used for compiling this summary index file are listed in the Keil.vidx file and can be downloaded from here: https://www.keil.com/pack/Keil.vidx
Based on these publicly available index files, everyone is equally positioned to create an index of available packs and their latest versions.
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2013-2023 ARM Limited. All rights reserved.
SPDX-License-Identifier: Apache-2.0
Licensed under the Apache License, Version 2.0 (the License); you may
not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an AS IS BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
$Date: 28. March 2023
$Revision: 1.1.1
$Project: Schema File for Package Index File Format Specification
Package Index file naming convention <vendor>.pidx
Vendor Index file naming convention <vendor>.vidx
SchemaVersion=1.1.1
-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="qualified" version="1.1.1">
<!-- semantic versioning (semver.org) <major>.<minor>.<patch>-<quality> -->
<xs:simpleType name="SemanticVersionType">
<xs:restriction base="xs:string">
<!-- major . minor . patch [[-]quality] [+build] -->
<xs:pattern value="[0-9]+\.[0-9]+\.[0-9]+(\-((0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\+([0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*))?" />
</xs:restriction>
</xs:simpleType>
<!-- some strings are used to construct filenames (e.g. package name). Such names can contain only subset of characters and must not contain neither spaces nor dots. -->
<xs:simpleType name="RestrictedString">
<xs:restriction base="xs:string">
<xs:pattern value="[\-_A-Za-z0-9]+"/>
<xs:pattern value="\S(.*\S)?"></xs:pattern>
</xs:restriction>
</xs:simpleType>
<!-- Vendor index file Description Type -->
<xs:complexType name="VidxType">
<xs:attribute name="url" type="xs:anyURI" use="required"/>
<xs:attribute name="vendor" type="RestrictedString" use="required"/>
<xs:attribute name="date" type="xs:date" use="optional"/>
</xs:complexType>
<!-- Package Description Type -->
<xs:complexType name="PdscType">
<xs:attribute name="url" type="xs:anyURI" use="required"/>
<xs:attribute name="vendor" type="RestrictedString" use="required"/>
<xs:attribute name="name" type="RestrictedString" use="required"/>
<xs:attribute name="version" type="SemanticVersionType" use="required"/>
<xs:attribute name="date" type="xs:date" use="optional"/>
<xs:attribute name="deprecated" type="xs:date" use="optional"/>
<xs:attribute name="replacement" type="RestrictedString" use="optional"/>
<xs:attribute name="size" type="xs:unsignedInt" use="optional"/>
</xs:complexType>
<!-- Package Description file Type -->
<xs:complexType name="PindexType">
<xs:sequence>
<xs:element name="pdsc" type="PdscType" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<!-- Vendor vendor's package index file tag -->
<xs:complexType name="VindexType">
<xs:sequence>
<xs:element name="pidx" type="VidxType" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<!-- Index description root point (Vendor Index file, Package Index file -->
<xs:element name="index" nillable="true">
<xs:complexType>
<xs:sequence>
<xs:element name="vendor" type="RestrictedString"/>
<xs:element name="url" type="xs:anyURI"/>
<xs:element name="timestamp" type="xs:dateTime" minOccurs="0"/>
<xs:choice minOccurs="1" maxOccurs="2">
<!-- index/list of packs -->
<xs:element name="pindex" type="PindexType"/>
<!-- index/list of vendor index files -->
<xs:element name="vindex" type="VindexType"/>
</xs:choice>
</xs:sequence>
<xs:attribute name="schemaVersion" type="SemanticVersionType" use="required"/>
</xs:complexType>
</xs:element>
</xs:schema>