nslink(8)

📦 version 7.34, in alpine 3.22, alpine 3.23, alpine 3.24

Ok so real talk, this page is nslink(8) from the Comtrol manual set, and it's literally the whole vibe guide to talking to DeviceMaster boxes over the network like they're normal serial ports. Stay with me, it's actually so good. 💅

✨ NAME ✨

nslink — the device driver for DeviceMaster. That's it, that's the whole thing. 🎀

✨ SYNOPSIS ✨

Kernel module

Yeah. It's a kernel module. Not a command, not a script, a module. Main character energy fr fr. 🔥

✨ DESCRIPTION ✨

So the nslink device driver is what gives you support for Comtrol DeviceMaster network-attached serial ports. It hands you regular, standard serial port semantics through the devices /dev/ttySI[0-n]. Iconic behavior, no cap. 🦋

The NS-Link driver implements a low-level serial device that runs underneath the same tty line discipline layer that all your other serial devices sit under. Which means — and this is the slay part — using a DeviceMaster is almost identical to using literally any other serial port. 🫶

BUT. (there's always a but 😭) Because it's all happening over the network, it's possible — thanks to network problems or other hardware problems — that the host may lose contact with that low-level serial device. And like, that is not something that usually happens with internal serial boards, bestie. So the NS-Link driver can return errors you'd never normally see from other serial drivers. Here's the whole tea:

                                                               Reconnect
       operation  !CLOCAL && !CD   Link Down     Link Timeout  Refusal[3]
       ---------  --------------  -----------    ------------  ---------

       read()          EOF          block[1]         EIO          EIO

       write()         EIO       success/block[2]    EIO        ENOTCONN

       open()     block till CD      EBUSY          EBUSY        EBUSY

Now the footnotes, because they matter:

  1. Assuming the fd is in blocking mode and there's no data in the line discipline rx buffer, a read() will block until either the connection comes back and data is available, or until the link times out. ⏳
  2. Up to 4K of write data will be queued, and subsequent writes will block until the connection resumes or the link times out. 📦
  3. A reconnect refusal happens when the network link between the host and the DeviceMaster times out and another host opens the port. Then if the connection to the original host comes back and the application still has the device open, the original host tries to reconnect to the port and gets refused by the DeviceMaster, because the port is in-use. Awkward. 🙈

Also — communications with the DeviceMaster can use either TCP/IP or the raw packet Ethernet interface. Two paths, both valid, pick your fighter. ⭐

🔥 LATENCY -- WRITE DATA 🔥

Default behavior of the NS-Link driver? It consolidates network traffic bound towards the DeviceMasters and sends data to all of them once every 10ms. Cute and efficient, but it can introduce a delay of up to 10ms when data is written to a DeviceMaster. ⏱️

Setting the low_latency flag on a DeviceMaster makes data written to that device go out immediately. That reduces the latency in outbound data — at the expense of increased CPU and network usage. Tradeoffs, always tradeoffs. 💀

The low_latency flag can be set in the nslink.conf(5) file, by using the setseral(8) utility (see below), or with the underlying TIOCSSERIAL and TIOCGSERIAL ioctl() calls. 🎀

🌸 LATENCY -- READ DATA 🌸

By default, serial data received by the DeviceMaster is sent to the NS-Link driver once every 10ms. That can introduce a delay of up to 10ms in the receive data path. (Original page typo'd it "recieve", we're keeping the facts, not the typo, luv u 💖)

In the DeviceMaster, this latency can be reduced in two ways:

Inter-character timeout

It's possible to configure an inter-character timeout that causes the DeviceMaster to send queued receive data when a gap is detected in the receive serial data stream. You can configure it either in the nslink.conf(5) file, by using the setseral(8) utility (see below), or with the underlying TIOCSSERIAL and TIOCGSERIAL ioctl() calls. ✨

Scan period

You can also change the DeviceMaster's scan period from the default 10ms down to a lower value. That decreases latency too — but it increases CPU and network usage. Configuring an inter-character timeout is generally the better way to reduce latency in receive data. 👑

The scan period is configured in the nslink.conf(5) file. A value of 0 causes the DeviceMaster to use its default scan period (10ms). 🌀

Retransmit Timer

You can also change the DeviceMaster's retransmit timer from the default 200ms to a lower value. This decreases the wait before retransmitting a packet, but increases CPU and network usage. The timer is configurable from 40ms up to the default value of 200ms, in 20ms intervals. It's configured in the nslink.conf(5) file. A value of 0 causes the DeviceMaster to use its default timer value (200ms). 🕐

💜 SETSERIAL INTERFACE 💜

The standard setserial(8) — or the underlying TIOCSSERIAL and TIOCGSERIAL ioctl() calls — may be used to access the following attributes of a DeviceMaster:

  • low_latency flag (read-write) — when set, causes write() data to be written immediately to the DeviceMaster. 🚀
  • irq (read-write) — the inter-character timeout value (in milliseconds) for the port. A value of 0 disables the inter-character timeout feature. ⏲️
  • port (read-only) — contains either the IP address or the low-order 32 bits of the MAC address of the DeviceMaster. 🏷️
  • line (read-only) — contains the port number within the DeviceMaster (e.g 0-7 for a port on an 8-port DeviceMaster). 🔢

✨ OPTIONS ✨

Configuration of the NS-Link driver happens via the configuration file /etc/nslink.conf(5) and via setserial(8), as described above. That's the whole options situation, bestie. 🎀

🌈 ENVIRONMENT 🌈

None

Yep. Nothing. Zero. Empty. The environment section is on a little digital vacation. 🏖️

🦋 FILES 🦋

  • /proc/driver/nslink/status — if the Linux kernel supports the /proc filesystem, this file contains the current status of the DeviceMaster the driver is configured to control. 📊
  • /proc/driver/nslink/ports — if the Linux kernel supports the /proc filesystem, this file contains the current status of the individual ports for which the driver is configured. 📋
  • devmast.bin — the application binary file downloaded to DeviceMaster by the load operation. Search path: current directory, /etc. 📁

💅 SEE ALSO 💅

nslinkd(8), nslinkadmin(8), nslinkrelease(8), nslinktool(8), setserial(8) — go read those too, they're the friend group. 🫶

🎀 BUGS 🎀

Check the release notes file for an up-to-date list. (Not gonna lie, "check the release notes" is the most mysterious sentence ever written. 😭)

⭐ FTP LOCATION ⭐

ftp://ftp.comtrol.com/

Go get your files, retro-style. 🧚

Heads up bestie: those network link errors up top are real and they're not the kind of thing you see with internal serial boards — so if you get an EIO, an ENOTCONN, or an EBUSY from a DeviceMaster port, don't panic, that's just the network being the network. 💀

That's the whole page, mwah 💋 — © Comtrol Corp., dated 4 March 2009, from the Comtrol corner of the manual world. Go forth and serialize responsibly. 🍓

📦 where this page comes from