Skip to content

Commit c8f4eb8

Browse files
VincentDaryVincentDary
committed
version 1.0
- Add CHANGELOG file. - Add AUTHOR file. - The banner licence of each file has been changed to 'Copyright 2015-2024 cmsis-svd Authors' - Add CMSIS SVD XML Schema Definition files for versions: 1.0, 1.1, 1.2, 1.3.1, 1.3.2, 1.3.3, 1.3.4, 1.3.5, 1.3.6, 1.3.7, 1.3.8, 1.3.9, 1.3.10, 1.3.11. Schema 1.3.11 is unofficial for the moment, but officially in review by the svd spec maintainers, and brings major fixes, see @ckudera PR in Open-CMSIS-Pack/svd-spec#14 . - Add CMSIS SVD Python model XML serializer SVDXmlSerializer, which is a refactored and modified version of the SVD XML serializer from the SVDSuite project. - CMSIS SVD Python model improvements: * CMSIS SVD spec support up to 1.3.11. * Model classes are now based on Python dataclass. * New SVD data types: SVDReadActionType, SVDModifiedWriteValuesType, SVDEnumUsageType, SVDEndianType, SVDDataTypeType, SVDAddressBlockUsageType, SVDAccessType, SVDSauAccessType, SVDProtectionType, SVDCPUNameType. * Add XML serializer methods: to_xml(), to_xml_file(), to_xml_node(). * Add JSON serializer methods: to_json(), to_json_file(). * Add new methods to access to peripherals, registers and fields: SVDDevice.get_peripherals(), SVDPeripheral.get_registers(), SVDRegister.get_fields() * Python type hint and PEP8 review. - CMSIS SVD Python parser improvements: * Add method for standalone SVD XML validation via: validate_xml_tree(), validate_xml_file() and validate_xml_str(). * Add flexible XML data validation to SVDParser.get_device() via xml_validation, schema_version and schema_version_detection parameters. * Add parsing for SVD XML device tag attributes: namespace and noNamespaceSchemaLocation * Python type hint and PEP8 review. - CMSIS SVD Python: * Add pyproject.toml to avoid pip install deprecation warning. * Replace Python dev-requirements.txt file by a DEV 'extras_require' in setup.py. * Python README improvements. * Move Python 'tests' and 'exemples' directories to the root of the Python package. - Fix regex SyntaxWarning message during bitfield range parsing. Reported by @brainstorm in #185 (comment) - Fix incompatibility with the CMSIS-SVD schema for enumeratedValues in fieldType. Reported by @gschwaer in #185 (comment) - Fix improper register field filtering based on 'reserved' field name. Reported by @BenBE in #185 (comment) - Fix for path traversal (CWE-22 and related) in SVDParser.for_packaged_svd() Reported by @BenBE in #185 (review) Fix proposal by @ckudera in #185 (comment)
1 parent 38d21d3 commit c8f4eb8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+154705
-86809
lines changed

‎.github/workflows/test.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jobs:
2222
- name: Install Dependencies
2323
run: |
2424
cd python
25-
pip install -r dev-requirements.txt
25+
pip install --editable .[DEV]
2626
- name: Run Unit Tests
2727
run: |
2828
cd python

‎AUTHORS‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The cmsis-svd team would like to acknowledge the following contributors:
2+
3+
Paul Osborne (@posborne) (Project initiator and main maintainer)
4+
Vincent Dary (@VincentDary) (core maintainer)
5+
Christian Kudera (@ckudera) (core maintainer)
6+
Benny Baumann (@BenBE) (core maintainer)
7+
Roman Valls Guimera (@brainstorm) (core maintainer)
8+
Odin Holmes (@odinthenerd)
9+
Ivan Kolesnikov (@KivApple)
10+
Niklas Hauser (@salkinium)
11+
Andrew Scheller (@lurch)
12+
Sylvain Pelissier (@sylvainpelissier)
13+
Ethan Slattery (@CrustyAuklet)
14+
Justin Clift (@justinclift)
15+
Stefan Hölzl (@stefan-hoelzl)
16+
Joakim Nohlgård (@jnohlgard)
17+
Robbe Derks (@robbederks)
18+
John Yu (@byu9)
19+
Taylor Hillegeist (@taylorh140)
20+
Gero Schwäricke (@gschwaer)
21+
Clement Calmels (@ccalmels)

