From aa956853cc37d163113cafb2f1982b7a3a306fd1 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Wed, 21 Jul 2021 00:12:31 -0400 Subject: initial commit --- slowbaud.rst | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 slowbaud.rst (limited to 'slowbaud.rst') diff --git a/slowbaud.rst b/slowbaud.rst new file mode 100644 index 0000000..13e9e64 --- /dev/null +++ b/slowbaud.rst @@ -0,0 +1,117 @@ +.. RST source for slowbaud(1) man page. Convert with: +.. rst2man.py slowbaud.rst > slowbaud.1 +.. rst2man.py comes from the SBo development/docutils package. + +.. |version| replace:: 0.0.1 +.. |date| date:: + +======== +slowbaud +======== + +---------------------------------------- +simulate a low bitrate serial connection +---------------------------------------- + +:Manual section: 1 +:Manual group: Urchlay's Useless Stuff +:Date: |date| +:Version: |version| + +SYNOPSIS +======== + +**slowbaud** ** [** ...] + +**slowbaud** ** **-c** [** [** ...]] + +DESCRIPTION +=========== + +slowbaud by default acts as a filter, or like the **cat(1)** command. It +reads files or its standard input, and writes the contents unmodified +to standard output... but slowly, at the given bits-per-second rate. +Output is unbuffered. + +With the **-c** option, it creates a pseudo-tty and runs the given command +in it (or an interactive shell, if no command is given). + +The ** argument supports a range of 1 to 500000. Timing +accuracy depends on your OS, kernel config (HZ and/or NO_HZ on Linux), +and system load. No "fancy" techniques like realtime scheduling +or hardware event timers are used. At bitrates up to 57600, on a +typical unloaded Linux system, the timing should be around 99.7% +accurate. + +ENVIRONMENT +=========== + +**SLOWBAUD_DEBUG** + Set this (to any value) in the environment to see verbose debug + output on stderr, including timing accuracy stats. + +**SHELL** + Standard \*nix environment variable, used to determine what + shell to run when **-c** is given with no **. If + unset, **/bin/sh** is used. + +EXIT STATUS +=========== + +Without **-c**, 0 for success, non-zero on any error such as +nonexistent/unreadable files. slowbaud exits immediately on such +errors (this is unlike **cat(1)**). + +With **-c**, exit status is that of the child process, or 127 if +the child process couldn't be spawned (e.g. command not found). +Of course, the child process could also exit with status 127... + +NOTES +===== + +We can't really insert a delay between the bits of a byte, since +I/O is done with byte granularity. For calculation purposes, +** is divided by 10 to get bytes per second. This +simulates "8-N-1": one start bit, 8 data bits, no parity, and 1 stop +bit (total of 10 bits per byte). + +The timing code works by calculating how long to sleep after each +character (in microseconds), but actually sleeping slightly less +than that, then busy-waiting until the rest of the interval expires. +At slower bitrates, this works well, and the CPU overhead is barely +noticeable (at least on reasonably fast modern systems). + +The timing error will almost always result in the bitrate +being slightly too slow at lower bitrates and slightly too fast at +higher ones. + +Timing is more accurate on Linux than OSX. It's done with getitimer() +and sigwait(). This works out to be slightly more accurate than +using usleep() on both Linux and OSX. It would be possible to use +the realtime timer_create() and clock_gettime() API on Linux, for +possibly even better accuracy, but OSX doesn't have these (and I want to be +portable). + +If this were a truly useful application, it would be worth trying to +decrease latency further, with realtime process scheduling. I didn't +do this because slowbaud is just a toy, and because the RT stuff tends +to be unportable and require elevated privileges (root, or something +like setrtlimit or extended filesystem attributes to manage capabilities). + +About the name... I'm aware that "baud" is not synonymous with bps. I +just think "slowbaud" sounds better than "slowbps", as a name. Anyway +the stty command on Linux misuses the term ("speed 38400 baud"), so +I'm in good company. + +BUGS +==== + +With **-c**, signals aren't handled gracefully. Window size changes +(SIGWINCH) don't get propagated to the child process, and pressing ^C +doesn't interrupt the process. Yet. + +COPYRIGHT +========= + +slowbaud is copyright 2021, B. Watson . Released +under the WTFPL. See http://www.wtfpl.net/txt/copying/ for details. -- cgit v1.2.3