Update README.md

Author: pavelrevak

README.md

@@ -1,131 +1,188 @@
 # PYSWD
 
-Debugging MCUs over SWD with ST-Link/V2 debugger
+Is a python module for debugging microcontrollers with SWD using ST-Link/V2 (/V2-1) debugger.
 
-Allow to access to any SWD enabled MCU
+This package also contain small command line tool.
 
-## Instalation:
+## Goal
 
-`pip3 install .`
+Is to create python module for access debugging interface on MCU with SWD interface.
 
-or reinstall (upgrade):
+Main purpose of python module is to create automated functional and hardware tests from simple python scripts and without special firmware for microcontroller.
 
-`pip3 install --upgrade .`
+## Compatibility
 
-uninstall:
+### OS
+PYSWD will work on Linux, Mac and Windows.
+### Python
+Python 3.4+ (Development is under python 3.6)
+### Dependencies
+- [pyusb](https://github.com/walac/pyusb) - is installed automatically as dependency with pip
+- [libusb](https://github.com/libusb/libusb)
 
-`pip3 uninstall pyswd`
+## Installation:
+### from downloaded sources
+```
+pip3 install .
+```
+### reinstall (upgrade):
+```
+pip3 install --upgrade .
+```
+### uninstall:
+```
+pip3 uninstall pyswd
+```
 
 ## Python SWD module
 
-`import swd`
-
-Constructor for connected swd device:
-
-`dev = swd.Stlink()`
-
-All public methods from `swd.Stlink` class:
-
-`version`
-Instance of ST-Link version (property)
-
-`get_target_voltage(self)`
-Get target voltage from programmer
-
-`get_coreid(self)`
-Get core ID from MCU
-
-`get_reg(self, reg)`
-Get core register (R0, R1, ... )
-(CPU must be halted to access core registers)
-
-`set_reg(self, reg, data)`
-Set core register
-(CPU must be halted to access core registers)
-
-`get_mem32(self, addr)`
-Get memory register (32 bits)
-
-`set_mem32(self, addr, data)`
-Set memory register (32 bits)
-
-`read_mem(self, addr, size)`
-Read memory (output is iterable)
-
-`write_mem(self, addr, data)`
-Write memory, data can be iterable
-
-`fill_mem(self, addr, pattern)`
-Fill memory with pattern
-
-### Example:
-
+### Constructor:
+`swd.Stlink(swd_frequency=1800000, logger=None)`
+#### Arguments:
+- swd_frequency: SWD communication frequency
+- logger: logging interface (optional)
 ```Python
 >>> import swd
-
 >>> dev = swd.Stlink()
-
+```
+### ST-Link version
+property with ST-Link version
+#### Return
+  instance of StlinkVersion
+```Python
 >>> dev.version.str
 'ST-Link/V2 V2J27S6'
-
+```
+### Target voltage
+Get target voltage measured by ST-Link
+#### Return
+  float target voltage in volts
+```Python
 >>> dev.get_target_voltage()
 3.21
-
+```
+### Core ID
+Get MCU core ID
+#### Return
+  32bit unsigned with core ID
+```Python
 >>> hex(dev.get_coreid())
 '0xbb11477'
-
+```
+### Get memory register
+`get_mem32(address)`
+#### Arguments:
+- address: address in memory, must be aligned to 32bits
+#### Return:
+  32bit unsigned data from memory
+```Python
 >>> hex(dev.get_mem32(0x08000000))
 '0x20001000'
-
+```
+### Set memory register
+`set_mem32(address, data)`
+#### Arguments:
+- address: address in memory, must be aligned to 32bits
+- data: 32bit unsigned data
+```Python
 >>> dev.set_mem32(0x20000200, 0x12345678)
-
 >>> hex(dev.get_mem32(0x20000200))
 '0x12345678
-
+```
+### Read memory
+`read_mem(address, size)`
+#### Arguments:
+- address: address in memory
+- size: number of bytes to read from memory
+#### Return:
+  iterable of read data
+```Python
 >>> data = dev.read_mem(0x08000000, 16)
 >>> ' '.join(['%02x' % d for d in data])
 '00 10 00 20 45 00 00 08 41 00 00 08 41 00 00 08'
-
+```
+### Write memory
+`write_mem(address, data)`
+#### Arguments:
+- address: address in memory
+- data: list or iterable of bytes whic will be stored into memory
+```Python
 >>> dev.write_mem(0x20000100, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
-
 >>> data = dev.read_mem(0x20000100, 15)
 >>> ' '.join(['%02x' % d for d in data])
 '01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f'
-
+```
+### Fill memory
+`write_mem(address, size, pattern)`
+#### Arguments:
+- address: address in memory
+- size: number of bytes to fill memory
+- pattern: list or iterable of bytes whic will be stored into memory
+```Python
 >>> dev.fill_mem(0x20000300, 20, [5, 6, 7])
 >>> data = dev.read_mem(0x20000300, 20)
 >>> ' '.join(['%02x' % d for d in data])
 '05 06 07 05 06 07 05 06 07 05 06 07 05 06 07 05 06 07 05 06'
-
+```
+### Read core register
+`get_reg(register)`
+On CortexM platform this will work only if program is halted
+#### Arguments
+- register: is numeric coded register (e.g. 0: R0, 1: R1, ...)
+#### Return
+  32bit unsigned data
+```Python
+>>> hex(dev.get_reg(1))
+'0x0800012e'
+```
+### Write core register
+`get_reg(register)`
+On CortexM platform this will work only if program is halted
+#### Arguments
+- register: is numeric coded register (e.g. 0: R0, 1: R1, ...)
+- data: 32bit unsigned data
+```Python
 >>> hex(dev.get_reg(1))
 '0x0800012e'
 ```
 
 ## Python application
+Simple tool for access MCU debugging features from command line. Is installed together with python module.
 
-    $ pyswd --help
-    usage: pyswd [-h] [-V] [-q] [-d] [-i] [-v] [-f FREQ] [action [action ...]]
-
-    positional arguments:
-      action                actions will be processed sequentially
-
-    optional arguments:
-      -h, --help            show this help message and exit
-      -V, --version         show program's version number and exit
-      -q, --quite           quite output
-      -d, --debug           increase debug output
-      -i, --info            increase info output
-      -v, --verbose         increase verbose output
-      -f FREQ, --freq FREQ  set SWD frequency
+```
+$ pyswd --help
+```
+### Usage:
+```
+pyswd [-h] [-V] [-q] [-d] [-i] [-v] [-f FREQ] [action [action ...]]
+```
+### positional arguments:
+```
+action                actions will be processed sequentially
+```
+### Optional arguments:
+```
+-h, --help            show this help message and exit
+-V, --version         show program's version number and exit
+-q, --quite           quite output
+-d, --debug           increase debug output
+-i, --info            increase info output
+-v, --verbose         increase verbose output
+-f FREQ, --freq FREQ  set SWD frequency
+````
+### List of available actions:
+```
+dump8:{addr}[:{size}]     print content of memory 8 bit register or dump
+dump16:{addr}[:{size}]    print content of memory 16 bit register or dump
+dump32:{addr}[:{size}]    print content of memory 32 bit register or dump
+dump:{addr}[:{size}]      print content of memory 32 bit register or 8 bit dump
 
-    list of available actions:
-      dump8:{addr}[:{size}]     print content of memory 8 bit register or dump
-      dump16:{addr}[:{size}]    print content of memory 16 bit register or dump
-      dump32:{addr}[:{size}]    print content of memory 32 bit register or dump
-      dump:{addr}[:{size}]      print content of memory 32 bit register or 8 bit dump
+set8:{addr}:{data}[:{data}..]     set 8 bit memory
 
-      set8:{addr}:{data}[:{data}..]     set 8 bit memory
+fill8:{addr}:{size}:{pattern}     fill memory with 8 bit pattern
+```
+(numerical values can be in different formats, like: 42, 0x2a, 0o52, 0b101010, 32K, 1M, ..)
 
-      fill8:{addr}:{size}:{pattern}     fill memory with 8 bit pattern
+## License
+Whole project is under MIT license
 
-      (numerical values can be in different formats, like: 42, 0x2a, 0o52, 0b101010, 32K, 1M, ..)