LEON3 Template design for Digilent Arty A7
------------------------------------------

Synthesis
---------

The design can be synthesized with Xilinx Vivado 2018.1. Use 'make
vivado' to run the complete flow, or 'make vivado-launch' for an
interactive session with Vivado. To program the FPGA in batch mode, use
'make vivprog'. To program the configuration flash, use 'make vivrom'.

XC7A100T is the default target FPGA. To change the target to XC7A35T,
change FPGA type in xconfig in the "Synthesis" section.

The design uses the Xilinx MIG memory interface with an AHB-2.0
interface by default. The MIG source code cannot be distributed due
to the prohibitive Xilinx license, so the MIG must be re-generated
with coregen before simulation and synthesis. Xilinx MIG interface
will automatically be generated when Vivado is launched.

A setup slack timing summary can be generated with 'make vivslack'
which outputs to the files vivslack.rpt, vivsetup.rpt and vivhold.rpt.


Simulation
----------

To simulate using GHDL:
  make ghdl
  make ghdl-run

To simulate using XSIM and run systest.c on the design using the
memory controller from Xilinx use the make targets:

  make soft
  make vivado-launch

To simulate using Modelsim/Aldec and run systest.c on the design
using the memory controller from Xilinx use the make targets:

  make map_xilinx_7series_lib
  make sim
  make mig_7series (only required if Xilinx MIG is enabled via xconfig)
  make soft
  make sim-launch

To simulate using Aldec Riviera use the following make targets:

  make map_xilinx_7series_lib
  make riviera
  make mig_series7 (only required if Xilinx MIG is enabled via xconfig)
  make soft
  make riviera-launch


Design overview
---------------

* The default configuration sets the system frequency to 83 MHz.

* The AHB clock is generated by the MMCM module in the MIG
  controller, and can be controlled via Coregen. When the MIG DDR3
  controller isn't present the AHB clock is generated from CLKGEN,
  and can be controlled via xconfig

* In order to connect through the USB JTAG-interface run
  "grmon -digilent".

* In order to connect through the Ethernet EDCL debug link
  "grmon -eth 192.168.0.175".

* The JTAG debug link is available via the USB-JTAG bridge.
  Start grmon with -digilent to connect with JTAG.

* Ethernet is supported in 10/100Mbit mode and EDCL is enabled.

* LEDs and buttons
  - LED 4: PLL locked
  - LED 5: Indicates the end of the calibration phase for the memory
    controller.
  - LED 6: DSU is active
  - LED 7: Processor is in error mode
  - BUTTON 3: DSU break
  - SWITCH 3: DSU enable
  - RESET: Reset


Example GRMON session
---------------------

The output from grmon should look something like this:

  GRMON debug monitor v3.2.8.2
  
  Copyright (C) 2020 Cobham Gaisler - All rights reserved.
  For latest updates, go to http://www.gaisler.com/
  Comments or bug-reports to support@gaisler.com

  GRLIB build version: 4254
  Detected frequency:  83.0 MHz
  
  Component                            Vendor
  LEON3 SPARC V8 Processor             Cobham Gaisler
  JTAG Debug Link                      Cobham Gaisler
  GR Ethernet MAC                      Cobham Gaisler
  SPI Memory Controller                Cobham Gaisler
  AHB/APB Bridge                       Cobham Gaisler
  LEON3 Debug Support Unit             Cobham Gaisler
  Xilinx MIG Controller                Cobham Gaisler
  Generic UART                         Cobham Gaisler
  Multi-processor Interrupt Ctrl.      Cobham Gaisler
  Modular Timer Unit                   Cobham Gaisler
  AMBA Wrapper for OC I2C-master       Cobham Gaisler
  SPI Controller                       Cobham Gaisler
  General Purpose I/O port             Cobham Gaisler
  General Purpose I/O port             Cobham Gaisler
  General Purpose I/O port             Cobham Gaisler
  
  Use command 'info sys' to print a detailed report of attached cores

