View source

Table of content 

__TOC__ 

<br> 

= Introduction  =

Ubicom's Programming Dongle (shown in Figure1, connected to a target) provides programming and debugging functions for the Ubicom32 family of processors such as IP3xxx, IP5xxx and IP7xxx through an Ethernet interface. <br>The Ubicom Programming Dongle is developed by Ubicom and it provides fast in-system debugging (ISD) and In-System Programming capability using the ISD/ISP interface of Ubicom32 based processors. <br>The Ubicom Programming Dongle is functionally equivalent to a JTAG debugger. However, the debug capabilities and usability features are superior to those provided by a JTAG debugger. A typical JTAG uses serial interface to communicate with the host while Ubicom Dongle uses Ethernet Interface to communicate with the host system. This presents a huge advantage over JTAG debuggers such as Debugging over High speed interface, Location independent debugging and easy maintenance. <br>[[Image:Ubicom dongle.JPG]]<br> Figure1: Ubicom Programming Dongle.<br> 

The Ubicom Programming Dongle has many features and uses such as:<br> In-Circuit (IC) level debugging.<br> IP connectivity through Ethernet interface<br> Debugging capabilities for UBICOM32 family of processors.<br> Remote debugging over IP through Ethernet interface.<br> Application level debugging via telnet connection.<br> Stand-alone / Programming only mode of operation.<br> Controllable from a remote PC via HTTP UI.<br>For more information about dongle, debugging or others, please visit http://developer.ubicom.com/<br> 

= How to use Ubicom Programming Dongle  =

This section has several sub sections explaining typical usages of Ubicom Dongle from setting up the connections to debugging the running code on target. <br> 

== Connecting the Ubicom Dongle to the Target  ==

The picture below shows Ubicom Programming Dongle connected to the target board. The different parts in the picture are listed and explained below. <br> [[Image:Setup_and_connections.jpg]]<br> Figure 2: Connecting Ubicom Programming Dongle<br>1 - Ubicom reference board<br>&nbsp;2 - Ubicom dongle.<br>&nbsp;3 - UART connection from target to PC, for console (optional).<br>&nbsp;4 –Ethernet LAN connection from board to hub/switch. 

&nbsp;5 –Ethernet connection from dongle to hub/switch. <br>&nbsp;6 - Connection PC Ethernet interface. <br>&nbsp;7 - Hub/switch<br>

== IP address of Dongle  ==

The Ubicom programming dongle is IP addressable and it can get IP address either dynamically from a DHCP server or statically from local configuration. By default, Ubicom Programming dongle is configured to get IP addresses from DHCP server present in its LAN. <br> 

=== Determining current IP address of the Dongle  ===

There are a couple of ways to determine IP address of the dongle. If the dongle has got IP address from a DHCP server, the DHCP lease list on the DHCP server would show the IP address of the dongle. However, if the Dongle was previously assigned a static IP address it could be determined by running udm4linux utility. udm4linux stands for Ubicom Device Manager 4 Linux. This utility is part of Ubicom distribution and can be found in the directory tools/bin/linux/. The picture Figure3 shows output of udm4linux utility. <br>[[Image:Udm4linux_output.JPG]]<br> Figure 3: Output from udm4linux tool

=== Changing IP address of the Dongle  ===

The IP address IP address settings of the dongle can be changed either through udm4linux tool or through the web UI available at http://&lt;current_dongle_ip_address&gt;. <br>udm4linux utility can be used to change the IP address or the IP mode (static to DHCP or vice versa). The help and options can be obtained by running udm4linux –help command and the output is as shown in Figure 4. <br>[[Image:Udm4linux help.JPG]]&nbsp;<br>Figure 4: udm4linux help and options 

The Dongle’s IP address and settings can also be changed from the web UI as shown in Figure 5. 
<br>[[Image:Dongle webui.JPG]]<br>  Figure 5: Web UI of Dongle.

== Accessing Target Console with Dongle  ==

Console on the target can be accessed through the Dongle if the console option has been enabled in the firmware running on the target. Refer http://developer.ubicom.com for information on building the firmware and debugging through console.<br>The target console is accessed by using telnet utility on the host PC and connecting to dongle IP address and port 50. '''Please note that there is no “:” between IP address and port number.''' 

<pre>
  $ telnet dongle_ip_address 50 
</pre>

