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.1 | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 slowbaud.1 (limited to 'slowbaud.1') diff --git a/slowbaud.1 b/slowbaud.1 new file mode 100644 index 0000000..7fcec1e --- /dev/null +++ b/slowbaud.1 @@ -0,0 +1,126 @@ +.\" Man page generated from reStructuredText. +. +.TH SLOWBAUD 1 "2021-07-21" "0.0.1" "Urchlay's Useless Stuff" +.SH NAME +slowbaud \- simulate a low bitrate serial connection +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.\" RST source for slowbaud(1) man page. Convert with: +. +.\" rst2man.py slowbaud.rst > slowbaud.1 +. +.\" rst2man.py comes from the SBo development/docutils package. +. +.SH SYNOPSIS +.sp +\fBslowbaud\fP \fI\fP [\fI\fP ...] +.sp +\fBslowbaud\fP \fI\fP \fB\-c\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. +.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). +.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. +.SH ENVIRONMENT +.INDENT 0.0 +.TP +.B \fBSLOWBAUD_DEBUG\fP +Set this (to any value) in the environment to see verbose debug +output on stderr, including timing accuracy stats. +.TP +.B \fBSHELL\fP +Standard *nix environment variable, used to determine what +shell to run when \fB\-c\fP is given with no \fI\fP\&. If +unset, \fB/bin/sh\fP is used. +.UNINDENT +.SH EXIT STATUS +.sp +Without \fB\-c\fP, 0 for success, non\-zero on any error such as +nonexistent/unreadable files. slowbaud exits immediately on such +errors (this is unlike \fBcat(1)\fP). +.sp +With \fB\-c\fP, exit status is that of the child process, or 127 if +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 +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 +simulates "8\-N\-1": one start bit, 8 data bits, no parity, and 1 stop +bit (total of 10 bits per byte). +.sp +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). +.sp +The timing error will almost always result in the bitrate +being slightly too slow at lower bitrates and slightly too fast at +higher ones. +.sp +Timing is more accurate on Linux than OSX. It\(aqs 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\(aqt have these (and I want to be +portable). +.sp +If this were a truly useful application, it would be worth trying to +decrease latency further, with realtime process scheduling. I didn\(aqt +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). +.sp +About the name... I\(aqm 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\(aqm in good company. +.SH BUGS +.sp +With \fB\-c\fP, signals aren\(aqt handled gracefully. Window size changes +(SIGWINCH) don\(aqt get propagated to the child process, and pressing ^C +doesn\(aqt interrupt the process. Yet. +.SH COPYRIGHT +.sp +slowbaud is copyright 2021, B. Watson <\fI\%yalhcru@gmail.com\fP>. Released +under the WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details. +.\" Generated by docutils manpage writer. +. -- cgit v1.2.3