Merge pull request #80 from sukidog/doc_changes

Doc improvements and additions

docs/DEVELOPERS-GUIDE.md

@@ -37,7 +37,7 @@ There are three defined ways in which DAPLink can be extended.  These are adding
 
 
 ## Test
-DAPLink has framework that allows automatic loading and testing of software on one or more boards. This can be run on the current development environment or a release package. Test results are written to the current directory, along with printed to the console. Testing is run from the run_test.py script in the test directory. For all testing options, see the run_test.py help output - ``run_test.py --help``. To run basic tests with the current development environment, see the steps below.
+DAPLink has a framework that allows automatic loading and testing of software on one or more boards. This can be run on the current development environment or a release package. Test results are written to the current directory and printed to the console. Tests are launched using the run_test.py script in the test directory. Specify --help to view testing options (``run_test.py --help``). To run basic tests with the current development environment, see the steps below.
 
 * Build the project to be tested.
 * [Enable automation mode](ENABLE_AUTOMATION.md) on the board if is has not been enabled already
@@ -55,4 +55,4 @@ DAPLink contains scripts to automate most of the steps of building a release.  I
 
 Note: A previous build can be reproduced by using the 'build_requirements.txt' of that build.
 To do this add the additional argument 'build_requirements.txt' when calling 'build_release_uvision.bat' in step 2.
-This will install and build with the exact version of the python packages used to create that build.
+This will install and build with the exact version of the python packages used to create that build.

docs/ENABLE_AUTOMATION.md

@@ -1,6 +1,6 @@
 # Enable Automation Features
 1. Update the interface software to a version at or above 0241
-2. Create an empty text file called "auto_on.cfg" on the drive while the reset button is held
-3. Release the reset button after the drive remounts and confirm "Automation Allowed" is set to 1 in details.txt
-4. Update the bootloader software to a version at or above 0241
-5. Confirm that "start_bl.act" causes the device to enter bootloader mode and "start_if.act" causes the device to enter interface mode
+1. Copy an empty text file called "auto_on.cfg" to the DAPLink MSD drive while the reset button is held.
+1. Release the reset button when the drive unmounts. When it remounts, confirm "Automation Allowed" is set to 1 in details.txt
+1. Update the bootloader software to a version at or above 0241
+1. Confirm that the "start_bl.act" MSD command causes the device to enter bootloader mode, and that the "start_if.act" command causes the device to enter interface mode. See [MSD Commands](MSD_COMMANDS.md)

docs/MSD_COMMANDS.md

@@ -0,0 +1,61 @@
+# MSD Commands
+
+DAPLink allows you to give it some simple commands via its MSD interface. By 
+copying a file with a certain name to the root of the DAPLink MSD drive, you 
+can get DAPLink to either perform an action or configure a flash-persisted 
+option. The contents of the file are ignored; you can pass it an empty file.
+
+These MSD commands work only if you are either holding down the RESET button 
+when you add the file to the MSD drive, or if you've turned on DAPLink's 
+automation-allowed mode. Of course, the way you turn on automation-allowed 
+mode is via an MSD command (see below).  So, you'll either hold the RESET 
+button each time you invoke an MSD command or you do so only once to turn 
+on automation-allowed mode. This mode is saved in flash and so it persists 
+across board reboots.
+
+By convention, files that end with ".act" trigger an action; files that end 
+with ".cfg" trigger an option change. The mechanism is case-insensitive.
+
+Every command completes by remounting the DAPLink MSD drive. Every command 
+is supported in both interface and bootload mode.
+
+`start_bl.act` This file will force DAPLink to remount in bootloader mode. 
+It is equivalent to unplugging the USB cable, and plugging it back in while 
+holding the RESET button. This command has no effect if DAPLink is already 
+in interface mode.
+
+`start_if.act` This file will force DAPLink to remount in interface mode. It 
+is equivalent to unplugging the USB cable and plugging it back in, when 
+DAPLink is currently in bootloader mode. This command has no effect if DAPLink 
+is already in bootloader mode.
+
+`auto_rst.cfg` This file will turn on Auto Reset mode. In this mode, the RESET 
+pin is automatically asserted after programming an application image to the 
+target processor flash via the DAPLink MSD drive (in interface mode). Note 
+that this mode does not affect when happens when you update the Hardware 
+Interface Circuit firmware (DAPLink) via the DAPLink MSD drive in bootloader 
+mode.
+
+`hard_rst.cfg` This file turns off Auto Reset mode.
+
+`assert.act` This file can be used to test DAPLink's assert utility. When you 
+copy this file to the DAPLink MSD drive, DAPLink generates a call to the 
+util_assert() method. An assert call causes the DAPLink MSD drive to remount
+with an additional file, ASSERT.TXT, appearing at the root of the drive. This file
+details where the assertion failure occurred (source file, line number). An
+assert call is a no-op if there is already an outstanding assert failure (there 
+can only be one). The outstanding assertion failure can be cleared by deleting
+ASSERT.TXT. The deletion causes a remount of the DAPLink MSD drive. In actuality, 
+any file operation (addition, deletion, content change) could be used to trigger 
+a DAPLink command. Deleting ASSERT.TXT is actually a DAPLink MSD command in its 
+own right.
+
+
+`refresh.act` This file forces a remount of the DAPLink MSD drive
+
+`auto_on.cfg` This file turns on automation-allowed mode. In this mode, DAPLink 
+MSD commands can be triggered without needing to hold down the RESET button 
+while copying the command file to the DAPLink MSD drive. Also, bootloader updates 
+are allowed only in automation-allowed mode.
+
+`auto_off.cfg` This file turns off automation-allowed mode.

