neorv32/sw/example/demo_xip/main.c

// #################################################################################################
// # << NEORV32 - Demo for the Execute In-Place (XIP) Module >>                                    #
// # ********************************************************************************************* #
// # BSD 3-Clause License                                                                          #
// #                                                                                               #
// # Copyright (c) 2024, Stephan Nolting. All rights reserved.                                     #
// #                                                                                               #
// # Redistribution and use in source and binary forms, with or without modification, are          #
// # permitted provided that the following conditions are met:                                     #
// #                                                                                               #
// # 1. Redistributions of source code must retain the above copyright notice, this list of        #
// #    conditions and the following disclaimer.                                                   #
// #                                                                                               #
// # 2. Redistributions in binary form must reproduce the above copyright notice, this list of     #
// #    conditions and the following disclaimer in the documentation and/or other materials        #
// #    provided with the distribution.                                                            #
// #                                                                                               #
// # 3. Neither the name of the copyright holder nor the names of its contributors may be used to  #
// #    endorse or promote products derived from this software without specific prior written      #
// #    permission.                                                                                #
// #                                                                                               #
// # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS   #
// # OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF               #
// # MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE    #
// # COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,     #
// # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE #
// # GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED    #
// # AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING     #
// # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED  #
// # OF THE POSSIBILITY OF SUCH DAMAGE.                                                            #
// # ********************************************************************************************* #
// # The NEORV32 Processor - https://github.com/stnolting/neorv32              (c) Stephan Nolting #
// #################################################################################################


/**********************************************************************//**
 * @file demo_xip/main.c
 * @author Stephan Nolting
 * @brief Interactive console program to upload and execute a XIP program.
 **************************************************************************/

#include <neorv32.h>


/**********************************************************************//**
 * @name User configuration
 **************************************************************************/
/**@{*/
/** UART BAUD rate */
#define BAUD_RATE 19200
/** Flash base address (32-bit) */
#define FLASH_BASE 0x00400000
/** Flash address bytes */
#define FLASH_ABYTES 3
/** XIP SPI clock prescaler select */
#define XIP_CLK_PRSC CLK_PRSC_128
/** Executable RAM buffer size in bytes */
#define BUFFER_SIZE (7*1024)
/**@}*/


/**********************************************************************//**
 * SPI flash commands
 **************************************************************************/
enum SPI_FLASH_CMD {
  SPI_FLASH_CMD_WRITE         = 0x02, /**< Write data */
  SPI_FLASH_CMD_READ          = 0x03, /**< Read data */
  SPI_FLASH_CMD_READ_STATUS   = 0x05, /**< Get status register */
  SPI_FLASH_CMD_WRITE_ENABLE  = 0x06, /**< Allow write access */
  SPI_FLASH_CMD_SECTOR_ERASE  = 0xD8  /**< Erase complete sector */
};

/**********************************************************************//**
 * Valid executable identification signature
 **************************************************************************/
#define EXE_SIGNATURE 0x4788CAFE


/**********************************************************************//**
 * @name Prototypes
 **************************************************************************/
void xip_flash_erase_sector(uint32_t base_addr);
void xip_flash_program(uint32_t *src, uint32_t base_addr, uint32_t size);
int uart_get_executable(uint32_t *dst, uint32_t *size);
uint32_t uart_get_word(void);


/**********************************************************************//**
 * @name RAM storage for executable
 **************************************************************************/
uint32_t ram_buffer[BUFFER_SIZE/4];


/**********************************************************************//**
 * Main function
 *
 * @note This program requires the XIP module and UART0.
 *
 * @return 0 if execution was successful
 **************************************************************************/
int main() {

  // capture all exceptions and give debug info via UART
  // this is not required, but keeps us safe
  neorv32_rte_setup();

  // setup UART at default baud rate, no interrupts
  neorv32_uart0_setup(BAUD_RATE, 0);

  // check if XIP module is implemented at all
  if (neorv32_xip_available() == 0) {
    neorv32_uart0_printf("Error! XIP module not synthesized!\n");
    return 1;
  }


  // ----------------------------------------------------------
  // Intro and setup
  // ----------------------------------------------------------
  neorv32_uart0_printf("<< XIP Demo Program >>\n\n");

  // configuration note
  neorv32_uart0_printf("Flash base address:  0x%x\n"
                       "XIP base address:    0x%x\n"
                       "Flash address bytes: %u\n", (uint32_t)FLASH_BASE, (uint32_t)XIP_MEM_BASE_ADDRESS, (uint32_t)FLASH_ABYTES);


  // warning if XIP cache is not implemented
  if ((NEORV32_XIP->CTRL & (1 << XIP_CTRL_BURST_EN)) == 0) {
    neorv32_uart0_printf("WARNING! No XIP cache implemented! The XIP program might run very slow...\n");
  }


  // reset XIP module and configure basic SPI properties
  // * clock prescaler = XIP_CLK_PRSC (see defines)
  // * clock divider = 4
  // * clock mode 0 (cpol = 0, cpha = 0)
  // * flash read command = SPI_FLASH_CMD_READ (see defines)
  // -> this function will also send 64 dummy clock cycles via the XIP's SPI port (with CS disabled)
  neorv32_xip_setup(XIP_CLK_PRSC, 4, 0, 0, SPI_FLASH_CMD_READ);

  neorv32_uart0_printf("XIP SPI clock speed: %u Hz\n\n", neorv32_xip_get_clock_speed());


  // ----------------------------------------------------------
  // Get executable for flash
  // ----------------------------------------------------------
  neorv32_uart0_printf("Compile a program for the XIP flash:\n"
                       "\n"
                       " Navigate to any example program folder (like 'neorv32/sw/example/hello_word').\n"
                       " Compile the program but relocate the executable to the beginning of the XIP flash:\n"
                       " make MARCH=rv32i_zicsr_zifencei USER_FLAGS+=\"-Wl,--defsym,__neorv32_rom_base=0x%x\" clean_all exe\n\n",
                       (uint32_t)(XIP_MEM_BASE_ADDRESS + FLASH_BASE));

  neorv32_uart0_printf("Press any key when you are ready.\n\n");
  neorv32_uart0_getc(); // wait for any key

  neorv32_uart0_printf("Now send the generated neorv32_exe.bin file in raw byte mode...\n");

  uint32_t exe_size = 0;
  int rc = uart_get_executable(&ram_buffer[0], &exe_size);

  // upload ok?
  if (rc) {
    neorv32_uart0_printf("[ERROR] Upload failed with error code %d!\n", rc);
    return -1;
  }

  // image size in range?
  if (exe_size > BUFFER_SIZE) {
    neorv32_uart0_printf("[ERROR] Executable size out of range (%u bytes, maximum = %u bytes)!\n", exe_size, BUFFER_SIZE);
    return -1;
  }
  else {
    neorv32_uart0_printf("Executable upload successful (%u bytes).\n\n", exe_size);
  }


  // ----------------------------------------------------------
  // Program flash
  // ----------------------------------------------------------

  // NOTE: this (direct SPI access via the XIP module) has to be done before the actual XIP mode is enabled!
  neorv32_uart0_printf("Erasing XIP flash (base = 0x%x)...\n", (uint32_t)FLASH_BASE);
  xip_flash_erase_sector(FLASH_BASE);

  neorv32_uart0_printf("Programming XIP flash (%u bytes)...\n", exe_size);
  xip_flash_program((uint32_t*)&ram_buffer[0], FLASH_BASE, exe_size);


  // ----------------------------------------------------------
  // Prepare XIP execution
  // ----------------------------------------------------------

  // configure and enable the actual XIP mode
  // * configure FLASH_ABYTES address bytes send to the SPI flash for addressing
  // * map the XIP flash to the address space starting at XIP_MEM_BASE_ADDRESS - only the 4 MSBs are relevant here
  // after calling this function the SPI flash is mapped to the processor's address space and is accessible as "normal"
  // memory-mapped read-only memory
  if (neorv32_xip_start(FLASH_ABYTES)) {
    neorv32_uart0_printf("Error! XIP mode configuration error!\n");
    return 1;
  }

  // since the flash is now mapped to the processor's address space we can dump its content by using normal memory accesses
  neorv32_uart0_printf("\nRead-back XIP flash content (first 10 words) via memory-mapped access...\n");
  uint32_t flash_base_addr = XIP_MEM_BASE_ADDRESS + FLASH_BASE;
  uint32_t *xip_mem = (uint32_t*)flash_base_addr;
  asm volatile("fence");
  uint32_t i;
  for (i=0; i<10; i++) {
    neorv32_uart0_printf("[0x%x] 0x%x\n", flash_base_addr + 4*i, xip_mem[i]);
  }

  // the flash is READ-ONLY in XIP mode - any write access to the XIP-mapped memory page will raise
  // a store bus exception / device error (captured by the NEORV32 runtime environment)
  neorv32_uart0_printf("\nTest write access to XIP memory (will raise an exception)...\n");
  *xip_mem = 0; // try to write to the flash using XIP


  // ----------------------------------------------------------
  // Run program from flash
  // ----------------------------------------------------------

  // finally, jump to the XIP flash's base address we have configured to start execution **from there**
  neorv32_uart0_printf("\nStarting Execute In-Place program (@0x%x)...\n", (uint32_t)(XIP_MEM_BASE_ADDRESS + FLASH_BASE));
  asm volatile("fence.i");
  asm volatile ("call %[dest]" : : [dest] "i" (XIP_MEM_BASE_ADDRESS + FLASH_BASE));


  // this should never be reached
  neorv32_uart0_printf("Error! Starting XIP program failed!\n");
  return 1;
}


