Operating instruction manual Command Line Flasher

Hilscher Gesellschaft für Systemautomation mbH www.hilscher.com DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Table of contents 2/38

Table of contents 1 Introduction ...... 3 1.1 Description of the contents...... 3 1.2 List of revisions ...... 3 1.3 Conventions in this document ...... 4 2 Brief description ...... 5 3 Tested systems, devices and interfaces ...... 6 4 Downloading Flasher and USB drivers...... 8 5 Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional)...... 10 6 Connecting device and opening command line ...... 15 7 Syntax, commands and parameters ...... 16 7.1 Syntax ...... 16 7.2 Commands...... 17 7.3 Parameters and values ...... 19 8 Typical use cases ...... 21 8.1 Getting help...... 21 8.2 Showing list of interfaces ...... 23 8.3 Showing list of flash busses and units ...... 25 8.4 Writing a file to flash...... 27 8.5 Reading from flash ...... 30 8.6 Erasing area in flash device ...... 31 9 Legal notes ...... 32 List of Figures ...... 36 List of Tables...... 37 Contacts...... 38

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Introduction 3/38

1 Introduction

1.1 Description of the contents This document describes the Command Line Interface Flasher tool (CLI Flasher) for netX SoCs. It provides information about the flasher’s functions and parameters and step-by-step instructions for typical use cases.

1.2 List of revisions Index Date Author Revision 1 2020-01-21 MKE Document created Table 1: List of revisions

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Introduction 4/38

1.3 Conventions in this document Notes, operation instructions and results of operation steps are marked as follows:

Notes

Important:

Note:

Operation instructions 1. Ø Ø 2. Ø Ø

Results

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Brief description 5/38

2 Brief description The CLI Flasher is a command line tool for initial programming of flash memory devices of netX products. Its purpose is to write, read, erase or verify data from/into internal or external flash memory devices connected to the netX. The Flasher runs under Linux and Windows.

Note: The Command Line Flasher tool is written in C and LUA. It is open- source and licensed under GPL-2.0. The source code is hosted on GitHub: https://github.com/muhkuh-sys/org.muhkuh.tools-flasher. Executable packages are provided on GitHub for Windows 7 and in 32 and 64 bit and several Ubuntu versions in 32 and 64 bit.

Tested CLI Flasher versions are available on the Hilscher knowledge base (for further information, see section Downloading Flasher and USB drivers [} page 8] in this document). Note that the Command Line Flasher is a tool for advanced users. When used in combination with batch files, it allows the automation of the software flashing process during the “end-of-line” production of netX devices.

Note: The Flasher and its drivers are also included in the netX Studio CDT installation. netX Studio CDT features a graphical user interface plugin for the Flasher that allows you to use its functions conveniently by mouse-click in a GUI, instead of having to manually enter commands and parameters in a shell. For information on how to use the GUI-integrated Flasher of netX Studio CDT, see How to ... Use the Flasher tool section in the netX Studio CDT Getting started document.

The Flasher communicates directly with the ROM loader of the netX ASICs. The supported interfaces of the Flasher are a subset of the netX ROM loader console mode interfaces. Instructions on how to put your netX into console mode (in order to use these interfaces) are provided in the "How to" collection for CLI Flasher of the Hilscher knowledge base. Additionally, the Flasher also supports the JTAG interface of the netX. For using its JTAG interface, the netX does not need to be in console mode. Note that using the Flasher tool on a Windows PC requires the installation of certain Windows USB drivers in order to communicate with the netX via its USB interface, respectively via UART-to-USB or JTAG-to-USB FTDI converter. For further information on how to install these drivers, see section Downloading Flasher and USB drivers [} page 8] in this document. (If you want to use Olimex ARM-USB-TINY H or Amontec JTAGkey JTAG-to-USB debuggers for flashing, see also section Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional) [} page 10]).

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Tested systems, devices and interfaces 6/38

3 Tested systems, devices and interfaces

For up-to-date information, please check the release notes of your Flasher version in the knowledge base. Links to the individual Flasher versions are provided on the page: https://kb.hilscher.com/x/6zBbBg.

Supported operating systems · Windows 7 · Windows 10 · Linux

Tested Flash interfaces The following table provides an overview of the interfaces that are tested and verified for the current CLI Flasher release (V1.6.0). netX type External parallel flash External serial flash Internal flash eMMC / SD card Bus: -b 0 Bus: -b 1 Bus: -b 2 Bus: -b 3 netX 10 Tested units: -u 0 (SQI) Tested chip select: -cs 0 (default)

