naspi_slave: SPI Slave Driver API Example Application
13 March 2005


Overview
--------
This application shows how to use the simple SPI Master and Slave Driver
API.


Supported Platforms and Processors
----------------------------------
This application is uses the SPI Slave API, thus requires the SPI Slave 
hardware available on the 9750 and 9360 chips.  This application runs on
the 9750 Development board.  With modification, this application can be
ported to the 9360 Development board.


Features and APIs being demonstrated
------------------------------------
    SPI Master
    - NASpiRegisterDevice()
    - NASpiReadWrite()
    - NASpiDeregisterDevice()
    SPI Slave
    - NASpiSlaveInitialize()
    - NASpiSlaveEnqueueBuffer()
    Signal Muliplexing and GPIO
    - NAsetGPIOpin()
    - NAconfigureGPIOpin()


Required external equipment and setup
-------------------------------------
NS9750 Development Board Setup

    1. Populate RN39(0 ohms) on Port D and populate RN40(0 ohms) on Port C.
    2. Short Port C's enable pin with Port D's enable pin.
       Short Port C's clk pin with Port D's clk pin.
       Connect Port C's dout pin with Port D's din pin.
       Connect Port D's dout pin with Port C's din pin.

Refer to the NS9750 hardware manual for more information about GPIO 
ports and SPI module for details.



BSP Requirements
----------------
The following BSP requirements are necessary to run the application.
    
    In bsp_serial.h:
        1. Set BSP_SERIAL_PORT_3 to BSP_SERIAL_SPI_SLAVE_DRIVER.
        2. Set BSP_SERIAL_PORT_4 to BSP_SERIAL_SPI_DRIVER.

    In bsp_drivers.h:
        1. Set BSP_INCLUDE_LCD_DRIVER to FALSE.

    For gpio.h
        1. Set BSP_GPIO_MUX_SERIAL_C to BSP_GPIO_MUX_SERIAL_SPI_APP.
        2. Set BSP_GPIO_MUX_SERIAL_D to BSP_GPIO_MUX_SERIAL_SPI_APP.
        3. Set BSP_GPIO_MUX_LCD to BSP_GPIO_MUX_INTERNAL_USE_ONLY.

    Note you must first compile the BSP listed from the supported platforms
    before you can successfully compile, link and execute this sample
    application.


Customizeable Application Parameters
------------------------------------
The application has the following hooks that allow easy modification of
it's current configuration.

    SPI_SLAVE_PORT
    The application Slave port (default is PORTC).  This can be modified to 
    any other port, but requires analogous BSP and hardware support.

    SPI_MASTER_PORT
    The application Master port (default is PORTD).  This can be modified to 
    any other port, but requires analogous BSP and hardware support.

    APP_DATA_SIZE
    Buffer size for SPI bursts.  Current value is 16384 (0x4000).

    MAX_TEST_DATA
    The total data transfered by the application.  For extended overnight 
    testing, or extended stress testing, the value can be raised to 
    (0xffffffff - APP_DATA_SIZE).

    "masterDevice2"
    "masterDevice"
    To change any of the tranmission parameters, like clock rate, either 
    of these records can be modified.


Running the Application
-----------------------
The file appconf.h contains the customizable application parameters necessary
for running the application.

The application needs to know if the parameters are to be stored in NVRAM.
The APP_USE_NVRAM parameter defines this behavior.  If it is defined as 0, all
parameters set in this file will be used but will not be written to NVRAM.  If
it is defined as 1, the values in this file will be used as defaults and will
be written to NVRAM.  

The following parameters define the serial port settings for the debug port.  

    APP_BSP_BAUD_RATE           9600
    APP_DIALOG_PORT             "/com/0"

In this example the first com port is set to 9600, no parity, 8 data bits and
1 stop bit.  Once the application starts, a dialog will be sent to the
serial port which will allow the parameters to be changed if APP_USE_NVRAM
is defined as 1.  The dialog will remain the number of seconds defined in the
APP_BSP_DELAY parameter.  If a key is entered within this time, the settings
can be changed.  The password for changing these settings is defined by the
APP_ROOT_PASSWORD parameter.

The following parameters define the IP acquisition mode and IP address
settings. The APP_IP_ADDRESS, APP_IP_SUBNET_MASK and APP_IP_GATEWAY are only
needed if APP_USE_STATIC_IP is defined as TRUE.

    APP_IP_ADDRESS
    APP_IP_SUBNET_MASK
    APP_IP_GATEWAY
    APP_USE_STATIC_IP
    APP_ENABLE_AUTO_IP

The application starts in the function applicationStart() in the file root.c.
This function displays:

    Test begin...

Successful test completion will display:

    SPI master/slave test finished

Prior to this message, two other messages could be displayed indicating the
level of bit errors.

    Slave recv bit error rate is 1/1000000000
    Master recv bit error rate is 1/1000000000

Due to the nature of transmission lines, data corruption can occur.  This 
error rate depends on many variables, including the quality of the 
interconnections, quality of the power supply, and level of nearby EMI.

Note the minimum bit error rate, ever recorded at Digi International was:

    13 bit errors in (1954912784*8) bits at a rate of 8.4exp-8%


Detailed Application Description
--------------------------------
The "naspi_slave" application is a single thread application that tests 
spi master and slave write/read reliability.  The test performs 
the following:

    1) Puts the SPI master's enable and clk line into idle state.
    2) Registers the SPI device on the SPI Master port using the API 
       function NASpiRegisterDevice().
    3) Initializes the SPI Slave port using the API function 
       NASpiSlaveInitialize().
    4) Enqueues buffers for the slave using the API function 
       NASpiSlaveEnqueueBuffer().  These buffers are used by the slave
       to receive data.
    5) Initiates data SPI transfers, using the API function 
       NASpiReadWrite() on the SPI master port.  When complete, 
       compares the received data to the data sent.
    6) Using the callback function appCallbackFn(), the SPI slave 
       process the received data, and then compares the received data 
       to the data sent.
    7) Repeats steps 4 through 6, until MAX_TEST_DATA bytes of data
       have been transferred.
    8) Deregisters the SPI device on master port using the API function 
       NASpiDeregisterDevice().
    9) Prints out errors and mismatches, if any.



Tree Strucuture
---------------
    +naspi_slave
    |   appconf.h             [sets application configuration settings]
    |   readme                [This readme file]
    |   root.c                [Application source file: contains 
    |
    +---+32b
    |       Makefile           [Make file for the GNU toolset]


The application uses the following files located in the
netos\src\linkerScripts directory.  These files are generated
when the BSP is built.

bootldr.dat     bootloader configuration file used to generate the
                file image.bin.  It controls the information placed
                in the bootloader header of the image.

image.ldr       GNU linker script used to build an image that can
                be debugged and used with the bootloader.
                
customize.ldr   Customizable GNU linker script