‎CHANGELOG‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
This file details the changelog of CMSIS-SVD project.
2+
3+
--------------------------------------------------------------------------------
4+
5+
[version 1.0]
6+
7+
Fix and Improvements:
8+
9+
- version 1.0 new design, code factoring and improvements: https://github.com/cmsis-svd/cmsis-svd/pull/185
10+
- Add CHANGELOG file.
11+
- Add AUTHOR file.
12+
- The banner licence of each file has been changed to 'Copyright 2015-2024 cmsis-svd Authors'
13+
- Add CMSIS SVD XML Schema Definition files for versions:
14+
1.0, 1.1, 1.2, 1.3.1, 1.3.2, 1.3.3, 1.3.4, 1.3.5, 1.3.6, 1.3.7, 1.3.8, 1.3.9, 1.3.10, 1.3.11.
15+
Schema 1.3.11 is unofficial for the moment, but officially in review by the svd spec maintainers,
16+
and brings major fixes, see @ckudera PR in https://github.com/Open-CMSIS-Pack/svd-spec/pull/14 .
17+
- Add CMSIS SVD Python model XML serializer SVDXmlSerializer, which is a refactored
18+
and modified version of the SVD XML serializer from the SVDSuite project.
19+
- CMSIS SVD Python model improvements:
20+
* CMSIS SVD spec support up to 1.3.11.
21+
* Model classes are now based on Python dataclass.
22+
* New SVD data types: SVDReadActionType, SVDModifiedWriteValuesType,
23+
SVDEnumUsageType, SVDEndianType, SVDDataTypeType, SVDAddressBlockUsageType,
24+
SVDAccessType, SVDSauAccessType, SVDProtectionType, SVDCPUNameType.
25+
* Add XML serializer methods: to_xml(), to_xml_file(), to_xml_node().
26+
* Add JSON serializer methods: to_json(), to_json_file().
27+
* Add new methods to access to peripherals, registers and fields:
28+
SVDDevice.get_peripherals(), SVDPeripheral.get_registers(), SVDRegister.get_fields()
29+
* Python type hint and PEP8 review.
30+
- CMSIS SVD Python parser improvements:
31+
* Add method for standalone SVD XML validation via: validate_xml_tree(),
32+
validate_xml_file() and validate_xml_str().
33+
* Add flexible XML data validation to SVDParser.get_device() via xml_validation,
34+
schema_version and schema_version_detection parameters.
35+
* Add parsing for SVD XML device tag attributes: namespace and noNamespaceSchemaLocation
36+
* Python type hint and PEP8 review.
37+
- CMSIS SVD Python:
38+
* Add pyproject.toml to avoid pip install deprecation warning.
39+
* Replace Python dev-requirements.txt file by a DEV 'extras_require' in setup.py.
40+
* Python README improvements.
41+
* Move Python 'tests' and 'exemples' directories to the root of the Python package.
42+
- Fix regex SyntaxWarning message during bitfield range parsing.
43+
Reported by @brainstorm in https://github.com/cmsis-svd/cmsis-svd/pull/185#issuecomment-2375592693
44+
- Fix incompatibility with the CMSIS-SVD schema for enumeratedValues in fieldType.
45+
Reported by @gschwaer in https://github.com/cmsis-svd/cmsis-svd/pull/185#issuecomment-1937233034
46+
- Fix improper register field filtering based on 'reserved' field name.
47+
Reported by @BenBE in https://github.com/cmsis-svd/cmsis-svd/pull/185#discussion_r1797755026
48+
- Fix for path traversal (CWE-22 and related) in SVDParser.for_packaged_svd()
49+
Reported by @BenBE in https://github.com/cmsis-svd/cmsis-svd/pull/185#pullrequestreview-2364230915
50+
Fix proposal by @ckudera in https://github.com/cmsis-svd/cmsis-svd/pull/185#issuecomment-2408710944
51+
52+
- format display_name with dim_indices: https://github.com/cmsis-svd/cmsis-svd/pull/187
53+
According to the SVD specification: https://www.keil.com/pack/doc/CMSIS/SVD/html/elem_registers.html#elem_register,
54+
the 'displayName' child element of the register element can also take advantage
55+
of the '%s' syntax. The only difference with 'name' is that 'displayName' is optional.
56+
This patch duplicates the logic used by 'name' for 'displayName'. Because it
57+
is not clear if 'displayName' must contain '%s' let's handle any error.
58+
59+
- Remove cmsis svd data directory: https://github.com/cmsis-svd/cmsis-svd/pull/182
60+
* Remove the data directory which takes up too much space.
61+
* Adjust the cmsis-svd files path for Python test and examples, to handle a cloned data directory.
62+
* README update for examples using the data directory.
63+
* A Github test workflow update for cloning the git repository cmsis-svd-data, required for test purpose.
64+
65+
66+
New to the cmsis-svd Github organisation and Core Maintainers of this project:
67+
68+
- Christian Kudera (@ckudera)
69+
- Benny Baumann (@BenBE)
70+
- Roman Valls Guimera (@brainstorm)
71+
72+
73+
New to the Pypi Python Package Maintainer:
74+
75+
- Vincent Dary (@VincentDary)
76+
77+
78+
New contributors:
79+
- Clement Calmels (@ccalmels) made their first contribution in https://github.com/cmsis-svd/cmsis-svd/pull/187
80+
- Roman Valls Guimera (@brainstorm) made their first contribution in https://github.com/cmsis-svd/cmsis-svd/pull/185#issuecomment-2375592693
81+
82+
83+
Thanks:
84+
85+
- Paul Osborne (@posborne)
86+
- Christian Kudera (@ckudera)
87+
- Benny Baumann (@BenBE)
88+
- Roman Valls Guimera (@brainstorm)
89+
- Gero Schwäricke (@gschwaer)
90+
- Clement Calmels (@ccalmels)
91+
- Vincent Dary (@VincentDary)
92+
- @jvogl-dev
93+
- @AJ528
94+
95+
96+
Again, thanks for all contributors and sorry if I missed your name here (please tell me @VincentDary !)

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,13 @@ It provides parsers that make code generation and tooling based on SVD
99
easier to build. Most parsers simply parse a provided SVD file and
1010
turn it into a data structure more easily used in that language.
1111