netX Tested units: Tested units: 100/500 -u 0 (SRamBus) -u 0 (SPI) Tested chip select: Tested chip select: -cs 0 (default) -cs 0 (default)

netX 50 Tested units: Tested units: -u 0 (SRamBus) -u 0 (SQI) Tested chip select: Tested chip select: -cs 0 (default) -cs 0 (default)

netX 51/52 Tested units: -u 0 (SQI) Tested chip select: -cs 0 (default)

netX Tested units: Tested units: 4000/4100 -u 0 (SQI) -u 0 (SDIO) Tested chip select: Tested chip select: -cs 0 (default) -cs 0 (default)

netX 90 Tested units: Tested units: -u 0 (SQI) -u 0 INTFLASH0 (COM CPU) Tested chip select: -u 1 INTFLASH1 (COM CPU) -cs 0 (default) -u 2 INTFLASH2 (APP CPU) -u 3 INTFLASH01 (combined INTFLASH of COM CPU) Tested chip select: -cs 0 (default)

netIOL Tested units: -u 0 (SQI) Tested chip select: -cs 0 (default) Table 2: Tested flash interfaces for CLI Flasher V1.6.0

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Tested systems, devices and interfaces 7/38

Supported netX interfaces netX type JTAG UART USB * Ethernet netX 10

netX 100/500

netX 50

netX 51/52

netX 4000/4100 netX 90

netIOL

Table 3: Supported netX interfaces CLI Flasher V1.6.0 * When connected via USB, netX 50, 51/52 and 4000/4100 present an USB-CDC device to the computer and appear as a serial device plugin (romloader_uart) in the CLI Flasher.

Note: You can use the list_interfaces command of the CLI Flasher to display a list of the interfaces that can be used to access your connected netX device (see section Commands [} page 17]).

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Downloading Flasher and USB drivers 8/38

4 Downloading Flasher and USB drivers This section describes how to download the CLI Flasher and its drivers.

Note: The Flasher and the drivers are also included in the netX Studio CDT installation package. This means that if you are a user of netX Studio CDT, you do not need to download the Flasher and its drivers separately as described in this section, but can instead use the Flasher included in your netX Studio CDT installation. You will find the command line flasher in the directory C:\ProgramData \Hilscher GmbH\netX Studio CDT\BuildTools\flasher \1.x.x (default path). The drivers should have been automatically installed during the setup process of netX Studio CDT.

1. Download CLI Flasher tool. Ø Go to the Command Line Interface Flasher (CLI Flasher) page: https://kb.hilscher.com/x/2zBbBg Ø In the Releases section, click on the link of the Current release, e.g. V1.x.x CLI Flasher Ê The page of the current release of the Flasher opens. Ø On the current release page, scroll down to the Download section and download the zip respectively tar file that is appropriate for your ; e.g. flasher_cli-1.6.0-windows_x86_64.zip. 2. Download USB drivers for Flasher tool. Ø In the Download section of the current release page, click the link under Use the USB drivers available under the following link. Ê The page of the current release of the USB drivers opens. Ø On the current driver release page, scroll down to the Download section and download the appropriate zip file; e.g. bootloader_windows_driver-2.x.x.zip.

Note: For the latest USB drivers, you can also go to the USB driver for Flasher CLI (muhkuh framework) page: https://kb.hilscher.com/x/8j7JBg, then click on the Current release link in the Releases section.

3. Unpack downloaded Flasher tool and the drivers. Ø Use an archive tool like e.g. 7-Zip to unpack the downloaded files. Ø Note that the Flasher tool is “portable” and does not need to be installed on your development laptop/PC. Just copy the unpacked flasher_cli-x.x.x folder to a directory that is convenient for you, e.g. C:\Tools\flasher_cli-1.6.0.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Downloading Flasher and USB drivers 9/38

4. Install USB drivers. Ø In the unpacked bootloader_windows_driver-x.x.x folder, open driver folder and double-click the setup file. Ø Allow the installer to make changes to your device and follow the instructions of the Muhkuh driver installation wizard.

Note: If you want to use the flasher with Olimex ARM-USB-TINY H or Amontec JTAGkey debuggers, see section Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional) [} page 10].

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional) 10/38

5 Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional)

Overview If you want to connect your netX to the CLI Flasher via Olimex ARM-USB- TINY H or Amontec JTAGkey JTAG-to-USB debuggers, you require a separate driver installation procedure. We recommend using a program called Zadig for this, which you can download from the web page http://zadig.akeo.ie/. Use version 2.3 or higher. Note that Zadig is an expert tool. Take care to select the correct devices when using it.

