├── .github ├── PULL_REQUEST_TEMPLATE │ └── schema_change.md ├── dependabot.yaml ├── download-pack-index.py ├── doxygen.json ├── linkchecker.json └── workflows │ ├── gh-pages.yaml │ ├── schema.yaml │ └── wiki.yaml ├── .gitignore ├── LICENSE ├── README.md ├── doc ├── Glossary.md ├── adr │ ├── 0001-record-architecture-decisions.md │ ├── 0002-use-cmsis-pack-for-component-distribution.md │ ├── 0003-component-source-structure-recommendations.md │ ├── 0004-default-open-source-license.md │ └── 0005-cmsis-pack-extension-component-changelogs.md └── index.html ├── doxygen ├── check_links.sh ├── examples │ ├── Pack_with_Board_Support.zip │ ├── Pack_with_Device_Support.zip │ └── Pack_with_Software_Components.zip ├── gen_doc.sh ├── images │ ├── BSPBundleDisplay.png │ ├── BasicDFPDisplay.png │ ├── BoardsSectionMusca-S1.png │ ├── CMSISDriverVIO.png │ ├── CodeVerify.png │ ├── CodeVerify.vsd │ ├── ComponentDisplay.png │ ├── ComponentSelection.png │ ├── Component_Instances.png │ ├── ConditionsDisplay.png │ ├── DFPFlow.png │ ├── DebugConnect.png │ ├── DebugConnect.vsd │ ├── DebugDisconnect.png │ ├── DebugDisconnect.vsd │ ├── DevBoardDisplay.png │ ├── DeviceDatabase2.png │ ├── ExampleDisplay.png │ ├── ExampleDisplayBSP.png │ ├── FPADisplay.png │ ├── FPATargetOptions.png │ ├── FlashDownload.vsd │ ├── FlashErase.png │ ├── FlashProgram.png │ ├── FlashVerify.png │ ├── GHhosting.png │ ├── IndexingService.png │ ├── MVCM3SpecTable.png │ ├── PDSC_Example_bottom.png │ ├── PDSC_Example_top.png │ ├── PackCreateSteps.png │ ├── RTX_Conf_CM_Wizard_View.png │ ├── Reset.png │ ├── Reset.vsd │ ├── SPVariants_small.png │ ├── SVDFlow.png │ ├── SVDIncluded.png │ ├── SoftwarePacks.png │ ├── StartupSystemFilesAdded.png │ ├── SystemStartupFiles.png │ ├── UserCodeTemplatesDisplay.png │ ├── VariantDisplay.png │ ├── api.png │ ├── component_files.png │ ├── conditions.png │ ├── dbg_uVision_connect_options.png │ ├── dbg_uVision_connect_options_old.png │ ├── dbg_uVision_dbgconf.png │ ├── dbg_uVision_dbgconf_wizard.png │ ├── dbg_uVision_debug_access_log.png │ ├── dbg_uVision_debugconfig.png │ ├── dbg_uVision_jtag_chain.png │ ├── dbg_uVision_reset_configs.png │ ├── dbg_uVision_reset_options.png │ ├── dbg_uVision_sequences.png │ ├── dbg_uVision_sqns_enable.png │ ├── dbg_uVision_sqns_log.png │ ├── dbgconf_confWizard.png │ ├── drawings.pptx │ ├── external_mac_example.png │ ├── internal_mac_example.png │ ├── maxInstancesDisplay.png │ ├── pack_structure.png │ ├── pack_structure_new.png │ ├── pack_trinity.png │ ├── requirements.png │ ├── schema_check.png │ ├── schema_check_output.png │ ├── sequence_flows.vsd │ ├── simplepack_rte.png │ ├── software_component.png │ └── uVision_AP_locked.png ├── pack.dxy ├── src │ ├── General.txt │ ├── apis_schema.txt │ ├── boards_schema.txt │ ├── changelogs_schema.txt │ ├── components_schema.txt │ ├── conditions_schema.txt │ ├── config_wizard.txt │ ├── csolution_schema.txt │ ├── debug_description.txt │ ├── devices_schema.txt │ ├── examples_schema.txt │ ├── flash_algorithms.txt │ ├── generators_schema.txt │ ├── licenses_schema.txt │ ├── pack_creation.txt │ ├── pack_dbg_setup_tutorial.txt │ ├── pack_publish.txt │ ├── parts_schema.txt │ ├── pdsc_format.txt │ └── sdf_schema.txt └── templates │ ├── DoxygenLayout_forUser.xml │ ├── check.png │ ├── cmsis.css │ ├── cmsis_footer.html │ ├── cmsis_footer.js │ ├── cmsis_header.html │ ├── logo.svg │ ├── navtree.css │ ├── search.css │ ├── tab_topnav.png │ └── tabs.css ├── schema ├── PACK.xsd └── PackIndex.xsd └── test └── pack_schema_version_history.py /.github/PULL_REQUEST_TEMPLATE/schema_change.md: -------------------------------------------------------------------------------- 1 | # Schema Change 2 | 3 | This pull request contributes a change to an Open-CMSIS-Pack file schema. 4 | Schema changes have a major impact on the tool ecosystem and need to be done carefully. 5 | 6 | ## Description 7 | 8 | :warning: Explain the reason for the proposed schema change. Add a references to the ADR implemented. Add a reference to the associated PR to [PackChk](https://github.com/Open-CMSIS-Pack/devtools/tree/main/tools/packchk). 9 | 10 | ## Checklist 11 | 12 | _checklist version 2021-11-10_ 13 | 14 | - [ ] Does this change implement an approved ADR? 15 | If yes is the reference provided in the description above? 16 | - [ ] Is the schema file changed, properly? 17 | - [ ] Is the schema version incremented according to [Semantic Versioning](https://semver.org/)? 18 | - [ ] Is the schema file header updated, version and date? 19 | - [ ] Is the schema file change history updated? 20 | - [ ] Does the updated schema file pass [XSD meta schema](https://www.w3.org/2012/04/XMLSchema.xsd) check? 21 | - [ ] Is the documentation updated, accordingly? 22 | - [ ] Are the [automatic checks](../tree/main/.github/workflows) updated or enhanced if required? 23 | - [ ] Are enhancements to [PackChk](https://github.com/Open-CMSIS-Pack/devtools/tree/main/tools/packchk) required to proof semantic usage of changed/added features? 24 | If yes is the reference to the pull request provided in the description above? 25 | -------------------------------------------------------------------------------- /.github/dependabot.yaml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: github-actions 4 | directory: "/" 5 | schedule: 6 | interval: "weekly" 7 | day: "sunday" 8 | open-pull-requests-limit: 10 9 | rebase-strategy: disabled 10 | -------------------------------------------------------------------------------- /.github/download-pack-index.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python3 2 | 3 | import os 4 | import shutil 5 | 6 | from argparse import ArgumentParser 7 | from multiprocessing.pool import ThreadPool 8 | from pathlib import Path 9 | from progress.bar import Bar 10 | from urllib.request import urlretrieve 11 | from urllib.parse import urlparse, urljoin 12 | from xml.dom import minidom 13 | 14 | KEIL_INDEX = 'https://www.keil.com/pack/index.pidx' 15 | OUTPUT = '.Web' 16 | 17 | def fetch_pdsc(item, output, cache_url): 18 | pdsc_filename = f"{item.attributes['vendor'].value}.{item.attributes['name'].value}.pdsc" 19 | pdsc_file = output.joinpath(pdsc_filename) 20 | 21 | if not pdsc_file.exists(): 22 | try: 23 | urlretrieve(urljoin(cache_url, pdsc_filename), pdsc_file) 24 | except Exception: 25 | try: 26 | urlretrieve(urljoin(item.attributes['url'].value, pdsc_filename), output.joinpath(pdsc_file)) 27 | except Exception: 28 | pass 29 | 30 | def main(): 31 | parser = ArgumentParser() 32 | parser.add_argument('-i', '--index', type=urlparse, default=KEIL_INDEX, help='The pack index to download.') 33 | parser.add_argument('-p', '--pdsc', type=urlparse, help='Base URL for cached pdsc files in index. Defaults to basename of index file.') 34 | parser.add_argument('-o', '--output', type=Path, default=OUTPUT, help='Output folder') 35 | parser.add_argument('-j', '--threads', type=int, default=8, help='Number of parallel downloads') 36 | parser.add_argument('-f', '--force', action='store_true', help='Force download') 37 | args = parser.parse_args() 38 | 39 | index_filename = Path(args.index.path).name 40 | index_file = args.output.joinpath(index_filename) 41 | cache_url = args.pdsc 42 | if not cache_url: 43 | cache_url = urljoin(args.index.geturl(), '.') 44 | 45 | if args.force: 46 | try: 47 | shutil.rmtree(args.output) 48 | except OSError as e: 49 | pass 50 | 51 | try: 52 | os.makedirs(args.output) 53 | except OSError: 54 | pass 55 | 56 | print(f"Downloading {args.index.geturl()} ...") 57 | urlretrieve(args.index.geturl(), index_file) 58 | 59 | print(f"Parsing {index_file} ...") 60 | indexXML = minidom.parse(str(index_file)) 61 | 62 | pdscs = indexXML.getElementsByTagName('pdsc') 63 | 64 | print('Downloading pdsc files ...') 65 | with ThreadPool(args.threads) as pool: 66 | bar = Bar('Processing', max=len(pdscs)) 67 | for i in pool.imap_unordered(lambda pdsc: fetch_pdsc(pdsc, args.output, cache_url), pdscs): 68 | bar.next() 69 | bar.finish() 70 | 71 | if __name__ == "__main__": 72 | main() 73 | -------------------------------------------------------------------------------- /.github/doxygen.json: -------------------------------------------------------------------------------- 1 | { 2 | "problemMatcher": [ 3 | { 4 | "owner": "doxygen", 5 | "severity": "warning", 6 | "pattern": [ 7 | { 8 | "regexp": "^(.*):(\\d+): warning: (.*)$", 9 | "file": 1, 10 | "line": 2, 11 | "message": 3 12 | } 13 | ] 14 | } 15 | ] 16 | } 17 | 18 | 19 | -------------------------------------------------------------------------------- /.github/linkchecker.json: -------------------------------------------------------------------------------- 1 | { 2 | "problemMatcher": [ 3 | { 4 | "owner": "linkchecker", 5 | "severity": "warning", 6 | "pattern": [ 7 | { 8 | "regexp": "^(.*):(\\d+);(.*);(.*)$", 9 | "file": 1, 10 | "line": 2, 11 | "message": 4 12 | } 13 | ] 14 | } 15 | ] 16 | } 17 | -------------------------------------------------------------------------------- /.github/workflows/gh-pages.yaml: -------------------------------------------------------------------------------- 1 | name: Publish Documentation 2 | on: 3 | workflow_dispatch: 4 | push: 5 | branches: 6 | - main 7 | paths: 8 | - '.github/workflows/gh-pages.yaml' 9 | - '.github/linkchecker.json' 10 | - 'doxygen/**' 11 | - 'schema/**' 12 | pull_request: 13 | branches: 14 | - main 15 | paths: 16 | - '.github/workflows/gh-pages.yaml' 17 | - '.github/linkchecker.json' 18 | - 'doxygen/**' 19 | jobs: 20 | docs: 21 | name: Build main documentation 22 | runs-on: ubuntu-22.04 23 | steps: 24 | - uses: actions/checkout@v4 25 | - name: Install packages 26 | run: | 27 | sudo apt-get update 28 | sudo apt-get install --no-install-recommends -y graphviz plantuml 29 | - name: Install doxygen 1.9.6 30 | run: | 31 | wget -O doxygen.tgz https://sourceforge.net/projects/doxygen/files/rel-1.9.6/doxygen-1.9.6.linux.bin.tar.gz/download 32 | sudo tar -C /opt -xf doxygen.tgz 33 | sudo ln -s /opt/doxygen-1.9.6/bin/doxygen /usr/local/bin/ 34 | which doxygen 35 | doxygen --version 36 | - name: Install linkchecker 37 | run: | 38 | sudo pip install LinkChecker 39 | - name: Generate doxygen 40 | run: | 41 | echo "::add-matcher::.github/doxygen.json" 42 | doxygen/gen_doc.sh 43 | echo "::remove-matcher owner=doxygen::" 44 | - name: Run linkchecker 45 | run: | 46 | echo "::add-matcher::.github/linkchecker.json" 47 | doxygen/check_links.sh doc/index.html 48 | echo "::remove-matcher owner=linkchecker::" 49 | - name: Archive documentation 50 | if: ${{ github.event_name == 'pull_request' }} 51 | uses: actions/upload-artifact@v4 52 | with: 53 | name: documentation 54 | path: doc/ 55 | retention-days: 1 56 | if-no-files-found: error 57 | - name: Archive documentation 58 | if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }} 59 | run: | 60 | cd doc 61 | tar -cvjf /tmp/doc.tbz2 . 62 | - uses: actions/checkout@v4 63 | if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }} 64 | with: 65 | ref: gh-pages 66 | - name: Publish documentation 67 | if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }} 68 | run: | 69 | rm -rf main 70 | mkdir main 71 | cd main 72 | tar -xvjf /tmp/doc.tbz2 73 | git config user.name github-actions 74 | git config user.email github-actions@github.com 75 | git add . 76 | git commit -m "Update main documentation" 77 | git push 78 | -------------------------------------------------------------------------------- /.github/workflows/schema.yaml: -------------------------------------------------------------------------------- 1 | name: Validate schemata 2 | on: 3 | workflow_dispatch: 4 | pull_request: 5 | branches: 6 | - main 7 | paths: 8 | - '.github/workflows/schema.yaml' 9 | - '.github/download-pack-index.py' 10 | - 'schema/**' 11 | - 'test/pack_schema_version_history.py' 12 | jobs: 13 | pack: 14 | name: Validate pack schema 15 | runs-on: ubuntu-22.04 16 | steps: 17 | - uses: actions/checkout@v4 18 | with: 19 | ref: ${{ github.event.pull_request.head.sha }} 20 | fetch-depth: 0 21 | - id: files 22 | uses: tj-actions/changed-files@v45 23 | - name: Install packages 24 | run: | 25 | sudo apt-get update 26 | sudo apt-get install --no-install-recommends -y libxml2-utils 27 | sudo pip install progress python-dateutil 28 | - name: Fetch Keil index 29 | run: wget https://www.keil.com/pack/index.pidx 30 | - name: Cache Keil index pdsc files 31 | uses: actions/cache@v4 32 | id: cache 33 | with: 34 | path: .Web 35 | key: keilindex-${{ hashFiles('index.pidx') }} 36 | - name: Fill cache 37 | if: ${{ steps.cache.outputs.cache-hit != 'true' }} 38 | run: python3 .github/download-pack-index.py -f 39 | - name: Run xmllint against XMLSchema.xsd 40 | run: | 41 | wget https://www.w3.org/2012/04/XMLSchema.xsd 42 | xmllint --noout --schema XMLSchema.xsd schema/PACK.xsd 43 | - name: Run xmllint against Keil index 44 | run: | 45 | rc=0 46 | for f in $(find .Web -name *.pdsc); do 47 | if ! xmllint --noout --schema schema/PACK.xsd $f; then 48 | echo "::error file=schema/PACK.xsd::Schema validation failed for $(basename $f)" 49 | rc=1 50 | fi 51 | done 52 | exit $rc 53 | - name: Check schema version history 54 | run: | 55 | echo "${{ github.event.pull_request.base.sha }}" > .git/ORIG_HEAD 56 | python test/pack_schema_version_history.py ${{ steps.files.outputs.all_changed_files }} 57 | 58 | index: 59 | name: Validate index schema 60 | runs-on: ubuntu-22.04 61 | steps: 62 | - uses: actions/checkout@v4 63 | - name: Install packages 64 | run: | 65 | sudo apt-get update 66 | sudo apt-get install --no-install-recommends -y libxml2-utils 67 | - name: Run xmllint against XMLSchema.xsd 68 | run: | 69 | wget https://www.w3.org/2012/04/XMLSchema.xsd 70 | xmllint --noout --schema XMLSchema.xsd schema/PackIndex.xsd 71 | - name: Run xmllint against keil.pidx 72 | run: | 73 | wget https://www.keil.com/pack/keil.pidx 74 | xmllint --noout --schema schema/PackIndex.xsd keil.pidx 75 | -------------------------------------------------------------------------------- /.github/workflows/wiki.yaml: -------------------------------------------------------------------------------- 1 | name: Sync wiki content 2 | on: 3 | workflow_dispatch: 4 | push: 5 | branches: 6 | - main 7 | paths: 8 | - '.github/workflows/wiki.yaml' 9 | - 'doc/Glossary' 10 | - 'doc/adr/*' 11 | jobs: 12 | wiki: 13 | name: Sync content to wiki 14 | runs-on: ubuntu-latest 15 | steps: 16 | - uses: actions/checkout@v4 17 | with: 18 | path: origin 19 | - uses: actions/checkout@v4 20 | with: 21 | repository: Open-CMSIS-Pack/Open-CMSIS-Pack.wiki 22 | path: wiki 23 | - name: Copy Glossary 24 | run: cp -f origin/doc/Glossary.md wiki/ 25 | - name: Update ADRs 26 | run: cat origin/doc/adr/*.md > wiki/Architecture-Decision-Records.md 27 | - name: Commit wiki update 28 | run: | 29 | git config user.name github-actions 30 | git config user.email github-actions@github.com 31 | git add . 32 | git commit -m "Sync wiki content from repository main branch" 33 | git push 34 | working-directory: wiki 35 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | CMakeLists.txt.user 2 | CMakeCache.txt 3 | CMakeFiles 4 | CMakeScripts 5 | Testing 6 | Makefile 7 | cmake_install.cmake 8 | install_manifest.txt 9 | compile_commands.json 10 | CTestTestfile.cmake 11 | _deps 12 | doc/html 13 | .DS_Store -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Open-CMSIS-Pack Specification 2 | 3 | The Open-CMSIS-Pack project delivers the infrastructure to integrate and manage software components and improve code reuse across embedded and IoT projects. The project is currently hosted and managed as an incubation project by Linaro in partnership with Arm, NXP and ST. 4 | 5 | This Open-CMSIS-Pack specification is part of the Common Microcontroller Software Interface Standard and covers the following areas: 6 | 7 | - **Pack:** Describes a delivery mechanism for software components, device parameters, and evaluation board support. It simplifies software re-use and product life-cycle management (PLM). 8 | 9 | - **Build:** Defines the build tools for project based on software packs. 10 | 11 | 12 | Linaro Project: [Open-CMSIS-Pack](https://linaro.atlassian.net/wiki/spaces/CMSIS/overview) 13 | 14 | ## Access to Specification 15 | 16 | The specification is pre-build and can be accessed here: [https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/index.html](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/index.html) 17 | 18 | ## License 19 | 20 | The Open-CMSIS-Pack project and its sub-components are licensed under Apache 2.0. 21 | 22 | ## Contributions and Pull Requests 23 | 24 | Contributions are accepted under Apache 2.0. Only submit contributions where you have authored all of the code. 25 | 26 | ### Proposals, Reviews and Project 27 | Please feel free to raise an [issue on GitHub](https://github.com/Open-CMSIS-Pack/Open-CMSIS-Pack/issues) 28 | to start the discussion about your proposal. 29 | 30 | We discuss proposals which we are dividing into 5 work streams with a dedicated label: 31 | 32 | - **Core Library Components** - common libraries that are re-used across a range of tools. The PoC Tools are the first consumers, but the library components can also be used to create commercial derivatives or inhouse tooling. 33 | - **Overall Project Concept** - procedures to generate packs and application software. We will consider complex applications such as multi-core processor systems or secure/non-secure partitions. 34 | - **PoC Tools** - command line tools and utilities that implement the overall concepts and are indented to be used for open-source projects or even integrated into commercial software tools. 35 | - **Process Improvements** - documentation and tools that help the software community to streamline and secure the software delivery to the user base. 36 | - **Resource Management** - describes the data models used to manage and organized software packs and application projects. 37 | 38 | These Issues are tracked inside the [project board](https://github.com/Open-CMSIS-Pack/Open-CMSIS-Pack/projects/1) 39 | 40 | ### Issues, Labels 41 | Please feel free to raise an [issue on GitHub](https://github.com/Open-CMSIS-Pack/Open-CMSIS-Pack/issues) 42 | to report misbehavior (i.e. bugs) 43 | 44 | Issues is your best way to interact directly with the maintenance team and the community. 45 | We encourage you to append implementation suggestions as this helps to decrease the 46 | workload of the very limited maintenance team. 47 | 48 | We will be monitoring and responding to issues as best we can. 49 | Please attempt to avoid filing duplicates of open or closed items when possible. 50 | In the spirit of openness we will be tagging issues with the following: 51 | 52 | - **bug** – We consider this issue to be a bug that will be investigated. 53 | 54 | - **wontfix** - We appreciate this issue but decided not to change the current behavior. 55 | 56 | - **out-of-scope** - We consider this issue loosely related to CMSIS. It might by implemented outside of CMSIS. Let us know about your work. 57 | 58 | - **question** – We have further questions to this issue. Please review and provide feedback. 59 | 60 | - **documentation** - This issue is a documentation flaw that will be improved in future. 61 | 62 | - **DONE** - We consider this issue as resolved - please review and close it. In case of no further activity this issues will be closed after a week. 63 | 64 | - **duplicate** - This issue is already addressed elsewhere, see comment with provided references. 65 | 66 | ### Pull Requests 67 | When raising a Pull Request (PR) changing the PACK.xsd schema file, please ensure that the version, date of change, release-notes and 68 | documentation get updated consistently throughout your PR. 69 | 70 | Rules: 71 | - Breaking/incompatible changes are not accepted and require further discussion 72 | 73 | Step 1: 74 | Edit the PACK.xsd file updating `=dd. mmm yyyy` and `=major.minor.patch` (Semantic Version) in: 75 | - `$Date: ` 76 | - `$Revision: ` 77 | - `SchemaVersion=` 78 | - Release Notes: `: v` and add itemized changes 79 | - `` 80 | 81 | Step 2: 82 | Edit the doxygen documentation located in "doxygen/src/*.txt" 83 | - add/update the documentation to reflect the proposed change following the existing document structure. 84 | - update the Release Notes section in "doxygen/src/General.txt" matching the itemized list in PACK.xsd. 85 | - update the version of the documentation `PROJECT_NUMBER= "Version "` in "doxygen/pack.dxy" to match the schema version. 86 | 87 | -------------------------------------------------------------------------------- /doc/Glossary.md: -------------------------------------------------------------------------------- 1 | # Recommended terminology 2 | 3 | ## General 4 | 5 | - **API** 6 | An application programming interface defines the interactions between multiple software 7 | intermediaries. They are what Open-CMSIS-Pack components publicly expose for the other components to use. 8 | - **API extension** 9 | A set of methods and types exposed by a Open-CMSIS-Pack Component expanding the capabilities of another 10 | Open-CMSIS-Pack component. 11 | - [**Baremetal application**](https://en.wikipedia.org/wiki/Bare_metal) 12 | **Bare metal** refers to a computer executing instructions directly on logic hardware without an 13 | intervening operating system. On Cortex-M target this is generally understood as an application 14 | running in a single thread without task-scheduling. A bare-metal application may still use interrupts. 15 | - **Bootstrap** 16 | Bootstrapping is a self-starting process that is supposed to proceed without external input. 17 | - **Application bootstrap** 18 | Covers the operation related to the application specific operations such as setup of the 19 | connectivity stacks as well as the various middleware constituting the application. 20 | - **Device bootstrap** 21 | Covers the operation related to the board/product startup. E.g. clock initialisation, external 22 | peripheral reset and initialisation. 23 | - **BSP** / **Board Support Package** 24 | A component providing board-specific support. 25 | This component typically provides through direct implementation or through dependencies, the device 26 | bootstrap and exposes the device specific features such as functions to get peripherals and/or bus 27 | instances, pin multiplexing etc. 28 | - **Components** 29 | The use of *component* on its own is deprecated because ambiguous. Please use one of those more 30 | specific forms instead: 31 | - **API component** 32 | A specialization of a software component that describes an interface. It must also document all 33 | expected behaviour of the API implementation as well as correct usage of the API. 34 | - **Implementation Component** 35 | A component that implements an interface. Such component may export an API extension.) 36 | - **Software component** 37 | A software component is a basic building block for the construction of applications. It is a set 38 | of files, include paths, configurations and dependencies. It can optionally implement one or 39 | more API. 40 | - **Connectivity** 41 | Any technology used to interact with entities beyond the device's boundary. 42 | For example, a UART interface may be considered connectivity when used as a Modbus server endpoint. 43 | - **Dependency** 44 | In context of software components is a relationship where one software component requires anything 45 | from the other software component or API component or configuration or tool chain or hardware. 46 | - **External peripheral** 47 | A piece of hardware external to the chip running the code. 48 | It may be controlled through a hardware-accelerated bus interface or a bit-banged bus interface. 49 | - **Host** / **Host platform** 50 | A machine running a desktop/server grade OS. 51 | - **Hardware (HW) Platform** 52 | A piece of hardware running an embedded application. This can be anything from development kits to 53 | standalone System on Chips or for example an IoT device. 54 | - **IoT OS** 55 | A set software stacks typically used by IoT devices and provided by an OS vendor (Mbed, Zephyr, 56 | AWS FreeRTOS, Azure RTOS, ...). An IoT OS is typically made of a kernel (the RTOS), a connectivity 57 | stack (IP, BLE etc), a storage stack (block devices, file systems etc) and other middleware. 58 | - **Internal** / **On-chip peripheral** 59 | A piece of hardware internal to the chip running the code. 60 | It is controlled through the chip memory space. 61 | - **Pack** / **Software Pack** 62 | A collection of files including a [Pack Description](#pack-desc) file forming 63 | one or more [Software Component](#component)(s) to be distributed, e.g. as an 64 | archive or through a [Software Repository](#software-repository). 65 | - **Pack Description** (PDSC) 66 | A machine readable file containing meta data for one or more [Software Component](#component)(s) 67 | maintained and shipped alongside. 68 | - **Pack Index** 69 | A machine readable index file of available [Pack](#software-pack)s and their according 70 | origin. The origin can be the location a [Pack](#software-pack) archive can be fetched from 71 | or a [Software Repository](#software-repository) to refer to. 72 | - **(Local) Packs Folder** 73 | A location within an [Application Developer](https://github.com/ARMmbed/Open-CMSIS-Pack-architecture/wiki/Requirements#application-developer)'s 74 | development environment where [Pack](#software-pack)s are stored to (unarchived). 75 | - **Peripheral driver** / **Hardware Abstraction Layer (HAL)** 76 | A piece of software interacting with some piece of hardware either as an *internal peripheral* through the memory bus or as an *external peripheral* through an ADC input, a SPI bus, or an I²C bus. 77 | In the context of Open-CMSIS-Pack, Peripheral driver and HAL driver are synonyms. 78 | Examples include: 79 | - The software driving a CRC hardware acceleration 80 | - The software driving a sensor, for example an accelerometer 81 | - The software driving a stepper motor controller 82 | - **Real-Time Operating System (RTOS)** 83 | Part of the OS that implements threading, real-time scheduling and related operations. 84 | Some well known RTOS for microcontrollers include FreeRTOS (used in AWS-FreeRTOS), RTX (used in Mbed-OS), and ThreadX (used in Azure RTOS). 85 | - **Software Repository** 86 | Arbitrary directory structure containing files typically version controlled 87 | by a [VCS](https://en.wikipedia.org/wiki/Version_control). 88 | 89 | ## Testing 90 | 91 | There are two major ways of categorising tests : 92 | 93 | - By scope: 94 | - **Unit tests** 95 | Covers a specific piece of software isolating it from its environment for example by mocking its dependencies. 96 | In the case of Internal peripheral drivers that means mocking/simulating the hardware's behaviour and/or memory map. 97 | - **Integration tests** 98 | Verifies that multiple components can work together in the expected way. 99 | - [**System tests**](https://en.wikipedia.org/wiki/System_testing) 100 | Verifies that the components work together as expected and that the whole system also behaves as defined. 101 | - By test objectives: 102 | - [**Functional tests**](https://en.wikipedia.org/wiki/Functional_testing) 103 | - [**API tests**](https://en.wikipedia.org/wiki/API_testing) 104 | - [**Stress tests**](https://en.wikipedia.org/wiki/Stress_testing) 105 | - **Memory tests** 106 | Checks the absence of leaks and buffer overflow. 107 | 108 | The following terms are generally accepted and listed here as reminders : 109 | 110 | - [**Acceptance test**](https://en.wikipedia.org/wiki/Acceptance_testing) 111 | Tests against design document(s) or specification(s). 112 | - **Regression test** 113 | Tests that are repeatable and used to catch regressions as the code base evolves. 114 | - **Test framework** 115 | Library used to help implement a test, e.g. CppUTest 116 | - **Test harness** 117 | Combination of the Test framework and test data that allow automation of the tests. 118 | - **Test infrastructure** 119 | Describes the environment where the tests are run. This includes CI and the required HW and SW tools down to the HW Platform boundaries. 120 | - **Test tool** 121 | Includes the software tools as well as the physical tools such as the FPGA test shield. 122 | 123 | ## Deprecated terminology 124 | 125 | Those terms are not forbidden but frowned upon because of their history, ambiguity and more generally their lack of clarity. 126 | 127 | - **Target** 128 | Has proven ambiguous and highly dependant on the context. 129 | It may identify a board, a module, a specific chip, a family of device, a core or even a platform or an OS. 130 | *Recommended alternative*: Use specific wording. 131 | - **Component** 132 | Similarly to *target* component may indistinctly refer to hardware or software elements. 133 | *Recommended alternative*: Use specific wording. See [Component](#component). 134 | 135 | ## System description terminology 136 | 137 | This section describes concepts required for describing system on chip (SoC) products, leveraging TrustZone-enabled cores and multi-cores. 138 | These concepts can also be used more widely to describe multi-SoC systems. 139 | 140 | - **Binary program** 141 | A binary program can be: 142 | - A bare-metal binary, 143 | - A monolithic OS binary and all the services running on top of it, 144 | - An OS that can install modules. Each module can be a binary on its own but still from an execution perspective as the OS is required for this service to run we consider it as a single binary in term of execution context. 145 | - A virtual machine or interpreter 146 | - **Execution Context** 147 | An execution context identifies the “cradle” allowing to run a binary program on a given hardware platform. 148 | - A context of execution has a 1-to-1 association to a hardware execution unit. 149 | - If we support virtual machines or interpreters, then the virtual machine is associated with one execution context. The programs interpreted by the virtual machine (VM) are stored as data sections in memory, and considered as execution modules within the VM's execution context. 150 | - **Execution Domain** 151 | An execution domain is a container aggregating all the platform resources (internal and external memories, peripherals) that an execution context can use “exclusively”. For shared resources (available for several execution contexts), we introduce the concept of shared execution domain. 152 | - **Execution Module** 153 | An execution module is an entity that has no standalone execution possibility. It relies on a “backbone" binary providing system services. So, an execution module is always associated with an execution context. 154 | - **Hardware Execution Unit** 155 | A hardware execution unit is either a cluster (i.e. group of cores), or a core, or a TrustZone world within a core (virtualization). This is the hardware entity (virtual or physical) running a binary program. 156 | - **System On Chip** 157 | A SoC (system on chip) can be a microcontroller (MCU) or a microprocessor (MP). 158 | - A SoC can have one or several processors. 159 | - A processor can have one or several cores (core = CPU+FPU+…). For example, a Cortex-A7 cluster can have two Cortex-A7 cores. -------------------------------------------------------------------------------- /doc/adr/0001-record-architecture-decisions.md: -------------------------------------------------------------------------------- 1 | # ADR 1: Record architecture decisions 2 | 3 | Date: 2020-05-19 4 | 5 | ## Status 6 | 7 | Accepted 8 | 9 | ## Context 10 | 11 | We need to record the architectural decisions made on this project. 12 | 13 | ## Decision 14 | 15 | We will use Architecture Decision Records, as [described by Michael 16 | Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). 17 | 18 | ## Consequences 19 | 20 | See Michael Nygard's article, linked above. For a lightweight ADR toolset, see 21 | Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools). 22 | -------------------------------------------------------------------------------- /doc/adr/0002-use-cmsis-pack-for-component-distribution.md: -------------------------------------------------------------------------------- 1 | # ADR 2: Use CMSIS-Pack for component distribution 2 | 3 | Date: 2020-12-08 4 | 5 | ## Status 6 | 7 | Accepted 8 | 9 | ## Context 10 | 11 | We need to be able to pack and distribute software components under their 12 | sources and pre-compiled binary. The technology selected must also manage 13 | dependencies between components and ideally offer some support for configuring an 14 | individual component. 15 | 16 | The component descriptor must be human readable (text-based) but may benefit 17 | from tools to generate/update it. 18 | 19 | How popular a solution is, in terms of available package and community 20 | engagement is also a critical aspect as it directly impacts the efforts we will 21 | need to put in to achieve a viable adoption level. 22 | 23 | The solution chosen must be developed in an open source and open governance 24 | model. 25 | 26 | We do not mandate a pack registry. If one comes with the pack architecture it 27 | must allow for additional registry to fetch from. 28 | 29 | It is intentionally left to the downstream _distribution_ maintainers 30 | (Zephyr/Mbed) to manage compatibility of the components. 31 | 32 | We evaluated some of the major solution currently available on the market: 33 | 34 | - [Conan.io](conan.io) 35 | 36 | Using it for cortex-m class target is a stretch[1](#fn1) 37 | of the tool. The integration with the build system(s) requires changes in 38 | to the tool itself[2](#fn2) (which is not desired) provided that 39 | we do not have control over the technology. 40 | 41 | - [CMSIS-Pack](https://arm-software.github.io/CMSIS_5/Pack/html/index.html) 42 | 43 | Mostly used within Keil uVision, this solution is already used by silicon partners 44 | to distribute some parts of their SDK. Although it is based on XML and 45 | requires tools to efficiently maintain it, it does provide all the necessary 46 | features. The CMSIS-Pack index counts 640 unique packages. Excluding device 47 | specific packages[4](#fn4) leaves around 70 packages, 48 | around 10 of which are `nRF_`packages and 37 are published either on 49 | http://www.keil.com/pack/ or https://github.com/MDK-Packs/Pack. 50 | 51 | - [Yotta](https://yottabuild.org/) 52 | 53 | Yotta is a serious contender to CMSIS-Pack in terms of offered featured and 54 | available components. The dependency architecture and strategy is already 55 | well defined. Based on JSON it is easy to create, and maintain. CLI tools 56 | already exist, rendering the user experience rather fluid. A previous attempt 57 | at using Yotta in Mbed OS faced strong rejection mostly due to regular 58 | breakage in the ecosystem. It seems that those issues were not much due to 59 | problem in the tool itself but rather to bad practice around the 60 | [semver](semver.org) rules. Yotta is not actively maintained. Yotta counts 61 | __314__ unique packages (excluding the test packages `test1`, `test2`, …). 62 | Excluding the device specific packages leaves around 200 middleware and 63 | external peripheral drivers[3](#fn3). 64 | 65 | - [lbuild](https://github.com/modm-io/lbuild) 66 | 67 | Even though it presents some really interesting features around code 68 | generation and code configuration it does not have enough effective adoption 69 | to become a serious contender since it would mean starting the adoption 70 | process from scratch. 71 | 72 | _Note:_ The number of packages is highly influenced by how the packages are 73 | bundled (by family/subfamily or package hierarchy). Thus the number of devices 74 | supported is hard to evaluate and compare but can generally be considered 75 | _large enough_ (yotta benefiting from mbed's large portability). 76 | 77 | ## Decision 78 | 79 | Considering the relative maturity, adoption, and the ability to contribute to 80 | these projects under an open source and open governance model, we've decided to 81 | use CMSIS-Pack as the starting point for Component specification. 82 | 83 | The process of evolving CMSIS-Pack is strictly guided by approved User Stories​. 84 | Breaking backward compatibility is acceptable given a viable migration story is 85 | provided. 86 | 87 | ## Consequences 88 | 89 | As raised by partners during a previous meeting, 90 | there's room for improvement on CMSIS-Packs but nothing that cannot be 91 | addressed on upcoming iterations. The group acknowledges the risk that evolving 92 | CMSIS-Pack might be slower to address requirements that substantially deviate 93 | from today's concepts than starting from scratch​. 94 | 95 | Partners and Arm parties specifically raised the following topics: 96 | - A system integrator may need a fix in a component and cannot wait for it to 97 | be upstreamed before shipping. A _pack customisation_ model must be defined. 98 | - Authentication of component will become a serious concern as the ecosystem 99 | develops. We will need to define a strategy to address that. 100 | 101 | Tools will need to be developed to ease the use of this technology. These 102 | will most probably need to evolve along with the specification in order to 103 | address feedback from the partners. 104 | 105 | Ideally the technology (specification and tools) should go under an 106 | open-governance in order to ease contribution and accelerate its adoption. 107 | 108 | ## Footnotes 109 | 110 | 1: https://github.com/conan-io/conan/issues/86#issuecomment-359483915 [↩︎](#a1) 111 | 2: https://github.com/conan-io/conan/pull/1494 [↩︎](#a2) 112 | 3: Extracted from mongodb's documents with `db.modules.find({}, {"json.name": 1, _id: 0}).map((entry) => { return entry.json.name }).sort().filter((el,i,a) => {return i===a.indexOf(el) && !el.startsWith("test")})` 113 | and extra manual filtering to remove device specific packages. [↩︎](#a3) 114 | 4: Extracted from https://sadevicepacksprodus.blob.core.windows.net/idxfile/index.pidx. 115 | Excluding device specific packages by filtering out name ending with **BSP** and **DFP** plus some 116 | extra filtering to remove device from vendors such as HDSC or maxim that are not ending with those 117 | tags. [↩︎](#a4) 118 | -------------------------------------------------------------------------------- /doc/adr/0003-component-source-structure-recommendations.md: -------------------------------------------------------------------------------- 1 | # ADR 3: Component source structure recommendations 2 | 3 | Date: 2020-08-07 4 | 5 | ## Status 6 | 7 | Proposed 8 | 9 | ## Context 10 | 11 | Open-CMSIS-Pack encourages componentization of software with meaningful APIs. The 12 | componentization enables parallel development, maintenance and distribution of 13 | software components. These components can come from multiple vendors, 14 | therefore it is very useful to unify the structure of component source trees. 15 | In addition, unified source structure helps with, 16 | 17 | * Better maintenance of components 18 | * Easy navigation through source 19 | 20 | ## Decision 21 | 22 | The following directory structure is recommended for new Open-CMSIS-Pack components: 23 | 24 | ```console 25 | 26 | ├── CONTRIBUTING.md 27 | ├── LICENSE.md 28 | ├── README.md 29 | ├── docs 30 | ├── examples 31 | │   └── 32 | │   └── .cpp 33 | ├── include 34 | │   └── 35 | │   └── .h 36 | ├── src 37 | │   └── .cpp 38 | ├── templates 39 | │   └── _template.cpp 40 | └── tests 41 | └── _test.cpp 42 | ``` 43 | 44 | ### Top level directory 45 | 46 | Named after the component. It is recommended to use `_` (underscore) 47 | as word separator instead of space(e.g., `mbed_events`). 48 | 49 | ### Contribution 50 | 51 | Contribution guidelines may be added to `CONTRIBUTING.md`. It may also 52 | specify the *license* under which contribution will be accepted. 53 | 54 | ### License 55 | 56 | Every component should contain license details. We recommend the following: 57 | 58 | * Single license 59 | 60 | The license text should be added to `LICENSE.md`. For example, to release a 61 | component under Apache 2.0, the full original 62 | [Apache 2.0 license text](http://www.apache.org/licenses/LICENSE-2.0) should 63 | be in `LICENSE.md`. 64 | 65 | * Multiple licenses 66 | 67 | A `LICENSE.md` file with the following text: 68 | ``` 69 | Unless specifically indicated otherwise in a file, files are licensed under 70 | the Apache 2.0 license, as can be found in: LICENSE-apache-2.0.txt 71 | ``` 72 | The full original 73 | [Apache 2.0 license text](http://www.apache.org/licenses/LICENSE-2.0) in 74 | LICENSE-apache-2.0.txt. 75 | 76 | Each source header should start with copyright line, the SPDX identifier 77 | and the license header: 78 | ``` 79 | Copyright (c) [First year]-[Last year], **Your Name or Company Here** 80 | SPDX-License-Identifier: 81 | 82 | ``` 83 | 84 | In order to release the component under different license, update `LICENSE.md` 85 | with desired license details and add full license text to 86 | `LICENSE-.txt` 87 | 88 | * Component with only binary 89 | 90 | A `LICENSE.md` file with the following text: 91 | ``` 92 | Unless specifically indicated otherwise in a file, files are licensed under the Permissive Binary License, as can be found in LICENSE-permissive-binary-license-1.0.txt 93 | ``` 94 | The full original 95 | [Permissive Binary License 1.0 text](https://os.mbed.com/licenses/permissive-binary-license/) 96 | in LICENSE-permissive-binary-license-1.0.txt. 97 | 98 | ### Documentation 99 | 100 | The `README.md` may contain brief introduction to the component and detailed 101 | documentation may be added under `docs` directory. Also, for components hosted 102 | on GitHub, this allows easily sharing the docs via GitHub pages, as GitHub 103 | pages can share either the root of a repo or its `docs` directory. 104 | 105 | ### Examples 106 | 107 | The `examples` directory may contain examples which demonstrate the use of the 108 | component. Each directory under `examples` should only contain one example. It is 109 | strongly recommended that examples are kept up-to-date and maintained such 110 | that they can be compiled and tested. 111 | 112 | ```console 113 | ├── examples 114 | │   └── example1 115 | │   └── example2 116 | ``` 117 | 118 | ### Headers 119 | 120 | All header files, including API header, should be added to `include/` 121 | (e.g., `include/mbed_events/mbed_events.h`). This convention 122 | forces API consumers to add component name while including API headers which 123 | avoids header inclusion collisions (e.g., `#include "mbed_events/mbed_events.h"`). 124 | 125 | ### Sources 126 | 127 | All source files should be added to the `src` directory. 128 | 129 | ### Templates 130 | 131 | Templates are application outlines which can act as a starting point for 132 | application developers. The only difference between `examples` and 133 | `templates` is that `examples` are complete and work out-of-the-box, 134 | whereas `templates` may not. If a component is providing a template then it 135 | should be added to the `templates` directory. 136 | 137 | ### Tests 138 | 139 | It's strongly recommended that every component contains at least unit test 140 | cases added in the `tests` directory. 141 | 142 | ## Consequences 143 | 144 | The component directory structure is recommended rather than enforced/mandated. 145 | Therefore it might be possible that existing components might not be migrated 146 | to the recommended directory structure. Due to the same reason, new components might 147 | not use the recommended directory structure. 148 | -------------------------------------------------------------------------------- /doc/adr/0004-default-open-source-license.md: -------------------------------------------------------------------------------- 1 | # ADR 4: Default Licenses for Open-CMSIS-Pack content 2 | 3 | Date: 2020-11-24 4 | 5 | ## Status 6 | 7 | Accepted 8 | 9 | ## Context 10 | 11 | Open-CMSIS-Pack content (such as specs, code, etc) needs to be licensed properly so 12 | that it can be widely adopted. The default license shall be permissive to 13 | allow adoption for proprietary and commercial use, free from copy-left 14 | obligations. 15 | 16 | A couple of well known Open Source Licenses have been taken into account: 17 | 18 | - [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause) 19 | - [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 20 | - [MIT License](https://opensource.org/licenses/MIT) 21 | - [Creative Commons CC-BY-SA 4.0][https://creativecommons.org/licenses/by-sa/4.0/legalcode] 22 | 23 | ## Decision 24 | 25 | By default all publicly published Open-CMSIS-Pack software is to be licensed under 26 | the Apache v2.0 license. However, Open-CMSIS-Pack may reuse software already licensed 27 | under another license, provided the license is permissive in nature and 28 | compatible with Apache v2.0. Documentation shipped alongside the code shall be 29 | licensed under the same license as the code. 30 | 31 | Specifications are to be licensed under the Creative Commons CC-BY-SA 4.0 32 | license (Creative Commons Attribution-ShareAlike 4.0 International Public 33 | License). 34 | 35 | All contributions to software and documents are licensed by contributors under 36 | the same license model as the software/document itself (ie. inbound == outbound 37 | licensing). 38 | 39 | ## Consequences 40 | 41 | The Apache License 2.0 grants permissive use to everybody, including 42 | adoption for proprietary and commercial use. It does not contain any 43 | copy-left obligations. 44 | 45 | The Creative Commons CC-BY-SA 4.0 permissive use to everybody, including 46 | adoption for proprietary and commercial use. It does not contain any 47 | copy-left obligations. 48 | -------------------------------------------------------------------------------- /doc/adr/0005-cmsis-pack-extension-component-changelogs.md: -------------------------------------------------------------------------------- 1 | # 5. Extend Open-CMSIS-Pack for per component changelogs 2 | 3 | Date: 2021-05-11 4 | 5 | ## Status 6 | 7 | Accepted 8 | 9 | ## Context 10 | 11 | Open-CMSIS-Pack specification supports recording changelogs as part of the releases section. Hence one cannot easily 12 | deduce which changes apply to which component(s). 13 | 14 | ## Decision 15 | 16 | Follow the approach already used for `` in the current [Pack Description](../Glossary.md#pack-desc) 17 | using references: 18 | * add optional section `` on the top level of the format 19 | * add one or more child elements `` to `` with attributes: 20 | * `id` (required) - a unique name which is used by components to associate itself with a `changelog` 21 | * `name` (required) - the relative path to the changelog file 22 | * `type` (optional) - mime-type of the changelog file, defaults to `text/plain;charset=UTF-8` 23 | * `default` (optional) - the default changelog is automatically associated with all components/apis, default to false 24 | * add optional attribute `changelog` to `` element. 25 | * add optional attribute `changelog` to `` element. 26 | * add optional attribute `changelog` to `` element. 27 | 28 | ## Consequences 29 | 30 | * Complexity of package description increases 31 | * the default mechanism allows to specify a single `changelog` for all components of a pack conveniently. 32 | * Validation tool is required to test: 33 | * for each `` that name is specified, unique (within pdsc) and file exists 34 | * a maximum of one `changelog` has attribute `default="true"` set 35 | * for each `` that attribute `changelog` unique ID exists (within pdsc) 36 | * for each `` that attribute `changelog` unique ID exists (within pdsc) 37 | * for each `` that attribute `changelog` unique ID exists (within pdsc) 38 | * Pack Manager requires extension 39 | * display changelog information per component 40 | -------------------------------------------------------------------------------- /doc/index.html: -------------------------------------------------------------------------------- 1 |  2 | 3 | 4 | Redirect to the Manual after 0 seconds 5 | 6 | 7 | 8 | 9 | 10 | 11 | If the automatic redirection is failing, click open manual. 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /doxygen/check_links.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | linkchecker -F csv --timeout 10 --check-extern $1 4 | 5 | OFS=$IFS 6 | IFS=$'\n' 7 | 8 | echo "# converted output from linkchecker" > linkchecker-in.csv 9 | echo "link;file;msg;src" >> linkchecker-in.csv 10 | for line in $(grep -E '^[^#]' linkchecker-out.csv | tail -n +2); do 11 | link=$(echo $line | cut -d';' -f 1) 12 | file=$(echo $line | cut -d';' -f 2) 13 | msg=$(echo $line | cut -d';' -f 4) 14 | src=$(echo $file | sed -E 's/file:\/\/(.*)\/doc\/.*/\1\/doxygen\/src/') 15 | echo "${link};${file};${msg};${src}" >> linkchecker-in.csv 16 | if [ -d $src ]; then 17 | origin=$(grep -Ern "href=['\"]${link}['\"]" $src) 18 | for o in $origin; do 19 | ofile=$(echo $o | cut -d':' -f 1) 20 | oline=$(echo $o | cut -d':' -f 2) 21 | echo "${ofile}:${oline};${link};${msg}" >&2 22 | done 23 | fi 24 | done 25 | 26 | IFS=$OFS 27 | 28 | exit 0 29 | -------------------------------------------------------------------------------- /doxygen/examples/Pack_with_Board_Support.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/examples/Pack_with_Board_Support.zip -------------------------------------------------------------------------------- /doxygen/examples/Pack_with_Device_Support.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/examples/Pack_with_Device_Support.zip -------------------------------------------------------------------------------- /doxygen/examples/Pack_with_Software_Components.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/examples/Pack_with_Software_Components.zip -------------------------------------------------------------------------------- /doxygen/gen_doc.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Version: 1.0.1 3 | # Date: 2021-10-27 4 | # This bash script generates Open-CMSIS-Pack Documentation: 5 | # 6 | # Pre-requisites: 7 | # - bash shell (for Windows: install git for Windows) 8 | # - doxygen 1.9.6 9 | 10 | set -o pipefail 11 | 12 | DIRNAME=$(dirname $(realpath $0)) 13 | if [[ -z "${DOXYGEN}" ]]; then 14 | DOXYGEN=$(which doxygen) 15 | fi 16 | 17 | if [[ ! -f "${DOXYGEN}" ]]; then 18 | echo "Doxygen not found!" >&2 19 | echo "Did you miss to add it to PATH?" 20 | exit 1 21 | else 22 | version=$("${DOXYGEN}" --version | sed -r -e 's/.*([1-9][0-9]*\.[0-9]+\.[0-9]+).*/\1/') 23 | echo "DOXYGEN is ${DOXYGEN} at version ${version}" 24 | if [[ "${version}" != "1.9.6" ]]; then 25 | echo " >> Version is different from 1.9.6 !" >&2 26 | fi 27 | fi 28 | 29 | function doxygen { 30 | pushd "$(dirname $1)" > /dev/null 31 | echo "${DOXYGEN} $1" 32 | "${DOXYGEN}" $(basename "$1") 33 | popd > /dev/null 34 | 35 | if [[ $2 != 0 ]]; then 36 | cp -f "${DIRNAME}/templates/search.css" "${DIRNAME}/../doc/html/search/" 37 | fi 38 | 39 | projectName=$(grep -E "PROJECT_NAME\s+=" $1 | sed -r -e 's/[^"]*"([^"]+)"/\1/') 40 | projectNumber=$(grep -E "PROJECT_NUMBER\s+=" $1 | sed -r -e 's/[^"]*"([^"]+)"/\1/') 41 | datetime=$(date -u +'%a %b %e %Y %H:%M:%S') 42 | sed -e "s/{datetime}/${datetime}/" "${DIRNAME}/templates/cmsis_footer.js" \ 43 | | sed -e "s/{projectName}/${projectName}/" \ 44 | | sed -e "s/{projectNumber}/${projectNumber}/" \ 45 | > "${DIRNAME}/../doc/${partname}/html/cmsis_footer.js" 46 | } 47 | 48 | echo "Cleaning existing documentation ..." 49 | find "${DIRNAME}/../doc/" -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} + 50 | 51 | echo "Generating documentation ..." 52 | doxygen "${DIRNAME}/pack.dxy" 1 53 | 54 | exit 0 55 | -------------------------------------------------------------------------------- /doxygen/images/BSPBundleDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/BSPBundleDisplay.png -------------------------------------------------------------------------------- /doxygen/images/BasicDFPDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/BasicDFPDisplay.png -------------------------------------------------------------------------------- /doxygen/images/BoardsSectionMusca-S1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/BoardsSectionMusca-S1.png -------------------------------------------------------------------------------- /doxygen/images/CMSISDriverVIO.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/CMSISDriverVIO.png -------------------------------------------------------------------------------- /doxygen/images/CodeVerify.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/CodeVerify.png -------------------------------------------------------------------------------- /doxygen/images/CodeVerify.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/CodeVerify.vsd -------------------------------------------------------------------------------- /doxygen/images/ComponentDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/ComponentDisplay.png -------------------------------------------------------------------------------- /doxygen/images/ComponentSelection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/ComponentSelection.png -------------------------------------------------------------------------------- /doxygen/images/Component_Instances.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/Component_Instances.png -------------------------------------------------------------------------------- /doxygen/images/ConditionsDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/ConditionsDisplay.png -------------------------------------------------------------------------------- /doxygen/images/DFPFlow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/DFPFlow.png -------------------------------------------------------------------------------- /doxygen/images/DebugConnect.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/DebugConnect.png -------------------------------------------------------------------------------- /doxygen/images/DebugConnect.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/DebugConnect.vsd -------------------------------------------------------------------------------- /doxygen/images/DebugDisconnect.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/DebugDisconnect.png -------------------------------------------------------------------------------- /doxygen/images/DebugDisconnect.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/DebugDisconnect.vsd -------------------------------------------------------------------------------- /doxygen/images/DevBoardDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/DevBoardDisplay.png -------------------------------------------------------------------------------- /doxygen/images/DeviceDatabase2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/DeviceDatabase2.png -------------------------------------------------------------------------------- /doxygen/images/ExampleDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/ExampleDisplay.png -------------------------------------------------------------------------------- /doxygen/images/ExampleDisplayBSP.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/ExampleDisplayBSP.png -------------------------------------------------------------------------------- /doxygen/images/FPADisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/FPADisplay.png -------------------------------------------------------------------------------- /doxygen/images/FPATargetOptions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/FPATargetOptions.png -------------------------------------------------------------------------------- /doxygen/images/FlashDownload.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/FlashDownload.vsd -------------------------------------------------------------------------------- /doxygen/images/FlashErase.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/FlashErase.png -------------------------------------------------------------------------------- /doxygen/images/FlashProgram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/FlashProgram.png -------------------------------------------------------------------------------- /doxygen/images/FlashVerify.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/FlashVerify.png -------------------------------------------------------------------------------- /doxygen/images/GHhosting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/GHhosting.png -------------------------------------------------------------------------------- /doxygen/images/IndexingService.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/IndexingService.png -------------------------------------------------------------------------------- /doxygen/images/MVCM3SpecTable.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/MVCM3SpecTable.png -------------------------------------------------------------------------------- /doxygen/images/PDSC_Example_bottom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/PDSC_Example_bottom.png -------------------------------------------------------------------------------- /doxygen/images/PDSC_Example_top.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/PDSC_Example_top.png -------------------------------------------------------------------------------- /doxygen/images/PackCreateSteps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/PackCreateSteps.png -------------------------------------------------------------------------------- /doxygen/images/RTX_Conf_CM_Wizard_View.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/RTX_Conf_CM_Wizard_View.png -------------------------------------------------------------------------------- /doxygen/images/Reset.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/Reset.png -------------------------------------------------------------------------------- /doxygen/images/Reset.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/Reset.vsd -------------------------------------------------------------------------------- /doxygen/images/SPVariants_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/SPVariants_small.png -------------------------------------------------------------------------------- /doxygen/images/SVDFlow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/SVDFlow.png -------------------------------------------------------------------------------- /doxygen/images/SVDIncluded.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/SVDIncluded.png -------------------------------------------------------------------------------- /doxygen/images/SoftwarePacks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/SoftwarePacks.png -------------------------------------------------------------------------------- /doxygen/images/StartupSystemFilesAdded.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/StartupSystemFilesAdded.png -------------------------------------------------------------------------------- /doxygen/images/SystemStartupFiles.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/SystemStartupFiles.png -------------------------------------------------------------------------------- /doxygen/images/UserCodeTemplatesDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/UserCodeTemplatesDisplay.png -------------------------------------------------------------------------------- /doxygen/images/VariantDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/VariantDisplay.png -------------------------------------------------------------------------------- /doxygen/images/api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/api.png -------------------------------------------------------------------------------- /doxygen/images/component_files.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/component_files.png -------------------------------------------------------------------------------- /doxygen/images/conditions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/conditions.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_connect_options.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_connect_options.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_connect_options_old.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_connect_options_old.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_dbgconf.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_dbgconf.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_dbgconf_wizard.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_dbgconf_wizard.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_debug_access_log.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_debug_access_log.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_debugconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_debugconfig.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_jtag_chain.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_jtag_chain.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_reset_configs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_reset_configs.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_reset_options.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_reset_options.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_sequences.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_sequences.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_sqns_enable.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_sqns_enable.png -------------------------------------------------------------------------------- /doxygen/images/dbg_uVision_sqns_log.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbg_uVision_sqns_log.png -------------------------------------------------------------------------------- /doxygen/images/dbgconf_confWizard.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/dbgconf_confWizard.png -------------------------------------------------------------------------------- /doxygen/images/drawings.pptx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/drawings.pptx -------------------------------------------------------------------------------- /doxygen/images/external_mac_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/external_mac_example.png -------------------------------------------------------------------------------- /doxygen/images/internal_mac_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/internal_mac_example.png -------------------------------------------------------------------------------- /doxygen/images/maxInstancesDisplay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/maxInstancesDisplay.png -------------------------------------------------------------------------------- /doxygen/images/pack_structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/pack_structure.png -------------------------------------------------------------------------------- /doxygen/images/pack_structure_new.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/pack_structure_new.png -------------------------------------------------------------------------------- /doxygen/images/pack_trinity.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/pack_trinity.png -------------------------------------------------------------------------------- /doxygen/images/requirements.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/requirements.png -------------------------------------------------------------------------------- /doxygen/images/schema_check.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/schema_check.png -------------------------------------------------------------------------------- /doxygen/images/schema_check_output.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/schema_check_output.png -------------------------------------------------------------------------------- /doxygen/images/sequence_flows.vsd: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/sequence_flows.vsd -------------------------------------------------------------------------------- /doxygen/images/simplepack_rte.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/simplepack_rte.png -------------------------------------------------------------------------------- /doxygen/images/software_component.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/software_component.png -------------------------------------------------------------------------------- /doxygen/images/uVision_AP_locked.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/images/uVision_AP_locked.png -------------------------------------------------------------------------------- /doxygen/src/apis_schema.txt: -------------------------------------------------------------------------------- 1 | /** 2 | \page pdsc_apis_pg /package/apis element 3 | 4 | Application Programming Interfaces (apis) are C/C++ interface specifications that allow software to be divided into largely independent modules. 5 | Such modules can then be developed, tested, and maintained independently, and reused by different projects. One example is the use of device drivers. 6 | If device drivers are developed for different devices implementing the same API, the application software itself can be written independent from the 7 | device it is build for. 8 | 9 | The apis allow to distribute the Application Programming Interface Specifications decoupled from actual implementation. One example is the CMSIS-RTOS API, 10 | which is specified as part of CMSIS, however, the actual RTOS implementation is provided by different vendors. 11 | 12 | An API consists of a name, a brief description as well as one or more header files, and a document containing a detailed specification of the API. 13 | 14 | The API typically defines one or more header files and optionally an include directory. It should have also related documentation that describes the API. 15 | 16 | \b Example: 17 | 18 | \code 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | \endcode 27 | 28 | The API can be used either in the same software pack or other software packs. Having the API definition in one central software pack provides the 29 | benefit that implementations are consistent. 30 | 31 | The include file and directory are included in the application project when a \b component is selected that specifics the same \b Cclass and \b Cgroup. 32 | The selection of a software component adds therefore both to a project: the files specified by the \ref element_component "component element" and the files specified by the \ref element_api "api element". 33 | Therefore, the component that is based on the API should not contain the header file that defines the API. 34 | 35 | \b Example: this component adds also the api header file above 36 | 37 | \code 38 | 39 | Software simulation of random number generator 40 | 41 | 42 | 43 | 44 | \endcode 45 | Optionally, it is possible to request a minimum API version using the \b Capiversion attribute. 46 | 47 | It is also possible to expose a combination of API definitions. An example for that is the CMSIS-Driver for Ethernet that is defined as: 48 | - Ethernet MAC interface 49 | - Ethernet PHY interface 50 | - Ethernet interface that defines both MAC and PHY (this defines two API header files) 51 | 52 |

 

