HM2_SPIX(9)

📦
version 2.9.4 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 HM2_SPIX 💖

okay bestie, buckle up — this is hm2_spix(9) from the LinuxCNC Documentation, and it's the HAL driver for Mesa Electronics Anything I/O boards that have SPI-enabled HostMot2 firmware. it's a long one, so this is part one. let's go 💅

✨ NAME ✨

hm2_spix — the LinuxCNC HAL driver for Mesa Electronics Anything I/O boards rockin' SPI-enabled HostMot2 firmware. no cap, that's literally what it is. 🦋

✨ SYNOPSIS ✨

loadrt hm2_spix

and then you sprinkle parameters on top, like seasoning. here's the whole menu:

  • config — [default: ""] — the HostMot2 config strings. they're described in the hostmot2(9) manpage, so go peek there if you need the tea.
  • spiclk_rate — [default: 25000] — sets the SPI clock rate in kHz for each probed board. see SPI CLOCK RATES below 🌈. every entry follows the spi_probe setting, so each probe grabs the next value off the spi_rate list. a spi_rate of 0 (zero) or less auto-selects the first rate in the list. and you can totally truncate the list down to however many boards you actually use.
  • spiclk_rate_rd — [default: same as spiclk_rate] — sets the SPI read clock rate in kHz. usually you read and write at the same speed, but if the round-trip is too long you may wanna slow the read down (again, see SPI CLOCK RATES below 🌸). truncate the list to the number of boards you use, same energy as above.
  • spi_probe — [default: 1] — probes SPI port and CE lines for a card. it's a bit-field telling the driver which SPI + CE combos to go hunting for:
    • 1 = SPI0/CE0
    • 2 = SPI0/CE1
    • 4 = SPI1/CE0
    • 8 = SPI1/CE1
    • 16 = SPI1/CE2

the probe happens exactly in that order, bestie. any boards it finds get numbered 0...4 in the order found. if a probe fails, that's an error and the driver will abort 😭. see also INTERFACE CONFIGURATION below.

  • force_driver — [default: <auto probe>] — forces a specific hardware driver to be selected. usually you do not need this; hm2_spix will normally pick the right hardware driver on its own, main character energy. see also HARDWARE DRIVERS below.
  • spidev_path — [default: <empty>] — overrides the device node path to the spidev device. the default is /dev/spidevX.Y, where X.Y is {0.0, 0.1, 1.0, 1.1, 1.2} in that order. heads up: this option only does anything if the spix_spidev hardware driver is selected or forced to be used 💀.
  • spi_noqueue — [default: 0 (off)] — force-disables queued command processing. normally all requests get queued if upstream asked for it, then sent in one bulk transfer, which cuts overhead significantly — by up to 35%. disabling the queue makes every transfer visible and way easier to debug. set it to any non-zero value to turn the queue off 🔥.
  • spi_debug — [default: -1] — sets the message level of the running process. it's set when spi_debug is a positive value between 0 and 5, where 0 means no messages at all and 5 means everything. a value of -1 leaves the current message level alone.
⚠️ Caveat Emptor, bestie: changing the message level is process-wide, and all modules within the process will start spitting out messages at whatever level you asked for. your terminal is gonna get so cluttered. 🙈

✨ DESCRIPTION ✨

hm2_spix is a device driver for all computer boards that have an available SPI port — yes, including Raspberry Pi 3, 4 and 5 🍓. it wires the SPI port up to Mesa's SPI-based Anything I/O boards running SPI-enabled HostMot2 firmware, and hands the whole thing to the LinuxCNC HAL. it's giving bridge energy, honestly.

this driver unifies all the previous hostmot2 SPI HAL drivers into one, with dedicated hardware drivers for Raspberry Pi models 3, 4 and 5, plus a fall-back to spidev for unknown boards ✨. further hardware drivers can be created and integrated whenever people ask for them.

the supported Mesa boards are: 7I90HD, 7I43, 7C80 and 7C81 👑

the board has to have compatible firmware loaded on it — stuff like 7i90_spi_*-bit, 7c80_*.bit and 7c81_*.bit — and you load that with the mesaflash(1) program. no firmware, no vibes.

oh and important: hm2_spix is only available when LinuxCNC is configured with "uspace" realtime. it works with Raspian and the PREEMPT_RT kernel. 💜

see also NOTES below.

✨ HARDWARE DRIVERS ✨

here's the lineup, and they get probed in this exact order:

  • spix_rpi3 — RPi3B, RPi3A+, RPi3B+, RPi4B, RPi4CM
  • spix_rpi5 — RPi5B, RPi5CM
  • spix_spidev — any board not recognised

