13.5.2 About creating the flash method Python script

For the purposes of this example the Python script is called example_flash.py.

  • Start by importing the objects required in the script:
from flashprogrammer.flash_method_v1 import FlashMethodv1
from com.arm.debug.flashprogrammer import TargetStatus
  • Then, define the class implementing the method:
class ExampleFlashWriter(FlashMethodv1): 
    def __init__(self, methodServices): 
        FlashMethodv1.__init__(self, methodServices) 
 
    def setup(self): 
        # perform any setup for the method here 
        pass 
 
    def teardown(self): 
        # perform any clean up for the method here 
        # return the target status 
        return TargetStatus.STATE_RETAINED 
 
    def program(self, regionID, offset, data): 
        # program a block of data to the flash 
        # regionID indicates the region within the device (as defined in the flash configuration file) 
        # offset is the byte offset within the region 
 
        # perform programming here 
 
        # return the target status 
        return TargetStatus.STATE_RETAINED

Note

  • The __init__ function is the constructor and is called when the class instance is created.
  • methodServices allows the method to make calls into the flash programmer - it should not be accessed directly.
  • FlashMethodv1 provides functions that the method can call while programming.
  • The program() and teardown() methods should return a value that describes the state the target has been left in.
    This can be one of:
    • STATE_RETAINED - The target state has not been altered from the state when programming started. In this state, the register and memory contents have been preserved or restored.
    • STATE_LOST - Register and memory contents have been altered, but a system reset is not required.
    • RESET_REQUIRED - It is recommended or required that the target be reset.
    • POWER_CYCLE_REQUIRED - It is required that the target be manually power cycled. For example, when a debugger-driven reset is not possible or not sufficient to reinitialize the target.

Creating the target platform setup and teardown scripts

If the hardware platform requires some setup (operations to be performed before flash programming) and/or teardown (operations to be performed after flash programming) functionality, you must create one or more scripts which contain setup() and teardown() functions. These can be in separate script files or you can combine them into a single file. This file should be placed into the configdb Flash directory so that it can be referenced using a FDB:// prefix in the flash configuration file.
For example, the contents of a single file which contains both the setup() and teardown() functions would be similar to:
from com.arm.debug.flashprogrammer.IFlashClient import MessageLevel 
from flashprogrammer.device import ensureDeviceOpen 
from flashprogrammer.execution import ensureDeviceStopped 
from flashprogrammer.device_memory import writeToTarget  

def setup(client, services):
     # get a connection to the core
     conn = services.getConnection()
     dev = conn.getDeviceInterfaces().get("Cortex-M3")
     ensureDeviceOpen(dev)
     ensureDeviceStopped(dev)
	 # Perform some target writes to enable flash programming
     writeToTarget(dev, FLASH_EN, intToBytes(0x81))  

def teardown(client, services):
     # get a connection to the core
     conn = services.getConnection()
     dev = conn.getDeviceInterfaces().get("Cortex-M3")
     ensureDeviceOpen(dev)
     ensureDeviceStopped(dev)
	 # Perform some target writes to disable flash programming
     writeToTarget(dev, FLASH_EN, intToBytes(0))

Creating the flash configuration file

To use the method to program flash, a configuration file must be created that describes the flash device, the method to use and any parameters or other information required. This is an .xml file and is typically stored in the same directory as the target's other configuration files ( Boards/<Manufacturer>/<Board name> ) as it contains target-specific information.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> 
<flash_config 
    xmlns:xi="http://www.w3.org/2001/XInclude" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns="http://www.arm.com/flash_config" 
    xsi:schemaLocation="http://www.arm.com/flash_config flash_config.xsd"> 
    <devices> 
        <device name="Example"> 
            <regions> 
                <region address="0x8000" size="0x10000"/> 
            </regions> 
            <programming_type type="FILE"> 
                <method language="JYTHON" script="FDB://example_flash.py" class="ExampleFlashWriter" method_config="Default"/> 
                <setup script="FDB://file_target.py" method="setup"/> 
                <teardown script="FDB://file_target.py" method="teardown"/> 
            </programming_type> 
        </device> 
    </devices> 
    <method_configs> 
        <method_config id="Default"> 
            <params> 
                <!-- Use last 2K of RAM --> 
                <param name="ramAddress" type="integer" value="0x00100000"/> 
                <param name="ramSize" type="integer" value="0x800"/> 
            </params> 
        </method_config> 
    </method_configs> 
</flash_config>
  • The flash_config tag defines used XML spaces and schema. This does not usually need to be changed. Under the flash_config tag, a devices tag is required. This contains a number of device tags, each representing one flash device on the target. The device tag defines the name of the device - this is the name reported by the info flash command and is used only when programming to a specific device. It also defines a number of regions where the flash device appears in the target's memory - the addresses of each region are matched against the address of each load region of the image being programmed.
  • The programming_type tag defines the programming method and setup/teardown scripts to be used for a flash programming operation. Currently, only FILE is supported.
  • The method tag defines the script which implements the programming method. Currently, only JYTHON is supported for the language attribute. The script and class attributes define which script file to load and the name of the class that implements the programming method within the script. The method_config attributes define which set of parameters are used by the device. This allows multiple devices to share a set of parameters.
  • The programming_type may also have optional setup and teardown tags. These define a script and a method within that script to call before or after flash programming.
  • Within the method_configs tag, the parameters for each device are contained within method_config tags.
  • Parameters must have a unique name and a default value. You can override the value passed to the method. See the help for the flash load command within the DS-5 Debugger.
  • Where the configuration file references another file, for example, the script files, the FDB:// prefix indicates that the file is located in the Flash subdirectory of the configuration database. If there are multiple databases, then the Flash subdirectory of each database is searched until the file is found.
  • The last file that needs to be changed is the project_types.xml file in the target's directory to tell DS-5 that the flash configuration can be found in the file created above. The following line should be added under the top-level platform_data tag:
    <flash_config>CDB://flash.xml</flash_config>
    The CDB:// prefix tells DS-5 that the flash.xml file is located in the same directory as the project_types.xml file.
Non-ConfidentialPDF file icon PDF versionARM DUI0446W
Copyright © 2010-2015 ARM. All rights reserved.