Installing driver for Olimex ARM-USB-TINY H Ø Connect the debugger to your development PC via USB. Ø Open Windows . Ê If no driver for the tool has been installed yet, the debugger is displayed under Other devices (it is displayed with two entries: as interface 0 and interface 1):

Figure 1: ARM-USB-TINY H in Device Manager without drivers (example in Windows 7)

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional) 11/38

Ø Open Zadig. Ê The Olimex debugger is displayed in the drop-down list:

Figure 2: Olimex debugger in Zadig

Note: If the Olimex debugger is not automatically displayed in the drop- down list, choose Options > List All Devices from the Menu, then select the Olimex debugger entry.

Ø Make sure that WinUSB is selected in the field to the right of the green arrow, then click Install Driver button. Ê The installation is started after a few seconds. Ø If the Windows security question for device software installation appears, allow the installation. Ø Repeat the installation for the second Olimex interface entry.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional) 12/38

Ê In the Windows Device Manager, the Olimex debugger should now be displayed under Universal Serial Bus devices:

Figure 3: ARM-USB-TINY H in Device Manager after driver installation (example in Windows 7) ð The debugger should now be ready to use.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional) 13/38

Installing driver for Amontec JTAGkey Ø Connect the debugger to your development PC via USB. Ø Open Windows Device Manager. Ê If no driver for the tool has been installed yet, the debugger is displayed under Other devices (it is displayed with two entries, one for interface 0 and one for interface 1):

Figure 4: Amontec JTAGkey in Device Manager without drivers (example in Windows 7) Ø Open Zadig. Ê The Amontec debugger is displayed in the drop-down list:

Figure 5: Amontec JTAGkey in Zadig

Note: If the Amontec debugger is not automatically displayed in the drop- down list, choose Options > List All Devices from the Menu, then select the Amontec debugger entry.

Ø Make sure that WinUSB is selected in the field to the right of the green arrow, then click Install Driver button.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Installing drivers for Olimex ARM-USB-TINY H and Amontec JTAGkey (optional) 14/38

Ê The installation is started after a few seconds. Ø If the Windows security question for device software installation appears, allow the installation. Ø Repeat the installation for the second Amontec interface entry. Ê In the Windows Device Manager, the Amontec debugger should now be displayed under Universal Serial Bus devices:

Figure 6: Amontec JTAGkey in Device Manager after driver installation (example in Windows 7) ð The debugger should now be ready to use.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Connecting device and opening command line 15/38

6 Connecting device and opening command line Ø Connect your netX device to your programming PC/laptop via one of the following interfaces: – JTAG – Serial/UART – USB – Standard Ethernet LAN

Note: First check which of these interfaces are supported by your Flasher version and your netX type. Not all interface/netX type combinations are available (see section Tested systems, devices and interfaces [} page 6]). Note also that if you are not using the JTAG interface, you must put your netX device into the console mode that supports the intended interface. Instructions for this can be found in the “How to” collection for CLI Flasher in the Hilscher knowledge base: https://kb.hilscher.com/x/rBbJBg

Ø Open a command prompt and change to the flasher_cli-x.x.x directory (i.e. the folder that contains the cli_flash.lua file). E.g by entering.: cd C:\Tools\flasher_cli-1.6.0

Figure 7: Command Prompt in flasher directory (example)

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Syntax, commands and parameters 16/38

7 Syntax, commands and parameters

7.1 Syntax Each command line starts with the lua5.1.exe cli_flash.lua invocation followed by a command and, if necessary, parameters that specify the command. Thus, the general syntax is as follows: lua5.1.exe cli_flash.lua [command] [parameter 1] [parameter 2] ... [parameter n] Example:

Figure 8: Syntax example

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Syntax, commands and parameters 17/38

7.2 Commands This section describes the most important commands (also called “modes”).

Commands for displaying information Command (mode) Description -h Shows a help text providing full information on commands and parameters. This command requires no parameters. list_interfaces Shows a list of interfaces (PC-to-netX plugin) that can be used to access the connected netX device. This command requires no parameters. Note: Each entry in the list consists of a name and a type. If the interface type is romloader_usb, romloader_jtag or romloader_eth, a netX device has been detected. If the interface type is romloader_uart, it refers to a serial port that may or may not be connected to a netX in console mode. The flasher does not try to send or receive on the serial port to avoid confusing other serial devices. The name can be specified on the command line (with the -p parameter) to select this interface. detect_netx Identifies the netX chip type (e.g. chip revision) at an interface. Requires you to specify the interface. If you omit the interface parameter, you will have to select the interface from a menu that appears before the detect_netx action is started. info Connects to a netX device, detects the chip type and lists the flash device interfaces that are available on this chip type: SPI, parallel flash, internal flash or SD/eMMC. Requires you to specify the interface. If you omit the interface parameter, you will have to select the interface from a menu that appears before the info action is started. Note: This command does not check if any of the displayed flash devices are actually connected to these interfaces. Note also that it may display busses and units that have not been verified yet (testing is in “experimental status”). For an overview of the busses and units that are tested and officially supported for individual netX types, see section Tested systems, devices and interfaces [} page 6]. Table 4: Flasher commands for displaying information

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Syntax, commands and parameters 18/38