53 |
54 | 55 | \section element_apis /package/apis 56 | 57 | This element is a grouping element for all application programming interfaces included in the software pack. 58 | The element itself is optional. Only one such section can exist in a package. 59 | 60 | \b Example: 61 | \code 62 | 63 | 64 | ... 65 | 66 | 67 | \endcode 68 | 69 |

 

70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 |
Parents Element Chain  
\ref pdsc_package_pg "package"\ref pdsc_package_pg "/package"  
Child ElementsDescriptionTypeOccurrence
\ref element_api "api"Named specification of an API containing a brief description, C/C++ header files and documentationApiType1..*
97 | 98 |

 

99 |
100 | 101 | \section element_api /package/apis/api 102 | 103 | Application Programming Interfaces (apis) are C/C++ interface specifications that allow components to inter-work 104 | by either implementing or using a set of functions, data types, and definitions. This element is mandatory and can exist multiple times. 105 | 106 | \b Example: 107 | \code 108 | 109 | 110 | UART Driver API for the Cortex-M processor based devices 111 | 112 | 113 | 114 | 115 | 116 | 117 | SPI Driver API for the Cortex-M processor based devices 118 | 119 | 120 | 121 | 122 | 123 | ... 124 | 125 | \endcode 126 | 127 |

 

128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 148 | 149 | 150 | 151 | 152 | 153 | 155 | 156 | 157 | 158 | 159 | 160 | 162 | 163 | 164 | 165 | 166 | 167 | 170 | 171 | 172 | 173 | 174 | 175 | 177 | 178 | 179 | 180 | 181 | 182 | 184 | 185 | 186 | 187 | 188 | 189 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | . 212 | 213 | 214 | 215 |
Parent ElementElement Chain
\ref element_apis "apis"\ref element_apis "/package/apis"
AttributesDescriptionTypeUse
CclassDefines the component class to which this component belongs. This is a mandatory part of the component ID. 147 | Predefined values can be used as listed in the table \ref CclassType "Component Classes".CclassTyperequired
CgroupDefines the component group to which this component belongs. This is a mandatory part of the component ID. 154 | Predefined values can be used as listed in the table \ref CgroupType "Component Groups".CgroupTyperequired
exclusiveMakes the selection of a component implementing the API exclusive. If set to \token{0}, then multiple components 161 | implementing the API can be selected concurrrently. Default is \token{1}.xs:booleanoptional
conditionEnter the identifier (attribute \em id) of a \ref element_condition "condition". The element is used if the condition resolves to \token{true}. 168 | If the condition resolves to \token{false}, then the element will be ignored. 169 | For example, an API might be specific for a certain toolchain or processor instruction set.xs:stringoptional
CapiversionVersion of the api. Is a mandatory part of the api ID. The version format is described in \ref VersionType "Version Type". 176 | VersionTypeoptional
licenseSetReference to the licenseSet with the given identifier \token{ID} listed in the licenseSets section of the package description. 183 | A licenseSet describes one or more license files which in this case govern the api.xs:stringoptional
changelog 190 | Reference to the \token{changelog} with the given identifier \token{ID} specified in the changelogs section of the package description. 191 | A changelog references a text file in the pack with a path relative to the pdsc containing changelog information for the api. 192 | The content of the referenced changelog file is not required to be exclusively used for a single api.xs:stringoptional
Child ElementsDescriptionTypeOccurrence
descriptionBrief summary about the purpose and scope of an API (maximum 256 characters, recommended 128 characters).BriefDescType0..1
\ref element_files "files"Grouping element for all file descriptions that are part of this component.group0..1
216 | 217 |

 