Typical busybox commands like vi, find, ls, cd are available in the console and on bootup, the console would look as shown in Figure 6. <br>&nbsp;[[Image:Target help.JPG]]<br>Figure 6: Target console accessed by Dongle.<br>

== Programming the Target using Dongle  ==

Ubicom Dongle can be used to program the target with firmware through ubicom32-elf-gdb utility that is part of the standard GNU toolchain present in Ubicom Linux distribution. Before starting GDB utility, connect the dongle to the target via the ISP/ISD interface and power-on both the target and the dongle. Assuming that the dongle IP address is 192.168.0.221, setup following environment variables for easy usage: 
<pre>$ export UBICOM_DONGLE=192.168.0.221:5010 
$ export PATH=$PATH:~/ubicom-disrto/toolchain/bin 
$ export LD_LIBRARY_PATH=~/ubicom-disrto/toolchain/lib 
</pre> 
Invoke GDB at a shell command prompt: 
<pre>
$ ubicom32-elf-gdb u-boot.elf 
</pre> 
GDB will show some version information and a new prompt. Enter the following command to attach gdb to the target. Please note that specifying IP address and port is needed only if UBICOM_DONGLE environment variable is not set as mentioned in previous step. 
<pre>
(gdb) target ubicom32 192.168.0.221:5010 
</pre> 
At this stage, GDB should connect to the target (i.e. the target) and reply: Connected to target. Please type: 
<pre> (gdb) load 
</pre> 
GDB will show the status of programming through a progressive series of dots and return to its prompt. Until gdb is instructed to disconnect form the target the target will remain in a halt/reset state. To disconnect from the target and quit GDB, execute the following 2 commands. 
<pre> (gdb) detach
 (gdb) quit
</pre> 
The target is now released from halt/reset state and would start/resume running. 

<br>

== Debugging Target using Dongle  ==

Ubicom Dongle can be used for In-System Debug (ISD) of target using ubicom32-elf-gdb or ubicom32-elf-insight utilities available as part of the toolchain supplied in Ubicom SDK. Please note that more information about debugging is available at http://developer.ubicom.com.<br>Using Ubicom dongle to debug is very simple operation as shown in the example below. <br>Launch the debugger using following command assuming that dongle_ip address is 192.168.0.221 and dongle is connected to live target. 
<pre>$ ubicom32-elf-insight vmlinux.elf
</pre> 
After debugger utility loads the target image, use the following command in the debugger console to attach the debugger utility to the target for In-System debugging. 
<pre>$ (gdb) target ubicom32 192.168.0.221:5010 
</pre> 
Since ubicom32-elf-gdb is based on standard GNU gdb, debugging with ubicom2-elf-gdb is very much like standard GNU gdb tools as shown below. <br>[[Image:Target_debug.JPG]]&nbsp;<br>Figure 7: Target debugging.<br><br>

== Dongle firmware upgrade  ==

Ubicom dongle can be updated to latest firmware available in from ubicom distribution using web UI. Latest firmware for the dongle is available in the districbution at the location (../Firmware/Dongle/ubicom_dongle_with_console.bin) . '''Please note that you might want to save your configuration before updating the dongle with the new firmware.''' <br>[[Image:Dongle_webui_firmware.JPG]]<br>Figure 8: Web UI of Ubicom Programming Dongle<br> <br>

== Typical error notifications  ==

=== Unable to find dongle  ===

This error means that the ubicom32-elf-gdb utility was unable to find IP connectivity to the Dongle. This error could occur if <br>• Dongle is not powered ON<br>• $UBICOM_DONGLE environment variable is not set or is different from the current IP address of the Dongle.<br>• Dongle IP address is in a different subnet and there is no IP route to the dongle IP address.'''<br>Solution:<br>'''Please check the IP address of the dongle using udm4linux utility as explained above.

=== Unable to establish ISD connection.  ===

This error could occur if communication between the dongle and target is lost. Possible reasons for this issue are<br>• The physical connection between dongle and target is lost because target board is not powered ON.<br>• The Dongle connection header attached to the ISD pins on the target is not aligned to PIN1 or not connected properly. '''<br>Solution:<br>'''• Check the connection between dongle and target. <br>• Ensure that pin1 of ISD connector on the development board matches with the pin1 on the dongle. If the problem persists, try connecting the header other way. <br>• Power cycling dongle or target could help too.<br>