.\" Copyright (c) 2016 W. Martinjak
.\" Copyright (c) 2017 B. Stultiens
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
.\" USA.
.TH HM2_RPSPI "9" "2017-06-05" "LinuxCNC Documentation" "HAL Component"

.SH NAME

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

.HP
.B loadrt hm2_rpspi
.RS 4
.TP
\fBconfig\fR [default: ""]
HostMot2 config strings, described in the
.BR hostmot2 (9)
manpage.
.TP
\fBspiclk_rate\fR [default: 31250]
Specify the SPI clock rate in kHz. See
.BR SPI\ CLOCK\ RATES
below.
.TP
\fBspiclk_rate_rd\fR [default: -1 (same as \fBspiclk_rate\fR)]
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
.BR SPI\ CLOCK\ RATES
below).
.TP
\fBspiclk_base\fR [default: 400000000]
This is the SPI clock divider calculation fallback value. Usually, the base
rate is read from
.I /sys/kernel/debug/clk/vpu/clk_rate
and used in the divider calculation (for the Rpi3 it should be 250\ MHz). The
\fBspiclk_base\fR is \fIonly\fR used as a fallback if the system's cannot be
read. It is normally safe (and recommended) that you leave this parameter as
is.
.br
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.
.TP
\fBspi_pull_miso\fR [default: 1 (pull\-down)]
.TP
\fBspi_pull_mosi\fR [default: 1 (pull\-down)]
.TP
\fBspi_pull_sclk\fR [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.
.TP
\fBspi_probe\fR [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
.BR 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)

.TP
\fBspi_debug\fR [default: \-1]
Set the message level of the running process. The message level is set if
\fBspi_debug\fR 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.

.SH 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 \fBstrongly\fR recommended that you unload/disable the kernel's spidev
driver by disabling it using
.BR 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
.BR mesaflash (1)
program.

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

.SH 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 \fBspi_probe\fR parameter to instruct the driver where to
search for the board(s).

.SH REALTIME PERFORMANCE OF THE BCM2835-SPI DRIVER

TBD.
.\"As of kernel 3.8, most or all kernel SPI drivers do not achieve the high"
.\"realtime response rate required for a typical LinuxCNC configuration.  The"
.\"driver was tested with ..."

.SH 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 \fBspiclk_rate\fR 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 \fBspiclk_rate_rd\fR) 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 \fBmust\fR 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.

.SH SEE ALSO

.BR hostmot2 (9)

.SH LICENSE

GPL