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 +++++++++++++++++++++++++++++++++++------------------------ slowbaud.1 | 49 +++++++++++++++----- slowbaud.rst | 49 +++++++++++++++----- 3 files changed, 162 insertions(+), 79 deletions(-) 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) diff --git a/slowbaud.1 b/slowbaud.1 index 7fcec1e..c25d8e9 100644 --- a/slowbaud.1 +++ b/slowbaud.1 @@ -38,28 +38,49 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] . .SH SYNOPSIS .sp -\fBslowbaud\fP \fI\fP [\fI\fP ...] +\fBslowbaud\fP [\fI\fP] [\fI\fP ...] .sp -\fBslowbaud\fP \fI\fP \fB\-c\fP [\fI\fP [\fI\fP ...]] +\fBslowbaud\fP [\fI\fP] \fB\-c\fP [\fI\fP [\fI\fP ...]] +.sp +\fBslowbaud\fP [\fI\fP] \fB\-e\fP \fI\fP [\fI\fP ...] .SH DESCRIPTION .sp slowbaud by default acts as a filter, or like the \fBcat(1)\fP 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. +Input and output are unbuffered. .sp -With the \fB\-c\fP option, it creates a pseudo\-tty and runs the given command -in it (or an interactive shell, if no command is given). +slowbaud can also act like \fBecho(1)\fP (the \fB\-e\fP option), or run an +interactive command (the \fB\-c\fP option). .sp -The \fI\fP 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. +The \fI\fP argument is optional. If it\(aqs not given, the +bit rate will be set from \fBSLOWBAUD_BPS\fP in the environment, or a +built\-in default of 2400 if not set. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fBbits\-per\-sec\fP +The bit ("baud") rate to simulate. This must be the first argument. +slowbaud assumes that if the first argument is a number, it\(aqs the bit rate. +If you\(aqre trying to pass a filename that consists only of digits, give +\fB\-\-\fP as the first argument, or use e.g. \fI\&./filename\fP\&. +.TP +.B \fB\-e\fP +Echo mode. Prints all further arguments as strings to stdout, separated +by a single space, at the given bit rate. Does not support backslash\-escapes, or any of +the options of the regular \fBecho\fP command. +.TP +.B \fB\-c\fP +Command mode. Next argument (if present) is the command to run, any remaining arguments +become arguments to the command. With no arguments after \fB\-c\fP, a shell is spawned. +This creates a pseudo\-tty, so the command can be interactive. +.UNINDENT .SH ENVIRONMENT .INDENT 0.0 .TP +.B \fBSLOWBAUD_BPS\fP +Can be used to set the bit rate, when no \fI\fP argument is used. +.TP .B \fBSLOWBAUD_DEBUG\fP Set this (to any value) in the environment to see verbose debug output on stderr, including timing accuracy stats. @@ -80,6 +101,12 @@ the child process couldn\(aqt be spawned (e.g. command not found). Of course, the child process could also exit with status 127... .SH NOTES .sp +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" 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 at least 99.7% accurate. +.sp We can\(aqt really insert a delay between the bits of a byte, since I/O is done with byte granularity. For calculation purposes, \fI\fP is divided by 10 to get bytes per second. This diff --git a/slowbaud.rst b/slowbaud.rst index 13e9e64..e88f890 100644 --- a/slowbaud.rst +++ b/slowbaud.rst @@ -21,9 +21,11 @@ simulate a low bitrate serial connection SYNOPSIS ======== -**slowbaud** ** [** ...] +**slowbaud** [**] [** ...] -**slowbaud** ** **-c** [** [** ...]] +**slowbaud** [**] **-c** [** [** ...]] + +**slowbaud** [**] **-e** ** [** ...] DESCRIPTION =========== @@ -31,21 +33,40 @@ 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. +Input and output are unbuffered. + +slowbaud can also act like **echo(1)** (the **-e** option), or run an +interactive command (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 +======= -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). +**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 digits, give + **--** as the first argument, or use e.g. *./filename*. -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. +**-e** + Echo mode. Prints all further arguments as strings to stdout, separated + by a single space, at the given bit rate. Does not support backslash-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 command 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. @@ -69,6 +90,12 @@ Of course, the child process could also exit with status 127... NOTES ===== +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" 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 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 -- cgit v1.2.3