grmon3> info sys
  cpu0      Cobham Gaisler  LEON3 SPARC V8 Processor    
            AHB Master 0
  ahbjtag0  Cobham Gaisler  JTAG Debug Link    
            AHB Master 1
  greth0    Cobham Gaisler  GR Ethernet MAC    
            AHB Master 2
            APB: 80000f00 - 80001000
            IRQ: 12
            edcl ip 192.168.0.175, buffer 16 kbyte
  spim0     Cobham Gaisler  SPI Memory Controller    
            AHB: fff00000 - fff80000
            AHB: 00000000 - 20000000
            IRQ: 10
            SPI memory device read command: 0x0b
  apbmst0   Cobham Gaisler  AHB/APB Bridge    
            AHB: 80000000 - 80100000
  dsu0      Cobham Gaisler  LEON3 Debug Support Unit    
            AHB: 90000000 - a0000000
            AHB trace: 1024 lines, 32-bit bus
            CPU0:  win 8, nwp 4, itrace 1024, V8 mul/div, lddel 2
                   stack pointer 0x47fffff0
                   icache 2 * 16 kB, 32 B/line, dir
                   dcache 2 * 16 kB, 32 B/line, dir
  mig0      Cobham Gaisler  Xilinx MIG Controller    
            AHB: 40000000 - 50000000
            APB: 80000500 - 80000600
            SDRAM: 128 Mbyte
  uart0     Cobham Gaisler  Generic UART    
            APB: 80000100 - 80000200
            IRQ: 2
            Baudrate 38425, FIFO debug mode available
  irqmp0    Cobham Gaisler  Multi-processor Interrupt Ctrl.    
            APB: 80000200 - 80000300
  gptimer0  Cobham Gaisler  Modular Timer Unit    
            APB: 80000300 - 80000400
            IRQ: 8
            8-bit scalar, 2 * 32-bit timers, divisor 83
  i2cmst0   Cobham Gaisler  AMBA Wrapper for OC I2C-master    
            APB: 80000400 - 80000500
            IRQ: 3
  spi0      Cobham Gaisler  SPI Controller    
            APB: 80000600 - 80000700
            IRQ: 5
            FIFO depth: 4, 1 slave select signals
            Maximum word length: 32 bits
            Controller index for use in GRMON: 0
  gpio0     Cobham Gaisler  General Purpose I/O port    
            APB: 80000900 - 80000a00
            IRQ: 4
  gpio1     Cobham Gaisler  General Purpose I/O port    
            APB: 80000a00 - 80000b00
            IRQ: 6
  gpio2     Cobham Gaisler  General Purpose I/O port    
            APB: 80000b00 - 80000c00
            IRQ: 7


grmon3> spim flash detect 
  Got manufacturer ID 0x20 and device ID 0xba18
  Detected device: ST/Numonyx N25Q128


GPIO
----

The design has 3 GPIO controllers.


GPIO0
-----

  GRGPIO0 line(s)  Direction  Board signal
    19:16            <-        SW[3:0]
    15:12            <-        BTN[3:0]
    11,10,9           ->       LED3_[R,G,B]
     8,7,6            ->       LED2_[R,G,B]
     5,3,2            ->       LED1_[R,G,B]
     2,1,0            ->       LED0_[R,G,B]

gpio0 can generate interrupt 4 from GPIO line 19:12. 


GPIO1
-----

GPIO1 controls the pins of the PMOD sockets and can generate interrupt
6 from GPIO line 31:0.

  GRGPIO1 line(s)  Direction  Board signal
    31:24            <->       PMOD JD
    23:16            <->       PMOD JC
    15:8             <->       PMOD JB
     7:0             <->       PMOD JA

Note the following from the "Arty A7 Reference Manual":
  "Warning: Since the Pmod pins are connected to Artix-7 FPGA pins
  using a 3.3V logic standard, care should be taken not to drive
  these pins over 3.4V."


GPIO2
-----

GPIO2 controls the pins of the Arduino/ChipKit sockets and can generate
interrupt 7 from GPIO line 19:0.

  GRGPIO2 line(s)  Direction  Board signal
    19:14            <->       A[5:0]
    13:0             <->       IO[13:0]

Note the following from the "Arty A7 Reference Manual":
  "Warning: The Arty A7 is not compatible with shields that output
  5V digital or analog signals. Driving pins on the shield connector
  above 3.4V may cause damage to the FPGA."


SPI flash memory controller
---------------------------

Boot Flash is provided via SPIMCTRL from the board's SPI flash device.

The design can also use on-chip ROM via the AHBROM core. Note that the
SPI memory controller must be disabled to include the AHBROM core in
the design. If both cores are enabled in xconfig only the SPI memory
controller will be instantiated in leon3mp.vhd.

Typically the lower part of the SPI flash device will hold the
configuration bitstream for the FPGA. The SPIMCTRL core is configured
with an offset value that will be added to the incoming AHB address
before the address is propagated to the SPI flash device. The
default offset is 0x00400000 (this value is set via xconfig and the
constant is called CFG_SPIMCTRL_OFFSET). When the processor starts
after power-up it will read address 0x0, this will be translated by
SPIMCTRL to 0x00400000.

SPIMCTRL can only add this offset to accesses made via the core's
memory area. For accesses made via the register interface the offset
must be taken into account. This means that if we want to program
the Flash with an application which is linked to address 0x0 (our
typical bootloader) then we need to add the offset 0x00400000 before
programming the file with GRMON. We load the Flash with our application
starting at 0x00400000 and SPIMCTRL will then translate accesses from
AMBA address 0x0 + n to Flash address 0x00400000 + n.

For further details on how to generate an image file and programming
the SPI flash, please see designs/leon3-terasic-de0-nano/README.txt.


3. Application UART
-------------------

The design has one APBUART, which is connected to the on-board
USB-UART bridge.


4. Debug link UART
------------------

The design can optionally be configured to have an AHBUART debug
link. It is disabled by default. If enabled, it will be connected to
the on-board USB-UART bridge and take precedence over the APBUART.


5. I2C master
-------------

One I2CMST core is connected to the Arduino I2C connectors.


6. SPI controller
-----------------

One SPICTRL core is connected to the 6-pin SPI header (J6).

The 6-pin SPI header (J6) has no connection with the on-board SPI
flash memory device. The SPICTRL operates independent of the SPIMCTRL.

