From 0baa92a29a25d2bcf85b29176d8f764c7fcd2db9 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Fri, 23 Jul 2021 21:15:55 -0400 Subject: doc update --- README.txt | 22 +++++++++++++--------- slowbaud.1 | 23 +++++++++++++---------- slowbaud.rst | 21 ++++++++++++--------- 3 files changed, 38 insertions(+), 28 deletions(-) diff --git a/README.txt b/README.txt index 870f356..843ac78 100644 --- a/README.txt +++ b/README.txt @@ -23,7 +23,7 @@ DESCRIPTION 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. + that's not set. OPTIONS bits-per-sec @@ -75,10 +75,8 @@ EXIT STATUS to open /dev/null for writing). NOTES - 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. + The timing inaccuracy will almost always result in the bitrate being slightly + too slow. 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 @@ -91,14 +89,20 @@ NOTES works well, and the CPU overhead is barely noticeable (at least on reasonably fast modern systems). - The timing inaccuracy will almost always result in the bitrate being slightly - too slow. + Timing accuracy depends on your OS, kernel config (HZ and/or NO_HZ on Linux), + and system load. Also on the amount of data, since the timing loop is + self-regulating (the first few bytes will have less accurate timing than later + ones). No "fancy" techniques like realtime scheduling or hardware event timers + are used. At bitrates up to 115200, on an unloaded Linux system, the timing + should be at least 99.9% accurate. At higher bitrates, accuracy will decrease. 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). + doesn't have these (and I want to be portable). On an unloaded OSX system, the + accuracy gets steadily worse as you go above 57600bps. There's also more CPU + overhead on OSX. If this were a truly useful application, it would be worth trying to increase accuracy further, with realtime process scheduling. I didn't do this because @@ -120,4 +124,4 @@ COPYRIGHT slowbaud is copyright 2021, B. Watson . Released under the WTFPL. See http://www.wtfpl.net/txt/copying/ for details. -0.0.1 2021-07-22 SLOWBAUD(1) +0.0.1 2021-07-23 SLOWBAUD(1) diff --git a/slowbaud.1 b/slowbaud.1 index 863383d..543bb03 100644 --- a/slowbaud.1 +++ b/slowbaud.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH SLOWBAUD 1 "2021-07-22" "0.0.1" "Urchlay's Useless Stuff" +.TH SLOWBAUD 1 "2021-07-23" "0.0.1" "Urchlay's Useless Stuff" .SH NAME slowbaud \- simulate a low bitrate serial connection . @@ -63,7 +63,7 @@ interactive command in a pseudo\-tty (the \fB\-c\fP option). .sp 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. +built\-in default of 2400 if that\(aqs not set. .SH OPTIONS .INDENT 0.0 .TP @@ -123,11 +123,8 @@ With \fB\-b\fP, exit status is 0, unless something catastrophic happened (e.g. unable to open \fB/dev/null\fP for writing). .SH NOTES .sp -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. +The timing inaccuracy will almost always result in the bitrate +being slightly too slow. .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, @@ -141,15 +138,21 @@ 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 inaccuracy will almost always result in the bitrate -being slightly too slow. +Timing accuracy depends on your OS, kernel config (HZ and/or NO_HZ +on Linux), and system load. Also on the amount of data, since the +timing loop is self\-regulating (the first few bytes will have less +accurate timing than later ones). No "fancy" techniques like realtime +scheduling or hardware event timers are used. At bitrates up to +115200, on an unloaded Linux system, the timing should be at least +99.9% accurate. At higher bitrates, accuracy will decrease. .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). +portable). On an unloaded OSX system, the accuracy gets steadily worse +as you go above 57600bps. There\(aqs also more CPU overhead on OSX. .sp If this were a truly useful application, it would be worth trying to increase accuracy further, with realtime process scheduling. I didn\(aqt diff --git a/slowbaud.rst b/slowbaud.rst index e270df7..bc6eb5a 100644 --- a/slowbaud.rst +++ b/slowbaud.rst @@ -46,7 +46,7 @@ interactive command in a pseudo-tty (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. +built-in default of 2400 if that's not set. OPTIONS ======= @@ -110,11 +110,8 @@ With **-b**, exit status is 0, unless something catastrophic happened NOTES ===== -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. +The timing inaccuracy will almost always result in the bitrate +being slightly too slow. We can't really insert a delay between the bits of a byte, since I/O is done with byte granularity. For calculation purposes, @@ -128,15 +125,21 @@ 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 inaccuracy will almost always result in the bitrate -being slightly too slow. +Timing accuracy depends on your OS, kernel config (HZ and/or NO_HZ +on Linux), and system load. Also on the amount of data, since the +timing loop is self-regulating (the first few bytes will have less +accurate timing than later ones). No "fancy" techniques like realtime +scheduling or hardware event timers are used. At bitrates up to +115200, on an unloaded Linux system, the timing should be at least +99.9% accurate. At higher bitrates, accuracy will decrease. 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). +portable). On an unloaded OSX system, the accuracy gets steadily worse +as you go above 57600bps. There's also more CPU overhead on OSX. If this were a truly useful application, it would be worth trying to increase accuracy further, with realtime process scheduling. I didn't -- cgit v1.2.3