README.adoc

   1 = README
   2
   3 svdpoke is a small program which loads ARM CMSIS-SVD files and displays MCU
   4 register values and their meanings. In combination with OpenOCD it can load
   5 the live register value from a connected MCU. It is written in Python and
   6 licensed under GPLv3+.
   7
   8 It uses the https://github.com/cmsis-svd/cmsis-svd[cmsis-svd] library to parse
   9 CMSIS-SVD files (licensed under Apache License v2.0). To interact with
  10 https://openocd.sourceforge.io/[OpenOCD] it connects to its local Telnet port
  11 (4444).
  12
  13 svdpoke was inspired by esynr3z's
  14 https://github.com/esynr3z/openocd-svd[openocd-svd]; its name was inspired by
  15 https://www.jemarch.net/poke[GNU poke] which provides similar functionality
  16 but for binary files.
  17
  18 https://open-cmsis-pack.github.io/svd-spec/main/[ARM CMSIS-SVD] files can be
  19 downloaded from the vendor. Many SVD files are collected in the following
  20 repositories: https://github.com/cmsis-svd/cmsis-svd-data and
  21 https://github.com/modm-io/cmsis-svd-stm32
  22
  23
  24 == Usage
  25
  26 Display a single register and use `0x1C000600` as register value.
  27
  28     $ svdpoke --svd STM32L496.svd --value 0x1C000600 RCC_CSR
  29     RCC_CSR @ 0x40021094 (0x40021000 + 0x94) = 0x1C000600:
  30        31 LPWRSTF        =    0b0 0x0 0 r  Low-power reset flag
  31        30 WWDGRSTF       =    0b0 0x0 0 r  Window watchdog reset flag
  32        29 IWDGRSTF       =    0b0 0x0 0 r  Independent window watchdog reset flag
  33        28 SFTRSTF        =    0b1 0x1 1 r  Software reset flag
  34        27 BORRSTF        =    0b1 0x1 1 r  BOR flag
  35        26 PINRSTF        =    0b1 0x1 1 r  Pin reset flag
  36        25 OBLRSTF        =    0b0 0x0 0 r  Option byte loader reset flag
  37        24 FIREWALLRSTF   =    0b0 0x0 0 r  Firewall reset flag
  38        23 RMVF           =    0b0 0x0 0 rw Remove reset flag
  39      11:8 MSISRANGE[3:0] = 0b0110 0x6 6 rw SI range after Standby mode
  40         1 LSIRDY         =    0b0 0x0 0 r  LSI oscillator ready
  41         0 LSION          =    0b0 0x0 0 rw LSI oscillator enable
  42
  43 Same, but load the value via `openocd` from a connected MCU:
  44
  45     $ svdpoke --svd STM32L496.svd --openocd RCC_CSR
  46     [Same output, omitted]
  47
  48 To show all registers of a peripheral specify only its name (can be combined
  49 with `--openocd` to load the values):
  50
  51     $ svdpoke --svd STM32L496.svd RCC
  52     RCC_CR @ 0x40021000 (0x40021000 + 0x0):
  53       29 PLLSAI2RDY    r  SAI2 PLL clock ready flag
  54       28 PLLSAI2ON     rw SAI2 PLL enable
  55       27 PLLSAI1RDY    r  SAI1 PLL clock ready flag
  56     [...]
  57     RCC_ICSCR @ 0x40021004 (0x40021000 + 0x4):
  58      30:24 HSITRIM[6:0] rw HSI clock trimming
  59      23:16 HSICAL[7:0]  r  HSI clock calibration
  60       15:8 MSITRIM[7:0] rw MSI clock trimming
  61     [...]
  62     RCC_CFGR @ 0x40021008 (0x40021000 + 0x8):
  63      30:28 MCOPRE[2:0] r  Microcontroller clock output prescaler
  64      26:24 MCOSEL[2:0] rw Microcontroller clock output
  65         15 STOPWUCK    rw Wakeup from Stop and CSS backup clock selection
  66     [...]
  67
  68 Multiple registers or peripherals can be given at the same time (also works
  69 with `--openocd`):
  70
  71     $ svdpoke --svd STM32L496.svd RCC LPTIM1_IER LPTIM1_CFGR
  72     [...]
  73
  74 To show all available peripherals give no arguments:
  75
  76     $ svdpoke --svd STM32L496.svd
  77     DAC           @ 0x40007400: Digital-to-analog converter
  78     DMA1          @ 0x40020000: Direct memory access controller
  79     DMA2          @ 0x40020400: Direct memory access controller
  80     [...]
  81
  82 The path to the SVD file can also be stored in the `SVDPOKE_SVD` environment
  83 variable:
  84
  85     $ export SVDPOKE_SVD="$(pwd)/STM32L496.svd"
  86     $ svdpoke
  87     [Same output, omitted]
  88
  89
  90 == Installation
  91
  92 cmsis-svd needs the Python libraries lxml and six, on Debian and derivatives
  93 these are available in `python3-lxml` and `python3-six`.
  94
  95 Clone this repository with submodules (for the cmsis-svd library) and then put
  96 `svdpoke.py` in your `$PATH` (or simply run `./svdpoke.py`).
  97
  98 Alternatively you can use a virtual environment:
  99
 100     $ python3 -mvenv .venv
 101     $ . .venv/bin/activate
 102     (.venv)$ pip install cmsis-svd
 103     (.venv)$ ./svdpoke.py
 104
 105
 106 == License
 107
 108 This program is licensed under GPL version 3 or later.
 109
 110 Copyright (C) 2025  Simon Ruderich
 111
 112 This program is free software: you can redistribute it and/or modify
 113 it under the terms of the GNU General Public License as published by
 114 the Free Software Foundation, either version 3 of the License, or
 115 (at your option) any later version.
 116
 117 This program is distributed in the hope that it will be useful,
 118 but WITHOUT ANY WARRANTY; without even the implied warranty of
 119 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 120 GNU General Public License for more details.
 121
 122 You should have received a copy of the GNU General Public License
 123 along with this program.  If not, see <http://www.gnu.org/licenses/>.