docs/PORT_BOARD.md

@@ -8,7 +8,7 @@ A board is composed of a Hardware Interface Circuit and target MCU. To create a
         - records/board/myboardname.yaml
 ```
 
-Next create a new file in the `records/board` dirctory called myboardname.yaml. This file defines the target MCU and allows overrideable board parameters to be configured. The target MCU in this example exists and is a Nordic nRF51822 (16k RAM variant)
+Next create a new file in the `records/board` directory called myboardname.yaml. This file defines the target MCU and allows overrideable board parameters to be configured. The target MCU in this example exists and is a Nordic nRF51822 (16k RAM variant)
 
 ```yaml
 common:
@@ -46,4 +46,4 @@ This assumes there is already target support present in the codebase. If adding
 const char *board_id = "0000";
 ```
 
-Now running `progen generate -t uvision` will create project files including the new board that can be developed and debugged. For more information about the yaml format [see the project_generator documentation.](https://github.com/project-generator/project_generator/wiki/Getting_started)
+Now running `progen generate -t uvision` will create project files including the new board that can be developed and debugged. For more information about the yaml format [see the project_generator documentation.](https://github.com/project-generator/project_generator/wiki/Getting_started)

docs/PORT_TARGET.md

@@ -1,5 +1,5 @@
 # Adding A New Target
-Adding new target support requires creating a flash algo blob and the implementation for some stub functions. Target support is added to the `source/target/<mfg>/<target>` directory. At minimum, 3 files are needed. The first is `source/<mfg>/target_reset.c`
+Adding new target support requires creating a flash algo blob and the implementation for some stub functions. Target support is added to the `source/target/<mfg>/<target>` directory. At minimum, 3 files are needed. The first is `source/target/<mfg>/target_reset.c`
 
 ```c
 /**
@@ -50,7 +50,7 @@ uint8_t target_set_state(TARGET_RESET_STATE state)
 
 uint8_t security_bits_set(uint32_t addr, uint8_t *data, uint32_t size)
 {
-    // if there are security bits in the programmable flash reigon
+    // if there are security bits in the programmable flash region
     //	a check should be performed. This method is used when programming
     //	by drag-n-drop and should refuse to program an image requesting
     //	to set the device security. This can be performed with the debug channel
@@ -130,7 +130,7 @@ static const program_target_t flash = {
     0x20000000,                // location to write prog_blob in target RAM
     sizeof(targetname_blob),   // prog_blob size
     targetname_blob,           // address of prog_blob
-    0x00000200                 // ram_to_flash_bytes_to_be_written
+    0x00000200                 // program_buffer_size, largest size that can be written in a single call to program page
 };
 
 ```
@@ -176,4 +176,4 @@ const target_cfg_t target_device = {
 };
 ```
 
-At this point these target specific files could be added to a board build and developed.
+At this point these target specific files could be added to a board build and developed.