12+
- [Python Package](https://github.com/cmsis-svd/cmsis-svd)
13+
1214
What is CMSIS-SVD
1315
-----------------
1416

1517
ARM provides the following description of
16-
[CMSIS-SVD (System View Description)](http://www.keil.com/pack/doc/CMSIS/SVD/html/index.html)
18+
[CMSIS-SVD (System View Description)](https://open-cmsis-pack.github.io/svd-spec/main/index.html)
1719

1820
> The CMSIS System View Description format(CMSIS-SVD) formalizes the
1921
> description of the system contained in ARM Cortex-M processor-based

‎python/MANIFEST.in‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
include README.md
2-
include README.rst
2+
recursive-include cmsis_svd/schemas *

‎python/README.md‎

Lines changed: 118 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,117 +1,170 @@
1-
Python CMSIS SVD Parser
2-
=======================
1+
# Python CMSIS-SVD
32

4-
This directory contains the code for a CMSIS SVD parser in Python.
5-
The parser is able to read in an input SVD and provide Python objects
3+
This directory contains the code for a CMSIS SVD Python parser and serializers.
4+
The parser is able to read in an input SVD and provide a Python data structures
65
containing the information from the SVD. This frees the developer
76
(you) from having to worry about the SVD XML and each vendor's little
8-
quirks.
7+
quirks. The serializers are able to dump the CMSIS SVD Python data structures to
8+
the SVD XML file format or to the JSON format.
99

10-
Install It
11-
----------
10+
## Install
1211

1312
You can install the latest stable version from pypi:
1413

15-
```sh
14+
```text
1615
pip install -U cmsis-svd
1716
```
1817

19-
To install the latest development version by doing. If this fails,
20-
you may need to update the version of pip you are using.
18+
To install the latest development version by doing.
2119

22-
```sh
23-
pip install -U -e 'git+https://github.com/posborne/cmsis-svd.git#egg=cmsis-svd&subdirectory=python'
20+
```text
21+
pip install -U -e 'git+https://github.com/cmsis-svd/cmsis-svd.git#egg=cmsis-svd&subdirectory=python'
2422
```
2523

26-
Note: Changes from Version 0.4
27-
------------------------------
24+
If this fails, you may need to update the version of pip you are using.
25+
26+
## Note: Changes from Version 0.4
2827

2928
For a very long period of time (2016-2023), the pypi package for cmsis-svd was out
3029
of data and included a large number of "bundled" SVD files. This has only grown and
3130
with the 0.5 release, those are no longer included as part of the python
3231
distributable. Other means of providing access to the SVD definitions may be
3332
revisited in the future.
3433

35-
Example
36-
-------
3734

38-
There's a lot of information you can glean from the SVDs for various
39-
platforms. Let's say, for instance, that I wanted to see the names
40-
and base address of each peripheral on the Freescale K20 (D7). Since the
41-
K20 SVD is packaged with the library, I can do the following:
35+
## Download CMSIS-SVD Files from the cmsis-svd Project
4236

43-
```python
44-
from cmsis_svd.parser import SVDParser
37+
The cmsis-svd project provides an aggregation of CMSIS-SVD files collected from
38+
silicon vendors in the [cmsis-svd-data](https://github.com/cmsis-svd/cmsis-svd-data)
39+
git repository. The next examples use CMSIS-SVD files from the CMSIS SVD data
40+
repository to illustrate usages of the cmsis-svd Python package. Clone the
41+
CMSIS SVD data repository to follow the next examples.
42+
43+
```text
44+
git clone --depth=1 -b main https://github.com/cmsis-svd/cmsis-svd-data.git
45+
```
4546

46-
SVD_DATA_DIR = "..."
4747

48-
parser = SVDParser.for_packaged_svd(SVD_DATA_DIR, 'Freescale', 'MK20D7.svd')
49-
for peripheral in parser.get_device().peripherals:
50-
print("%s @ 0x%08x" % (peripheral.name, peripheral.base_address))
48+
## Usage
49+
50+
There's a lot of information you can glean from the SVDs for various
51+
platforms. Let's say, for instance, that I wanted to parse and create a CMSIS
52+
SVD Python data structure for the Atmel SAM9CN11. Since the SAM9CN11 SVD is
53+
packaged in the CMSIS SVD data repository, I can do the following:
54+
55+
```pycon
56+
>>> SVD_DATA_DIR = "cmsis-svd-data/data"
57+
>>>
58+
>>> from cmsis_svd import SVDParser
59+
>>> parser = SVDParser.for_packaged_svd(SVD_DATA_DIR, 'Atmel', 'AT91SAM9CN11.svd')
60+
>>> SAM9CN11_device = parser.get_device()
61+
>>> type(SAM9CN11_device)
62+
<class 'cmsis_svd.model.SVDDevice'>
5163
```
5264

53-
This generates the following output:
65+
Alternatively, It is possible to validate the SAM9CN11 SVD XML file before
66+
parsing, specifying the `xml_validation` boolean flag to `get_device()`. In this
67+
case the `SVDParser` try to retrieve the XML schema version used by the file via
68+
the `schemaVersion` attribute of the `device` xml tag, otherwise if not found the
69+
last SVD XML schema version is used. Moreover, the validation step can be
70+
tailored to feet your need via the `schema_version` and
71+
`schema_version_detection` parameters, see the doc `help(SVDParser.get_device)`.
5472

73+
```pycon
74+
>>> SAM9CN11_device = parser.get_device(xml_validation=True)
5575
```
56-
FTFL_FlashConfig @ 0x00000400
57-
AIPS0 @ 0x40000000
58-
AIPS1 @ 0x40080000
59-
AXBS @ 0x40004000
60-
DMA @ 0x40008000
61-
FB @ 0x4000c000
62-
FMC @ 0x4001f000
63-
FTFL @ 0x40020000
64-
DMAMUX @ 0x40021000
65-
CAN0 @ 0x40024000
66-
SPI0 @ 0x4002c000
67-
SPI1 @ 0x4002d000
76+
77+
Below, an example to retrieve the names and base address of each peripheral for
78+
the Atmel SAM9CN11.
79+
80+
```pycon
81+
>>> for peripheral in SAM9CN11_device.get_peripherals():
82+
... print("%s @ 0x%08x" % (peripheral.name, peripheral.base_address))
83+
...
84+
SPI0 @ 0xf0000000
85+
SPI1 @ 0xf0004000
86+
HSMCI @ 0xf0008000
87+
AES @ 0xf000c000
6888
...
6989
```
7090

71-
Example 2: Convert to JSON
72-
--------------------------
91+
The Python data structures representing the SVD data provides a XML serializer
92+
via the `to_xml()` method:
93+
94+
```pycon
95+
>>> print(SAM9CN11_device.to_xml())
96+
<?xml version='1.0' encoding='utf-8'?>
97+
<device xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="CMSIS-SVD_Schema_1_1.xsd" schemaVersion="1.1">
98+
<vendor>Atmel</vendor>
99+
<name>AT91SAM9CN11</name>
100+
<series>SAM9CN</series>
101+
<version>20130208</version>
102+
...
103+
```
73104

74-
The data structures representing the SVD data have the ability to
75-
convert themselves to a dictionary suitable for serialization as
76-
JSON. This works recursively. To generate JSON data and pretty print
77-
it you can do something like the following:
105+
In addition, It is possible to produce an `lxml` element to customise the
106+
XML tree directly via the `to_xml_node()` method:
107+
108+
```pycon
109+
>>> device_element = SAM9CN11_device.to_xml_node()
110+
>>> type(device_element)
111+
<class 'lxml.etree._Element'>
112+
>>> device_element.tag
113+
'device'
114+
>>> device_element.find('name').text
115+
'AT91SAM9CN11'
116+
```
78117

79-
```python
80-
from cmsis_svd.parser import SVDParser
118+
The Python data structures representing the SVD data provides a JSON serializer
119+
via the `to_json()` method:
120+
121+
```pycon
122+
>>> print(SAM9CN11_device.to_json())
123+
{
124+
"access": null,
125+
"address_unit_bits": 8,
126+
"cpu": null,
127+
"description": "Atmel AT91SAM9CN11 device: ARM926EJ Embedded Microprocessor Unit, 400MHz, Crypto engine, LCD, USB, LPDDR/DDR2/MLC NAND support, 217 Pins (refer to http://www.atmel.com/devices/SAM9CN11.aspx for more)",
128+
"header_definitions_prefix": null,
129+
"header_system_filename": null,
130+
"license_text": null,
131+
"name": "AT91SAM9CN11",
132+
...
133+
```
81134

82-
SVD_DATA_DIR = "..."
135+
In addition, It is possible to produce a JSON serializable dictionary to
136+
customise the dict directly via the `to_dict()` method:
83137

84-
parser = SVDParser.for_packaged_svd(SVD_DATA_DIR, 'Freescale', 'MK20D7.svd')
85-
svd_dict = parser.get_device().to_dict()
86-
print(json.dumps(svd_dict, sort_keys=True,
87-
indent=4, separators=(',', ': ')))
138+
```pycon
139+
>>> device_dict = SAM9CN11_device.to_dict()
140+
>>> type(device_dict)
141+
<class 'dict'>
142+
>>> device_dict['name']
143+
'AT91SAM9CN11'
88144
```
89145

90-
Development
91-
-----------
146+
## Development
92147

93-
Once you have the code checked out, you can run the following from
94-
this directory to install dependencies:
148+
Once you have the code checked out, you can run the following command from
149+
the `python` directory to install the `cmsis-svd` Python package in editable
150+
mode with the development dependencies:
95151

96-
```sh
97-
virtualenv env
98-
source env/bin/activate
99-
pip install -r dev-requirements.txt
152+
```text
153+
cd cmsis-svd/python && pip install --editable .[DEV]
100154
```
101155

102156
Then, to run the tests:
103157

104-
```sh
158+
```text
105159
cd cmsis-svd/
106160
git clone --depth=1 https://github.com/cmsis-svd/cmsis-svd-data.git
107161
cd python/
108-
nose2 .
162+
nose2
109163
```
110164

111165
By default, tests will run in parallel according to the number of
112166
processors available on the system.
113167

114-
Contributing
115-
------------
168+
## Contributing
116169

117-
Please open issues and submit pull requests on Github.
170+
Please open [issues](https://github.com/cmsis-svd/cmsis-svd/issues) and submit [pull requests](https://github.com/cmsis-svd/cmsis-svd/pulls) on Github.

0 commit comments

Comments
 (0)