Add 'dmctl'

2021-07-30 17:34:35 +00:00 · 2021-07-30 17:34:35 +00:00 · 40b34e741d
parent d10f6a1b25
commit 40b34e741d
1 changed files with 123 additions and 0 deletions
--- a/dmctl.md
+++ b/dmctl.md
@ -0,0 +1,123 @@
+`dmctl` is the host-side utility for configuring the device at runtime. It can be used to query device info, switch to another mode, or perform a few mode-specific commands.
+
+### General usage
+
+The `dmctl.sh` script can be found in the `host/` directory in the source tree.
+
+```
+$ ./dmctl.sh --help
+usage: dmctl [-h] [--conn CONN] subcommand ...
+
+optional arguments:
+  -h, --help       show this help message and exit
+  --conn CONN      Connection string. Either a dmj-char device in /dev, a USB
+                   bus.device number, or a USB VID:PID pair. Defaults to trying
+                   /dev/dmj-* (if there is only one), and cafe:1312 otherwise.
+
+subcommands:
+  For more info on each subcommand, run the program with 'subcommand --help' as
+  arguments.
+
+  subcommand       Command to send to the device
+    get-device-info
+                   Shows device info
+    get-mode-info  Shows mode info. A mode can optionally be specified, default
+                   is the current mode.
+    set-mode       Set the device mode
+    uart-cts-rts   Get, enable/disable UART hardware flow control
+    tempsensor     Get or set the IRC emulation enable/address of the
+                   temperature sensor.
+    jtag-scan      JTAG pinout scanner
+    sump-overclock
+                   SUMP logic analyzer overclock settings
+```
+
+### General subcommands
+
+#### get-device-info
+
+Shows general device information. No other arguments required. Example:
+
+```
+$ ./dmctl.sh get-device-info
+CMSIS-DAP (RP2040 Pico): protocol version: 00.10, currently in mode 1 (Default mode with misc features)
+available modes: 1, 4
+```
+
+#### get-mode-info
+
+Gets info of a specific mode. An extra mode number can be specified, but it defaults to the current mode. Using `all` as mode number displays the information of all available modes. Example:
+
+```
+$ ./dmctl.sh get-mode-info 
+mode 1: Default mode with misc features: version 00.10 with features 1, 2, 3, 4
+$ ./dmctl.sh get-mode-info 4
+mode 4: SUMP logic analyzer mode: version 00.10 with no features 
+$ ./dmctl.sh get-mode-info 42
+No mode 42 available
+$ ./dmctl.sh get-mode-info all
+mode  1: Default mode with misc features: version 00.10 with features 1, 2, 3, 4
+mode  4: SUMP logic analyzer mode: version 00.10 with no features 
+```
+
+#### set-mode
+
+This subcommand changes the device mode. Do note that this causes the device to temporarily disconnect for about one half to one second, in order to reconfigure its interface descriptor tables. Example:
+
+```
+$ ./dmctl.sh set-mode 4
+```
+
+### Mode 1-specific subcommands
+
+#### uart-cts-rts
+
+Enable or disable UART hardware flow control. Example:
+
+```
+$ ./dmctl.sh uart-cts-rts --get
+Flow control disabled
+$ ./dmctl.sh uart-cts-rts --enable
+$ ./dmctl.sh uart-cts-rts --disable
+$ ./dmctl.sh uart-cts-rts --set [true|false|0|1]
+```
+
+#### tempsensor
+
+Configures the device address of the emulated I2C temperature sensor device. Example:
+
+```
+$ ./dmctl.sh tempsensor --get
+Temperature sensor I2C emulation disabled
+$ ./dmctl.sh tempsensor --set 0x18
+Temperature sensor I2C device changed from disabled to 0x18
+$ ./dmctl.sh tempsensor --get
+Temperature sensor I2C device at address 0x18
+$ ./dmctl.sh tempsensor --disable
+Temperature sensor I2C device changed from 0x18 to disabled
+```
+
+### Mode 3-specific subcommands
+
+#### jtag-scan
+
+TODO
+
+### Mode 4-specific subcommands
+
+#### sump-overclock
+
+This subcommand can be used to get or set the SUMP logic analyzer sampling overclock settings. The actual meaning of the values passed depends on the hardware used. Example:
+
+```
+$ ./dmctl.sh sump-overclock --get
+0
+$ ./dmctl.sh sump-overclock --enable
+$ ./dmctl.sh sump-overclock --get
+1
+$ ./dmctl.sh sump-overclock --set 0
+```
+
+The setting is a single byte. However, a number of hardware platforms have a binary "enable/disable" option, for which `--enable`/`--disable` flag are made available. These simply set the byte value to 0 or 1.
+
+On the Raspberry Pico, only 0 and nonzero are available as options, which resp. mean overclocking disabled (133 MHz) and enabled (200 MHz). Sampling happens at 1/4th of the system clock, thus, with overclocking enabled, the sample rate becomes 50 MHz.