Commands for accessing the flash Command (mode) Description detect Tries to identify the specified flash device. Must be followed by the parameters (optional parameters are indicated in curly brackets): {interface} [bus] {unit} {chip select} Note: If you omit the interface parameter, you will have to select the interface from a menu that appears before you can start the detect action. If you omit the unit and chip select parameters, the flasher tool will automatically use 0 as default value. flash Writes the specified file to the specified flash device destination. Must be followed by the following parameters (optional parameters are indicated in curly brackets): {interface} [bus] {unit} {chip select} {offset} [file] Note: If you omit the interface parameter, you will have to select the interface from a menu that appears before you can start the flash action. If you omit the unit and chip select parameters, the flasher tool will automatically use 0 as default value. If you omit the offset parameter, the flasher tool will automatically use the default offset 0x0 (start of the flash unit). read Reads specified flash area and writes output to file. Must be followed by the parameters (optional parameters are indicated in curly brackets): {interface} [bus] {unit} {chip select} {offset} [size] [file] Note: If you omit the interface parameter, you will have to select the interface from a menu that appears before you can start the read action. If you omit the unit and chip select parameters, the flasher tool will automatically use 0 as default value. If you omit the offset parameter, the flasher tool will automatically use the default offset 0x0 (start of the flash unit). erase Deletes contents of specified flash area. Must be followed by the parameters (optional parameters are indicated in curly brackets): {interface} [bus] {unit} {chip select} {offset} [size] Note: If you omit the interface parameter, you will have to select the interface from a menu that appears before you can start the erase action. If you omit the unit and chip select parameters, the flasher tool will automatically use 0 as default value. If you omit the offset parameter, the flasher tool will automatically use the default offset 0x0 (start of the flash unit). Table 5: Commands for accessing the flash

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Syntax, commands and parameters 19/38

7.3 Parameters and values The following table describes the relevant parameters and their values. Note that different netX types can support different interfaces and units; therefore check also section Tested systems, devices and interfaces [} page 6]. Parameter Description Values Example interface -p Selects the interface Depends on the netX type. Use the -p romloader (“plugin”) that will be used list_interfaces command to _uart_com1 for the action. display a list of interfaces/values that Note: You can omit this the netX offers and can be used by the parameter and select the flasher (see also section Showing list interface from a menu of interfaces [} page 23]). instead, which appears right before you start the action. However, using this parameter in the command line would allow you to run the flasher without user interaction in order to automate your production process. bus -b Selects the flash type. 0 External parallel flash -b 1 1 External serial flash denotes external serial flash 2 Internal flash 3 SD/eMMC unit -u Selects one out of several Depends on the selected bus and on -u 0 units/interfaces of the same the netX type (see section Tested denotes SQI flash on flash type if there are more systems, devices and the external serial than one units/interfaces at interfaces [} page 6] for your netX). flash bus (bus 1) a bus (e.g. SQI and SPI You can also use the info command flash at bus 1) to display the “Board info” showing a list of available busses and units (see section Showing list of flash busses and units [} page 25]). chip -cs Selects chip select signal of Depends on the netX and on the –cs 0 select the interface (if applicable) circuitry of the PCB (see section Tested systems, devices and interfaces [} page 6] for your netX). Default value: 0 offset -s Byte address in the 0x0 -s 0x3000 selected flash device, ... where to start the action. Note: The default offset is 0x0 (start of the flash unit) size -l Length (number of bytes) of Must be ≤ flash device size -l 0xFA0 the area to be read or Note: When size is specified as erased. 0xffffffff, the flasher uses the detected size of the flash device.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Syntax, commands and parameters 20/38

Parameter Description Values Example file *.* If used in a flash *.* firmware.nxi command: Name of the binary file to be written to the specified flash destination. Note: The file must be available in the directory of the flasher tool; otherwise you have to specify the path to the location of the file. If used in a read *.* flash_backup.bin command: Name of the output file in which you want to store data read from the specified flash. Note: The file will be automatically created or – if already existing – overwritten. Table 6: Flasher parameters and values

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 21/38

