1 #####################################################################
2 # SUMP2 by BlackMesaLabs GNU GPL V2 Open Source License. Python 3.x
3 # (C) Copyright 2016 Kevin M. Hubbard - All rights reserved.
4 #####################################################################
6 This document describes the SUMP2 software and hardware.
8 2.0 Software Architecture
9 The SUMP2 application is a Python 3.5 script using the PyGame module
10 for mouse and graphical user interface. Communication to hardware is
11 via TCP Socket communications to a BD_SERVER.py instance. The SW is
12 architected as a GUI wrapper around a command line application with
13 a bd_shell interface. When the PyGame GUI is used, mouse menu
14 selections create commands that are then interpreted by bd_shell.
15 In theory, sump2.py may be executed without PyGame as a command line
16 only program to arm the sump2 hardware and then dump captured data
17 to a VCD file for offline viewing by another application.
19 3.0 Command Descriptions
20 Zoom_In : Increase signal view magnification 2x
21 Zoom_Out : Decrease signal view magnification 2x
22 Zoom_Full : View all signal samples : WARNING May be slow
23 Zoom_Previous : Return to previous zoom view.
24 Zoom_to_Cursors : View region bound by cursors
25 Crop_to_Cursors : Reduce sample set to region bound by cursors
26 Cursors_to_View : Bring both cursors into current view
27 Cursor1_to_Here : Bring Cursor1 to mouse pointer
28 Cursor2_to_Here : Bring Cursor2 to mouse pointer
29 Acquire_Single : Arm hardware for single non-RLE acquisition
30 Acquire_Continuous : Arm hardware for looping non-RLE acquisitions
31 Acquire_Stop : Issue a stop to hardware from current Arming
32 Acquire_RLE_1x : Arm hardware for RLE acquisition no decimation
33 Acquire_RLE_8x : Arm hardware for RLE acquisition 8x decimation
34 Acquire_RLE_64x : Arm hardware for RLE acquisition 64x decimation
35 File_Load : Load a bd_shell script file
36 File_Save : Save capture to a VCD,PNG,JPG, etc file
37 Save_Rename : Rename the last file saved
38 Fonts : Increase or Decrease GUI font size
39 BD_SHELL : Close GUI and open a BD_SHELL command line
41 Rename : Rename a selected signal's nickname
42 Insert_Divider : Insert a dummy signal divider
43 Clipboard : Cut and Paste selected signals
44 Visibility : Change visibility. Impacts RLE Compression
45 Trigger_Rising : Set Trigger for Rising edge of selected
46 Trigger_Falling : Set Trigger for Falling edge of selected
47 Trigger_Watchdog : Set Trigger for Watchdog timeout of selected
48 Set_Pattern0 : Advanced Triggering
49 Set_Pattern1 : Advanced Triggering
50 Clear_Pattern_Match: Advanced Triggering
51 Set_Data_Enable : Advanced data sampling
52 Clear_Data_Enable : Advanced data sampling
53 SUMP_Configuration : Modify advanced SUMP variables
54 Acquisition_Length : Configure amount of non-RLE RAM to use
56 4.0 SUMP2 Environment Variables
57 bd_connection : Connection type to hardware. tcp only
58 bd_protocol : Communication protocol to HW, poke only
59 bd_server_ip : IP address or localhost for bd_server
60 bd_server_socket : Socket Number for bd_server, 21567 typ
61 sump_addr : 32bit PCI address of sump_ctrl_reg
62 sump_data_enable : Event bits to use for data_enable feature
63 sump_rle_event_en : Event bits to use for RLE capture
64 sump_rle_post_trig_len : Max number of post trigger RLE samples
65 sump_rle_pre_trig_len : Max number of pre trigger RLE samples
66 sump_trigger_delay : Number of clocks to delay trigger
67 sump_trigger_field : Event bits to use for trigger
68 sump_trigger_nth : nTh trigger to trigger on
69 sump_trigger_type : or_rising,or_falling,watchdog,pattern_ris
70 sump_user_ctrl : 32bit user_ctrl field
71 sump_user_pattern0 : 32bit user pattern0 field
72 sump_user_pattern1 : 32bit user pattern1 field
73 sump_watchdog_time : Watchdog timeout for Watchdog trigger
76 The SUMP2 hardware is a single verilog file with fixed input parms
77 for the depth and width of capture memory to use. A maximum SUMP2
78 configuration contains a 32bit Block RAM for non-RLE events and a
79 64bit Block RAM for RLE events and time stamps. In addition to 32
80 signal events, SUMP2 may also capture 16 DWORDs (512 bits ) of non
81 RLE data. The SUMP2 software automatically adjusts to each instance
82 of hardware for memory depth, width and advanced features. A key
83 feature for acquiring long captures in time is the ability to mask
84 any of the event inputs, which can be used to dramatically reduce
85 event occurrence and support capturing only events of interest. The
86 software supports masking events by double-clicking the signal name
87 prior to arming which hides the signals and masks them from the RLE
88 compression. 10x to 1000x compression is possible run-time for some
89 designs by dynamically masking input events prior to acquisition.
91 events[31:0] -+->| Trigger Logic |-------------------------
92 | --------------- ----------------- |
93 +---------------------->| RLE Compression | |
94 | --------------- | Timestamp and |<-+
95 +->| RLE RAM |<---| Addr Generator | |
96 | --------------- ----------------- |
97 | --------------- ----------------- |
98 ->| non-RLE RAM |<-+-| Addr Generator |<-
99 --------------- | -----------------
101 dwords[511:0] -->| non-RLE RAM |<-
104 6.0 Working with large RLE datasets
105 RLE datasets can be overwhelming large to work with in software once
106 samples have been decompressed. Compression ratios of 10,000:1 are
107 possible for some systems. SUMP Software provides internal tools for
108 reducing the hardware captured RLE dataset to more manageable size
109 for both viewing and VCD generation.
110 crop_to_cursors : Permanently crops the number of samples to a
111 region indicated by the cursors.
112 RLE Decimation : 8x and 64x decimation specified at arming will
113 acquire the RLE data and reduce the sample rate
114 by 8x or 64x prior to rendering.
115 Signal Hiding : Hiding a signal prior to acquisition will mask
116 the signal entirely and increase the overall RLE
117 acquisition length. Hiding a signal post acquire
118 speeds up rendering time for remaining signals.
121 The following is an example of manually modifying sump2_wave.txt
122 file in order to group together multiple events into a bundle.
124 /event[12] -nickname event[12]
125 /event[13] -nickname event[13]
126 /event[14] -nickname event[14]
127 /event[15] -nickname event[15]
130 The original OSH+OSS SUMP was designed in 2007 as an external logic
131 logic analyzer using a Xilinx FPGA eval board for capturing external
132 electrical signals non compressed to all available FPGA block RAM.
133 See http://www.sump.org/projects/analyzer/
134 The original developer published the serial communication protocol
135 and also wrote a Java based waveform capture tool. The simplicity of
136 the protocol and the quality and maintenance of the Open-Source Java
137 client has inspired many new SUMP compliant projects such as:
138 'Open Logic Sniffer' : https://www.sparkfun.com/products/9857
140 7.1 SUMP1-RLE ( 2014 )
141 Black Mesa Labs developed the SUMP1-RLE hardware in 2014 as a
142 software protocol compatible SUMP engine that was capable of real
143 time hardware compression of samples ( Run Length Encoded ). The
144 idea of the project was to leverage the open-source Java software
145 and couple it with new hardware IP that was capable of storing deep
146 capture acquisitions using only a single FPGA Block RAM, allowing
147 SUMP to be used internally with existing FPGA designs rather than
148 a standalone device. FPGA vendor closed license logic analyzers all
149 store using no compression requiring vast amount of Block RAMS to
150 be useful and typically do not fit will within the limited fabric
151 resources of an existing FPGA design requiring debugging. SUMP1-RLE
152 was later enhanced to include 2 DWORDs of sampled data along with
153 the RLE compressed signal events. This enhancement required new
154 software which was written in .NET Powershell for Windows platform.
156 7.2 SUMP2-RLE ( 2016 )
157 SUMP2 is a software and hardware complete redesign to improve upon
158 the SUMP1-RLE concept. For SUMP2 the .NET software was tossed due
159 to poor user interface performance and replaced with a PyGame based
160 VCD waveform viewer ( chip_wave.py also from BML ). The SUMP2 HW
161 is now a single Verilog file with no backwards compatibility with
162 any legacy SUMP hardware or software systems. SUMP2 hardware is
163 designed to capture 512bits of DWORDs and 32bits of events versus
164 the SUMP1 limits of 16 event bits and 64bits of DWORDs. Sample
165 depth for SUMP2 is now completely defined by a hardware instance
166 with software that automatically adapts. The RLE aspect of SUMP2
167 is optional and not required for simple data intensive captures.
168 SUMP2 software includes bd_shell support for changing variables
169 on the fly and providing simple low level hardware access to regs.
172 The SUMP2.py application does not communicate directly to hardware
173 but instead uses BD_SERVER.py as an interface layer. BD_SERVER is
174 a multi use server application that accepts requests via TCP to
175 read and write to low level hardware and then translates those
176 requests using one of many low level hardware protocols available.
177 BD_SERVER allows the low level communications to easily change from
178 interfaces like USB FTDI serial to PCI without requiring any change
179 to the high level application. This interface also supports the
180 debugging of an embedded system from a users regular desktop with
181 a standard Ethernet or Wifi connection between the two. Typical use
182 is to run both python applications on same machine and use the TCP
183 localhost feature within the TCP stack for communications.
185 ------------ -------------- ---------------
186 | sump2.py |<------->| bd-server.py |<------->| SUMP Hardware |
187 ------------ Ethernet -------------- USB,PCI ---------------
190 This hardware and software is released under the GNU GPLv2 license.
191 Full license is available at http://www.gnu.org
projects / BML_sump2 / blob