hm2_spix - LinuxCNC HAL driver for the Mesa Electronics Anything IO boards with SPI enabled HostMot2 firmware.
loadrt hm2_spix
config [default: ""]
HostMot2 config strings, described in the hostmot2(9) manpage.
spiclk_rate [default: 25000]
Specify the SPI clock rate in kHz for each probed board. See SPI CLOCK RATES below. Each entry follows the spi_probe setting, where each probe takes the next value of the spi_rate list. A spi_rate of 0 (zero) or less automatically selects the first rate in the list. You may truncate the list to the number of boards you use.
spiclk_rate_rd [default: 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). You may truncate the list to the number of boards you use.
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. It is an error if a probe fails and the driver will abort. See also INTERFACE CONFIGURATION below.
force_driver [default: <auto probe>]
Force a specific hardware driver to be selected. This is usually not necessary and the hm2_spix driver will normally select the appropriate hardware driver automatically. See also HARDWARE DRIVERS below.
spidev_path [default: <empty>]
Override the device node path to the spidev device. Default is /dev/spidevX.Y, where X.Y is {0.0, 0.1, 1.0, 1.1, 1.2} in that order. This option has only effect if the spix_spidev hardware driver is selected or forced to be used.
spi_noqueue [default: 0 (off)]
Force disable queued command processing. Normally, all requests are queued if requested by upstream and sent in one bulk transfer. This reduces overhead significantly by up to 35%. Disabling the queue makes each transfer visible and more easily debug-able. Set to any non-zero value to disable the queue.
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.
hm2_spix is a device driver for all computer boards with an available SPI port, including Raspberry Pi 3, 4 and 5. The SPI port interfaces with Mesa’s SPI based Anything I/O boards with SPI enabled HostMot2 firmware to the LinuxCNC HAL.
This driver unifies all previous hostmot2 SPI hal drivers in one with dedicated hardware drivers for Raspberry Pi models 3, 4 and 5 and has a fall-back to spidev for unknown boards. Further hardware drivers may be created and integrated when requested.
The supported Mesa boards are: 7I90HD, 7I43, 7C80 and 7C81.
The board must have a compatible firmware (like: 7i90_spi_*-bit, 7c80_*.bit and 7c81_*.bit) loaded on the board by the mesaflash(1) program.
hm2_spix is only available when LinuxCNC is configured with "uspace" realtime. It works with Raspian and PREEMPT_RT kernel.
See also NOTES below.
The following hardware drivers are implemented and probed in order:
Probing the hardware is implemented by matching known computer boards against the device-tree compatible string-list from /proc/device-tree/compatible. Normally, the first hardware driver giving a match will be selected. However, it is possible to force a specific driver to be used using the force_driver option with the name of the driver you want to use.
Up to five device 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 your design and setup. Use the spi_probe parameter to instruct the driver where to search for the board(s).
For the Mesa 7C80 and 7C81 you’ll always want to configure SPI0/CE0. These boards have a matching 40-pin header for the computer board.
The SPI ports are located on the 40-pin header for those computer boards with a compatible header. The GPIO numbers are only guaranteed to be valid for Raspberry Pi boards.
Port SPI0:
Port SPI1:
Using a RPi3 will work, but is not the best option. Currently, the RPi4 is known to work adequately. The newer RPi5 is a lot faster and will normally run a servo-thread at 1 kHz without problems.
All other computer boards and LinuxCNC configurations need to be tested thoroughly.
All other parameters: TBD.
The SPI driver can provide frequencies beyond what is acceptable for any board. 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 frequencies, especially in the high MHz range because of a simple clock divider structure. The base frequency is different between boards and the divider for SPI0/SPI1 scales using discrete factors with formula f=trunc(base/(2*divider)). The following list specifies the highest possible spiclk_rate and spiclk_rate_rd frequencies (in kHz) for discrete divider settings:
Note that the clock rate setting is heavily influenced by rounding and may be higher than expected if the divider rounds to the next lower value. You can check the actual clock rate by enabling informational messages (set spi_debug=3).
The slowest selectable SPI clock frequency for SPI0 and SPI1 are not for production systems. They can be selected for testing purposes. You should not expect any real-time performance with such slow setting.
The highest theoretically possible SPI clock frequency is higher than stated in the above table. However, you will not be able to build any reliable hardware interface at that frequency. The driver limits the clock to 50.0 MHz (cpiclk_rate=50000). The Mesa board interface supports frequencies up to 50 MHz and that is with good cabling in write direction only.
Writing to the Mesa board 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 33.33 MHz and read at 25.00 MHz.
The maximum SPI clock of the spix_rpi5 driver has been tested up to 50 MHz write speed and 33 MHz read speed on the 7C80 and 7C81. However, it is not recommended to run at the limit on production systems. A safe setting would be to set one step below the maximum speeds.
If you know your setup and do not require the spix_spidev driver, then it is strongly recommended that you unload/disable the kernel’s SPI drivers dw_spi and dw_spi_mmio for the RPi5 or spi_bmc2835 for the RPi3 and RPi4. The hm2_spix hardware drivers attempt to unload the kernel driver at startup if detected and restore it at exit if initially loaded. However, there are no guarantees about the effectiveness of the module unload/load actions.
Warning: having both kernel and user-space SPI drivers installed can result in unexpected interactions and system instabilities.
The Raspberry Pi must have an adequate power supply. At high speeds and noise on the supply, there is the possibility of strange behaviour if the noise gets out of hand.
The Mesa 7C80 provides enough local power to the host via the 40-pin interface header if your external power supply is adequate (on connector TB6). The Mesa 7C81 needs an adequate external 5V power supply (on connector TB1) and feeds it directly to the host interface header.
For the Raspberry Pi 4: Be sure to have a proper heat-sink mounted on the SoC or it will get too warm and may crash.
For the Raspberry Pi 5: Be sure to have a proper active heat-sink mounted on the SoC or it will get too warm and may crash.
hostmot2(9)
GPL