8 Typical use cases

8.1 Getting help Ø Change into the flasher directory (if you have not done so already). Ø To display the integrated help text, enter the following command: lua5.1.exe cli_flash.lua –h

Figure 9: command Ø Press Enter on your keyboard. Ê The program shows the help text:

Figure 10: End of help text

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 22/38

Ø Scroll upwards and expand the shell window to see the beginning of the help text:

Figure 11: Help text

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 23/38

8.2 Showing list of interfaces Ø Change into the flasher directory (if you have not done so already). Ø To display a list of the interfaces, enter the following command: lua5.1.exe cli_flash.lua list_interfaces

Figure 12: Show interfaces Ø Press Enter on your keyboard. Ê The program detects the connected interfaces. The list should include the interface that you are currently connected with:

Figure 13: Interface options detected by the command line flasher

Note: Each entry in the list consists of a name and a type. If the interface type is romloader_usb, romloader_jtag or romloader_eth, a netX device has been detected. If the interface type is romloader_uart, it refers to a serial port that may or may not be connected to a netX in console mode. The flasher does not try to send or receive on the serial port to avoid confusing other serial devices.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 24/38

To select an interface by adding it as a parameter in the command line, you have to use its name; i.e. if you wanted to show the board info of the netX via the JTAG interface in example above, you would have to enter: lua5.1.exe cli_flash.lua info -p romloader_jtag_netX90_COM@NXHX_90-JTAG@2:12

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 25/38

8.3 Showing list of flash busses and units Ø Change into the flasher directory (if you have not done so already). Ø To display a list of flash busses and units (“board info”), enter the following command: lua5.1.exe cli_flash.lua info

Figure 14: Show board info Ø Press Enter on your keyboard. Ê The program tries to detect the connected interfaces. In the end, the available interface options are listed for selection. The list should include the interface that you are currently connected with:

Figure 15: Interface options detected by the command line flasher Ø Enter the number of the interface you want to use; e.g. if you want to use the JTAG interface from the list in the example shown above, you have to enter 5 at the prompt.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 26/38

Note: If you want to select the interface by adding it as a parameter/ argument in the command line (instead of selecting it by just entering its number from the list), use the string between colon and brackets; i.e. for the example shown in the figure above, you would have to use: lua5.1.exe cli_flash.lua info -p romloader_jtag_netX90_COM@NXHX_90-JTAG@2:11

Ø Press Enter on your keyboard. Ê The flasher sets up the interface and shows the busses and units that are available:

Figure 16: Board info

Note: The info command does not check if any of the displayed flash devices are actually connected to these interfaces. Note also that it may display busses and units that have not been verified yet (testing is in “experimental status”). For an overview of the busses and units that are tested and officially supported for individual netX types, see section Tested systems, devices and interfaces [} page 6].

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 27/38

8.4 Writing a file to flash

Important: The Flasher checks whether the specified area is empty before it executes the flash (i.e. write) command. If the area is not empty, the Flasher will erase the whole 4kByte sector before it starts the actual writing process. Note that this may lead to unwanted data loss inside the flash device.

This section shows how to proceed if you want to write a file called firmware.nxi to offset 0x3000 of INTFLASH0 (first internal flash of the COM CPU) of a netX 90 SoC: Option 1 (Selecting interface from menu) Ø Change into the flasher directory (if you have not done so already). Ø Enter the following command: lua5.1.exe cli_flash.lua flash -b 2 -u 0 -cs 0 -s 0x3000 firmware.nxi

Figure 17: Example of entering flash parameters

Note: The file that you want to write to the flash must be stored in the directory of the flasher script; otherwise you have to specify the path to the location of the file.

Ø Press Enter on your keyboard.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 28/38

Ê The flasher prompts you to select an interface:

Figure 18: Select interface prompt Ø Enter the number of the interface you want to use, then press Enter on your keyboard. Ê The flasher writes the file to the device. The end of the action is indicated by the Image flashed message:

Figure 19: Image flashed Option 2 (specifying interface directly in command line) As an alternative, you can also specify the interface directly in command line. The additional step of selecting and entering the interface number from the ”Please select the interface” menu will thereby be omitted: Ø If you do not know it already, find out and note the exact name of the interface that you want to use. (You can display a list of interfaces by using the list_interfaces command.) Ê In this example, you want to use the romloader_jtag_netX90_COM@NXHX_90-JTAG@2:11 interface.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 29/38

Ø To start flashing, enter the following command: lua5.1.exe cli_flash.lua flash -p romloader_jtag_netX90_COM@NXHX_90- JTAG@2:11 -b 2 -u 0 -cs 0 -s 0x3000 firmware.nxi

