background image

IN3032UG: Ethernet Debugger User Guide

The information disclosed to you hereunder (the “Materials”) is provided solely for the selection and use

of Intona products. To the maximum extent permitted by applicable law: (1) Materials are made available

”AS IS” and with all faults, Intona hereby DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS,

IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,

NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE; and (2) Intona shall not be liable

(whether in contract or tort, including negligence, or under any other theory of liability) for any loss or damage

of any kind or nature related to, arising under, or in connection with, the Materials (including your use of the

Materials), including for any direct, indirect, special, incidental, or consequential loss or damage (including

loss of data, profits, goodwill, or any type of loss or damage suffered as a result of any action brought by

a third party) even if such damage or loss was reasonably foreseeable or Intona had been advised of the

possibility of the same. Intona assumes no obligation to correct any errors contained in the Materials or to

notify you of updates to the Materials or to product specifications. You may not reproduce, modify, distribute,

or publicly display the Materials without prior written consent. Intona products are not designed or intended

to be fail-safe or for use in any application requiring fail-safe performance.

© Copyright Intona Technology GmbH, Germany.

Intona and other designated brands included herein are trademarks of Intona in Germany and other countries.

All other trademarks are the property of their respective owners.

Website: https://intona.eu

Summary of Contents for IN3032UG

Page 1: ...g for any direct indirect special incidental or consequential loss or damage including loss of data profits goodwill or any type of loss or damage suffered as a result of any action brought by a third party even if such damage or loss was reasonably foreseeable or Intona had been advised of the possibility of the same Intona assumes no obligation to correct any errors contained in the Materials or...

Page 2: ...Software Installation 9 3 1 Linux 9 3 2 macOS 9 3 3 Windows 9 3 4 Verifying Device Access 10 3 5 Wireshark extcap Setup 10 3 5 1 Linux macOS 10 3 5 2 macOS app bundle 11 3 5 3 Windows 11 3 6 Firmware Update 11 3 6 1 Unix like 11 3 6 2 Windows 12 4 Capturing 13 4 1 Wireshark extcap 13 4 1 1 Capturing Options 13 4 1 2 Wireshark extcap Toolbar 13 4 2 Directly Starting Wireshark from Host Tool 13 4 3 ...

Page 3: ...ions 20 5 10 Packet Injection 23 5 11 Blocking Ports 24 5 12 Packet Disruption 24 5 13 MDIO Access 25 5 13 1 Raw MDIO access 25 5 13 2 Changing PHY Ethernet Speed 25 5 14 Device Settings 25 6 Known Problems 26 7 Further Readings 26 7 1 White Papers 26 7 1 1 Ethernet Debugger Timing 26 7 2 Statements 26 7 2 1 Letter of Volatility 26 3 ...

Page 4: ... nor will it attempt to send random packets to it ARP etc The latter would show up in Wireshark and confuse your development efforts Capture can be directly started from Wireshark if installed correctly The userspace driver also provides a command line interface which can be used to access advanced feature An IPC interface is provided for use cases like scripting The debugger can block packets in ...

Page 5: ...h capture scenarios 1 4 2 Firmware 1 08 Updating to host tool v1 3 is recommended Bug fixes Fix occasional packet corruption with some links in 100 MBit mode this affects both packet capture and ethernet communication Hopefully fix 10 MBit mode Improve speed settings handling always enable auto negotiation and control advertisings instead Work around a FX3 issue that made firmware updates under US...

Page 6: ...ng Bug fixes Skip possibly old data when starting capture Fix description of some hw_info fields Fix undefined behavior in USB error handling path New features Add nopad bw bytes bw packets parameters to inject command Add update parameter to hw_info command Add capture speed test command line option 1 5 2 Host tool v1 4 60a3f48 windows build 66 Potential incompatibilities and problems Change auto...

Page 7: ...tcap mode terminate properly if no packets were captured New features Full support for firmware 1 06 Slightly improved link status reporting Extend capabilities of inject and disrupt commands Change USB device name format and include device address allows distinguishing multiple devices connected to chained hubs Accept device serial number as device name and report it via extcap to Wireshark Add q...

Page 8: ... to have a link while the other port does not They also can have mismatched speed In both cases capture will not work 2 1 2 Main LED Normally the main LED should be blue It will blink if capturing is in progress The following states exist LED state Meaning Blue USB super speed connection is up Green USB high speed connection is up slow but functional Cyan USB power only will not work Blue blinking...

Page 9: ...e software is provided as source code you can automatically download and build it using Homebrew brew install HEAD intona ethernet debugger nose Homebrew is a 3rd party project for installing freely available software on macOS See https brew sh for details and how to install Homebrew itself You need to setup Wireshark extcap manually See below We decided to not provide binaries for macOS because i...

Page 10: ...ch as our host tool to provide a capturing source See the Wireshark extcap section for details If the host tool is not correctly installed as extcap source you will not be able to start capture from the Wireshark GUI but other methods of capturing will still work The host tool supports extcap directly via special command line parameters It must be located in the extcap sub directory within the Wir...

