From 5acaf87d3cc244038c993b18ea22000c6a144dac Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Wed, 21 Jul 2021 00:36:07 -0400 Subject: Update docs --- README.txt | 143 +++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 86 insertions(+), 57 deletions(-) (limited to 'README.txt') diff --git a/README.txt b/README.txt index 28132d3..d9e2c32 100644 --- a/README.txt +++ b/README.txt @@ -1,79 +1,108 @@ -SLOWBAUD(1) Urchlay's Useless Stuff SLOWBAUD(1) +SLOWBAUD(1) Urchlay's Useless Stuff SLOWBAUD(1) NAME slowbaud - simulate a low bitrate serial connection SYNOPSIS - slowbaud [ ...] + slowbaud [] [ ...] - slowbaud -c [ [ ...]] + 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). + slowbaud [] -e [ ...] - 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% accu‐ - rate. +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. Input and output are + unbuffered. + + slowbaud can also act like echo(1) (the -e option), or run an interactive com‐ + mand (the -c option). + + The argument is optional. If it's not given, the bit rate will + be set from SLOWBAUD_BPS in the environment, or a built-in default of 2400 if + not set. + +OPTIONS + bits-per-sec + The bit ("baud") rate to simulate. This must be the first argument. + slowbaud assumes that if the first argument is a number, it's the bit + rate. If you're trying to pass a filename that consists only of dig‐ + its, give -- as the first argument, or use e.g. ./filename. + + -e Echo mode. Prints all further arguments as strings to stdout, separated + by a single space, at the given bit rate. Does not support back‐ + slash-escapes, or any of the options of the regular echo command. + + -c Command mode. Next argument (if present) is the command to run, any + remaining arguments become arguments to the command. With no arguments + after -c, a shell is spawned. This creates a pseudo-tty, so the com‐ + mand can be interactive. ENVIRONMENT + SLOWBAUD_BPS + Can be used to set the bit rate, when no argument is + used. + SLOWBAUD_DEBUG - Set this (to any value) in the environment to see verbose debug output on - stderr, including timing accuracy stats. + 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. + 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)). + Without -c, 0 for success, non-zero on any error such as nonexistent/unread‐ + able 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... + 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 capa‐ - bilities). - - 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. + The bitrate has 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" tech‐ + niques like realtime scheduling or hardware event timers are used. At bitrates + up to 57600, on a typical unloaded Linux system, the timing should be at least + 99.7% accurate. + + 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 sig‐ + wait(). 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 com‐ + mand 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. + 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. + slowbaud is copyright 2021, B. Watson . Released under the + WTFPL. See http://www.wtfpl.net/txt/copying/ for details. -0.0.1 2021-07-21 SLOWBAUD(1) +0.0.1 2021-07-21 SLOWBAUD(1) -- cgit v1.2.3