Figure 20: Example of specifying flasher interface in command line The flasher writes the file to the device. The end of the action is indicated by the Image flashed message.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 30/38

8.5 Reading from flash This section shows how to proceed if you want to read 4000 bytes from offset 0x2000 of INTFLASH2 (internal flash of the APP CPU) of a netX 90 SoC, thereby storing the output in an file called output.bin. Ø Change into the flasher directory (if you have not done so already). Ø Enter the following command: lua5.1.exe cli_flash.lua read -b 2 -u 2 -cs 0 -s 0x2000 -l 0xFA0 output.bin

Figure 21: Example of read command Ø Press Enter on your keyboard. Ê The flasher prompts you to select an interface. Ø Enter the number of the interface you want to use, then press Enter on your keyboard. Ê The flasher reads the indicated flash area and writes the contents to the specified output file on your PC/laptop. The end of the action is indicated by the 4000 bytes written to file output.bin message.

Note: As an alternative, you can specify the interface directly in the command line: lua5.1.exe cli_flash.lua read -p romloader_jtag_netX90_COM@NXHX_90-JTAG@2:11 -b 2 -u 2 -cs 0 -s 0x2000 -l 0xFA0 output.bin

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Typical use cases 31/38

8.6 Erasing area in flash device This section shows how to proceed if you want to erase 8000 bytes of INTFLASH1 (second internal flash of the COM CPU) of a netX 90 SoC, starting from offset 0x5F000.

Note: Note that you cannot erase arbitrary areas in the flash device. The area to be erased is extended to the nearest erase block boundaries. That is, if the erase block size is 0x1000 bytes and you want to erase 0x1f40 bytes at 0x5f000 (0x5f000 to 0x60f3f), the area that will actually be erased is from 0x5f000 to 0x60fff. This applies to SPI, parallel and internal flash, but not to SD/eMMC.

Ø Change into the flasher directory (if you have not done so already). Ø Enter the following command: lua5.1.exe cli_flash.lua erase -b 2 -u 1 -cs 0 -s 0x5F000 -l 0x1F40

Figure 22: Example of erase command Ø Press Enter on your keyboard. Ê The flasher prompts you to select an interface. Ø Enter the number of the interface you want to use, then press Enter on your keyboard. Ê The flasher erases the indicated flash area. The end of the action is indicated by the Area erased message.

Note: As an alternative, you can specify the interface directly in the command line: lua5.1.exe cli_flash.lua erase -p romloader_jtag_netX90_COM@NXHX_90-JTAG@2:11 -b 2 -u 1 -cs 0 -s 0x5F000 -l 0x1F40

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Legal notes 32/38

9 Legal notes

Copyright © Hilscher Gesellschaft für Systemautomation mbH All rights reserved. The images, photographs and texts in the accompanying materials (in the form of a user's manual, operator's manual, Statement of Work document and all other document types, support texts, documentation, etc.) are protected by German and international copyright and by international trade and protective provisions. Without the prior written consent, you do not have permission to duplicate them either in full or in part using technical or mechanical methods (print, photocopy or any other method), to edit them using electronic systems or to transfer them. You are not permitted to make changes to copyright notices, markings, trademarks or ownership declarations. Illustrations are provided without taking the patent situation into account. Any company names and product designations provided in this document may be brands or trademarks by the corresponding owner and may be protected under trademark, brand or patent law. Any form of further use shall require the express consent from the relevant owner of the rights.

Important notes Utmost care was/is given in the preparation of the documentation at hand consisting of a user's manual, operating manual and any other document type and accompanying texts. However, errors cannot be ruled out. Therefore, we cannot assume any guarantee or legal responsibility for erroneous information or liability of any kind. You are hereby made aware that descriptions found in the user's manual, the accompanying texts and the documentation neither represent a guarantee nor any indication on proper use as stipulated in the agreement or a promised attribute. It cannot be ruled out that the user's manual, the accompanying texts and the documentation do not completely match the described attributes, standards or any other data for the delivered product. A warranty or guarantee with respect to the correctness or accuracy of the information is not assumed. We reserve the right to modify our products and the specifications for such as well as the corresponding documentation in the form of a user's manual, operating manual and/or any other document types and accompanying texts at any time and without notice without being required to notify of said modification. Changes shall be taken into account in future manuals and do not represent an obligation of any kind, in particular there shall be no right to have delivered documents revised. The manual delivered with the product shall apply. Under no circumstances shall Hilscher Gesellschaft für Systemautomation mbH be liable for direct, indirect, ancillary or subsequent damage, or for any loss of income, which may arise after use of the information contained herein.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Legal notes 33/38

