Ubuntu Manpage: hm2_rpspi - LinuxCNC HAL driver for the Mesa Electronics SPI Anything IO boards, with HostMot2 firmware.

Provided by: linuxcnc-uspace_2.9.4-2ubuntu1_amd64

NAME

       hm2_rpspi - LinuxCNC HAL driver for the Mesa Electronics SPI Anything IO boards, with HostMot2 firmware.

SYNOPSIS


       loadrt hm2_rpspi

           config [default: ""]
                  HostMot2 config strings, described in the hostmot2(9) manpage.

           spiclk_rate [default: 31250]
                  Specify the SPI clock rate in kHz. See SPI CLOCK RATES below.

           spiclk_rate_rd [default: -1 (same as spiclk_rate)]
                  Specify the SPI read clock rate in kHz. Usually you read and write at the same speed. However,
                  you  may  want  to reduce the reading speed if the round-trip is too long (see SPI CLOCK RATES
                  below).

           spiclk_base [default: 400000000]
                  This is the SPI clock divider calculation fallback value. Usually, the base rate is read  from
                  /sys/kernel/debug/clk/vpu/clk_rate and used in the divider calculation (for the Rpi3 it should
                  be  250 MHz). The spiclk_base is only used as a fallback if the system's cannot be read. It is
                  normally safe (and recommended) that you leave this parameter as is.
                  You should set this manually to 250000000 if your system does not provide access to the kernel
                  clock settings. Otherwise, your SPI clock frequency will be only 62.5% of the requested value.

           spi_pull_miso [default: 1 (pull-down)]

           spi_pull_mosi [default: 1 (pull-down)]

           spi_pull_sclk [default: 1 (pull-down)]
                  Enable or disable pull-up/pull-down on the SPI lines. A value of 0 disables  any  pull-up/down
                  on  the  pin.  A  value  of 1 means pull-down and 2 means pull-up. The chip enable line(s) are
                  always pull-up enabled.

           spi_probe [default: 1]
                  Probe SPI port and CE lines for a card. This is a bit-field indicating which  combinations  of
                  SPI and CE should be probed:
                   -  1 = SPI0/CE0,
                   -  2 = SPI0/CE1,
                   -  4 = SPI1/CE0,
                   -  8 = SPI1/CE1,
                   - 16 = SPI1/CE2.

                  The  probe is performed exactly in above order. Any boards found will be numbered 0...4 in the
                  order found. See also INTERFACE CONFIGURATION below.

                  It is an error if a probe fails and the driver will  abort.   The  SPI0/SPI1  peripherals  are
                  located at GPIO pins (with 40-pin I/O header pin-number in parentheses):
                   - SPI0: MOSI=10(19), MISO=9(21), SCLK=11(23), CE0=8(24), CE1=7(26)
                   - SPI1: MOSI=20(38), MISO=19(35), SCLK=21(40), CE0=18(12), CE1=17(11), CE2=16(36)

           spi_debug [default: -1]
                  Set  the message level of the running process. The message level is set if spi_debug is set to
                  a positive value between 0 and 5, where 0 means no messages at all and 5 means  everything.  A
                  value of -1 does not touch the current message level.

                  Caveat  Emptor:  changing the message level is process-wide and all modules within the process
                  will spit out messages at the requested level. This may  cause  quite  some  clutter  in  your
                  terminal.

DESCRIPTION

       hm2_rpspi  is  a  device  driver  for  the Raspberry Pi 2/3 that interfaces Mesa's SPI based Anything I/O
       boards (with the HostMot2 firmware) to the LinuxCNC HAL.  This driver is not based on  the  linux  spidev
       driver, but on a dedicated BCM2835-SPI driver.

       It  is  strongly  recommended  that  you  unload/disable the kernel's spidev driver by disabling it using
       raspi-config.  Please note that having both kernel and user-space SPI drivers  installed  can  result  in
       unexpected interactions and system instabilities.

       The supported boards are: 7I90HD.

       The  board  must  have  a  compatible  firmware  (ie.:  7i90_spi_svst4_8.bit)  loaded on the board by the
       mesaflash(1) program.

       hm2_rpspi is only available when LinuxCNC is configured with "uspace" realtime.  It  works  with  Raspian
       and PREEMPT_RT kernel.

INTERFACE CONFIGURATION

       Up  to  five  devices (7i90 boards) are supported. Two on SPI0 and three on SPI1.  It is recommended that
       you, at most, use two devices and each device connected to a separate SPI port. You can choose  which  CE
       lines  you  prefer  or  fit  the design and setup the spi_probe parameter to instruct the driver where to
       search for the board(s).

REALTIME PERFORMANCE OF THE BCM2835-SPI DRIVER

       TBD.

SPI CLOCK RATES

The maximum SPI clock of the BCM2835-SPI driver and the 7i90 is documented over 32MHz. The SPI driver can
provide frequencies well beyond what is acceptable for the 7i90. A safe value to start with would be
12.5 MHz (spiclk_rate=12500) and then work your way up from there.

The SPI driver generates (very) discrete clock frequency values, especially in the MHz range because of a
simple clock divider structure. The base frequency is 250 MHz and the divider for SPI0/SPI1 scales using
discrete factors. The following list specifies the spiclk_rate setting and the discrete SPI clock
frequency (250 MHz / (2n) for n > 1):
- 62500 - 62.500 MHz,
- 41667 - 41.667 MHz,
- 31250 - 31.250 MHz,
- 25000 - 25.000 MHz,
- 20834 - 20.833 MHz,
- 17858 - 17.857 MHz,
- 15625 - 15.625 MHz,
- 13889 - 13.889 MHz,
- 12500 - 12.500 MHz,
- 11364 - 11.364 MHz,
- 10417 - 10.417 MHz,
- 9616 - 9.615 MHz,
- ....

The lowest selectable SPI clock frequency is 30 kHz (spiclk_rate=30) for SPI0 and SPI1. Theoretically,
the SPI0 port could go slower, but there is no point in doing so. You should not expect any real-time
performance with such slow setting, unless your machine is located next to a black hole.

The highest SPI clock frequency is, theoretically, 125 MHz. However, you will not be able to build any
reliable hardware interface at that frequency. The driver limits the clock to 62.5 MHz
(cpiclk_rate=62500). The chances are rather slim that you get the interface to work reliably at this
frequency. The 7i90 interface only supports frequencies up to 50 MHz and that is with perfect cabling and
impedance matching (in write direction only).

Writing to the 7i90 may be done faster than reading. This is especially important if you have "long"
wires or any buffers on the SPI-bus path. You can set the read clock frequency to a lower value (using
spiclk_rate_rd) to counter the effects of the SPI-bus round-trip needed for read actions. For example,
you can write at 41.67 MHz and read at 25.00 MHz.

It should be noted that the Rpi3 must have an adequate 5V power supply and the power should be properly
decoupled right on the 40-pin I/O header. At high speeds and noise on the supply, there is the
possibility of noise throwing off the SoC's PLL(s), resulting in strange behaviour.

For optimal performance on the Rpi3, you must disable the "ondemand" CPU frequency governor. You may add
the following to your /etc/rc.local file:
echo -n 1200000 > /sys/devices/system/cpu/cpufreq/policy0/scaling_min_freq
echo -n performance > /sys/devices/system/cpu/cpufreq/policy0/scaling_governor

Be sure to have a proper heatsink mounted on the SoC or it will get too warm and crash.

LICENSE

       GPL

LinuxCNC Documentation                             2017-06-05                                       HM2_RPSPI(9)