Page 11: ...E with the actual username You may need to create the last component of the path The installer does not try to use this Updating Wireshark tends to remove and recreate the Wireshark installation directory This will also remove the intona ethernet debugger bat file created by the Ethernet Debug ger installer You could run the installer again to fix this Manually moving the bat to the Wireshark user...

Page 12: ...te If the device option is provided the tool will update the given device without asking for confirmation firmware update all will update all detected devices without asking for confirmation In both cases at least with v1 2 the firmware is written only if it s newer than the firmware on the device unless firmware update force is provided Old host tool versions before release v1 2 do not ask for a ...

Page 13: ...mount of resources to deal with packet input Capturing to disk via the nose tool may help reducing packet drop You can open the capture file with Wireshark afterwards Various error conditions may deadlock Wireshark and the host tool on capture start 4 1 1 Capturing Options Wireshark lets you set some Ethernet Debugger specific options before starting capture Click on the gear like symbol left of t...

Page 14: ...s by using decoupled memory buffers but these may be slowly filled up until a software overrun happens Example Capturing to a file until Ctrl C is hit and log capture statistics to stdout nose capture stats fifo target_file pcapng Manually starting Wireshark On terminal 1 mkfifo tmp fifo nose fifo tmp fifo On terminal 2 wireshark k i tmp fifo 4 5 Selecting the Device If you have multiple Ethernet ...

Page 15: ...tion 5 3 Supported Command Line Options You can list supported options as follows nose help Current list of options Name Description verbosity 0 1 2 Set verbosity log level 0 silent 1 normal default 2 verbose messages version Print host software version and exit selftest Run internal self test Requires a loop between the two ports selftest serial Internal wireshark Start wireshark and dump packets...

Page 16: ...sted below are accessible only through this interface By default the host tool will read from stdin and accept commands It will terminate if stdin is closed or returns EOF If run on the terminal it offers an interactive command line using libreadline If the host tool was built without libreadline or you can use the rlwrap5 3rd party tool to get comfortable line editing and history rlwrap nose argu...

Page 17: ...or creating GUI frontends For example you could inject or drop packets under specific situations or start stop capturing at specific times The IPC server created with ipc server is available as long as the host tool runs The path at which the IPC communication channel is available depends on the OS The tool prints the full path when it starts the server The ipc connect option makes the host tool i...

Page 18: ...dio_read phy 1 address 1 id 1 client to host tool id 1 result 31049 success true host tool to client The id field is an arbitrary integer chosen by the client and can be used to associate requests with replies The C style comments are for illustration and not part of the protocol For example on the shell and with socat you could do the above by Terminal 1 nose ipc server test Terminal 2 echo comma...

Page 19: ...entify Function The blink_led command will flash the device main LED blue green for a moment This is helpful to determine which device is opened on a host tool instance if multiple Ethernet Debuggers are connected to a PC 19 ...

Page 20: ...erType 0xBEEF The feature as currently implemented can test at most Layer 2 devices like ethernet switches Testing devices that operate on a higher layer such as IP routers are not supported as that would require implementing parts of ARP and IP though it s theoretically possible 5 9 2 Instructions Connect the devices as in the diagram above On the PC open two nose instances one for the sender one...

Page 21: ... master latency_tester_receiver Starting capture thread succeeded Receiver setup Listening to incoming packets Starting recording sequence seq 99 diff 410 seq 199 diff 410 seq 299 diff 410 The output gives you an idea whether it actually works Actual data should be retrieved by using file output File output can be used with for example Receiver file output latency_tester_receiver out file mydata t...

Page 22: ...ists skipping sequence The file mydata txt was deleted shortly after the receiver was started The file was then created again and opened for writing The host program picked up the next sequence of test packets and wrote them to mydata txt The sequences after that are skipped because mydata txt still exists It will log two skip messages per sequence because it encounters a first packet from both pa...

Page 23: ...dwidth stream of the same packet being repeated Use inject_stop to disable the injector again Use hw_info to check whether it s currently enabled CRC errors can be injected Degenerate packets too short IPG too low can be created with the raw parameter Low level physical layer coding errors can be generated with the gen error parameter PHY emits symbol error for a specific byte The IPG can be contr...

Page 24: ...unblock B A block_ports AB Block all traffic block_ports none Unblock all traffic This command uses the same hardware logic as the disrupt command basically it s just a simpler version of the same command Using either resets the state set by the other command 5 12 Packet Disruption The disrupt command can be used to drop or to destroy some or all packets in a certain direction This is a form of er...

Page 25: ...mes which makes it slower and may be annoying when troubleshooting connected devices The set_device_phy_wait command can be used to set the fixed time after which the state machine assumes the PHY cannot establish a link The manual mode lets each PHY negotiate the speed independently which will lead to problems if the device s port A and B PHYs do not negotiate the same speed This mode is useful o...

Page 26: ...ed trying to open Wireshark s extcap control pipes Restarting Wireshark helps you may need to kill the blocked nose process as well Firmware versions before 1 08 had issues with 10 100 MBit modes If you encounter problems always update to the latest firmware version and host tool available here6 7 Further Readings 7 1 White Papers 7 1 1 Ethernet Debugger Timing The Ethernet Debugger can be used to...

Reviews: