SPI Slave To Avalon Master Bridge Design Example v2.0 readme.txt ================================================================= Overview ========= This design example demonstrates how to use the SPI Slave to Avalon Master Bridge, which provides a connection between host system and remote system for SPI transactions. Tool Requirements ================= The examples in this archive require the following software tools: - Quartus II software version 9.1 SP1 or later - Nios II Embedded Design Suite (EDS) version 9.1 SP1 or later This design also requires the following development board: - Embedded Systems Development Kit , Cyclone III Edition Hardware Design Specifications ============================== Host system : -------------- - Nios II/f - Onchip memory : 156K - System timer - System ID - JTAG UART - SPI Core Remote System ------------- - SPI Slave to Avalon Master Bridge - Onchip memory : 4K Usage Instructions for running the software ============================================ 1. Open the Nios II 9.1SP1 Command Shell. 2. Change directory to the project directory. 3. Program the configuration file (sof) to the board by typing nios2-configure-sof spi_bridge.sof 4. Change directory to /software_examples/app/spi_bridge_test 5. Run the create-this-app script by typing ./create-this-app 6. Download the elf file by typing nios2-download -g spi_bridge_test.elf && nios2-terminal 7. Alternately, you can import the software projects (after Step 5) into Nios II Software Build Tools for Eclipse to run/debug the software. The software will write and read back a block of data to the on-chip memory via the SPI Slave to Avalon Master Bridge. You will see the following messages on the nios2-terminal for successful execution. -------------------------------------------------------------------------------- Creating random test data ... Writing data to onchip memory ... Write transaction unsuccessful Reading data from onchip memory ... Comparing data ... Compare data completes error free -------------------------------------------------------------------------------- Note ===== 1. If you wish to recompile the hardware design in Quartus II you will need to regenerate the system in SOPC Builder. Take note that you will need to regenerate two SOPC systems, cpu_spi_core and spi_bridge_system. 2. By default, only one system.h file is created even if two SOPC systems exist in your project. To create two system.h files for two SOPC systems, you will need to manually create the second system.h file. In this example, spi_bridge_system.h is created for spi_bridge_system via the sopc-create-header-files command in the create-this-bsp script. This command will need an input parameter, which is the second SOPC system's .sopcinfo file and output paramter, xxx_system.h. For details, type sopc-create-header-files --help in the Nios II Command Shell. 3. To port the software in the alt_spi_to_avalon_bridge to another CPU , you will need to replace the functions in the spi_command files with your own SPI master driver functions. Software API ============ This section discusses the software API for the SPI Slave To Avalon Master Bridge. When an external processor is used to send or receive SPI data to a SPI Slave to Avalon Master Bridge, the external processor can use the Altera-supplied software API to convert the SPI transactions to the protocols used by the bridge. The source code is located in the alt_spi_to_avalon_bridge folder. The files included are: - transaction_to_packet.c - transaction_to_packet.h - packet_to_byte.c - packet_to_byte.h - byte_to_core.c - byte_to_core.h - spi_command.c - spi_command.h Define DYNAMIC_MEMORY_ALLOC for each file if you are going to use the heap memory or STATIC_MEMORY_ALLOC for static memory. Memory will be allocated for send data as well as the expected response data. If you use STATIC_MEMORY_ALLOC, take note that the static memory allocated is sufficient for up to 1KB of transaction only. Change the buffer size defines (TRANSACTION_BUFFER_LENGTH, PACKET_BUFFER_LENGTH, BYTE_BUFFER_LENGTH) if you wish to change the static memory size. --------------------------------------------------------------------------------------------- unsigned char transaction_channel_write(unsigned int address, unsigned int burst_length, unsigned char* data_buffer, unsigned char sequential) --------------------------------------------------------------------------------------------- This function will write a block of data to an address according to the following parameters: - address : 32-bit address of a slave component connected to the bridge - burst_length : length of data in bytes - data_buffer : pointer the the data to be written for the write transactions - sequential : flag to increment[1]/non-increment address[0] If sequential is set to 1, 4 bytes of data will be written to the given address and the address will be incremented for the next 4 bytes of address. If sequential is set to 0, 4 bytes of data will be written to the given address and the address will not be incremented for the next 4 bytes. This means that the next 4 bytes will still be written to the same given address, replacing the first 4 bytes. This function will append a transaction header to the block of data. If the return number of bytes is correct, this function returns TRUE. --------------------------------------------------------------------------------------------- unsigned char transaction_channel_read(unsigned int address, unsigned int burst_length, unsigned char* data_buffer, unsigned char sequential) --------------------------------------------------------------------------------------------- The algorithm of transaction_channel_read() is similar to transaction_channel_write() except that it performs read operation and this function always return TRUE. --------------------------------------------------------------------------------------------------- unsigned char packet_to_byte_convert (unsigned int send_length, unsigned char* send_data, unsigned int response_length, unsigned char* response_data) --------------------------------------------------------------------------------------------------- This function includes the following parameters: - send length : size of send data - send data : pointer to the send data - response_length : size of response data - response_data : pointer to the response data This function will insert these special characters into send data, SOP(0x7a), EOP (0x7b), CHANNEL (0x7c) and CHANNEL ID (0x00). The special characters will be inserted with the following sequence : SOP | CHANNEL | CH ID | .... Data ....... | EOP | Last byte of data | If any byte of send data is a special character, this function will insert an ESC (0x7d), followed by the data XORed with 0x20. Similarly, when this function finds any special characters in the response data, it will drop the special characters from the response data. --------------------------------------------------------------------------------------------------- unsigned char byte_to_core_convert (unsigned int send_length, unsigned char* send_data, unsigned int response_length, unsigned char* response_data) --------------------------------------------------------------------------------------------------- This function includes the following parameters: - send length : size of send data - send data : pointer to the send data - response_length : size of response data - response_data : pointer to the response data This function will check for special characters, IDLE(0x4a) and ESC(0x4d).If a data byte is a special character, this function will insert an ESC (Escape) followed by the data XORed with 0x20. Similarly, when this function finds any special characters in the response data, it will drop the special characters from the response data. -------------------------------------------------------------------------------------------------------- int spi_command(unsigned int base, unsigned int slave, unsigned int write_length, const unsigned char * write_data, unsigned int read_length, unsigned char * read_data, unsigned int flags) -------------------------------------------------------------------------------------------------------- This function is a mirror of the alt_avalon_spi_command(), which is the SPI driver of the SPI core. If you are using a different SPI driver, do replace this function with your own SPI driver function. For more info on alt_avalon_spi_command(), refer to http://www.altera.com/literature/hb/nios2/n2cpu_nii51011.pdf Release History =============== Version 1.0 ------------- Initial release Version 2.0 ------------- Add software API explaination Contacting Altera ================= Although we have made every effort to ensure that this version of example designs work correctly, there may be problems that we have not encountered. If you have a question or problem that is not answered by the information provided in this readme file, please contact your Altera Field Applications Engineer. If you have additional questions that are not answered in the documentation provided with this design, contact Altera Applications using one of the following methods: Technical Support Hotline: (800) 800-EPLD (U.S.) (408) 544-7000 (Internationally) World wide web: http://www.altera.com/support Last updated January, 2010 Copyright © 2010 Altera Corporation. All rights reserved.