probing the hardware works by matching known computer boards against the device-tree compatible string-list from /proc/device-tree/compatible. normally the first hardware driver that gives a match gets selected 🌸. but if you want to be extra, you can force a specific driver with the force_driver option, passing the name of the driver you want to use.

✨ INTERFACE CONFIGURATION ✨

up to five device boards are supported: two on SPI0 and three on SPI1 🎀. the recommendation is that you use at most two devices, and that each device gets its own separate SPI port. you pick whichever CE lines suit your design and setup, no judgement. then use the spi_probe parameter to tell the driver where to go looking for the board(s).

for the Mesa 7C80 and 7C81 you'll always want to configure SPI0/CE0. those boards have a matching 40-pin header for the computer board, iykyk.

the SPI ports live on the 40-pin header for those computer boards that have a compatible header. just so you know: the GPIO numbers are only guaranteed to be valid for Raspberry Pi boards.

Port SPI0:

  • MOSI — GPIO 10 — 40-pin 19
  • MISO — GPIO 9 — 40-pin 21
  • SCLK — GPIO 11 — 40-pin 23
  • CE0 — GPIO 8 — 40-pin 24 — /dev/spidev0.0
  • CE1 — GPIO 7 — 40-pin 26 — /dev/spidev0.1

Port SPI1:

  • MOSI — GPIO 20 — 40-pin 38
  • MISO — GPIO 19 — 40-pin 35
  • SCLK — GPIO 21 — 40-pin 40
  • CE0 — GPIO 18 — 40-pin 12 — /dev/spidev1.0
  • CE1 — GPIO 17 — 40-pin 11 — /dev/spidev1.1
  • CE2 — GPIO 16 — 40-pin 36 — /dev/spidev1.2

✨ REALTIME PERFORMANCE OF THE HM2_SPIX DRIVER ✨

using an RPi3 will work, but ngl it's 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 any problems 🔥.

all other computer boards and LinuxCNC configurations need to be tested thoroughly. like, actually thoroughly. don't skip this.

all other parameters: TBD.

🌈 SPI CLOCK RATES 💅

okay bestie so here's the tea on clock speeds: the SPI driver can absolutely hand you frequencies that no board on this earth can handle. a safe starting point? 12.5 MHz (spiclk_rate=12500). then work your way up from there like you're leveling up in a game. slay responsibly. 🎀

the SPI driver spits out (very) discrete clock frequencies — especially up in the high MHz range — because the divider structure is simple like that. the base frequency is different between boards, and the divider for SPI0/SPI1 scales using discrete factors with formula f=trunc(base/(2*divider)).

so here's the whole menu of the highest possible spiclk_rate and spiclk_rate_rd frequencies (in kHz) for discrete divider settings. RPi3 / RPi4 / RPi5 columns, k? 🦋

  • Base — RPi3: 400 MHz, RPi4: 500 MHz, RPi5: 200 MHz
  • Fastest — RPi3: 50000, RPi4: 50000, RPi5: 50000
  • RPi3: 40000, RPi4: 41666, RPi5: 33333
  • RPi3: 33333, RPi4: 35714, RPi5: 25000
  • RPi3: 28571, RPi4: 31250, RPi5: 20000
  • RPi3: 25000, RPi4: 27777, RPi5: 16666
  • RPi3: 22222, RPi4: 25000, RPi5: 14285
  • RPi3: 20000, RPi4: 22727, RPi5: 12500
  • RPi3: 18181, RPi4: 20833, RPi5: 11111
  • RPi3: 16666, RPi4: 19230, RPi5: 10000
  • RPi3: 15384, RPi4: 17857, RPi5: 9090
  • RPi3: ..., RPi4: ..., RPi5: ...
  • Slowest SPI0 — RPi3: 4, RPi4: 4, RPi5: 4
  • Slowest SPI1 — RPi3: 49, RPi4: 62, RPi5: 4
heads up bestie: the clock rate setting is heavily influenced by rounding and may end up higher than you 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 exist so you can select them for testing purposes. do not expect any real-time performance with such a slow setting, fr fr. 💀

the highest theoretically possible SPI clock frequency is higher than what that table says. but — and this is the part nobody wants to hear — 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. iconic behavior honestly. ✨

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. 🫶

📝 NOTES

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 — and say it with me — 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. like, actual chaos energy.

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. 🔥🔥

👀 SEE ALSO

⚖️ LICENSE

GPL

and that's the whole page bestie, you ate it 💅 this lore dropped from LinuxCNC, dated 03/17/2026, and the page it lives on is HM2_SPIX(9) — go forth and clock responsibly 🌸✨

📦 where this page comes from