
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1. CORE:

  Riscv core has single issue 5-stage pipeline with result forwarding options.
  Core supports supervisor/user levels and has simple MMU.

  ISA Compliance:
    Base ISA      : Version 2.1
    Privileged ISA: Version 1.11



  1.1: CPU configuration:

    - BOOT_ADDR    [31:0] = 0x80000000
    - CPU_ID       [31:0] = 0x00000000
    - CACHE_ADDR_L [31:0] = 0x80000000  - cacheable address low limit
    - CACHE_ADDR_H [31:0] = 0xFFFFFFFF  - cacheable address high limit

  1.2: Cache configuraton:
    - WAYS           [1 to 8]  = 2      - Number of ways (1,2,4,8 allowed)
    - LINE_ADDR_W    [6 to 12] = 10     - Line address(2n words)
    - LINE_SIZE_W    [2 to 8]  = 5      - Line size (2n bytes)


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
2. PERIPHERALS:

  Current peripherals and their base address and IRQ vector number

   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  |  Peripheral     |  Base address  |  IRQ nro  |  Linux Driver            |
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  |  IRQ Cntroller  |  0x90000000    |    -      |  CONFIG_XILINX_INTC      |
  |  Timer          |  0x91000000    |    0      |                          |
  |  Uart Lite      |  0x92000000    |    1      |  CONFIG_SERIAL_UARTLITE  |
  |  SPI Lite       |  0x93000000    |    2      |  CONFIG_SPI_XILINX       |
  |  GPIO           |  0x94000000    |    3      |                          |
  |  16550 Uart     |  0x95000000    |    4      |  CONFIG_SERIAL_8250      |
  |  DMA            |  0x99000000    |    4      |                          |
  |  RV_IF          |  0x9B000000    |    4      |                          |
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -




  2.1: Interrupt Controller (INTC)
  = = = = = = = = = = = = = = = = =

     INTC has multiple interrupt inputs from peripheral devices and it
     combines them to a single interrupt request to processor. It has
     registers to check, enable, and acknowledge interrupts.
     Number of interrupt inputs is set in synthesis with generic NR_IRQS
     and it is currently 5.

     Kernel driver setting in dts file:
      compatible = "xlnx,xps-intc-1.00.a";

                  _______________________________________________
                 |                                               |
                 |                                               |
             5   |    ---------   ---------                      |
      intr --/---|-->| Int Det | | Irq Gen |-----------------------> irq
                 |    ---------   ---------                      |
                 |        |          /|\                         |
                 |    ___\|/__________|____                      |
                 |   |       Reg Bank      |                     |
                 |   |---------------------|     ____________    |
                 |   |       IRQ_ISR       |    |            |   |
                 |   |       IRQ_IPR       |    |            |   |
                 |   |       IRQ_IER       |    | Peripheral |   |
                 |   |       IRQ_IAR       |<-->| Interface  |<--|--> ppbus
                 |   |       IRQ_SIE       |    |            |   |
                 |   |       IRQ_CIE       |    |            |   |
                 |   |       IRQ_IVR       |    |____________|   |
                 |   |       IRQ_MER       |                     |
                 |   |_____________________|                     |
                 |                                               |
                 |_______________________________________________|

                              INTC Block Diagram


     Registers are accessed through peripheral bus.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  Register  |  Offset  |  Type  |  Description                       |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  IRQ_ISR   |  0x0000  |  [RW]  |  Interrupt Status Register         |
     |  IRQ_IPR   |  0x0004  |  [R]   |  Interrupt Pending Register        |
     |  IRQ_IER   |  0x0008  |  [RW]  |  Interrupt Enable Register         |
     |  IRQ_IAR   |  0x000C  |  [W]   |  Interrupt Acknowledge Register    |
     |  IRQ_SIE   |  0x0010  |  [W]   |  Set Interrupt Enable bits         |
     |  IRQ_CIE   |  0x0014  |  [W]   |  Clear Interrupt Enable bits       |
     |  IRQ_IVR   |  0x0018  |  [RW]  |  Interrupt Vector Register         |
     |  IRQ_MER   |  0x001C  |  [RW]  |  Master Enable Register            |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


     Register bit fields and description:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | IRQ Reg | Bits        |  Name   |  Description                        |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | IRQ_ISR | NR_IRQS-1:0 | STATUS  | Pending interrupt (unmasked) bitmap |
     |         |             |         |    0 - not active                   |
     |         |             |         |    1 - active                       |
     | IRQ_IPR | NR_IRQS-1:0 | PENDING | Pending interrupts (masked) bitmap  |
     |         |             |         |    IPR[x] = ISR[x] & IER[x]         |
     |         |             |         |                                     |
     | IRQ_IER | NR_IRQS-1:0 | ENABLE  | Interrupt enable mask               |
     |         |             |         |                                     |
     | IRQ_IAR | NR_IRQS-1:0 | ACK     | Bitmap of interrupts to acknowledge |
     |         |             |         |    ISR[x] = ~IAR[x] & ISR[x]        |
     |         |             |         |    (clears also IPR[x]              |
     |         |             |         |                                     |
     | IRQ_SIE | NR_IRQS-1:0 | SET     | Bitmap of interrupts to enable      |
     |         |             |         |    IER[x] = SIE[x] | IER[x]         |
     |         |             |         |                                     |
     | IRQ_CIE | NR_IRQS-1:0 | CLR     | Bitmap of interrupts to disable     |
     |         |             |         |    IER[x] = SIE[x] & ~IER[x]        |
     |         |             |         |                                     |
     |         |             |         |                                     |
     | IRQ_IVR |        31:0 | VECTOR  | Highest priority active interrupt   |
     |         |             |         | vector number                       |
     | IRQ_MER |           1 | HIE     | Hardware interrupt enable           |
     | IRQ_MER |           0 | ME      | Master enable                       |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -




  2.2: Timer
  = = = = = = = = = = = = = = = = =

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  Register   |  Offset  |  Type  |  Description                        |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  TMR_CTRL0  |  0x0008  |  [RW]  |  Control                            |
     |  TMR_CMP0 * |  0x000C  |  [RW]  |  Compare Value (interrupt on match) |
     |  TMR_VAL0 * |  0x0010  |  [RW]  |  Current Value                      |
     |  TMR_CTRL1  |  0x0014  |  [RW]  |  Control                            |
     |  TMR_CMP1   |  0x0018  |  [RW]  |  Compare value (interrupt on match) |
     |  TMR_VAL1   |  0x001C  |  [RW]  |  Current value                      |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

     *) NOTE: Timer0 can be set to 64-bit in hardware
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  Register   |  Offset  |  Type  |  Description                        |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  TMR_CMP0H  |  0x002C  |  [RW]  |  Compare Value                      |
     |  TMR_VAL0H  |  0x0020  |  [RW]  |  Current Value                      |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


    Register bit fields and description:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | TMR Reg    | Bits |  Name       |  Description          |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | TMR_CTRL0  |    2 | TMR0_ENA    | Timer 0 enable        |
     |            |    1 | TMR0_IRQ    | Timer 0 IRQ enable    |
     |            |      |             |                       |
     | TMR_CMP0   | 31:0 | TMR0_CMP    | Timer 0 compare value |
     |            |      |             |                       |
     | TMR_VAL0   | 31:0 | TMR0_VAL    | Timer 0 value         |
     |            |      |             |                       |
     | TMR_CTRL1  |    2 | TMR1_ENA    | Timer 1 enable        |
     |            |    1 | TMR1_IRQ    | Timer 1 IRQ enable    |
     |            |      |             |                       |
     | TMR_CMP1   | 31:0 | TMR1_CMP    | Timer 1 compare value |
     |            |      |             |                       |
     | TMR_VAL1   | 31:0 | TMR1_VAL    | Timer 1 value         |
     |            |      |             |                       |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - -



  2.3: Uart Lite
  = = = = = = = = = = = = = = = = =
    XUartLite implements hardware of driver for the Xilinx UARTL ite device.
    This UART is a minimal hardware implementation with minimal features.
    Most of the features, including baud rate, parity, and number of data
    bits are only configurable when the hardware device is built and
    cannot be altered by software.

    The device has no transmit and receive FIFOs and supports interrupts.
    The receiver of the device can not be disabled so the receive register
    may contain unwanted data but a software reset is provided to allow
    the user to reset the RX full register.

    An interrupt is generated when the transmit register transitions from
    having data to being empty or when any data is contained in the receive
    register.

    Kernel driver setting in dts file:
     compatible = "xlnx,xps-uartlite-1.00.a";

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  Register    |  Offset  |  Type  |  Description                  |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  ULITE_RX    |  0x0000  |  [R]   |  UART Data Register           |
     |  ULITE_TX    |  0x0004  |  [W]   |  UART Data Register           |
     |  ULITE_ST    |  0x0008  |  [R]   |  UART Status Register         |
     |  ULITE_CTRL  |  0x000C  |  [RW]  |  UART Configuration Register  |
     |  ULITE_DIV   |  0x0010  |  [RW]  |  UART Divider Register        |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


    Register bit fields and description:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | UART Reg   | Bits |  Name       |  Description        |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | ULITE_RX   | 7:0  | RX_DATA     | Received data       |
     |            |      |             |                     |
     | ULITE_TX   | 7:0  | TX_DATA     | Transmit data       |
     |            |      |             |                     |
     | ULITE_ST   |   4  | ST_IE       | Irq enable status   |
     |            |   3  | ST_TXFULL   | Transmitter busy    |
     |            |   2  | ST_TXEMPTY  | TX register empty   |
     |            |   1  | ST_RXFULL   | Receiver ready      |
     |            |   0  | ST_RXVALID  | Receiver ready      |
     |            |      |             |                     |
     | ULITE_CTRL |   4  | CTRL_IE     | Irq enable          |
     |            |   1  | CTRL_RST_RX | Software reset      |
     |            |      |             |                     |
     | ULITE_DIV  |   12 | UART_DIV    | Baud rate           |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | NOTES: RXFULL == RXVALID                              |
     |        ST_IE not used in logic                        |
     |                                                       |
     |        UART_DIV: Default 1M @ 50MHz system clock      |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - -



  2.4: SPI Lite
  = = = = = = = = = = = = = = = = =

    SPI lite is a master 1-bit spi which has 8 byte tx and rx fifos.
    The SPI interface uses standard MOSI, MISO, SCLK, and either an
    active-low or active-high CS. The SPI module has run-time configurable
    baud rate, bit ordering, and SPI mode (CPOL, CPHA) selection and
    includes a loopback feature for testing.

    Kernel driver setting in dts file:
      compatible = "xlnx,xps-spi-2.00.b";


      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  Register   |  Offset  |  Type  |  Description                          |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  SPI_DGIER  |  0x001C  |  [RW]  |  SPI Global Interrupt Enable Register |
     |  SPI_IPISR  |  0x0020  |  [RW]  |  SPI Interrupt Status Register        |
     |  SPI_IPIER  |  0x0028  |  [RW]  |  SPI Interrupt Enable Register        |
     |  SPI_SRR    |  0x0040  |  [W]   |  SPI Software Reset Register          |
     |  SPI_CR     |  0x0060  |  [RW]  |  SPI Control Register                 |
     |  SPI_SR     |  0x0064  |  [R]   |  SPI Status Register                  |
     |  SPI_DTR    |  0x0068  |  [W]   |  SPI Data Transmit Register           |
     |  SPI_DRR    |  0x006C  |  [R]   |  SPI Data Receive Register            |
     |  SPI_SSR    |  0x0070  |  [RW]  |  SPI Slave Select Register            |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


     Register bit fields and description:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | SPI Reg   | Bits |  Name      |  Description                    |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     | SPI_DGIER |   31 | DGIER      | Global irq enable               |
     |           |      |            |                                 |
     | SPI_IPISR |    2 | IPISR      | TX fifo empty                   |
     |           |      |            |                                 |
     | SPI_IPIER |    2 | IPIER      | Enable TX fifo empty irq        |
     |           |      |            |                                 |
     | SPI_SRR   | 31:0 | SRR        | Writing 0x0000000A flushes      |
     |           |      |            | fifos and reset logic           |
     |           |      |            |                                 |
     | SPI_CR    |    9 | LSB_1ST    | Transmit lsb bit first          |
     |           |    8 | TX_INHIBIT | Inhibit transmit (enable)       |
     |           |    7 | MANUAL_SS  | (No function)                   |
     |           |    6 | RXFIFO_RST | Flush RX fifo                   |
     |           |    5 | TXFIFO_RST | Flush TX fifo                   |
     |           |    4 | CPHA       | Clock phase                     |
     |           |    3 | CPOL       | CLOCK polarity                  |
     |           |    2 | MASTER     | Master mode                     |
     |           |    1 | ENABLE     | SPI enable                      |
     |           |    0 | LOOPBACK   | Enable loopback testing         |
     |           |      |            |                                 |
     | SPI_SR    |    3 |            | Transmit fifo full              |
     |           |    2 |            | Transmit fifo empty             |
     |           |    1 |            | Receive fifo full               |
     |           |    0 |            | Receive fifo empty              |
     |           |      |            |                                 |
     | SPI_DTR   | 31:0 | DTR        | Transmit data byte              |
     |           |      |            |                                 |
     | SPI_DRR   |  7:0 | DRR        | Received data byte              |
     |           |      |            |                                 |
     | SPI_SSR   |    0 | SSR        | Slave select (cs output value)  |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


  2.5: GPIO
  = = = = = = = = = = = = = = = = =

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  Register    |  Offset  |  Type  |  Description                      |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     |  GPIO_DIR         |  0x0000  |  [RW]  |  GPIO Configuration Register |
     |  GPIO_IN          |  0x0004  |  [R]   |  GPIO Input Status           |
     |  GPIO_OUT         |  0x0008  |  [RW]  |  GPIO Output Control         |
     |  GPIO_OUT_SET     |  0x000C  |  [W]   |  GPIO Output Control Set     |
     |  GPIO_OUT_CLR     |  0x0010  |  [W]   |  GPIO Output Control Clr     |
     |  GPIO_INT_MASK    |  0x0014  |  [RW]  |  GPIO Interrupt Enable Mask  |
     |  GPIO_INT_SET     |  0x0018  |  [W]   |  GPIO Interrupt Set          |
     |  GPIO_INT_CLR     |  0x001C  |  [W]   |  GPIO Interrupt Clear        |
     |  GPIO_INT_STATUS  |  0x0020  |  [R]   |  GPIO Interrupt Raw Status   |
     |  GPIO_INT_LEVEL   |  0x0024  |  [RW]  |  GPIO Interrupt Level        |
     |  GPIO_INT_MODE    |  0x0028  |  [RW]  |  GPIO Interrupt Mode         |
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -




  2.6: 16550 uart:
    16550 uart is designed to be compatible with industry standard
    National Semiconductors' NS16550A. It can be conected to computer
    using serial cable and RS232 protocol

    - - -
    Example to configure 16550 uart at 115200 baud rate:

        li t1, UART_BASE

        li t0, 0x00
        sb t0, UART_REG_IE(t1)     // Disable all interrupts

        li t0, 0x80
        sb t0, UART_REG_LC(t1)     // Enable DLAB (set baud rate divisor)

        // Baud Rate = Clock Frequency / (16 x N)  and that N = DLL + DLM
        // 50000000 / (16 * 27)  == 115740.74074    ( 27 = 0x1B )

        li t0, 0x1B
        sb t0, UART_REG_DL1(t1)    // Set divisor (lo byte)

        li t0, 0x00
        sb t0, UART_REG_DL2(t1)    // (uint8_t)(divisor >> 8);     //  (hi byte)

        li t0, 0x03
        sb t0, UART_REG_LC(t1)     // 8 bits, no parity, one stop bit

        li t0, 0xC7
        sb t0, UART_REG_FC(t1) //Enable FIFO, clear them, with 14-byte threshold



- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3. Debug uart

   Debug uart is connected to uart pins after reset and it can be used to
   upload software to DDR memory.

   Read / write protocol:

      #  REQ_WRITE = 0x10,  LEN, ADDR0,1,2,3,  DATA0,1,2,3
      SendByte { 0x10 }
      #    LEN (bytes)
      SendByte { 0x04 }
      #    ADDR (32 bits)         ! ! NOTE: MSB BYTE 1ST
      SendByte { 0x80 }
      SendByte { 0x00 }
      SendByte { 0x00 }
      SendByte { 0x00 }
      #    DATA (LEN x bytes)     ! ! NOTE: LSB BYTE 1ST
      SendByte { 0xBE }
      SendByte { 0xBA }
      SendByte { 0xCE }
      SendByte { 0xFA }


      # REQ_READ = 0x11;  LEN, ADDR0,1,2,3
      SendByte { 0x11 }
      SendByte { 0x04 }
      SendByte { 0x90 }
      SendByte { 0x00 }
      SendByte { 0x00 }
      SendByte { 0x04 }
      => receive LEN bytes


   When software is in DDR the core is released from reset by writing
   0x00000001 to register in address 0xF00000000 :

      SendByte { 0x10 }   # write cmd
      SendByte { 0x04 }   # word
      SendByte { 0xF0 }   # ADDR (32 bits)      ! ! NOTE: MSB BYTE 1ST
      SendByte { 0x00 }
      SendByte { 0x00 }
      SendByte { 0x00 }
      SendByte { 0x01 }   # DATA (LEN x bytes)  ! ! NOTE: LSB BYTE 1ST
      SendByte { 0x00 }
      SendByte { 0x00 }
      SendByte { 0x00 }

  Releasing core reset also switches uart lite rx/tx to uart pins.



  Running run.py uploads software and releses core from reset, like:
    ./run.py -d /dev/ttyUSB0 -b 1000000 -f kernel.elf

  usage: run.py [-h] [-t TYPE] [-d DEVICE] [-b BAUD] -f FILENAME [-p PROGARGS]

  optional arguments:
    -h, --help   show this help message and exit
    -t TYPE      Device type (uart|ftdi)
    -d DEVICE    Serial Device
    -b BAUD      Baud rate
    -f FILENAME  File to load
    -p PROGARGS  Program load argument string

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
