From 40d861447be7e648c268e347aa55baa736da74da Mon Sep 17 00:00:00 2001 From: John Cortell Date: Wed, 23 Mar 2016 21:52:09 -0500 Subject: [PATCH] Doc improvements and additions --- docs/DEVELOPERS-GUIDE.md | 4 +-- docs/ENABLE_AUTOMATION.md | 8 ++--- docs/MSD_COMMANDS.md | 61 +++++++++++++++++++++++++++++++++++++++ docs/PORT_BOARD.md | 4 +-- docs/PORT_TARGET.md | 8 ++--- 5 files changed, 73 insertions(+), 12 deletions(-) create mode 100644 docs/MSD_COMMANDS.md diff --git a/docs/DEVELOPERS-GUIDE.md b/docs/DEVELOPERS-GUIDE.md index 33a3cc5aa..958233839 100644 --- a/docs/DEVELOPERS-GUIDE.md +++ b/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. \ No newline at end of file diff --git a/docs/ENABLE_AUTOMATION.md b/docs/ENABLE_AUTOMATION.md index cce3ec6bc..829523598 100644 --- a/docs/ENABLE_AUTOMATION.md +++ b/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) \ No newline at end of file diff --git a/docs/MSD_COMMANDS.md b/docs/MSD_COMMANDS.md new file mode 100644 index 000000000..cb089e2e8 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/PORT_BOARD.md b/docs/PORT_BOARD.md index 6e1c39595..e72ff7ee3 100644 --- a/docs/PORT_BOARD.md +++ b/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) \ No newline at end of file diff --git a/docs/PORT_TARGET.md b/docs/PORT_TARGET.md index 8af4128e8..b37e47b8e 100644 --- a/docs/PORT_TARGET.md +++ b/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//` directory. At minimum, 3 files are needed. The first is `source//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//` directory. At minimum, 3 files are needed. The first is `source/target//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. \ No newline at end of file