Liability disclaimer The hardware and/or software was created and tested by Hilscher Gesellschaft für Systemautomation mbH with utmost care and is made available as is. No warranty can be assumed for the performance or flawlessness of the hardware and/or software under all application conditions and scenarios and the work results achieved by the user when using the hardware and/or software. Liability for any damage that may have occurred as a result of using the hardware and/or software or the corresponding documents shall be limited to an event involving willful intent or a grossly negligent violation of a fundamental contractual obligation. However, the right to assert damages due to a violation of a fundamental contractual obligation shall be limited to contract-typical foreseeable damage. It is hereby expressly agreed upon in particular that any use or utilization of the hardware and/or software in connection with · Flight control systems in aviation and aerospace; · Nuclear fission processes in nuclear power plants; · Medical devices used for life support and · Vehicle control systems used in passenger transport shall be excluded. Use of the hardware and/or software in any of the following areas is strictly prohibited: · For military purposes or in weaponry; · For designing, engineering, maintaining or operating nuclear systems; · In flight safety systems, aviation and flight telecommunications systems; · In life-support systems; · In systems in which any malfunction in the hardware and/or software may result in physical injuries or fatalities. You are hereby made aware that the hardware and/or software was not created for use in hazardous environments, which require fail-safe control mechanisms. Use of the hardware and/or software in this kind of environment shall be at your own risk; any liability for damage or loss due to impermissible use shall be excluded.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Legal notes 34/38