// ============================================================================================================
// Helper functions
// ============================================================================================================


/**********************************************************************//**
 * Erase sector starting at base address.
 *
 * @param[in] base_addr Base address of sector to erase.
 **************************************************************************/
void xip_flash_erase_sector(uint32_t base_addr) {

  uint32_t tmp = 0;

  union {
    uint64_t uint64;
    uint32_t uint32[sizeof(uint64_t)/sizeof(uint32_t)];
  } data;

  // set write-enable latch
  // 1 byte command
  data.uint32[0] = 0;
  data.uint32[1] = SPI_FLASH_CMD_WRITE_ENABLE << 24; // command: set write-enable latch
  neorv32_xip_spi_trans(1, &data.uint64);

  // execute sector erase command
  // 1 byte command, FLASH_ABYTES bytes address
  tmp = SPI_FLASH_CMD_SECTOR_ERASE << 24; // command: erase sector
  if (FLASH_ABYTES == 1) { tmp |= (base_addr & 0x000000FF) << 16; } // address
  if (FLASH_ABYTES == 2) { tmp |= (base_addr & 0x0000FFFF) <<  8; } // address
  if (FLASH_ABYTES == 3) { tmp |= (base_addr & 0x00FFFFFF) <<  0; } // address
  data.uint32[0] = 0;
  data.uint32[1] = tmp;
  neorv32_xip_spi_trans(1 + FLASH_ABYTES, &data.uint64);

  // check status register: WIP bit has to clear
  while(1) {
    tmp = SPI_FLASH_CMD_READ_STATUS << 24; // read status register command
    data.uint32[0] = 0;
    data.uint32[1] = tmp;
    neorv32_xip_spi_trans(2, &data.uint64);
    if ((data.uint32[0] & 0x01) == 0) { // WIP bit cleared?
      break;
    }
  }
}


/**********************************************************************//**
 * Helper function to program the XIP flash via the direct SPI access feature of the XIP module.
 *
 * @warning This function can only be used BEFORE the XIP-mode is activated!
 * @note This function is blocking and performs individual writes for each byte (little-endian byte order!).
 *
 * @param[in] src Pointer to data that will be copied to flash (32-bit).
 * @param[in] base_addr Image base address (in flash).
 * @param[in] size Image size in bytes.
 * @return Returns 0 if write was successful.
 **************************************************************************/
