227 lines
7.4 KiB
Plaintext
227 lines
7.4 KiB
Plaintext
README File for the SPI Tool
|
|
============================
|
|
|
|
The I2C tool provides a way to debug SPI related problems. This README file
|
|
will provide usage information for the SPI tools.
|
|
|
|
CONTENTS
|
|
========
|
|
|
|
o System Requirements
|
|
- SPI Driver
|
|
- Configuration Options
|
|
o Help
|
|
o Common Line Form
|
|
o Common Command Options
|
|
- "Sticky" Options
|
|
- Environment variables
|
|
- Common Option Summary
|
|
o Command summary
|
|
- bus
|
|
- dev
|
|
- get
|
|
- set
|
|
- verf
|
|
o I2C Build Configuration
|
|
- NuttX Configuration Requirements
|
|
- I2C Tool Configuration Options
|
|
|
|
System Requirements
|
|
===================
|
|
|
|
The SPI tool is designed to be implemented as a NuttShell (NSH) add-on. Read
|
|
the apps/nshlib/README.txt file for information about add-ons.
|
|
|
|
Configuration Options
|
|
---------------------
|
|
CONFIG_NSH_BUILTIN_APPS - Build the tools as an NSH built-in command
|
|
CONFIG_SPITOOL_MINBUS - Smallest bus index supported by the hardware (default 0).
|
|
CONFIG_SPITOOL_MAXBUS - Largest bus index supported by the hardware (default 3)
|
|
CONFIG_SPITOOL_DEFFREQ - Default frequency (default: 40000000)
|
|
CONFIG_SPITOOL_DEFMODE - Default mode, where;
|
|
0 = CPOL=0, CHPHA=0
|
|
1 = CPOL=0, CHPHA=1
|
|
2 = CPOL=1, CHPHA=0
|
|
3 = CPOL=1, CHPHA=1
|
|
CONFIG_SPITOOL_DEFWIDTH - Default bit width (default 8)
|
|
CONFIG_SPITOOL_DEFWORDS - Default number of words to exchange (default 1)
|
|
|
|
HELP
|
|
====
|
|
|
|
he SPI tools supports some help output. That help output can be view
|
|
by entering either:
|
|
|
|
nsh> spi help
|
|
|
|
or
|
|
|
|
nsh> spi ?
|
|
|
|
Here is an example of the help output. I shows the general form of the
|
|
command line, the various SPI commands supported with their unique command
|
|
line options, and a more detailed summary of the command SPI command
|
|
options.
|
|
|
|
nsh> Usage: spi <cmd> [arguments]
|
|
Where <cmd> is one of:
|
|
|
|
Show help : ?
|
|
List buses : bus
|
|
SPI Exchange : exch [OPTIONS] [<hex senddata>]
|
|
Show help : help
|
|
|
|
Where common "sticky" OPTIONS include:
|
|
[-b bus] is the SPI bus number (decimal). Default: 0 Current: 2
|
|
[-f freq] SPI frequency. Default: 4000000 Current: 4000000
|
|
[-m mode] Mode for transfer. Default: 0 Current: 0
|
|
[-u udelay] Delay after transfer in uS. Default: 0 Current: 0
|
|
[-w width] Width of bus. Default: 8 Current: 8
|
|
[-x count] Words to exchange Default: 1 Current: 4
|
|
|
|
NOTES:
|
|
o An environment variable like $PATH may be used for any argument.
|
|
o Arguments are "sticky". For example, once the SPI address is
|
|
specified, that address will be re-used until it is changed.
|
|
|
|
WARNING:
|
|
o The SPI commands may have bad side effects on your SPI devices.
|
|
Use only at your own risk.
|
|
|
|
COMMAND LINE FORM
|
|
=================
|
|
|
|
The SPI is started from NSH by invoking the 'spi' command from the NSH
|
|
command line. The general form of the 'spi' command is:
|
|
|
|
spi <cmd> [arguments]
|
|
|
|
Where <cmd> is a "sub-command" and identifies one SPI operation supported
|
|
by the tool. [arguments] represents the list of arguments needed to perform
|
|
the SPI operation. Those arguments vary from command to command as
|
|
described below. However, there is also a core set of common OPTIONS
|
|
supported by all commands. So perhaps a better representation of the
|
|
general SPI command would be:
|
|
|
|
i2c <cmd> [OPTIONS] [arguments]
|
|
|
|
Where [OPTIONS] represents the common options and and arguments represent
|
|
the operation-specific arguments.
|
|
|
|
COMMON COMMAND OPTIONS
|
|
======================
|
|
|
|
"Sticky" Options
|
|
----------------
|
|
In order to interact with SPI devices, there are a number of SPI parameters
|
|
that must be set correctly. One way to do this would be to provide to set
|
|
the value of each separate command for each SPI parameter. The SPI tool
|
|
takes a different approach, instead: The SPI configuration can be specified
|
|
as a (potentially long) sequence of command line arguments.
|
|
|
|
These arguments, however, are "sticky." They are sticky in the sense that
|
|
once you set the SPI parameter, that value will remain until it is reset
|
|
with a new value (or until you reset the board).
|
|
|
|
Environment Variables
|
|
---------------------
|
|
NOTE also that if environment variables are not disabled (by
|
|
CONFIG_DISABLE_ENVIRON=y), then these options may also be environment
|
|
variables. Environment variables must be preceded with the special
|
|
character $. For example, PWD is the variable that holds the current
|
|
working directory and so $PWD could be used as a command line argument. The
|
|
use of environment variables on the I2C tools command is really only useful
|
|
if you wish to write NSH scripts to execute a longer, more complex series of
|
|
SPI commands.
|
|
|
|
Common Option Summary
|
|
---------------------
|
|
|
|
[-b bus] is the SPI bus number (decimal). Default: 0
|
|
Which SPI bus to commiuncate on. The bus must have been initialised
|
|
as a character device in the config in the form /dev/spiX (e.g. /dev/spi2).
|
|
|
|
The valid range of bus numbers is controlled by the configuration settings
|
|
CONFIG_SPITOOL_MINBUS and CONFIG_SPITOOL_MAXBUS.
|
|
|
|
The bus numbers are small, decimal numbers.
|
|
|
|
[-m mode] SPI Mode for transfer.
|
|
Which of the available SPI modes is to be used. Options are;
|
|
0 = CPOL=0, CHPHA=0
|
|
1 = CPOL=0, CHPHA=1
|
|
2 = CPOL=1, CHPHA=0
|
|
3 = CPOL=1, CHPHA=1
|
|
|
|
[-u udelay] Delay after transfer in uS. Default: 0
|
|
Any extra delay to be provided after the transfer. Not normally needed
|
|
from the command line.
|
|
|
|
[-x count] Words to exchange Default: 1
|
|
The number of words to be transited over the bus. For sanitys sake this is
|
|
limited to a relatively small number (40 by default). Any data on the
|
|
command line is sent first, padded by 0xFF's while any remaining data
|
|
are received.
|
|
|
|
[-w width] is the data width (varies according to target). Default: 8
|
|
|
|
Various SPI devices support different data widths. This option is untested.
|
|
|
|
[-f freq] I2C frequency. Default: 4000000 Current: 4000000
|
|
|
|
The [-f freq] sets the frequency of the SPI device. The default is very conservative.
|
|
|
|
COMMAND SUMMARY
|
|
===============
|
|
|
|
List buses: bus [OPTIONS]
|
|
--------------------------
|
|
|
|
This command will simply list all of the configured SPI buses and indicate
|
|
which are supported by the driver and which are not:
|
|
|
|
BUS EXISTS?
|
|
Bus 1: YES
|
|
Bus 2: NO
|
|
|
|
The valid range of bus numbers is controlled by the configuration settings
|
|
CONFIG_SPITOOL_MINBUS and CONFIG_SPITOOL_MAXBUS.
|
|
|
|
Exchange data: exch [OPTIONS] <Optional TX Data>
|
|
------------------------------------------------
|
|
|
|
This command triggers an SPI transfer, returning the data back from the far end.
|
|
As an example (with MOSI looped back to MISO);
|
|
|
|
nsh>spi exch -b 2 -x 4 aabbccdd
|
|
Received: AA BB CC DD
|
|
nsh>
|
|
|
|
Note that the TXData are always specified in hex, and are always two digits each,
|
|
case insensitive.
|
|
|
|
I2C BUILD CONFIGURATION
|
|
=======================
|
|
|
|
NuttX Configuration Requirements
|
|
--------------------------------
|
|
The SPI tools requires the following in your NuttX configuration:
|
|
|
|
1. Application configuration.
|
|
|
|
Using 'make menuconfig', select the SPI tool. The following
|
|
definition should appear in your .config file:
|
|
|
|
CONFIG_SYSTEM_SPI=y
|
|
|
|
2. Device-specific SPI driver support must be enabled:
|
|
|
|
CONFIG_SPI_DRIVER=y
|
|
|
|
The SPI tool will then use the SPI character driver to access the SPI
|
|
bus. These devices will reside at /dev/spiN where N is the I2C bus
|
|
number.
|
|
|
|
NOTE 1: The SPI driver ioctl interface is defined in
|
|
include/nuttx/spi/spi.h.
|