From: Simon Ruderich Date: Fri, 3 Oct 2025 08:41:45 +0000 (+0200) Subject: Add README X-Git-Url: https://ruderich.org/simon/gitweb/?a=commitdiff_plain;h=cdb8ebec7833e8a49234d9ada92965ffe47f6656;p=svdpoke%2Fsvdpoke.git Add README --- diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..41b9018 --- /dev/null +++ b/README.adoc @@ -0,0 +1,123 @@ += README + +svdpoke is a small program which loads ARM CMSIS-SVD files and displays MCU +register values and their meanings. In combination with openocd it can load +the live register value from a connected MCU. It is written in Python and +licensed under GPLv3+. + +It uses the https://github.com/cmsis-svd/cmsis-svd[cmsis-svd] library to parse +CMSIS-SVD files (licensed under Apache License v2.0). To interact with +https://openocd.sourceforge.io/[openocd] it connects to its local Telnet port +(4444). + +svdpoke was inspired by esynr3z's +https://github.com/esynr3z/openocd-svd[openocd-svd]; its name was inspired by +https://www.jemarch.net/poke[GNU poke] which provides similar functionality +but for binary files. + +https://open-cmsis-pack.github.io/svd-spec/main/[ARM CMSIS-SVD] files can be +downloaded from the vendor. Many SVD files are collected in the following +repositories: https://github.com/cmsis-svd/cmsis-svd-data and +https://github.com/modm-io/cmsis-svd-stm32 + + +== Usage + +Display a single register and use `0x1C000600` as register value. + + $ svdpoke --svd STM32L496.svd --value 0x1C000600 RCC_CSR + RCC_CSR @ 0x40021094 (0x40021000 + 0x94) = 0x1C000600: + 31 LPWRSTF = 0b0 0x0 0 r Low-power reset flag + 30 WWDGRSTF = 0b0 0x0 0 r Window watchdog reset flag + 29 IWDGRSTF = 0b0 0x0 0 r Independent window watchdog reset flag + 28 SFTRSTF = 0b1 0x1 1 r Software reset flag + 27 BORRSTF = 0b1 0x1 1 r BOR flag + 26 PINRSTF = 0b1 0x1 1 r Pin reset flag + 25 OBLRSTF = 0b0 0x0 0 r Option byte loader reset flag + 24 FIREWALLRSTF = 0b0 0x0 0 r Firewall reset flag + 23 RMVF = 0b0 0x0 0 rw Remove reset flag + 11:8 MSISRANGE[3:0] = 0b0110 0x6 6 rw SI range after Standby mode + 1 LSIRDY = 0b0 0x0 0 r LSI oscillator ready + 0 LSION = 0b0 0x0 0 rw LSI oscillator enable + +Same, but load the value via `openocd` from a connected MCU: + + $ svdpoke --svd STM32L496.svd --openocd RCC_CSR + [Same output, omitted] + +To show all registers of a peripheral specify only its name (can be combined +with `--openocd` to load the values): + + $ svdpoke --svd STM32L496.svd RCC + RCC_CR @ 0x40021000 (0x40021000 + 0x0): + 29 PLLSAI2RDY r SAI2 PLL clock ready flag + 28 PLLSAI2ON rw SAI2 PLL enable + 27 PLLSAI1RDY r SAI1 PLL clock ready flag + [...] + RCC_ICSCR @ 0x40021004 (0x40021000 + 0x4): + 30:24 HSITRIM[6:0] rw HSI clock trimming + 23:16 HSICAL[7:0] r HSI clock calibration + 15:8 MSITRIM[7:0] rw MSI clock trimming + [...] + RCC_CFGR @ 0x40021008 (0x40021000 + 0x8): + 30:28 MCOPRE[2:0] r Microcontroller clock output prescaler + 26:24 MCOSEL[2:0] rw Microcontroller clock output + 15 STOPWUCK rw Wakeup from Stop and CSS backup clock selection + [...] + +Multiple registers or peripherals can be given at the same time (also works +with `--openocd`): + + $ svdpoke --svd STM32L496.svd RCC LPTIM1_IER LPTIM1_CFGR + [...] + +To show all available peripherals give no arguments: + + $ svdpoke --svd STM32L496.svd + DAC @ 0x40007400: Digital-to-analog converter + DMA1 @ 0x40020000: Direct memory access controller + DMA2 @ 0x40020400: Direct memory access controller + [...] + +The path to the SVD file can also be stored in the `SVDPOKE_SVD` environment +variable: + + $ export SVDPOKE_SVD="$(pwd)/STM32L496.svd" + $ svdpoke + [Same output, omitted] + + +== Installation + +cmsis-svd needs the Python libraries lxml and six, on Debian and derivatives +these are available in `python3-lxml` and `python3-six`. + +Clone this repository with submodules (for the cmsis-svd library) and then put +`svdpoke.py` in your `$PATH` (or simply run `./svdpoke.py`). + +Alternatively you can use a virtual environment: + + $ python3 -mvenv .venv + $ . .venv/bin/activate + (.venv)$ pip install cmsis-svd + (.venv)$ ./svdpoke.py + + +== License + +This program is licensed under GPL version 3 or later. + +Copyright (C) 2025 Simon Ruderich + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . diff --git a/svdpoke.py b/svdpoke.py index 0f26256..a0042e7 100755 --- a/svdpoke.py +++ b/svdpoke.py @@ -1,9 +1,8 @@ #!/usr/bin/env python3 -# svdpoke uses SVD files to display MCU register values and their meanings, -# including the current value if given. It can also be used in combination -# with openocd to connect to a MCU and read the register values directly from -# the connected device. +# svdpoke is a small program which loads ARM CMSIS-SVD files and displays MCU +# register values and their meanings. In combination with openocd it can load +# the live register value from a connected MCU. # SPDX-License-Identifier: GPL-3.0-or-later # Copyright (C) 2025 Simon Ruderich