void xip_flash_program(uint32_t *src, uint32_t base_addr, uint32_t size) {

  uint32_t data_byte = 0;
  uint32_t cnt = 0;
  uint32_t flash_addr = base_addr;
  uint32_t tmp = 0;

  union {
    uint64_t uint64;
    uint32_t uint32[sizeof(uint64_t)/sizeof(uint32_t)];
  } data;

  while (1) {

    // get data byte
    data_byte = src[cnt/4];
    data_byte >>= (cnt & 3) * 8; // little-endian byte order!
    data_byte &= 0x000000FF;

    // set write-enable latch
    // 1 byte command
    data.uint32[0] = 0;
    data.uint32[1] = SPI_FLASH_CMD_WRITE_ENABLE << 24; // command: set write-enable latch
    neorv32_xip_spi_trans(1, &data.uint64);

    // write byte
    // 1 byte command, FLASH_ABYTES bytes address, 1 byte data
    data.uint32[1] = SPI_FLASH_CMD_WRITE << 24; // command: byte write
    data.uint32[0] = 0;
    if (FLASH_ABYTES == 1) { data.uint32[1] |= (flash_addr & 0x000000FF) << 16; } // address
    if (FLASH_ABYTES == 2) { data.uint32[1] |= (flash_addr & 0x0000FFFF) <<  8; } // address
    if (FLASH_ABYTES == 3) { data.uint32[1] |= (flash_addr & 0x00FFFFFF) <<  0; } // address

    if (FLASH_ABYTES == 1) { data.uint32[1] |= data_byte <<  8; } // data byte
    if (FLASH_ABYTES == 2) { data.uint32[1] |= data_byte <<  0; } // data byte
    if (FLASH_ABYTES == 3) { data.uint32[0] = data_byte << 24; } // data byte

    neorv32_xip_spi_trans(2 + FLASH_ABYTES, &data.uint64);
    flash_addr++;

    // check status register: WIP bit has to clear
    while(1) {
      tmp = SPI_FLASH_CMD_READ_STATUS << 24; // read status register command
      data.uint32[0] = 0;
      data.uint32[1] = tmp;
      neorv32_xip_spi_trans(2, &data.uint64);
      if ((data.uint32[0] & 0x01) == 0) { // WIP bit cleared?
        break;
      }
    }

    // done?
    cnt++;
    if (cnt == size) {
      break;
    }
  }
}


/**********************************************************************//**
 * Get NEORV32 executable via UART.
 *
 * @param[in] dst Pointer to uin32_t data array where the executable will be stored.
 * @param[out] length Pointer to a uin32_t to store the executable size in bytes.
 * @return Returns 0 on success.
 **************************************************************************/
int uart_get_executable(uint32_t *dst, uint32_t *length) {

  // check if valid image
  uint32_t signature = uart_get_word();
  if (signature != EXE_SIGNATURE) {
    return -1;
  }

  // image size and checksum
  uint32_t size  = uart_get_word(); // size in bytes
  uint32_t check = uart_get_word(); // complement sum checksum

  *length = size;

  // transfer program data
  uint32_t checksum = 0;
  uint32_t d = 0, i = 0;
  while (i < (size/4)) { // in words
    d = uart_get_word();
    checksum += d;
    dst[i++] = d;
  }

  // error during transfer?
  if ((checksum + check) != 0) {
    return -2;
  }

  return 0;
}


/**********************************************************************//**
 * Get 32-bit word from UART.
 *
 * @return 32-bit data word.
 **************************************************************************/
uint32_t uart_get_word(void) {

  union {
    uint32_t uint32;
    uint8_t  uint8[sizeof(uint32_t)];
  } data;

  uint32_t i;
  for (i=0; i<4; i++) {
    data.uint8[i] = (uint8_t)neorv32_uart0_getc();
  }

  return data.uint32;
}