Switch to using an OS-independent serial layer

[penguin359]

Before sitting down and writing some code, I thought I'd discuss this idea and see how receptive the team is to it. Looking through the codebase, it appears that the primary piece of it that is blocking it from compiling on Windows is the serial transport layer it uses. This should be straight-forward to implement on Windows as well and improve the cross-platform potential for this project. It could just be an alternate module which is selected conditionally; however, it might make more sense to use an already implemented crate for handling the cross-platform differences. The Rust serialport crate seems to be receiving regular updates although I haven't extensively evaluated it just yet. Would this be a good way to take this for a contribution to Mujina Miner?

[rkuester]

Hey @penguin359! I believe you're right: the primary platform dependencies at the moment are the serial port and the USB hotplug implementations. I'm definitely open to seeing those work on macOS and even Windows. (However, I don't think it will ever be a top priority for the project to support those platforms.)

Initially, I used the serialport crate. But as the project became more complex, I ended up with a custom implementation for a few reasons:

1. If I recall correctly, I switched to tokio-serial as Mujina's architecture became more async.
2. We need to set unusual baud rates, and that didn't seem to work with serialport or tokio-serial. I don't remember the exact details, and it's possible the problem wasn't with serialport in the end.
3. We need the ability to switch baud rates after the streams are in operation for a while. This was impossible with tokio-serial once the TX and RX streams were split and passed to different async tasks.

So, I'm open to a more portable implementation, but it probably won't be as straightforward as using serialport. But I'm happy to be proven wrong!

I'm currently working on the driver for EmberOne, where the on-the-fly baud rate switching is more critical. (Interestingly, it's not necessary to switch to a higher speed for a Bitaxe Gamma's single chip.) You might have to wait a bit to see where this leads, so all the requirements are clear.

USB hotplug might be a good starting point immediately. It's well-abstracted at the moment, but only has a Linux implementation.

[penguin359]

Yes, that is understandable. Then I'll just take a whack at trying to implement a selectable OS transport. I think Windows support is mostly useful just to keep it more open for others to tinker and possibly contribute as well as ensuring it's not completely dependent on a single OS in case where this might be used in other embedded, non-Linux contexts. As for unusual baud rates, I am working with a chip that uses 9-bit serial and can do higher baud rates like 5M and 10M baud beyond where there is POSIX definitions. I've worked with two different hardware implementations that implement it each with their own specific Linux drivers.

One of them is somewhat standard. For all baud rates that match up to an existing definition, up to 2Mbaud, you'd use the normal flag with the termios.c_cflag field. When using the highest two baud rates which don't have a standard definition, they just added a custom value well above the existing enum values so it wouldn't conflict. Not a bad option, but definitely specific to that driver. It much better than the hack I've seen using ioctl(TIOCSSERIAL, struct serial_struct) to set a custom divisor which affects the actual interpretation of all speeds set via termios for that serial device. Probably the best solution, however, would haven been for them to switch to using the termios2 structure with ioctl(TCSETS2) which uses a regular integer for the baud rates instead of an enum value. It doesn't seem to be well-documented, but it appears to have been added back during the Linux 2.6.x timeline and avoids the need for custom magic values between userspace and the driver.

For the 9-bit configuration, the driver borrowed the ioctl() calls for enabling RS-485 as that protocol uses 9-bit words for sending address/data not unlike what our chip uses.

Now, the other chip I am using which is commercially available uses a much less clean API for the driver. It re-uses the CS5 word-size flag and interprets it as 9-bit since 5-bit is pretty much unheard of these days. They provide both Windows, Mac and Linux drivers so I suspect this is the same on all platforms as 5-bit is present on all of the operating systems. It at least avoids custom magic values or uncommon/non-standard ioctl() calls but feels like a hack. Now, for setting the baud rate with this driver, if you want anything beyond the standard baud rates available via the enum for termios, they invented their own custom ioctl() call which you have to implement and the developers seem to be completely unaware that ioctl(TCSETS2, struct termios2) even exists. No idea what their Windows driver looks like here.

So, yeah, unfortunately, some of this isn't even standard across different drivers.

[rkuester]

Recording a brainstorm idea:

Maybe it's better to return to a well-supported, platform-independent serial library and instead add a layer of indirection where a single, dedicated task owns the port and provides channels that can be passed out to the end users.

[Nickamoto]

Hey @rkuester, just wanted to follow up on your note about USB hotplug being a good starting point. That's exactly what I've been running into.

I'm new to contributing here and have been trying to get set up on macOS with a BitAxe Gamma. The USB discovery stub ("USB discovery is not yet implemented for macOS") means I can't enumerate connected devices at all, so I started working on an IOKit implementation to fill that gap.

I've got something working. It finds the BitAxe and resolves the serial port path (/dev/cu.usbmodem31101) correctly on my machine. I tried to model it after the Linux udev implementation so it fits into the existing transport layer without changing anything else.

I wanted to check in before going further. Does this sound like the right direction? Happy to open a proper issue and PR if it's something the project wants.⁦