Warranty Hilscher Gesellschaft für Systemautomation mbH hereby guarantees that the software shall run without errors in accordance with the requirements listed in the specifications and that there were no defects on the date of acceptance. The warranty period shall be 12 months commencing as of the date of acceptance or purchase (with express declaration or implied, by customer's conclusive behavior, e.g. putting into operation permanently). The warranty obligation for equipment (hardware) we produce is 36 months, calculated as of the date of delivery ex works. The aforementioned provisions shall not apply if longer warranty periods are mandatory by law pursuant to Section 438 (1.2) BGB, Section 479 (1) BGB and Section 634a (1) BGB [Bürgerliches Gesetzbuch; German Civil Code] If, despite of all due care taken, the delivered product should have a defect, which already existed at the time of the transfer of risk, it shall be at our discretion to either repair the product or to deliver a replacement product, subject to timely notification of defect. The warranty obligation shall not apply if the notification of defect is not asserted promptly, if the purchaser or third party has tampered with the products, if the defect is the result of natural wear, was caused by unfavorable operating conditions or is due to violations against our operating regulations or against rules of good electrical engineering practice, or if our request to return the defective object is not promptly complied with.

Costs of support, maintenance, customization and product care Please be advised that any subsequent improvement shall only be free of charge if a defect is found. Any form of technical support, maintenance and customization is not a warranty service, but instead shall be charged extra.

Additional guarantees Although the hardware and software was developed and tested in-depth with greatest care, Hilscher Gesellschaft für Systemautomation mbH shall not assume any guarantee for the suitability thereof for any purpose that was not confirmed in writing. No guarantee can be granted whereby the hardware and software satisfies your requirements, or the use of the hardware and/or software is uninterruptable or the hardware and/or software is fault-free. It cannot be guaranteed that patents and/or ownership privileges have not been infringed upon or violated or that the products are free from third-party influence. No additional guarantees or promises shall be made as to whether the product is market current, free from deficiency in title, or can be integrated or is usable for specific purposes, unless such guarantees or promises are required under existing law and cannot be restricted.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Legal notes 35/38

Confidentiality The customer hereby expressly acknowledges that this document contains trade secrets, information protected by copyright and other patent and ownership privileges as well as any related rights of Hilscher Gesellschaft für Systemautomation mbH. The customer agrees to treat as confidential all of the information made available to customer by Hilscher Gesellschaft für Systemautomation mbH and rights, which were disclosed by Hilscher Gesellschaft für Systemautomation mbH and that were made accessible as well as the terms and conditions of this agreement itself. The parties hereby agree to one another that the information that each party receives from the other party respectively is and shall remain the intellectual property of said other party, unless provided for otherwise in a contractual agreement. The customer must not allow any third party to become knowledgeable of this expertise and shall only provide knowledge thereof to authorized users as appropriate and necessary. Companies associated with the customer shall not be deemed third parties. The customer must obligate authorized users to confidentiality. The customer should only use the confidential information in connection with the performances specified in this agreement. The customer must not use this confidential information to his own advantage or for his own purposes or rather to the advantage or for the purpose of a third party, nor must it be used for commercial purposes and this confidential information must only be used to the extent provided for in this agreement or otherwise to the extent as expressly authorized by the disclosing party in written form. The customer has the right, subject to the obligation to confidentiality, to disclose the terms and conditions of this agreement directly to his legal and financial consultants as would be required for the customer's normal business operation.

Export provisions The delivered product (including technical data) is subject to the legal export and/or import laws as well as any associated regulations of various countries, especially such laws applicable in Germany and in the United States. The products / hardware / software must not be exported into such countries for which export is prohibited under US American export control laws and its supplementary provisions. You hereby agree to strictly follow the regulations and to yourself be responsible for observing them. You are hereby made aware that you may be required to obtain governmental approval to export, reexport or import the product.

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public List of Figures 36/38

List of Figures

Figure 1: ARM-USB-TINY H in Device Manager without drivers (example in Windows 7) . 10 Figure 2: Olimex debugger in Zadig ...... 11 Figure 3: ARM-USB-TINY H in Device Manager after driver installation (example in Windows 7)...... 12 Figure 4: Amontec JTAGkey in Device Manager without drivers (example in Windows 7) . 13 Figure 5: Amontec JTAGkey in Zadig...... 13 Figure 6: Amontec JTAGkey in Device Manager after driver installation (example in Windows 7)...... 14 Figure 7: Command Prompt in flasher directory (example) ...... 15 Figure 8: Syntax example ...... 16 Figure 9: Get help command ...... 21 Figure 10: End of help text...... 21 Figure 11: Help text ...... 22 Figure 12: Show interfaces ...... 23 Figure 13: Interface options detected by the command line flasher ...... 23 Figure 14: Show board info...... 25 Figure 15: Interface options detected by the command line flasher ...... 25 Figure 16: Board info ...... 26 Figure 17: Example of entering flash parameters...... 27 Figure 18: Select interface prompt...... 28 Figure 19: Image flashed ...... 28 Figure 20: Example of specifying flasher interface in command line...... 29 Figure 21: Example of read command...... 30 Figure 22: Example of erase command...... 31

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public List of Tables 37/38

List of Tables

Table 1: List of revisions ...... 3 Table 2: Tested flash interfaces for CLI Flasher V1.6.0 ...... 6 Table 3: Supported netX interfaces CLI Flasher V1.6.0 ...... 7 Table 4: Flasher commands for displaying information ...... 17 Table 5: Commands for accessing the flash...... 18 Table 6: Flasher parameters and values ...... 19

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public Contacts 38/38

Contacts

HEADQUARTERS Germany Hilscher Gesellschaft für Systemautomation mbH Rheinstrasse 15 65795 Hattersheim Phone: +49 (0) 6190 9907-0 Fax: +49 (0) 6190 9907-50 E-: [email protected] Support Phone: +49 (0) 6190 9907-99 E-mail: [email protected]

SUBSIDIARIES China Japan Hilscher Systemautomation (Shanghai) Co. Ltd. Hilscher Japan KK 200010 Shanghai Tokyo, 160-0022 Phone: +86 (0) 21-6355-5161 Phone: +81 (0) 3-5362-0521 E-mail: [email protected] E-mail: [email protected] Support Support Phone: +86 (0) 21-6355-5161 Phone: +81 (0) 3-5362-0521 E-mail: [email protected] E-mail: [email protected]

France Korea Hilscher France S.a.r.l. Hilscher Korea Inc. 69500 Bron Seongnam, Gyeonggi, 463-400 Phone: +33 (0) 4 72 37 98 40 Phone: +82 (0) 31-789-3715 E-mail: [email protected] E-mail: [email protected] Support Phone: +33 (0) 4 72 37 98 40 Switzerland E-mail: [email protected] Hilscher Swiss GmbH 4500 Solothurn Phone: +41 (0) 32 623 6633 India E-mail: [email protected] Hilscher India Pvt. Ltd. Pune, Delhi, Mumbai Support Phone: +91 8888 750 777 Phone: +49 (0) 6190 9907-99 E-mail: [email protected] E-mail: [email protected]

Italy USA Hilscher Italia S.r.l. Hilscher North America, Inc. 20090 Vimodrone (MI) Lisle, IL 60532 Phone: +39 02 25007068 Phone: +1 630-505-5301 E-mail: [email protected] E-mail: [email protected] Support Support Phone: +39 02 25007068 Phone: +1 630-505-5301 E-mail: [email protected] E-mail: [email protected]

Command Line Flasher | Operating instruction manual © Hilscher 2020 DOC191201OI01EN | Revision 1 | English | 2020-01 | Released | Public