Merge pull request #177 from Pradeep2004/master

New Readme file to debug Murax SoC without usnig Jtag Adapter

doc/nativeJtag/Readme

@@ -0,0 +1,80 @@
+1. INTRODUCTION 
+
+The traditional way of debugging an SoC which is programmed inside a FPGA was by using a JTAG Adapter which comes with an FTDI Chip. In recent times, modern FPGA’s come with an integrated FTDI chip which makes debugging easy with only a USB cable.
+
+In this document, I am going to guide you through the steps in an experiment which I conducted along with my supervisor to debug an SoC named MURAX without using an external JTAG adapter on ARTY A7 FPGA.
+
+2. Generation of Bscane2 within Murax SoC in Linux
+
+The BSCANE2 allows access between the internal FPGA logic and the JTAG Boundary Scan logic controller. This allows for communication between the internal running design and the dedicated JTAG pins of the FPGA.
+
+2.1 Steps to create Bscane2
+
+• After cloning all the files from https://github.com/SpinalHDL/VexRiscv, go to this path : src/main/scala/vexriscv/demo and find the Murax.scala file.
+
+• Comment out the following lines to remove the toplevel jtag I/O pins in Murax.scala file
+   val jtag = slave(Jtag())
+   val jtagClkBuffer = SB_GB()
+   jtagClkBuffer.USER_SIGNAL_TO_GLOBAL_BUFFER <> io.jtag_tck
+   jtagClkBuffer.GLOBAL_BUFFER_OUTPUT <> murax.io.jtag.tck
+   murax.io.jtag.tdi <> io.jtag_tdi
+   murax.io.jtag.tdo <> io.jtag_tdo
+   murax.io.jtag.tms <> io.jtag_tms
+
+• In the Murax.scala file, delete line number 253 and add the following lines :
+          val jtagCtrl = JtagTapInstructionCtrl()
+          val tap = jtagCtrl.fromXilinxBscane2(userId = 2)
+          jtagCtrl <> plugin.io.bus.fromJtagInstructionCtrl(ClockDomain(tap.TCK))
+
+• Add the following import statement at the beginning in Murax.scala :
+import spinal.lib.com.jtag.JtagTapInstructionCtrl
+
+• Then to generate the SoC with a demo program already in ram, run:
+sbt "runMain vexriscv.demo.MuraxWithRamInit"
+
+• A verilog file will be generated with the name Murax.v and four .bin files will be generated inside VexRiscv folder which can be used to program the FPGA. Inside the Murax.v file, we can see that the Bscane2 ports will be instantiated, confirming that the Bscane2 has been created within the Murax SoC to debug it.
+ 
+3. Programming Arty A7 FPGA
+
+There are many applications to program a FPGA. I am using Xilinx Vivado 2020 Application to program the FPGA.
+
+3.1 Steps involved to program the FPGA
+
+• Create a new project and choose the board which are using and choose the constraint file.
+
+• As, I mentioned in the previous section a verilog file and  four .bin files will be generated in the Vexriscv folder. Copy these files and paste them inside your vivado project in this path : project_name.srcs\sources_1\imports\Downloads
+
+• Create a toplevel file by instantiating Murax I/O ports in it to blink the LED’s on the FPGA. (Note : The program to blink the LED’s is already present in Murax.v file). The toplevel file and constraint file, if required can be found here : https://github.com/SpinalHDL/VexRiscv/tree/master/scripts/Murax/arty_a7 , but make sure all the jtag ports of Murax are commented or deleted in the toplevel file.
+
+• Next, click Generate Bitstream and program the FPGA with the bit file. You can see the LED’s blink and Murax SoC has been programmed into the FPGA.
+
+4. Debugging via OpenOCD GDB in Linux
+
+• In a new terminal in Linux, after cloning and setting up openocd with the steps provided in this link : https://github.com/SpinalHDL/openocd_riscv , run the below command to establish a openocd connection with Jtag of FPGA.
+• To run openocd : 
+Use the below command :
+src/openocd -c "set CPU0_YAML ..VexRiscv/cpu0.yaml" -f tcl/interface/usb_connect.cfg -f tcl/interface/soc_init.cfg
+
+• You basically have to provide 2 files.
+usb_connect.cfg => interface configuration
+soc_init.cfg => take over the control of the CPU.
+
+• For usb_connect.cfg
+you can take it from https://github.com/SpinalHDL/SaxonSoc/blob/dev-0.3/bsp/digilent/ArtyA7SmpLinux/openocd/usb_connect.cfg (without modifications i would say)
+
+
+• For soc_init.cfg
+https://github.com/SpinalHDL/SaxonSoc/blob/dev-0.3/bsp/digilent/ArtyA7SmpLinux/openocd/soc_init.cfg
+You can take it but you need to : set cpu_count to 1 and remove Line 22 to 35.
+
+• Then, after openocd is running, in new terminal, follow the below commands in VexriscvSocSoftware folder ( https://github.com/SpinalHDL/VexRiscvSocSoftware )
+
+• Go to the path VexRiscvSocSoftware/projects/murax/demo/build and then give the below commands :
+
+ riscv64-unknown-elf-gdb demo.elf 
+ target remote localhost:3333
+ monitor reset halt
+ load
+ continue
+
+• After giving the monitor reset halt command you can see that the LED’s stop blinking and when the continue command is given the LED’s start continuing from the point where they stopped.

doc/nativeJtag/soc_init.cfg

@@ -0,0 +1,20 @@
+set cpu_count 1
+
+
+for {set i 0} {$i < $cpu_count} {incr i} {
+    target create saxon.cpu$i vexriscv -endian little -chain-position $TAP_NAME -coreid $i -dbgbase [expr $i*0x1000+0x10B80000]
+    vexriscv readWaitCycles 40
+    vexriscv cpuConfigFile $CPU0_YAML
+    if {$SPINAL_SIM != "yes"} {
+        vexriscv jtagMapping 3 3 0 1 2 2
+    }
+}
+
+for {set i 0} {$i < $cpu_count} {incr i} {
+    targets saxon.cpu$i
+    poll_period 50
+    init
+    soft_reset_halt
+}
+
+puts " done"

doc/nativeJtag/usb_connect.cfg

@@ -0,0 +1,32 @@
+if [info exists env(SPINAL_SIM)] {
+    set SPINAL_SIM $::env(SPINAL_SIM)
+} else {
+    set SPINAL_SIM no
+}
+
+
+
+if {$SPINAL_SIM == "yes"} {
+    interface jtag_tcp
+    set _CHIPNAME fpga_spinal
+    set TAP_NAME $_CHIPNAME.bridge
+    set _CPUTAPID 0x10001fff
+    jtag newtap $_CHIPNAME bridge -expected-id $_CPUTAPID -irlen 4 -ircapture 0x1 -irmask 0xF
+    reset_config none
+    adapter_khz 50000
+} else {
+    interface ftdi
+    ftdi_device_desc "Digilent USB Device"
+    ftdi_vid_pid 0x0403 0x6010
+    ftdi_channel 0
+    ftdi_layout_init 0x00e8 0x60eb
+    ftdi_tdo_sample_edge falling
+
+    reset_config none
+    adapter_khz 50000
+
+    source [find cpld/xilinx-xc7.cfg]
+    source [find cpld/jtagspi.cfg]
+
+    set TAP_NAME xc7.tap
+}