Add README

diff --git a/README.adoc b/README.adoc
new file mode 100644 (file)
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 <http://www.gnu.org/licenses/>.

diff --git a/svdpoke.py b/svdpoke.py
index 0f2625663ef6c293ed5fc9a93aaf64d1d0f377c1..a0042e7fd3e6f927b8a64b950b0c773d9bf1982a 100755 (executable)
--- 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