218 | */ 219 | -------------------------------------------------------------------------------- /doxygen/src/changelogs_schema.txt: -------------------------------------------------------------------------------- 1 | /**************************************************************************************************/ 2 | /** 3 | \page pdsc_changelogs_pg /package/changelogs element 4 | The concept of changelogs gets introduced to support the association of components and apis with changelog files shipped as part of the pack. 5 | This provides space for more detailed listing of changes between revisions of components and apis. Changelog files may contain the change history for one or more components/apis. 6 | A \token{changelog} describes the path and filename of a text file and specifies an "id" that is used by components and apis to link to this changelog file. 7 | 8 | Supported use cases: 9 | - the content of the whole pack can be associated with a single changelog. In this case the attribute default can be set to "true" and not explicit references need to be added 10 | to each and every api and component. Any api or component with explicit changelog reference will not be associated with the "default" changelog. 11 | \code 12 | 13 | 23 | 24 | 25 | 26 | 27 | 28 | Driver for myapi 29 | 30 | 31 | 32 | 33 | 34 | ... 35 | 36 | 37 | 38 | 39 | Implementation of myapi driver against the Driver myapi 40 | 41 | 42 | 43 | 44 | ... 45 | 46 | 47 | \endcode 48 | The id attribute of a changelog is used to associate individual components and apis with a changelog. 49 | 50 |

 

51 |
52 | 53 | \section element_changelogs /package/changelogs/ 54 | Grouping element for changelog file descriptions. No more than one such group may exist in a Pack. The use of changelogs is optional. 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 |
ParentChain
\ref pdsc_package_pg "package"\ref pdsc_package_pg "/package"
Child ElementsDescriptionTypeOccurrence
\ref element_changelog "changelog"A reference to a file in the pack containing the change history for components and apis.ChangelogType1..*
78 | 79 |

 

80 |
81 | 82 | \section element_changelog /package/changelogs/changelog 83 | An element containing a reference to a changelog files included in the pack. 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 118 | 119 | 120 | 121 |
ParentChain
\ref element_changelogs "changelogs"\ref pdsc_package_pg "/package/changelogs"
AttributesDescriptionTypeUse
idchangelog identifier string which must be unique within the scope of the pdsc file. 103 | The id is used by bundles, components and apis to associate it with a changelog.xs:stringrequired
nameSpecifies a path relative to package description file and the filename of the changelog file for the specified id.xs:stringrequired
defaultIf set to 'true' this changelog is associated with all 116 | apis and components, which are not explicitly referencing another changelog. 117 | There can only be a single default changelog. This optional attribute is treated as 'false' if not specified.xs:stringoptional
122 | 123 |

 

124 |
125 | 126 | */ 127 | -------------------------------------------------------------------------------- /doxygen/src/csolution_schema.txt: -------------------------------------------------------------------------------- 1 | /**************************************************************************************************/ 2 | /** 3 | \page pdsc_csolution_pg /package/csolution element 4 | 5 | The element \ref element_csolution describes the pack content that relates to *csolution projects* that are managed using the CMSIS-Toolbox. 6 | 7 | \section element_csolution /package/csolution 8 | 9 | Grouping element for csolution. No more than one such group can exist in a package description. 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 |
ParentChain
\ref pdsc_package_pg "package"\ref pdsc_package_pg "/package"
Child ElementsDescriptionTypeOccurrence
\ref element_clayer "clayer"Description of a clayer; a software layer collects source files and software components along with configuration files for re-use in different projects.ClayerType0..*
\ref element_cs_template "template"Description of project templates that are used in an IDE to start new *csolution projects*.ClayerType0..*
39 | 40 | \b Example: 41 | 42 | \code 43 | 44 | 47 | 48 | 49 | \endcode 50 | 51 |

 

52 |
53 | 54 | \section element_clayer /package/csolution/clayer 55 | 56 | A clayer section provides the information for accessing a software layer that is stored in a pack. If a condition is specified, the clayer is only listed when the condition resolves to true. 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 101 | 102 | 103 | 104 |
ParentChain
\ref element_examples "csolution"\ref element_csolution
AttributesDescriptionTypeUse
typeType of the clayerxs:stringrequired
pathPath to the directory that contains the software layer.xs:stringrequired
fileName of the `*.clayer.yml` file (optional with relative path to the directory specified with path).xs:stringrequired
copy-toPath that used to copy the software layer into the *csolution project* (default is attribute path).xs:stringoptional
conditionEnter the \b id of a \ref element_conditions "condition". The clayer is available and will be listed only when the filter condition is true 100 | (no component dependencies are evaluated).xs:stringoptional
105 | 106 | \b Example: 107 | \code 108 | 109 | 110 | 111 | 112 | \endcode 113 | 114 |

 

115 |
116 | 117 | \section element_cs_template /package/csolution/template 118 | 119 | A template section provide one or more project templates for starting a new *csolution project* in an IDE. If a condition is specified, the template is only available when the condition resolves to true. 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 |
ParentChain
\ref element_examples "csolution"\ref element_csolution
AttributesDescriptionTypeUse
nameName of the templatexs:stringrequired
pathPath to the directory that contains the template.xs:stringrequired
fileName of the `*.csolution.yml` file (optional with relative path to the directory specified with path).xs:stringrequired
copy-toPath that used to copy the template into the *csolution project* (default is attribute path).xs:stringoptional
conditionEnter the \b id of a \ref element_conditions "condition". The template is available and will be listed only when the filter condition is true 163 | (no component dependencies are evaluated).xs:stringoptional
Child ElementsDescriptionTypeOccurrence
descriptionBriefly documents the purpose and scope of the template (maximum 256 characters, recommended 128 characters).BriefDescType1
180 | 181 | \b Example: 182 | \code 183 | 184 | 187 | 190 | 191 | \endcode 192 | 193 |

 

194 | 195 | */ 196 | -------------------------------------------------------------------------------- /doxygen/src/examples_schema.txt: -------------------------------------------------------------------------------- 1 | /**************************************************************************************************/ 2 | /** 3 | \page pdsc_examples_pg /package/examples element 4 | 5 | The element \ref element_example describes fully defined examples contained in the Pack. 6 | An example lists the files that belong to an example. The example itself and each individual file may 7 | refer to a \ref element_condition "condition" that must resolve to true; if it is false the example or file will be ignored. 8 | The board element is used to reference to one or more board descriptions using the board vendor and name an example is targeted for. 9 | Each example may optionally specify attributes e.g. providing a short list of the most significant components using Class (Cclass=), Group (Cgroup=), Subgroup (Csub) and a Version (Cversion=). 10 | 11 | \b Example 12 | \code 13 | 14 | 15 | This is a basic example demonstrating the development flow and letting the LED on the board blink 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | Blinky 25 | Getting Started 26 | 27 | 28 | 29 | 30 | \endcode 31 | 32 |

 

33 |
34 | 35 | \section element_examples /package/examples 36 | 37 | Grouping element for examples. No more than one such group can exist in a Pack. 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 |
ParentChain
\ref pdsc_package_pg "package"\ref pdsc_package_pg "/package"
Child ElementsDescriptionTypeOccurrence
\ref element_example "example"Description of fully specified projectExampleType1..*
61 | 62 |

 

63 |
64 | 65 | \section element_example /package/examples/example 66 | 67 | An example section is used to provide the required information for accessing an example project contained in a Pack. All examples contained in the installed packs can be 68 | listed including a brief description. A selected example will get copied into a user selected destination folder. Based on the user selected environment the respective project 69 | file will be loaded. The ID of an example is the combination of the Pack vendor, the board information and the example name and version. Examples with the same ID are 70 | treated as a single example. 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 97 | 98 | 99 | 100 | 101 | 102 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 |
ParentChain
\ref element_examples "examples"\ref element_examples
AttributesDescriptionTypeUse
nameName of the examplexs:stringrequired
folderRelative path to the example base folder within the package. If selected, then the directory including all sub-folders and files will be copied, 96 | unless the archive attribute gets set.xs:stringrequired
archiveFilename and extension of the archive file containing all files and sub-folders of the example. The archive is located in the path specified by the 103 | attribute \b folder. If selected, then the whole archive will be extracted.xs:stringoptional
docDocument that describes the example.xs:stringrequired
versionExample version number. The version format is described in \ref VersionType "Version Type".VersionTypeoptional
publicSet publishing permissions for the documentation. If \tagem{public} is \token{true}, then the vendor gives permission 123 | to extract the documentation from the pack and publish it on a web-page. Links to web pages are assumed to be public. 124 | The default value is \token{true}.xs:booleanoptional
Child ElementsDescriptionTypeOccurrence
descriptionBriefly documents the purpose and scope of the example (maximum 256 characters, recommended 128 characters). The test can be displayed in an example selector.BriefDescType1
\ref element_example_board "board"Complex type providing a reference to a board description using board name and vendor.BoardReferenceType0..*
\ref element_example_project "project"Complex type describing the project files for different environmentsExampleProjectType1
\ref element_example_attributes "attributes"Group element for project attributes, which list required components, define example categories, and set keywords to filter and search for examples.ExampleAttributesType0..1
159 | 160 |

 

161 |
162 | 163 | \section element_example_board /package/examples/example/board 164 | This element specifies the board that can be used with the example project. 165 | 166 | \b Example: 167 | \code 168 | 169 | \endcode 170 | 171 |

 

172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 |
ParentChain
\ref element_example "example"\ref element_example
AttributesDescriptionTypeUse
vendorVendor name of the board.xs:stringrequired
nameCommercial name of the board.xs:stringrequired
DvendorVendor name of the device used on the board. Use predefined values as listed in the table \ref DeviceVendorEnum "Device Vendor". DeviceVendorEnumoptional
DfamilyName of the target device family used on the board. This attribute is optional if either DsubFamily or Dname is already specified. \n \token{Deprecated since version 1.1}xs:stringoptional
DsubFamilyName of the target device sub-family used on the board. This attribute is optional if either Dfamily or Dname is already specified. \n \token{Deprecated since version 1.1}xs:stringoptional
DnameName of the target device used on the board. This attribute is optional if either Dfamily or DsubFamily is already specified. \n \token{Deprecated since version 1.1}.xs:stringoptional
225 | 226 | \note 227 | Values for \token{deprecated attributes} are read from the board description element \ref element_board_mountedDevice. 228 | 229 |

 

230 |
231 | 232 | \section element_example_project /package/examples/example/project 233 | Different development tools store project information in tool specific file formats. A single example 234 | may include project files for multiple tools or environments. 235 | Therefore the project element is a sequence of one or more \em environment elements that describe the name of the environment and the project file to be loaded by the respective development tool. 236 | 237 | Example: 238 | \code 239 | 240 | 241 | 242 | 243 | \endcode 244 | 245 |

 

246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 |
ParentChain
\ref element_example "example"\ref element_example
Child ElementsDescriptionTypeOccurrence
\ref element_example_project_env "environment"Specifies the environment and project file with extension.xs:complexType1..*
269 | 270 |

 

271 |
272 | 273 | \section element_example_project_env /package/examples/example/project/environment 274 | The environment element describes the name of the environment and the project file to be loaded. 275 | 276 | Example: 277 | \code 278 | 279 | 280 | 281 | 282 | 283 | \endcode 284 | 285 |

 

286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 306 | 307 | 308 | 309 | 310 | 311 | 313 | 314 | 315 | 316 | 317 | 318 | 323 | 324 | 325 | 326 |
ParentChain
\ref element_example_project "project"\ref element_example_project
AttributesDescriptionTypeUse
nameIdentifier of the development tool (for example: \token{uv}, \token{iar}, \token{csolution}, etc.) 305 | targeted by the project file specified by the load attribute.xs:stringrequired
loadSpecifies the project file with extension. A path relative to \em folder attribute of the element 312 | \ref element_example can be appended.xs:stringrequired
folderSpecifies the subdirectory to be copied into the user's project folder relative to \em folder attribute of the element \ref element_example. 319 | This attribute is used by example descriptions that support multiple tool-chains/IDEs, each stored in a separate folders. Note: for copying eclipse 320 | projects it is required that the .project file is located in the base directory and all project files are located in the base directory or in one of the 321 | subdirectories. In this case even common files are required to be duplicated. 322 | xs:stringoptional
327 | 328 |

 

329 |
330 | 331 | \section element_example_attributes /package/examples/example/attributes 332 | 333 | Example: 334 | \code 335 | 336 | 337 | Example Project 338 | For a specific board 339 | ... 340 | 341 | 342 | ... 343 | Blinky 344 | Getting Started 345 | 346 | 347 | \endcode 348 | 349 |

 

350 | 351 | 352 | 353 | 354 | 355 | 356 | 357 | 358 | 359 | 360 | 361 | 362 | 363 | 364 | 365 | 366 | 367 | 368 | 369 | 370 | 371 | 372 | 373 | 374 | 375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 |
ParentChain
\ref element_example "example"\ref element_example
Child ElementsDescriptionTypeOccurrence
categoryFree form string defining an example category. A category can be used to filter examples in an example browser.xs:string0..*
\ref element_example_attribute_component "component"Group for defining the components used in the example.ComponentCategoryType0..*
keywordFree form string defining a keyword that relates to the example. A keyword can be used to search for examples.xs:string0..*
385 | 386 |

 

387 |
388 | 389 | \section element_example_attribute_component /package/examples/example/attributes/component 390 | The component element specifies the Cclass to which the example belongs. 391 | This can be used to list all related components within an example. 392 | 393 | Example: 394 | \code 395 | 396 | ... 397 | 398 | 399 | ... 400 | 401 | \endcode 402 | 403 |

 

404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 419 | 420 | 421 | 422 | 423 | 424 | 425 | 426 | 427 | 428 | 429 | 430 | 431 | 432 | 433 | 434 | 435 | 436 | 437 | 438 | 439 | 440 | 441 | 442 | 443 | 444 | 445 | 446 | 447 | 448 | 449 | 450 |
ParentChain
\ref element_example_attributes "attribute"\ref element_example_attributes
AttributeDescriptionTypeUse
CclassFree form string defining an example class. Predefined values can be used as listed in the table \ref CclassType "Component Classes".CclassTyperequired
CgroupFree form string defining an example group. Predefined values can be used as listed in the table \ref CgroupType "Component Groups".CgroupTypeoptional
CsubFree form string defining an example subgroup. The type is described in \ref CsubType "Component Subgroups".CsubTypeoptional
CversionFree form string defining an example version. The version format is described in \ref VersionType "Version Type".VersionTypeoptional
CvendorFree form string defining the vendor of the example.xs:stringoptional
451 |

 

452 | 453 | */ 454 | -------------------------------------------------------------------------------- /doxygen/src/flash_algorithms.txt: -------------------------------------------------------------------------------- 1 | /**************************************************************************************************/ 2 | /** 3 | \page flashAlgorithm Flash Programming 4 | 5 | Flash Programming Algorithms are a piece of software to erase or download applications to Flash devices. A device 6 | family pack (DFP) usually contains predefined Flash algorithms for programming the devices that are supported within. A 7 | template for creating new algorithms are available in the ARM:CMSIS Pack. The following section describes the process 8 | in more detail. 9 | 10 | 11 | \section CreateFPA Creating a new Algorithm 12 | 13 | Flash programming algorithms are defined with functions to erase and program the Flash device. Special compiler and linker 14 | settings are required. Follow these steps to create and configure a new Flash programming algorithm: 15 | -# Copy the content from the ARM:CMSIS Pack folder (usually 16 | C:\\Keil\\ARM\\Pack\\ARM\\CMSIS\\version\\Device\\\_Template_Flash) to a new folder. 17 | -# Rename the project file \b NewDevice.uvprojx to represent the new Flash ROM device name, for example \b MyDevice.uvprojx. 18 | -# Open the project with uVision. From the toolbar, use the drop-down Select Target to define the processor 19 | architecture. \b Cortex-M fits for all Cortex-M0/M0+, M3, and M4 devices. The configuration assumes a little-endian 20 | microcontroller. In case of a big-endian microcontroller, select the correct processor core with \b Project - 21 | Options for Target - \b Device. 22 | -# Open the dialog \b Project - Options for Target - \b Output and change the content of the field 23 | Name of Executable to represent the device, for example \b MyDevice. 24 | -# Adapt the programming algorithms in the file \ref FlashPrg. 25 | -# Adapt the device parameters in the file \ref FlashDev. 26 | -# Use \b Project - Build Target to generate the new Flash programming algorithm. The output file (for example 27 | \b MyDevice.FLM) has to be \ref AddFPA "added" to the \b DFP. 28 | 29 | \note 30 | - Creating a Flash programming algorithm with 31 | MDK-Lite is not supported. 32 | - Flash programming algorithms use Read-Only Position Independent and Read-Write Position Independent program 33 | code. These options are set in the dialogs \b Project - Options for Target - \b C/C++ and \b Project - 34 | Options for Target - \b Asm. 35 | - The dialog \b Project - Options for Target - \b Linker defines the linker scatter file \b Target.lin. The error 36 | L6305 is disabled with \c --diag_suppress \c L6305. 37 | - The \subpage algorithmFunc "Flash Algorithm Functions" section contains reference for all the available functions. 38 | 39 | \anchor FlashPrg 40 | FlashPrg.c 41 | ---------- 42 | The file \b FlashPrg.c contains the mandatory Flash programming functions \ref Init, \ref UnInit, \ref EraseSector, and 43 | \ref ProgramPage. Optionally, depending on the device features (or to speed-up execution), the functions \ref EraseChip, 44 | \ref BlankCheck, and \ref Verify can be implemented. 45 | 46 | \anchor FlashDev 47 | FlashDev.c 48 | ---------- 49 | The file \b FlashDev.c contains parameter definitions for: 50 | -# the Flash programming functions. 51 | -# the \b FlashDevice structure: 52 | \code 53 | struct FlashDevice const FlashDevice = { 54 | FLASH_DRV_VERS, // Driver Version, do not modify! 55 | "New Device 256kB Flash", // Device Name 56 | ONCHIP, // Device Type 57 | 0x00000000, // Device Start Address 58 | 0x00040000, // Device Size in Bytes (256kB) 59 | 1024, // Programming Page Size 60 | 0, // Reserved, must be 0 61 | 0xFF, // Initial Content of Erased Memory 62 | 100, // Program Page Timeout 100 mSec 63 | 3000, // Erase Sector Timeout 3000 mSec 64 | 65 | // Specify Size and Address of Sectors 66 | 0x002000, 0x000000, // Sector Size 8kB (8 Sectors) 67 | 0x010000, 0x010000, // Sector Size 64kB (2 Sectors) 68 | 0x002000, 0x030000, // Sector Size 8kB (8 Sectors) 69 | SECTOR_END 70 | }; 71 | \endcode 72 | 73 | \note 74 | The Device Name is usually be shown in tools to identify the Flash algorithm. Make sure that this name reflects the device name. 75 | 76 | \note 77 | The Programming Page Size specifies the block size for programming using the function \ref ProgramPage. For devices with small block sizes 78 | it might be better to specify a multiple of the physical block size as this reduces the communication overhead to the target. 79 | An optimal block size for fast programming is 1024 bytes, however the system itself does not restrict this size value. 80 | 81 | 82 | \section AddFPA Adding an Algorithm to a Pack 83 | The generated *.FLM file needs to be added to the DFP, so that it is available to the tool user for programming 84 | his device. Usually, a directory \b Flash is created and the algorithm is saved in this directory. 85 | 86 | The algorithm is specified within the the \ref element_family level: 87 | \code 88 | 89 | ... 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | ... 99 | 100 | \endcode 101 | 102 | The argument \a start specifies the base address for the Flash programming algorithm. 103 | 104 | The argument \a size specifies the size covered by the Flash programming algorithm. End address = start + size - 1. 105 | 106 | The argument \a default specifies whether a Flash programming algorithm is set as the default algorithm in a project (when 107 | \token{true}). If \a default is not set or false, the Flash programming algorithm can be configured on a lower level. 108 | However, the Flash programming algorithm of a project can be changed manually at any time during development. 109 | */ 110 | 111 | 112 | /**************************************************************************************************/ 113 | /** 114 | \page algorithmFunc Algorithm Functions 115 | 116 | The following functions are available for creating new Flash programming algorithms: 117 | Function Name |Indication |Description 118 | -----------------|-----------|----------- 119 | \ref BlankCheck |optional |Check and compare patterns. 120 | \ref EraseChip |optional |Delete entire Flash memory content. 121 | \ref EraseSector |mandatory |Delete Flash memory content of a specific sector. 122 | \ref Init |mandatory |Initialize and prepare device for Flash programming. 123 | \ref ProgramPage |mandatory |Write the application into the Flash memory. 124 | \ref UnInit |mandatory |De-initialize the microcontroller after one of the Flash programming steps. 125 | \ref Verify |optional |Compare Flash memory content with the program code. 126 | 127 | The following diagrams show how the functions of the Flash Programming Algorithms are executed by a development tool. 128 | 129 | The Flash Erase sequence is executed to erase the Flash content. 130 | 131 | \image html FlashErase.png "Flash Erase" 132 | 133 | The Flash Program sequence is executed to program the Flash memory. 134 | 135 | \image html FlashProgram.png "Flash Program" 136 | 137 | The Flash Verify sequence is executed to verify the content after flash programming. 138 | 139 | \image html FlashVerify.png "Flash Verify" 140 | 141 |

 

142 |
143 | 144 | \section BlankCheck BlankCheck 145 | \code 146 | int BlankCheck (unsigned long adr, unsigned long sz, unsigned char pat); 147 | \endcode 148 | \brief Blank Check 149 | \param adr Block start address 150 | \param sz Block size in bytes 151 | \param pat Pattern to compare 152 | \return status information: 153 | - 0 when the block content is equal to the pattern pat. 154 | - 1 when the block content differs from the pattern pat. 155 | \details 156 | The function \b BlankCheck can be used to check whether the specified block is empty, or whether the content is equal to a 157 | specific pattern defined in the argument \a pat. 158 | 159 | The argument \a adr specifies the start address of the block that is to be verified. 160 | 161 | The argument \a sz specifies the size of the block that is to be verified. 162 | 163 | Code Example 164 | \code 165 | int BlankCheck (unsigned long adr, unsigned long sz, unsigned char pat) { 166 | 167 | unsigned long i, j, k; 168 | 169 | // Recalculate address for External SDRAM addresses 170 | if (adr >= SDRAM_START) 171 | adr = adr - SDRAM_START + USER_OFFSET; 172 | 173 | for (i = 0; i < sz; i += 256) { 174 | // Read 256 bytes 175 | ReadPage_HW (adr+i, 256, &rd_buf[0]); 176 | 177 | // Determine size to compare 178 | if ((sz-i) >= 256) k = 256; 179 | else k = (sz-i); 180 | 181 | // Check up to 256 bytes if equal to pattern "pat" 182 | for (j = 0; j < k; j++) 183 | if (rd_buf[j] != pat) return (1); // Memory is not blank 184 | } 185 | 186 | return (0); // Memory is blank 187 | } 188 | \endcode 189 | 190 |

 

191 |
192 | 193 | \section EraseChip EraseChip 194 | \code 195 | int EraseChip (void); 196 | \endcode 197 | \return status information: 198 | - 0 on success. 199 | - 1 on failure. 200 | \details 201 | The function \b EraseChip deletes the content of the entire Flash memory. It is invoked whenever the uVision menu 202 | \b Flash - \b Erase is used, or whenever an attempt is made to download the program to Flash and the option 203 | Erase Full Chip has been set in the Flash Download Setup dialog. If this function is missing in the Flash 204 | Programming Algorithm, the \ref EraseSector function is executed until the entire content of the Flash memory area has been 205 | deleted. 206 | 207 | Code Example 208 | \code 209 | int EraseChip (void) { 210 | 211 | FLASH->CR |= FLASH_MER; // Mass Erase Enabled 212 | FLASH->CR |= FLASH_STRT; // Start Erase 213 | 214 | while (FLASH->SR & FLASH_BSY) { 215 | IWDG->KR = 0xAAAA; // Reload IWDG 216 | } 217 | 218 | FLASH->CR &= ~FLASH_MER; // Mass Erase Disabled 219 | 220 | return (0); // Done 221 | } 222 | \endcode 223 | 224 |

 

225 |
226 | 227 | \section EraseSector EraseSector 228 | \code 229 | int EraseSector (unsigned long adr); 230 | \endcode 231 | \param adr Sector address 232 | \return status information: 233 | - 0 on success. 234 | - 1 on failure. 235 | 236 | \details 237 | The function \b EraseSector deletes the content of the sector starting at the address specified by the argument \a adr. The 238 | function is invoked whenever the uVision menu \b Flash - \b Erase is used, or whenever an attempt is made to download the 239 | program to Flash and the option Erase Sectors has been set in the Flash Download Setup dialog. 240 | 241 | Code Example 242 | \code 243 | int EraseSector (unsigned long adr) { 244 | 245 | FLASH->CR |= FLASH_PER; // Page Erase Enabled 246 | FLASH->AR = adr; // Page Address 247 | FLASH->CR |= FLASH_STRT; // Start Erase 248 | 249 | while (FLASH->SR & FLASH_BSY) { 250 | IWDG->KR = 0xAAAA; // Reload IWDG 251 | } 252 | 253 | FLASH->CR &= ~FLASH_PER; // Page Erase Disabled 254 | 255 | return (0); // Done 256 | } 257 | \endcode 258 | 259 |

 

260 |
261 | 262 | \section Init Init 263 | \code 264 | int Init (unsigned long adr, unsigned long clk, unsigned long fnc); 265 | \endcode 266 | \param adr Device base address 267 | \param clk Clock frequency (Hz) 268 | \param fnc Function code 269 | \return status information: 270 | - 0 on success. 271 | - 1 on failure. 272 | 273 | \details 274 | The function \b Init initializes the microcontroller for Flash programming. It is invoked whenever an attempt is made to 275 | download the program to Flash. 276 | 277 | The argument \a adr specifies the base address of the device. 278 | 279 | The argument \a clk specifies the clock frequency for prgramming the device. 280 | 281 | The argument \a fnc is a number: 282 | - 1 stands for Erase. 283 | - 2 stands for Program. 284 | - 3 stands for Verify. 285 | 286 | Thus, different initialization sections can be implemented for each individual Flash programming step. 287 | 288 | Code Example 289 | \code 290 | int Init (unsigned long adr, unsigned long clk, unsigned long fnc) { 291 | 292 | // Zero Wait State 293 | FLASH->ACR = 0x00000000; 294 | 295 | // Unlock Flash 296 | FLASH->KEYR = FLASH_KEY1; 297 | FLASH->KEYR = FLASH_KEY2; 298 | 299 | // Test if IWDG is running (IWDG in HW mode) 300 | if ((FLASH->OBR & 0x04) == 0x00) { 301 | // Set IWDG time out to ~32.768 second 302 | IWDG->KR = 0x5555; // Enable write access to IWDG_PR and IWDG_RLR 303 | IWDG->PR = 0x06; // Set prescaler to 256 304 | IWDG->RLR = 4095; // Set reload value to 4095 305 | } 306 | 307 | return (0); 308 | } 309 | \endcode 310 | 311 |

 

312 |
313 | 314 | \section ProgramPage ProgramPage 315 | \code 316 | int ProgramPage (unsigned long adr, unsigned long sz, unsigned char *buf); 317 | \endcode 318 | \param adr Page start address 319 | \param sz Page size 320 | \param buf Data to be written 321 | \return status information: 322 | - 0 on success. 323 | - 1 on failure. 324 | 325 | \details 326 | The function \b ProgramPage is used to write code into the Flash memory. It is invoked to 327 | download a program to Flash. As Flash memory is typically organized in blocks or pages, the parameters to the function \b ProgramPage 328 | must not cross alignment boundaries of these flash pages. The page size is specified in the struct FlashDevice with the value 329 | Program Page Size. 330 | 331 | The argument \a adr specifies the start address of the page that is to be programmed. It is aligned by the host programming system to a start address 332 | of a flash page. 333 | 334 | The argument \a sz specifies the data size in the data buffer. The host programming system ensures that page boundaries are not crossed. 335 | 336 | The argument \a buf points to the data buffer containing the data to be programmed. 337 | 338 | \note 339 | The host programming system ensures that the argument \a adr + \a sz never crosses any page boundary. The function \b ProgramPage does therefore not 340 | require any provisions for that. 341 | 342 | Code Example 343 | \code 344 | int ProgramPage (unsigned long adr, unsigned long sz, unsigned char *buf) { 345 | 346 | sz = (sz + 1) & ~1; // Adjust size for Half Words 347 | 348 | while (sz) { 349 | 350 | FLASH->CR |= FLASH_PG; // Programming Enabled 351 | 352 | M16(adr) = *((unsigned short *)buf); // Program Half Word 353 | while (FLASH->SR & FLASH_BSY); 354 | 355 | FLASH->CR &= ~FLASH_PG; // Programming Disabled 356 | 357 | // Check for Errors 358 | if (FLASH->SR & (FLASH_PGERR | FLASH_WRPRTERR)) { 359 | FLASH->SR |= FLASH_PGERR | FLASH_WRPRTERR; 360 | return (1); // Failed 361 | } 362 | 363 | // Go to next Half Word 364 | adr += 2; 365 | buf += 2; 366 | sz -= 2; 367 | 368 | } 369 | 370 | return (0); // Done 371 | } 372 | \endcode 373 | 374 |

 

375 |
376 | 377 | \section UnInit UnInit 378 | \code 379 | int UnInit (unsigned long fnc); 380 | \endcode 381 | \param fnc Function code 382 | \return status information: 383 | - 0 on success. 384 | - 1 on failure. 385 | 386 | \details 387 | The function \b UnInit de-initializes the microcontroller and is invoked at the end of an erasing, programming, or verifying 388 | step. 389 | 390 | The argument \a fnc is a number: 391 | - 1 stands for Erase. 392 | - 2 stands for Program. 393 | - 3 stands for Verify. 394 | 395 | Thus, different de-initialization sections can be implemented for each individual Flash programming step. 396 | 397 | Code Example 398 | \code 399 | int UnInit (unsigned long fnc) { 400 | 401 | // Lock Flash 402 | FLASH->CR |= FLASH_LOCK; 403 | 404 | return (0); 405 | } 406 | \endcode 407 | 408 |

 

409 |
410 | 411 | \section Verify Verify 412 | \code 413 | unsigned long Verify (unsigned long adr, unsigned long sz, unsigned char *buf); 414 | \endcode 415 | \param adr Start address 416 | \param sz Size in bytes 417 | \param buf Data to be compared 418 | \return status information: 419 | - the sum of (adr+sz) - on success. 420 | - any other number - on failure, and represents the failing address. 421 | 422 | \details 423 | The function \b Verify compares the content of the Flash memory with the program code \a *buf. 424 | 425 | The argument \a adr specifies the start address for the verification. 426 | 427 | The argument \a sz specifies the size of the verification. 428 | 429 | The argument \a buf points to the buffer containing the data to be verified. 430 | 431 | Code Example 432 | \code 433 | unsigned long Verify (unsigned long adr, unsigned long sz, unsigned char *buf) { 434 | unsigned long i, adr_dest, in_page_ofs; 435 | 436 | if (adr < block_size) { // Verifying 2-nd level bootloader data 437 | adr_dest = adr + page_usr_size; // skip page 0 of block 0 438 | } else { // Verifying program data 439 | FindBlock(adr, 0); 440 | adr_dest = nand_block_offset + (adr & (block_size-1)); 441 | } 442 | in_page_ofs = adr_dest & (page_usr_size-1); 443 | 444 | if (ReadPage_HW(adr_dest, page_usr_size, data_buf)) return (1); 445 | for (i=0; i 13 | 14 | 15 | 16 | 17 | 18 | \endcode 19 | - individual components and apis can be associated with a specific \token{licenseSet} 20 | \b Example - an api and a component associated with different specific \token{licenseSets}. 21 | \code 22 | ... 23 | 24 | ... 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | CMSIS Driver API for SPI peripherals 36 | 37 | 38 | 39 | 40 | 41 | ... 42 | 43 | 44 | 45 | 46 | Implementation of an SPI driver against the CMSIS Driver SPI API 47 | 48 | 49 | 50 | 51 | ... 52 | 53 | 54 | \endcode 55 | - the license file element can optionally specify an attribute \token{url} to allow license inspection without the need to download a pack. 56 | 57 | Note, the licenseSets description section supersedes the file specified by the license element, if the tools supports \token{licenseSets}. 58 | The id attribute of a licenseSet is used to associate individual components and apis with a licenseSet. 59 | 60 |

 

61 |
62 | 63 | \section element_licenseSets /package/licenseSets/ 64 | Grouping element for licenseSets. No more than one such group can exist in a Pack. None is required. 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 |
ParentChain
\ref pdsc_package_pg "package"\ref pdsc_package_pg "/package"
Child ElementsDescriptionTypeOccurrence
\ref element_licenseSet "licenseSet"Description of a collection of license filesLicenseSetType1..*
88 | 89 |

 

90 |
91 | 92 | \section element_licenseSet /package/licenseSets/licenseSet 93 | An element containing a list of one or more license files. 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 114 | 115 | 116 | 117 | 118 | 119 | 122 | 123 | 124 | 125 | 126 | 127 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 |
ParentChain
\ref element_licenseSets "licenseSets"\ref pdsc_package_pg "/package/licenseSets"
AttributesDescriptionTypeUse
idlicense set identifier string which must be unique within the scope of the pdsc file. 113 | The id is used in components and apis to associate it with the licenseSet.xs:stringrequired
defaultIf set to 'true' this licenseSet is associated with the pack's content and for all 120 | apis and components, which are not explicitly referencing another licenseSet. 121 | There can only be a single default licenseSet. This optional attribute is treated as 'false' if not specified.xs:booleanoptional
gatingIf set to 'true' this licenseSet is required to be accepted/acknowledged by the user before the installation 128 | process starts extracting any other files than license files from the pack. If declined the pack installation 129 | process will terminate. This optional attribute is treated as 'false' if not specified. 130 | xs:booleanoptional
Child ElementsDescriptionTypeOccurrence
\ref element_licensefile "license"Description of a license file reference, unique identifier, title and default attributesLicensefileType1..*
147 | 148 |

 

149 |
150 | 151 | \section element_licensefile /package/licenseSets/licenseSet/license 152 | An element describing an individual license file. 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 186 | 187 | 188 | 189 | 190 | 191 | 193 | 194 | 195 | 196 |
ParentChain
\ref element_licenseSets "licenseSet"\ref element_licenseSet "/package/licenseSets/licenseSet"
AttributesDescriptionTypeUse
namelicense filename with pack base directory relative path. The license file is an ASCII text file 172 | with '*.txt' or no file extensionxs:stringrequired
titleA display string used by tools to represent the license.xs:stringrequired
spdxA machine readable license ID string according to the SPDX License List. In case a license is not listed here do not use this attribute.xs:stringoptional
urlA public web link to the license text matching the file content referenced by \token{name} attribute. 192 | This url allows the inspection of license terms by the user prior to downloading the pack.xs:anyURIoptional
197 |

 

198 |
199 | 200 | */ 201 | -------------------------------------------------------------------------------- /doxygen/src/pack_publish.txt: -------------------------------------------------------------------------------- 1 | /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ 2 | /** 3 | \page createPackPublish Publish a CMSIS-Pack 4 | 5 | Before you start distributing a software pack, make sure that it does not contain errors. Use the tools described in the 6 | \ref createPackUtil section for verification. Once you have validated that the PDSC file and the pack contain no errors, 7 | you have basically two options for distributing a software pack: 8 | - \ref cp_LocalInstallation 9 | - \ref cp_WebDownload 10 | 11 | The following sections assume that you are familiar with the 12 | CMSIS-Toolbox and 13 | especially with 14 | cpackget. 15 | 16 | \section createPackUtil Checking CMSIS-Packs 17 | 18 | Software packs are ZIP files that contain a \ref packFormat "PDSC" file and other content. The ZIP file needs to be consistent 19 | and the PDSC file within has to be validated against the XML schema file (PACK.xsd). An open-source checking tool is available 20 | that helps you with both tasks: a 21 | Bash library for gen-pack scripts. 22 | Make sure that you have used it to validate your PDSC file and the pack contents before submitting it to any 23 | \ref cp_KeilComPack "pack indexing service". The library can be used on all major host operating systems and can also be run 24 | in GitHub actions. 25 | 26 | \section cp_LocalInstallation Local installation 27 | 28 | The easiest way to distribute a software pack is attaching it to an email or using other means of electronic distribution 29 | (for example using a file server). Install the software pack on a PC using 30 | cpackget, 31 | the pack management tool that comes with the CMSIS-Toolbox: 32 | \code 33 | cpackget add vendor.packname.version.pack 34 | \endcode 35 | If the PDSC file does not contain a valid \c \elem{url} element, a 36 | manual installation is required to update a software pack. Otherwise, \c cpackget can check for updates on the server or the 37 | local machine that is specified by \c \elem{url}. 38 | 39 | \note For automatic updates on a local machine, specify the \c \elem{url} using the 40 | file URI scheme. 41 | 42 | \section cp_WebDownload Web download 43 | 44 | If you want to make your packs publicly available, you need to host them on the web. For publishing packs, these 45 | options are available: 46 | - \ref cp_HowWebDownloadWorks 47 | - \ref cp_GitHubHosting 48 | 49 | The following diagram shows how you can publish your packs when using a \ref cp_KeilComPack "pack indexing service": 50 | 51 | \image html IndexingService.png "Pack hosting and indexing service" 52 | 53 | When you run the command \c cpackget \c update-index, the tool queries the \ref pidxFile "package index file (index.pidx)" 54 | from the pack index server. This file is generated using the \ref cp_vidx2pidx "vidx2pidx tool" from the 55 | \ref vidxFile "vendor index file (index.vidx)" which points to all known \elem{vendor}.pidx and stand-alone PDSC files. 56 | 57 | The PIDX file allows you to change pack versions and add packs to your distribution list. All packs that are referenced in the 58 | PIDX file will be processed and validated. Only error-free packs will become available via web pages and development tools. 59 | 60 | \note Refer to the \ref cp_KeilComPack section for more information how to get listed on such an indexing server. 61 | 62 | \subsection cp_HowWebDownloadWorks Self-hosted packs 63 | 64 | Any web server can be used to host a software pack (specified by the \c \elem{url} element in the PDSC file). At this location, 65 | the following files should be present: 66 | -# \elem{vendor}.\elem{name}.pdsc [required]: pack description file. 67 | -# \elem{vendor}.\elem{name}.\elem{version}.pack [required]: pack file where \elem{version} refers to the latest version 68 | specified in the PDSC file. 69 | -# \elem{vendor}.pidx [optional]: list with all packs hosted and maintained by the vendor (refer to \ref pidxFile) 70 | 71 | All previous versions listed in the \elem{releases} section of the PDSC file should be present at the \c \elem{url} as well. This 72 | allows users to revert updates or to download a previous version of a software pack (for maintenance purposes). 73 | 74 | The \elem{vendor}.pidx allows you to publish multiple packs to a \ref cp_KeilComPack "Pack Index Service" at once. 75 | 76 | \note 77 | - The \elem{url} element in \elem{vendor}.\elem{name}.pdsc is the location where these services check for new packs. At this 78 | \elem{url} location, an (unversioned) \elem{vendor}.\elem{name}.pdsc file and a (versioned) 79 | \elem{vendor}.\elem{name}.\elem{version}.pack must be available. 80 | - The \elem{url} is the page where the pack is downloaded. This means, if the URL or the PDSC/pack files become unavailable, users are unable to download the pack. 81 | - When a new PDSC/pack file is available, it is important to update the version number, otherwise the \ref cp_KeilComPack "Pack Index Service" will not recognize that the pack has changed. 82 | - Previous versions of a (versioned) \elem{vendor}.\elem{name}.\elem{version}.pack should remain available. 83 | 84 | \subsection cp_GitHubHosting GitHub-hosted packs 85 | 86 | If you develop your packs publicly on GitHub, you can use the infrastructure to host your packs. The recommended way to do 87 | this is as follows (note that in this example, \elem{orgname} is equal to \elem{vendor} in the other examples. We use 88 | \elem{orgname} here as this is the nomenclature on GitHub): 89 | - Create a repository for the PIDX file, for example \c github.com/orgname/indexrepo. The PIDX file should be named \elem{orgname}.pidx. 90 | - Create seperate repositories for each pack, for example: 91 | - \c github.com/orgname/name1 92 | - \c github.com/orgname/name2 93 | - At the top-level of each repository's \c main branch, you need have a \elem{orgname}.\elem{nameX}.pdsc file. 94 | - Once you publish a pack, attach the \elem{orgname}.\elem{nameX}.\elem{version}.pack file to the release assets - this will be 95 | used as the download location of the pack. 96 | 97 | This diagram shows an exemplary set up on GitHub with pack versions 1.0.0 and 1.3.0: 98 | 99 | \image html GHhosting.png "Hosting packs on GitHub" 100 | 101 | \subsubsection gh_pidx PIDX file on GitHub 102 | 103 | The vendor (orgname) PIDX file would look like the following: 104 | 105 | \code{.xml} 106 | 107 | 108 | 109 | orgname 110 | https://github.com/orgname/indexrepo/raw/main/ 111 | 2024-08-22T15:00:10.7300074+00:00 112 | 113 | 114 | 115 | 116 | 117 | \endcode 118 | 119 | \note When updating one of the packs, you only need to change the version number and update the timestamp. All other entries 120 | remain the same. Please make sure that only release quality packs are made available using this mechanism. You can build local 121 | releases of a pack anytime for testing purposes. 122 | 123 | \subsubsection gh_pdsc PDSC file on GitHub 124 | 125 | A PDSC file for one of the repositories would look like this: 126 | 127 | \code{.xml} 128 | 129 | 130 | 131 | orgname 132 | name1 133 | LICENSE 134 | Whatever Pack 135 | https://github.com/orgname/name1/raw/main/ 136 | info@orgname.com 137 | https://github.com/orgname/name1.git 138 | 139 | Initial release 140 | 141 | … 142 | \endcode 143 | 144 | When updating a pack, you need to: 145 | - Change the \elem{url} to the location of the latest pack file in the PDSC. 146 | - Add a new \elem{release} version with the correct entries in the PDSC. 147 | - Attach the pack file to the release assets. 148 | - Update the PIDX file with the latest version information. 149 | 150 | \note 151 | While the repository's \c main branch can be used to host the PDSC file, additional confidence against unwanted changes can 152 | be made if you use a dedicated branch for hosting the PDSC file. This avoids breaking unintentionally the pack location when 153 | accepting a pull request (PR). 154 | 155 | \section cp_KeilComPack Using a pack index service 156 | 157 | Tool, software, or silicon vendors may provide a web infra-structure that lists packs that are available from multiple 158 | vendors. Companies like Arm or IAR provide such a service for making CMSIS-Packs available to a 159 | wider audience of developers. The packs are then found by pack management tools and their contents are listed on web sites, 160 | such as Arm's list of CMSIS-Packs. 161 | 162 | Once you are ready to publish your packs, please send the URL of the \elem{vendor}.\elem{name}.pdsc or \elem{vendor}.pidx 163 | file to the following email addresses: 164 | 165 | - for Arm tools, email to CMSIS@arm.com. 166 | - for IAR tools, email to CMSIS@iar.com. 167 | 168 | Arm uses the pack information to generate a list of available software packs. The following content will be processed in 169 | order to generate the web site (https://www.keil.arm.com/packs/): 170 | - Version 171 | - Release notes 172 | - Devices 173 | - Boards 174 | - Examples 175 | - Software components 176 | - Description 177 | - An Overview.md file if present 178 | 179 | Furthermore, the data is used to create lists of boards 180 | and devices. 181 | 182 | Please allow up to seven working days for the process. If the files contain any errors, you will be notified. Otherwise, the 183 | information is added to the index server. We strongly recommend using a \ref pidxFile for better maintainability. 184 | 185 | \subsection cp_vidx2pidx The vidx2pidx conversion tool 186 | 187 | If you want to check the content of you \ref pidxFile, you can use the vidx2pidx utility to create your own \c index.pidx 188 | file. Once created, you can use it with \c cpackget to install the packs listed in the PIDX file. 189 | 190 | Follow these steps to run the conversion and installatin: 191 | - Download vidx2pidx. 192 | - Create you \elem{vendor}.vidx file just listing the \elem{vendor.pidx} file. 193 | Code example 194 | 195 | \code{.xml} 196 | 197 | vendor 198 | 199 | 2024-08-08T06:30:00 200 | 201 | 202 | 203 | 204 | \endcode 205 | - Run 206 | \code 207 | vidx2pidx vendor.vidx 208 | \endcode 209 | to create the \c index.pidx. 210 | - Run 211 | \code 212 | cpackget init -R packroot index.pidx 213 | \endcode 214 | to create a new pack root directory with only the packs from the \c index.pidx. 215 | - Run 216 | \code 217 | cpackget list -p -R packroot 218 | \endcode 219 | to show all packs and check if the process was successful. 220 | - Install all listed packs using 221 | \code 222 | cpackget add -R packroot 223 | \endcode 224 | to check if all packs can be downloaded and installed. 225 | 226 | \subsection cp_PackRehosting Rehosting a pack 227 | 228 | Sometimes, it is necessary to rehost a pack (moving a pack from one URL to another). Rehosting implies changing the \elem{url} 229 | element in the PDSC file. To ensure that the pack is found by a \ref cp_KeilComPack "Pack Index Service", follow this procedure: 230 | - Create a new version of the pack: update the \elem{vendor}.\elem{name}.pdsc file with the new \elem{url} ("url_B") and a new 231 | \ref element_release "\" tag with an incremented version. 232 | - Place a copy of this latest \elem{vendor}.\elem{name}.pdsc file at url_B and url_A (the original URL). 233 | - Add this new PDSC file to an updated \elem{vendor}.\elem{name}.\elem{version}.pack (needs to match the version number in 234 | the PDSC file). 235 | - Copy the new \elem{vendor}.\elem{name}.\elem{version}.pack \b only to url_B. 236 | - Copy all previous packs from url_A to url_B (so that they are available at the new location). 237 | - Inform Arm about the new URL by either: 238 | - updating the \elem{vendor}.pidx with url_B for this pack \em or 239 | - emailing a link to the new PDSC file if your company does not maintain a \elem{vendor}.pidx 240 | 241 | \note 242 | - The PDSC file and all pack versions need to be accessible from the same new URL ("url_B"). 243 | - Arm recommends to keep the url_A alive for at least six months so that users have time to pick up the change. Be aware 244 | that users who have not noticed the change might be unable to find pack updates once url_A have become unavailable. 245 | 246 | \subsection cp_PackRenaming Renaming a pack 247 | 248 | Sometimes, it is necessary to rename a pack (because the pack vendor and/or its name have changed for example). To ensure 249 | that the pack is found by a \ref cp_KeilComPack "Pack Index Service" and the tools, follow this procedure: 250 | - Create a new: 251 | - PDSC file with the updated \elem{name} and/or \elem{vendor}, for example NewVendor.NewName.pdsc. The 252 | \elem{version} should start at 1.0.0. 253 | - pack containing the new PDSC file with the corresponding \elem{name} and/or \elem{vendor}, for example 254 | NewVendor.NewName.1.0.0.pack. 255 | - Create a new: 256 | - version of the old PDSC file (Vendor.Name.pdsc) with a new \elem{release} tag (with an updated version), 257 | containing the \elem{deprecated} and \elem{replacement} element. The latter pointing to the "NewVendor.NewName". 258 | - version of the old \elem{vendor}.\elem{name}.\elem{version}.pack file with the PDSC you have created above. 259 | - Copy: 260 | - all four files (new PDSC and pack, updated old PDSC and pack) to the \elem{url} location. 261 | 262 | \note 263 | - Using this approach, you can only do a one-to-one pack replacement. 264 | - If you want to create more than one replacement pack for a given source pack, you need to work with 265 | \ref element_requirements_pg "requirements". 266 | 267 | \section packIndexFile Pack index files 268 | 269 | CMSIS-Pack is designed as a web-based distribution network. Each provider of a CMSIS-Pack (also referred to as \a vendor) is 270 | responsible for hosting, maintaining and publishing unique versions of a CMSIS-Pack. 271 | 272 | A CMSIS-Pack is uniquely identified by \.\.\.pack. All published versions of a pack and the 273 | PDSC file need to be available in the same web folder specified by \elem{url}. Multiple different packs may be located in the 274 | same web folder. 275 | 276 | \subsection pidxFile Package index file (PIDX) 277 | 278 | The package index file lists all CMSIS-Packs hosted and maintained by a vendor. The file is hosted by the vendor and has the 279 | name \.pidx. The \ tag needs to match the file name. The file also contains the \elem{url} to it's origin, as 280 | well as a \ of it's last update. 281 | 282 | It is the vendor's obligation to update this file whenever: 283 | - a new pack is added. 284 | - a new version of a pack is added. 285 | - a pack is deprecated. 286 | - a replacement for a pack becomes available. 287 | 288 | \b MyVendor.pidx example 289 | 290 | \code{.xml} 291 | 292 | 293 | 294 | MyVendor 295 | https://www.MyVendor.com/pack/ 296 | 2024-01-25T15:00:10.7300074+00:00 297 | 298 | 299 | ... 300 | 301 | 302 | \endcode 303 | 304 | Each individual pack is referenced by the attributes: 305 | - \elem{url} = web folder where the PDSC and packs reside. 306 | - \elem{vendor} = vendor of the pack. 307 | - \elem{name} = the name of the pack. 308 | - \elem{version} = the version number of the latest available release for the pack. 309 | 310 | The package index file for the CMSIS-Pack compliant packs, hosted on www.keil.com can be found here: 311 | https://www.keil.com/pack/Keil.pidx. 312 | 313 | The benefit of a single package index file is, that this file only needs to be exchanged once and can be polled for updates 314 | 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 315 | CMSIS@arm.com attaching a version of the \.pidx file. 316 | 317 | \subsection vidxFile Vendor index file (VIDX) 318 | 319 | A vendor index file lists package index files from different vendors. This information can be used to compile a list of known 320 | packs. 321 | 322 | \b MyVendor.vidx example 323 | 324 | \code{.xml} 325 | 326 | 327 | 328 | MyVendor 329 | www.MyVendor.com/pack 330 | 2024-01-08T10:30:00 331 | 332 | 333 | ... 334 | 335 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | -------------------------------------------------------------------------------- /doxygen/templates/check.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/templates/check.png -------------------------------------------------------------------------------- /doxygen/templates/cmsis_footer.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 15 | 16 | 17 | 18 | 19 | 20 | -------------------------------------------------------------------------------- /doxygen/templates/cmsis_footer.js: -------------------------------------------------------------------------------- 1 | function writeFooter() { 2 | document.write('Generated on {datetime} for {projectName} {projectNumber} by Arm Ltd. All rights reserved.'); 3 | }; 4 | -------------------------------------------------------------------------------- /doxygen/templates/cmsis_header.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | $title 7 | $projectname: $title 8 | $title 9 | 10 | 11 | 12 | 13 | 14 | $treeview 15 | $search 16 | $mathjax 17 | 18 | 19 |
20 | 21 |
22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 35 | 36 | 37 | 38 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 |
30 |
$projectname 31 |  $projectnumber 32 |
33 |
$projectbrief
34 | 		39 |
$projectbrief
40 | 		$searchbox
51 |
52 | 53 | 54 | -------------------------------------------------------------------------------- /doxygen/templates/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | -------------------------------------------------------------------------------- /doxygen/templates/navtree.css: -------------------------------------------------------------------------------- 1 | 2 | #nav-tree ul { 3 | list-style:none outside none; 4 | margin:0px; 5 | padding:0px; 6 | } 7 | 8 | #nav-tree li { 9 | white-space:nowrap; 10 | margin:0px; 11 | padding:0px; 12 | vertical-align: middle; 13 | } 14 | 15 | #nav-tree .plus { 16 | margin:0px; 17 | } 18 | 19 | #nav-tree .selected { 20 | background-image: url('tab_a.png'); 21 | background-repeat:repeat-x; 22 | color: #fff; 23 | text-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); 24 | } 25 | 26 | #nav-tree img { 27 | margin:0px; 28 | padding:0px; 29 | border:0px; 30 | } 31 | 32 | #nav-tree a { 33 | text-decoration:none; 34 | padding:0px; 35 | margin-top:0px; 36 | outline:none; 37 | } 38 | 39 | #nav-tree .label { 40 | margin:0px; 41 | padding:0px; 42 | font: 12px 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; 43 | 44 | } 45 | 46 | #nav-tree .label a { 47 | padding:2px; 48 | 49 | } 50 | 51 | #nav-tree .selected a { 52 | text-decoration:none; 53 | color:#fff; 54 | } 55 | 56 | #nav-tree .children_ul { 57 | margin:0px; 58 | padding:0px; 59 | } 60 | 61 | #nav-tree .item { 62 | margin:0px; 63 | padding:0px; 64 | } 65 | 66 | #nav-tree { 67 | padding: 0px 0px; 68 | padding-left: 10px; /*correction to add space before the first arrow in nav-tree */ 69 | background-color: #FAFAFF; 70 | font-size:14px; 71 | overflow:auto; 72 | } 73 | 74 | #doc-content { 75 | overflow:auto; 76 | display:block; 77 | padding:0px; 78 | margin:0px; 79 | -webkit-overflow-scrolling : touch; /* iOS 5+ */ 80 | } 81 | 82 | #side-nav { 83 | padding:0 6px 0 0; 84 | margin: 0px; 85 | display:block; 86 | position: absolute; 87 | left: 0px; 88 | width: 300px; 89 | } 90 | 91 | .ui-resizable .ui-resizable-handle { 92 | display:block; 93 | } 94 | 95 | .ui-resizable-e { 96 | background:url("splitbar.png") repeat scroll right center transparent; 97 | 98 | cursor:e-resize; 99 | height:100%; 100 | right:0; 101 | top:0; 102 | width:6px; 103 | } 104 | 105 | .ui-resizable-handle { 106 | display:none; 107 | font-size:0.1px; 108 | position:absolute; 109 | z-index:1; 110 | } 111 | 112 | #nav-tree-contents { 113 | margin: 6px 0px 0px 0px; 114 | } 115 | 116 | #nav-tree { 117 | background-image:url('nav_h.png'); 118 | background-repeat:repeat-x; 119 | background-color: #F9FAFC; 120 | } 121 | #nav-sync { 122 | position:absolute; 123 | top:5px; 124 | right:24px; 125 | z-index:0; 126 | } 127 | 128 | #nav-sync img { 129 | opacity:0.0; 130 | } 131 | 132 | #nav-sync img:hover { 133 | opacity:0.0; 134 | } 135 | @media print 136 | { 137 | #nav-tree { display: none; } 138 | div.ui-resizable-handle { display: none; position: relative; } 139 | } -------------------------------------------------------------------------------- /doxygen/templates/search.css: -------------------------------------------------------------------------------- 1 | /*---------------- Search Box */ 2 | 3 | #FSearchBox { 4 | float: left; 5 | } 6 | 7 | #searchli { 8 | float: right; 9 | display: block; 10 | width: 170px; 11 | height: 24px; 12 | } 13 | 14 | #MSearchBox { 15 | white-space : nowrap; 16 | position: absolute; 17 | float: none; 18 | display: inline; 19 | margin-top: 3px; 20 | right: 0px; 21 | width: 170px; 22 | z-index: 102; 23 | } 24 | 25 | #MSearchBox .left 26 | { 27 | display:block; 28 | position:absolute; 29 | left:10px; 30 | width:20px; 31 | height:19px; 32 | background:url('search_l.png') no-repeat; 33 | background-position:right; 34 | } 35 | 36 | #MSearchSelect { 37 | display:block; 38 | position:absolute; 39 | width:20px; 40 | height:19px; 41 | } 42 | 43 | .left #MSearchSelect { 44 | left:4px; 45 | } 46 | 47 | .right #MSearchSelect { 48 | right:5px; 49 | } 50 | 51 | #MSearchField { 52 | display:block; 53 | position:absolute; 54 | height:19px; 55 | background:url('search_m.png') repeat-x; 56 | border:none; 57 | width:116px; 58 | margin-left:20px; 59 | padding-left:4px; 60 | color: #909090; 61 | outline: none; 62 | font: 9pt Arial, Verdana, sans-serif; 63 | } 64 | 65 | #FSearchBox #MSearchField { 66 | margin-left:15px; 67 | } 68 | 69 | #MSearchBox .right { 70 | display:block; 71 | position:absolute; 72 | right:10px; 73 | top:0px; 74 | width:20px; 75 | height:19px; 76 | background:url('search_r.png') no-repeat; 77 | background-position:left; 78 | } 79 | 80 | #MSearchClose { 81 | display: none; 82 | position: absolute; 83 | top: 4px; 84 | background : none; 85 | border: none; 86 | margin: 0px 4px 0px 0px; 87 | padding: 0px 0px; 88 | outline: none; 89 | } 90 | 91 | .left #MSearchClose { 92 | left: 6px; 93 | } 94 | 95 | .right #MSearchClose { 96 | right: 2px; 97 | } 98 | 99 | .MSearchBoxActive #MSearchField { 100 | color: #000000; 101 | } 102 | 103 | /*---------------- Search filter selection */ 104 | 105 | #MSearchSelectWindow { 106 | display: none; 107 | position: absolute; 108 | left: 0; top: 0; 109 | border: 1px solid #90A5CE; 110 | background-color: #F9FAFC; 111 | z-index: 1; 112 | padding-top: 4px; 113 | padding-bottom: 4px; 114 | -moz-border-radius: 4px; 115 | -webkit-border-top-left-radius: 4px; 116 | -webkit-border-top-right-radius: 4px; 117 | -webkit-border-bottom-left-radius: 4px; 118 | -webkit-border-bottom-right-radius: 4px; 119 | -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); 120 | } 121 | 122 | .SelectItem { 123 | font: 8pt Arial, Verdana, sans-serif; 124 | padding-left: 2px; 125 | padding-right: 12px; 126 | border: 0px; 127 | } 128 | 129 | span.SelectionMark { 130 | margin-right: 4px; 131 | font-family: monospace; 132 | outline-style: none; 133 | text-decoration: none; 134 | } 135 | 136 | a.SelectItem { 137 | display: block; 138 | outline-style: none; 139 | color: #000000; 140 | text-decoration: none; 141 | padding-left: 6px; 142 | padding-right: 12px; 143 | } 144 | 145 | a.SelectItem:focus, 146 | a.SelectItem:active { 147 | color: #000000; 148 | outline-style: none; 149 | text-decoration: none; 150 | } 151 | 152 | a.SelectItem:hover { 153 | color: #FFFFFF; 154 | background-color: #3D578C; 155 | outline-style: none; 156 | text-decoration: none; 157 | cursor: pointer; 158 | display: block; 159 | } 160 | 161 | /*---------------- Search results window */ 162 | 163 | iframe#MSearchResults { 164 | width: 60ex; 165 | height: 15em; 166 | } 167 | 168 | #MSearchResultsWindow { 169 | display: none; 170 | position: absolute; 171 | left: 0; top: 0; 172 | border: 1px solid #000; 173 | background-color: #EEF1F7; 174 | } 175 | 176 | /* ----------------------------------- */ 177 | 178 | 179 | #SRIndex { 180 | clear:both; 181 | padding-bottom: 15px; 182 | } 183 | 184 | .SREntry { 185 | font-size: 10pt; 186 | padding-left: 1ex; 187 | } 188 | 189 | .SRPage .SREntry { 190 | font-size: 8pt; 191 | padding: 1px 5px; 192 | } 193 | 194 | body.SRPage { 195 | margin: 5px 2px; 196 | } 197 | 198 | .SRChildren { 199 | padding-left: 3ex; padding-bottom: .5em 200 | } 201 | 202 | .SRPage .SRChildren { 203 | display: none; 204 | } 205 | 206 | .SRSymbol { 207 | font-weight: bold; 208 | color: #425E97; 209 | font-family: Arial, Verdana, sans-serif; 210 | text-decoration: none; 211 | outline: none; 212 | } 213 | 214 | a.SRScope { 215 | display: block; 216 | color: #425E97; 217 | font-family: Arial, Verdana, sans-serif; 218 | text-decoration: none; 219 | outline: none; 220 | } 221 | 222 | a.SRSymbol:focus, a.SRSymbol:active, 223 | a.SRScope:focus, a.SRScope:active { 224 | text-decoration: underline; 225 | } 226 | 227 | .SRPage .SRStatus { 228 | padding: 2px 5px; 229 | font-size: 8pt; 230 | font-style: italic; 231 | } 232 | 233 | .SRResult { 234 | display: none; 235 | } 236 | 237 | DIV.searchresults { 238 | margin-left: 10px; 239 | margin-right: 10px; 240 | } 241 | -------------------------------------------------------------------------------- /doxygen/templates/tab_topnav.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/2441c1a16945dcd3f7fe1a0d44e3d7860807106c/doxygen/templates/tab_topnav.png -------------------------------------------------------------------------------- /doxygen/templates/tabs.css: -------------------------------------------------------------------------------- 1 | .tabs, .tabs1, .tabs2, .tabs3, .main_nav { 2 | background-image: url('tab_b.png'); 3 | width: 100%; 4 | z-index: 101; 5 | font-size: 10px; 6 | } 7 | 8 | .tabs1 { 9 | background-image: url('tab_topnav.png'); 10 | font-size: 12px; 11 | } 12 | 13 | .tabs2 { 14 | font-size: 10px; 15 | } 16 | .tabs3 { 17 | font-size: 9px; 18 | } 19 | 20 | .tablist, .main-menu { 21 | margin: 0; 22 | padding: 0; 23 | display: table; 24 | line-height: 24px; 25 | } 26 | 27 | .tablist li { 28 | float: left; 29 | display: table-cell; 30 | background-image: url('tab_b.png'); 31 | list-style: none; 32 | margin:0px; 33 | } 34 | 35 | .tabs1 .tablist li { 36 | 37 | background-image: url('tab_topnav.png'); 38 | 39 | } 40 | 41 | .tablist a { 42 | display: block; 43 | padding: 0 20px; 44 | font-weight: bold; 45 | background-image:url('tab_s.png'); 46 | background-repeat:no-repeat; 47 | background-position:right; 48 | color: #283A5D; 49 | text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); 50 | text-decoration: none; 51 | outline: none; 52 | } 53 | 54 | .tabs1 .tablist a { 55 | padding: 0 10px; 56 | } 57 | 58 | .tablist a:hover { 59 | background-image: url('tab_h.png'); 60 | background-repeat:repeat-x; 61 | color: #fff; 62 | text-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); 63 | text-decoration: none; 64 | } 65 | 66 | .tablist li.current a { 67 | background-image: url('tab_a.png'); 68 | background-repeat:repeat-x; 69 | color: #fff; 70 | text-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); 71 | } 72 | -------------------------------------------------------------------------------- /schema/PackIndex.xsd: -------------------------------------------------------------------------------- 1 | 2 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | -------------------------------------------------------------------------------- /test/pack_schema_version_history.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python3 2 | # -*- coding: utf-8 -*- 3 | 4 | import re 5 | import subprocess 6 | import sys 7 | from pathlib import Path 8 | 9 | from dateutil.parser import parse 10 | 11 | DIRNAME = Path(__file__).parent.absolute() 12 | PATTERN = "::error file={},line={}::{}" 13 | 14 | rc = 0 15 | 16 | 17 | def log_error(file, line, message): 18 | global rc 19 | print(PATTERN.format(file.relative_to(DIRNAME.joinpath("..").resolve()), line, message)) 20 | rc = 1 21 | 22 | 23 | def get_from_cmd(cmd, cwd=Path.cwd()): 24 | print("./"+cwd.relative_to(Path.cwd()).as_posix(), "$", " ".join(cmd)) 25 | result = subprocess.run(cmd, capture_output=True, cwd=cwd) 26 | stdout = result.stdout.decode("utf-8").strip() 27 | stderr = result.stderr.decode("utf-8").strip() 28 | if stdout: 29 | print(">", stdout) 30 | if stderr: 31 | print(">", stderr) 32 | print() 33 | return stdout 34 | 35 | 36 | def main(): 37 | print("Checking PACK.xsd version information...\n") 38 | 39 | schema_file = DIRNAME.joinpath('../schema/PACK.xsd').resolve() 40 | dxy_file = DIRNAME.joinpath('../doxygen/pack.dxy').resolve() 41 | doc_file = DIRNAME.joinpath('../doxygen/src/General.txt').resolve() 42 | 43 | date_pattern = re.compile('\\$Date:\\s+(\\d+\\. \\w+ \\d{4})') 44 | rev_pattern = re.compile('\\$Revision:\\s+(\\d+\\.\\d+\\.\\d+)') 45 | version_pattern = re.compile('SchemaVersion=(\\d+\\.\\d+\\.\\d+)') 46 | history_pattern = re.compile('(\\d+\\. \\w+ \\d{4}): v(\\d+\\.\\d+\\.\\d+)') 47 | property_pattern = re.compile('^\\s*\\s*$') 48 | 49 | date = (None, 0) 50 | revision = (None, 0) 51 | version = (None, 0) 52 | history = (None, 0) 53 | xsproperty = (None, 0) 54 | 55 | with(open(schema_file)) as schema: 56 | for i, line in enumerate(schema): 57 | date = (date_pattern.search(line), i) if not date[0] else date 58 | revision = (rev_pattern.search(line), i) if not revision[0] else revision 59 | version = (version_pattern.search(line), i) if not version[0] else version 60 | history = (history_pattern.search(line), i) if not history[0] else history 61 | xsproperty = (property_pattern.search(line), i) if not xsproperty[0] else xsproperty 62 | 63 | date = (parse(date[0][1]), date[1] + 1) if date[0] else None 64 | revision = (revision[0][1], revision[1] + 1) if revision[0] else None 65 | version = (version[0][1], version[1] + 1) if version[0] else None 66 | history = (parse(history[0][1]), history[0][2], history[1] + 1) if history[0] else None 67 | xsproperty = (xsproperty[0][1], xsproperty[1] + 1) if xsproperty[0] else None 68 | 69 | author_date = parse(get_from_cmd(['git', 'log', '-1', '--pretty=%ad', '--date=format:%Y-%m-%d', schema_file.name], 70 | cwd=schema_file.parent)) 71 | base_rev = get_from_cmd(['git', 'merge-base', 'ORIG_HEAD', 'HEAD'], cwd=schema_file.parent) 72 | head_rev = get_from_cmd(['git', 'log', '-1', '--pretty=%H', schema_file.name], cwd=schema_file.parent) 73 | blame = get_from_cmd(['git', 'blame', f"{base_rev}..{head_rev}", '-l', '-L', f"{revision[1]},{revision[1]}", 74 | schema_file.name], cwd=schema_file.parent) 75 | blamed_rev = blame.split(' ')[0] 76 | 77 | dxy_version_pattern = re.compile('PROJECT_NUMBER\s*=\s*"Version (\\d+\\.\\d+\\.\\d+)"') 78 | 79 | dxy_version = (None, 0) 80 | with(open(dxy_file)) as dxy: 81 | for i, line in enumerate(dxy): 82 | dxy_version = (dxy_version_pattern.search(line), i) if not dxy_version[0] else dxy_version 83 | dxy_version = (dxy_version[0][1], dxy_version[1] + 1) if dxy_version[0] else None 84 | 85 | history_version_pattern = re.compile('(\\d+\\.\\d+\\.\\d+)') 86 | history_version = dict() 87 | with(open(doc_file)) as doc: 88 | accept = False 89 | for i, line in enumerate(doc): 90 | if line == '\n': 91 | accept = True 92 | if accept: 93 | if line == '
': 94 | break 95 | v = history_version_pattern.search(line) 96 | if v: 97 | history_version[i + 1] = v[1] 98 | 99 | if not date: 100 | log_error(schema_file, 0, "Modification date tag '$Date:
. ' missing or wrong format!") 101 | elif date[0] != author_date: 102 | log_error(schema_file, date[1], "Modification date tag not updated, " 103 | f"should be '{author_date.strftime('%d. %b %Y')}'!") 104 | 105 | if not revision: 106 | log_error(schema_file, 0, "Latest version tag '$Revision: ..' missing or wrong format!") 107 | elif blamed_rev.startswith('^') and blamed_rev[1:] != head_rev[:-1]: 108 | log_error(schema_file, revision[1], f"Revision tag not updated, should be incremented!") 109 | else: 110 | if not version: 111 | log_error(schema_file, 0, "Schema version tag 'SchemaVersion='.. missing or wrong format!") 112 | elif version[0] != revision[0]: 113 | log_error(schema_file, version[1], f"Schema version tag not updated, should be '{revision[0]}' instead if '{version[0]}'!") 114 | 115 | if not history: 116 | log_error(schema_file, 0, "Change history '
. : ..' missing or wrong format!") 117 | elif history[1] != revision[0] or history[0] != author_date: 118 | log_error(schema_file, history[2], "Change history not updated, should contain " 119 | f"'{author_date.strftime('%d. %B %Y')}: v{revision[0]}'!") 120 | if not xsproperty: 121 | log_error(schema_file, 0, "xs:schema property 'version' missing!") 122 | elif xsproperty[0] != revision[0]: 123 | log_error(schema_file, xsproperty[1], f"xs:schema property 'version' not updated, should be '{revision[0]}' instead of '{xsproperty[0]}'!") 124 | 125 | if not dxy_version: 126 | log_error(dxy_version, 0, "Doxygen setting 'PROJECT_VERSION = \"Version ..\"' missing!") 127 | elif dxy_version[0] != revision[0]: 128 | log_error(dxy_file, dxy_version[1], f"Doxygen setting 'PROJECT_VERSION' not updated, should be 'Version {revision[0]}' instead of '{dxy_version[0]}'!") 129 | 130 | if revision[0] not in history_version.values(): 131 | line = sorted(history_version.keys())[0] 132 | log_error(doc_file, line, "Revision History not updated, should contain " 133 | f"table row for version {revision[0]}") 134 | 135 | 136 | if __name__ == "__main__": 137 | if 'schema/PACK.xsd' in sys.argv \ 138 | or 'test/pack_schema_version_history.py' in sys.argv: 139 | main() 140 | 141 | sys.exit(rc) 142 | --------------------------------------------------------------------------------