--- /dev/null
+#####################################################################
+# SUMP2 by BlackMesaLabs GNU GPL V2 Open Source License. Python 3.x
+# (C) Copyright 2016 Kevin M. Hubbard - All rights reserved.
+#####################################################################
+1.0 Scope
+ This document describes the SUMP2 software and hardware.
+
+2.0 Software Architecture
+ The SUMP2 application is a Python 3.5 script using the PyGame module
+ for mouse and graphical user interface. Communication to hardware is
+ via TCP Socket communications to a BD_SERVER.py instance. The SW is
+ architected as a GUI wrapper around a command line application with
+ a bd_shell interface. When the PyGame GUI is used, mouse menu
+ selections create commands that are then interpreted by bd_shell.
+ In theory, sump2.py may be executed without PyGame as a command line
+ only program to arm the sump2 hardware and then dump captured data
+ to a VCD file for offline viewing by another application.
+
+3.0 Command Descriptions
+ Zoom_In : Increase signal view magnification 2x
+ Zoom_Out : Decrease signal view magnification 2x
+ Zoom_Full : View all signal samples : WARNING May be slow
+ Zoom_Previous : Return to previous zoom view.
+ Zoom_to_Cursors : View region bound by cursors
+ Crop_to_Cursors : Reduce sample set to region bound by cursors
+ Cursors_to_View : Bring both cursors into current view
+ Cursor1_to_Here : Bring Cursor1 to mouse pointer
+ Cursor2_to_Here : Bring Cursor2 to mouse pointer
+ Acquire_Single : Arm hardware for single non-RLE acquisition
+ Acquire_Continuous : Arm hardware for looping non-RLE acquisitions
+ Acquire_Stop : Issue a stop to hardware from current Arming
+ Acquire_RLE_1x : Arm hardware for RLE acquisition no decimation
+ Acquire_RLE_8x : Arm hardware for RLE acquisition 8x decimation
+ Acquire_RLE_64x : Arm hardware for RLE acquisition 64x decimation
+ File_Load : Load a bd_shell script file
+ File_Save : Save capture to a VCD,PNG,JPG, etc file
+ Save_Rename : Rename the last file saved
+ Fonts : Increase or Decrease GUI font size
+ BD_SHELL : Close GUI and open a BD_SHELL command line
+
+ Rename : Rename a selected signal's nickname
+ Insert_Divider : Insert a dummy signal divider
+ Clipboard : Cut and Paste selected signals
+ Visibility : Change visibility. Impacts RLE Compression
+ Trigger_Rising : Set Trigger for Rising edge of selected
+ Trigger_Falling : Set Trigger for Falling edge of selected
+ Trigger_Watchdog : Set Trigger for Watchdog timeout of selected
+ Set_Pattern0 : Advanced Triggering
+ Set_Pattern1 : Advanced Triggering
+ Clear_Pattern_Match: Advanced Triggering
+ Set_Data_Enable : Advanced data sampling
+ Clear_Data_Enable : Advanced data sampling
+ SUMP_Configuration : Modify advanced SUMP variables
+ Acquisition_Length : Configure amount of non-RLE RAM to use
+
+4.0 SUMP2 Environment Variables
+ bd_connection : Connection type to hardware. tcp only
+ bd_protocol : Communication protocol to HW, poke only
+ bd_server_ip : IP address or localhost for bd_server
+ bd_server_socket : Socket Number for bd_server, 21567 typ
+ sump_addr : 32bit PCI address of sump_ctrl_reg
+ sump_data_enable : Event bits to use for data_enable feature
+ sump_rle_event_en : Event bits to use for RLE capture
+ sump_rle_post_trig_len : Max number of post trigger RLE samples
+ sump_rle_pre_trig_len : Max number of pre trigger RLE samples
+ sump_trigger_delay : Number of clocks to delay trigger
+ sump_trigger_field : Event bits to use for trigger
+ sump_trigger_nth : nTh trigger to trigger on
+ sump_trigger_type : or_rising,or_falling,watchdog,pattern_ris
+ sump_user_ctrl : 32bit user_ctrl field
+ sump_user_pattern0 : 32bit user pattern0 field
+ sump_user_pattern1 : 32bit user pattern1 field
+ sump_watchdog_time : Watchdog timeout for Watchdog trigger
+
+5.0 SUMP2 Hardware
+ The SUMP2 hardware is a single verilog file with fixed input parms
+ for the depth and width of capture memory to use. A maximum SUMP2
+ configuration contains a 32bit Block RAM for non-RLE events and a
+ 64bit Block RAM for RLE events and time stamps. In addition to 32
+ signal events, SUMP2 may also capture 16 DWORDs (512 bits ) of non
+ RLE data. The SUMP2 software automatically adjusts to each instance
+ of hardware for memory depth, width and advanced features. A key
+ feature for acquiring long captures in time is the ability to mask
+ any of the event inputs, which can be used to dramatically reduce
+ event occurrence and support capturing only events of interest. The
+ software supports masking events by double-clicking the signal name
+ prior to arming which hides the signals and masks them from the RLE
+ compression. 10x to 1000x compression is possible run-time for some
+ designs by dynamically masking input events prior to acquisition.
+ ---------------
+ events[31:0] -+->| Trigger Logic |-------------------------
+ | --------------- ----------------- |
+ +---------------------->| RLE Compression | |
+ | --------------- | Timestamp and |<-+
+ +->| RLE RAM |<---| Addr Generator | |
+ | --------------- ----------------- |
+ | --------------- ----------------- |
+ ->| non-RLE RAM |<-+-| Addr Generator |<-
+ --------------- | -----------------
+ --------------- |
+ dwords[511:0] -->| non-RLE RAM |<-
+ ---------------
+
+6.0 Working with large RLE datasets
+ RLE datasets can be overwhelming large to work with in software once
+ samples have been decompressed. Compression ratios of 10,000:1 are
+ possible for some systems. SUMP Software provides internal tools for
+ reducing the hardware captured RLE dataset to more manageable size
+ for both viewing and VCD generation.
+ crop_to_cursors : Permanently crops the number of samples to a
+ region indicated by the cursors.
+ RLE Decimation : 8x and 64x decimation specified at arming will
+ acquire the RLE data and reduce the sample rate
+ by 8x or 64x prior to rendering.
+ Signal Hiding : Hiding a signal prior to acquisition will mask
+ the signal entirely and increase the overall RLE
+ acquisition length. Hiding a signal post acquire
+ speeds up rendering time for remaining signals.
+
+ 6.1 Bundles
+ The following is an example of manually modifying sump2_wave.txt
+ file in order to group together multiple events into a bundle.
+ /my_cnt -bundle -hex
+ /event[12] -nickname event[12]
+ /event[13] -nickname event[13]
+ /event[14] -nickname event[14]
+ /event[15] -nickname event[15]
+
+7.0 History
+ The original OSH+OSS SUMP was designed in 2007 as an external logic
+ logic analyzer using a Xilinx FPGA eval board for capturing external
+ electrical signals non compressed to all available FPGA block RAM.
+ See http://www.sump.org/projects/analyzer/
+ The original developer published the serial communication protocol
+ and also wrote a Java based waveform capture tool. The simplicity of
+ the protocol and the quality and maintenance of the Open-Source Java
+ client has inspired many new SUMP compliant projects such as:
+ 'Open Logic Sniffer' : https://www.sparkfun.com/products/9857
+
+ 7.1 SUMP1-RLE ( 2014 )
+ Black Mesa Labs developed the SUMP1-RLE hardware in 2014 as a
+ software protocol compatible SUMP engine that was capable of real
+ time hardware compression of samples ( Run Length Encoded ). The
+ idea of the project was to leverage the open-source Java software
+ and couple it with new hardware IP that was capable of storing deep
+ capture acquisitions using only a single FPGA Block RAM, allowing
+ SUMP to be used internally with existing FPGA designs rather than
+ a standalone device. FPGA vendor closed license logic analyzers all
+ store using no compression requiring vast amount of Block RAMS to
+ be useful and typically do not fit will within the limited fabric
+ resources of an existing FPGA design requiring debugging. SUMP1-RLE
+ was later enhanced to include 2 DWORDs of sampled data along with
+ the RLE compressed signal events. This enhancement required new
+ software which was written in .NET Powershell for Windows platform.
+
+ 7.2 SUMP2-RLE ( 2016 )
+ SUMP2 is a software and hardware complete redesign to improve upon
+ the SUMP1-RLE concept. For SUMP2 the .NET software was tossed due
+ to poor user interface performance and replaced with a PyGame based
+ VCD waveform viewer ( chip_wave.py also from BML ). The SUMP2 HW
+ is now a single Verilog file with no backwards compatibility with
+ any legacy SUMP hardware or software systems. SUMP2 hardware is
+ designed to capture 512bits of DWORDs and 32bits of events versus
+ the SUMP1 limits of 16 event bits and 64bits of DWORDs. Sample
+ depth for SUMP2 is now completely defined by a hardware instance
+ with software that automatically adapts. The RLE aspect of SUMP2
+ is optional and not required for simple data intensive captures.
+ SUMP2 software includes bd_shell support for changing variables
+ on the fly and providing simple low level hardware access to regs.
+
+8.0 BD_SERVER.py
+ The SUMP2.py application does not communicate directly to hardware
+ but instead uses BD_SERVER.py as an interface layer. BD_SERVER is
+ a multi use server application that accepts requests via TCP to
+ read and write to low level hardware and then translates those
+ requests using one of many low level hardware protocols available.
+ BD_SERVER allows the low level communications to easily change from
+ interfaces like USB FTDI serial to PCI without requiring any change
+ to the high level application. This interface also supports the
+ debugging of an embedded system from a users regular desktop with
+ a standard Ethernet or Wifi connection between the two. Typical use
+ is to run both python applications on same machine and use the TCP
+ localhost feature within the TCP stack for communications.
+
+ ------------ -------------- ---------------
+ | sump2.py |<------->| bd-server.py |<------->| SUMP Hardware |
+ ------------ Ethernet -------------- USB,PCI ---------------
+
+9.0 License
+ This hardware and software is released under the GNU GPLv2 license.
+ Full license is available at http://www.gnu.org
+
projects / BML_sump2 / blobdiff