diff options
Diffstat (limited to 'tap/tap.texinfo')
| -rwxr-xr-x | tap/tap.texinfo | 826 |
1 files changed, 826 insertions, 0 deletions
diff --git a/tap/tap.texinfo b/tap/tap.texinfo new file mode 100755 index 0000000..820e803 --- /dev/null +++ b/tap/tap.texinfo @@ -0,0 +1,826 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename tap.info +@setcontentsaftertitlepage +@settitle Tap +@c %**end of header + + +@c information for a proper install +@dircategory Communication Programs +@direntry +* Tap: (tap). A program to communicate with a serial line tap. +@end direntry + + +@c include commands and keystrokes with the regular index +@syncodeindex fn cp +@syncodeindex ky cp + + +@ifinfo +This file documents Tap, a program to read data from (and write data to) +a serial port. Amongst other things, it may be used to facilitate the +reverse engineering of serial communication protocols. + +Copyright @copyright{} 1999 Jonathan E duSaint @email{jon@@mbayweb.com}. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``Copying'' and ``GNU General Public License'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the Free Software Foundation. +@end ifinfo + + +@titlepage +@title Tap 1.0 +@subtitle A program to communicate with a serial line tap. +@author Jonathan E duSaint <jon@@mbayweb.com> + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1999 Jonathan E duSaint @email{jon@@mbayweb.com} + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +sections entitled ``Copying'' and ``GNU General Public License'' are +included exactly as in the original, and provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the Free Software Foundation. +@end titlepage + + +@ifnottex +@node Top, Introduction, , (dir) +@comment node-name, next, previous, up +@top Tap + +Tap is a program designed to read data from and write data to the serial +port. As such it has a wide variety of applications. For example, it +can be used to prototype serial hardware, or to read data from a serial +line tap, which can facilitate the reverse engineering of serial line +communication protocols. + +This documentation corresponds with version 1.0 of Tap. +@end ifnottex + +@menu +* Introduction:: An introduction to @code{Tap} and the manual. +* The Command Line:: The ins and outs of the interface. +* Command Overview:: A look at the commands. +* Input and Output:: Communicating with the serial line. +* The Set Command:: Setting the environment. + +* Index:: The command, concept, and keystroke index. + +@detailmenu +--- The Detailed Node Listing --- +* Conventions:: Document conventions. +* Invocation:: How to start @code{Tap} and the command line options. +* Overview:: A brief tour through @code{Tap}. + +* History:: How to use the history functionality. +* Editing:: Command line editing. + +* C-B: Moving Left. Moving the cursor to the left. +* Left Arrow: Moving Left. + Moving the cursor to the left. +* C-F: Moving Right. Moving the cursor to the right. +* Right Arrow: Moving Right. + Moving the cursor to the right. +* C-A:: Moving the cursor to the start of the line. +* C-E:: Moving the cursor to the end of the line. +* C-D:: Deleting the character under the point. +* C-H:: Deleting the character to the left of the point. +* C-U:: Entering a numerical argument. +* C-space: Killing and Yanking Text. + Setting the mark position. +* C-K: Killing and Yanking Text. + Killing from the point to the end of the line. +* C-W: Killing and Yanking Text. + Killing in between the mark and the point. +* C-Y: Killing and Yanking Text. + Yanking text from the kill ring. +* C-T:: Transposing characters. +* C-L:: Clearing the screen. +* tab:: Command line completion. + +* alias:: Assign a different name to a command. +* capture:: Capture incoming data to a file or a register. +* clear:: Clear the input window. +* close:: Close an open serial port. +* help:: Get help on a command. +* open:: Open a serial port. +* out:: Write format controlled data to the serial port. +* print:: Print the contents of a file or a register. +* quit:: Quit the program. +* set:: Change the behavior of the program. +* unalias:: Remove an alias. + +* Help:: The --help command line option. +* version:: The --version command line option. +* port:: The --port command line option. +* save-history:: The --save-history command line option. +@end detailmenu +@end menu + + +@node Introduction, The Command Line, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + +This chapter serves as an introduction to the manual as well as to +@code{Tap}, and documents the command line options. + +@menu +* Conventions:: Document conventions. +* Invocation:: How to start @code{Tap} and the command line options. +* Overview:: A brief tour through @code{Tap}. +@end menu + + +@node Conventions, Invocation, Introduction, Introduction +@comment node-name, next, previous, up +@section Conventions +@cindex Document, How to Read +@cindex Explanation of the C-? Syntax +@cindex C-? Syntax, Explanation of + +The syntax @dfn{C-whatever} means to press the @kbd{Control} key and to +simultaneously press the @kbd{whatever} key. For example, @kbd{C-P} +means to hold down the @kbd{Control} key, and then hit the @kbd{P} key. + +When the command definitions are presented, the command usage is put +first. Then follows a description of the function. If there is more +than one way to use a function, then each invocation is shown with an +explanation after it. + + +@node Invocation, Overview, Conventions, Top +@comment node-name, next, previous, up +@section Invocation +@cindex Options +@cindex Command Line Options +@cindex Startup Options +@cindex Invocation + +To start @code{Tap}, merely type @kbd{tap} at the shell prompt. If it +is properly installed, you should be presented with the interface. If +it isn't, then read the file @file{INSTALL} for information on how to do +so. @code{Tap} can be invoked with several different command line +options. + +@menu +* Help:: The --help command line option. +* version:: The --version command line option. +* port:: The --port command line option. +* save-history:: The --save-history command line option. +@end menu + + +@node Help, version, Invocation, Invocation +@comment node-name, next, previous, up +@subsection @code{--help} +@findex --help +@findex -h +@cindex @code{help}, Command Line Option + +@code{--help}, @code{-h} + +Invoking @code{Tap} with this option will cause @code{Tap} to print a +short help message to @var{stdout} and then exit. + + +@node version, port, Help, Invocation +@comment node-name, next, previous, up +@subsection @code{--version} +@findex --version +@findex -v +@cindex @code{version}, Command Line Option + +@code{--version}, @code{-v} + +Invoking @code{Tap} with this option will cause @code{Tap} to print +version and copyright information to @var{stdout} and then exit. + + +@node port, save-history, version, Invocation +@comment node-name, next, previous, up +@subsection @code{--port} +@cindex Default Port +@cindex Port, Opening on Invocation +@findex --port +@findex -p +@cindex @code{port}, Command Line Option + +@code{--port} @file{serial port}, @code{-p} @file{serial port} + +With this option, @code{Tap} will open @file{serial port} at startup. +If the serial port can't be opened, @code{Tap} will print an error +message at startup. + + +@node save-history, , port, Invocation +@comment node-name, next, previous, up +@subsection @code{--save-history} +@findex --save-history +@findex -s +@cindex @code{save-history}, Command Line Option +@cindex Saving History +@cindex History, Saving +@cindex History File +@cindex Default History File + +@code{--save-history} @file{history filename}, @code{-s} @file{history filename} + +This option will cause @code{Tap} to read history information at startup +from the file specified and to write history information at shutdown to +the file. If the file specified doesn't exist, it will be created, and +if no file is specified, the default will be used, which is usually +@file{~/.tap_history}. + + +@node Overview, , Invocation, Introduction +@comment node-name, next, previous, up +@section Overview +@findex help, Command + +This overview assumes that @code{tap} is already properly installed on +your system. If it isn't, read the file @file{INSTALL} for instructions. + +To start, invoke @code{tap} from the command line by typing @kbd{tap}. +Once it is started, you will notice that the screen is divided into two +parts, both with headers. The top part is called the @dfn{input window} +and the bottom part is called the @dfn{output window}. At the bottom of +the screen is the status bar. It should state that no serial port is +open on one side, and suggest typing @code{help} for help. + +As a first experiment, try typing @code{help}. You will be presented +with a brief summary of all of the commands available. To get more +specific help information, type @code{help command-name} + + +@node The Command Line, Command Overview, Introduction, Top +@comment node-name, next, previous, up +@chapter The Command Line +@cindex Command Line Interface + +If you are familiar with @code{Bash} or @code{Emacs}, then you should +already have a good grasp of most of the functionality of the command +line interface. While @code{Tap} doesn't actually use the @code{GNU +Readline} or the @code{GNU History} libraries, the interface was +designed to be very similar. All commands are saved in a history list, +although if a command is repeated one or more times, only one copy is +saved. Also, while entering text on the command line, a variety of +keystrokes are available for command line editing. + +@menu +* History:: How to use the history functionality. +* Editing:: Command line editing. +@end menu + +@node History, Editing, The Command Line, The Command Line +@comment node-name, next, previous, up +@section History +@cindex History Functionality +@cindex History List +@cindex History File +@kindex C-P +@kindex C-N +@kindex Up Arrow +@kindex Arrow, Up +@kindex Down Arrow +@kindex Arrow, Down + +Every time a command is entered, it is automatically inserted into the +internal history list. However, if the command is identical to the +previous command, a list entry is not made. + +To access previous entries, press either @kbd{Up Arrow}, or +@kbd{C-P}. To access more recent entries, press either @kbd{Down +Arrow}, or @kbd{C-N}. + +If a previous entry is edited and @kbd{Enter} is not pressed, the edited +copy will be saved in the place of the original. However, once +@kbd{Enter} is pressed, the original copy will once again be available. + +When @code{Tap} is invoked with the @code{--save-history} +(@pxref{save-history}) option, all history entries are read at startup +from the file specified, or, if one isn't specified, from the default +file. At shutdown, the current history list is appended onto the file. + +If a file is specified that doesn't exist, then one will be created at +shutdown. + + +@node Editing, , History, The Command Line +@comment node-name, next, previous, up +@section Editing +@cindex Command Line Editing +@cindex Editing, Command Line + +@code{Tap} contains features for editing the current command line. The +keystrokes are the same as used in @code{Emacs} and in the @code{Bash} +shell's @code{Emacs} mode. + +@menu +--- list of keystrokes --- +* C-B: Moving Left. Moving the cursor to the left. +* Left Arrow: Moving Left. + Moving the cursor to the left. +* C-F: Moving Right. Moving the cursor to the right. +* Right Arrow: Moving Right. + Moving the cursor to the right. +* C-A:: Moving the cursor to the start of the line. +* C-E:: Moving the cursor to the end of the line. +* C-D:: Deleting the character under the point. +* C-H:: Deleting the character to the left of the point. +* C-U:: Entering a numerical argument. +* C-space: Killing and Yanking Text. + Setting the mark position. +* C-K: Killing and Yanking Text. + Killing from the point to the end of the line. +* C-W: Killing and Yanking Text. + Killing in between the mark and the point. +* C-Y: Killing and Yanking Text. + Yanking text from the kill ring. +* C-T:: Transposing characters. +* C-L:: Clearing the screen. +* tab:: Command line completion. +@end menu + +@node Moving Left, Moving Right, Editing, Editing +@comment node-name, next, previous, up +@subsection Moving Left +@kindex C-B +@kindex Left Arrow +@kindex Arrow, Left +@cindex Point Movement +@cindex Cursor Movement + +@kbd{C-B}, @kbd{Left Arrow} + +Both of these keystrokes will move the point one character to the left, +if possible. + + +@node Moving Right, C-A, Moving Left, Editing +@comment node-name, next, previous, up +@subsection Moving Right +@kindex C-F +@kindex Right Arrow +@kindex Arrow, Right +@cindex Point Movement +@cindex Cursor Movement + +@kbd{C-F}, @kbd{Right Arrow} + +Both of these keystrokes will move the point one character to the right, +if possible. + + +@node C-A, C-E, Moving Right, Editing +@comment node-name, next, previous, up +@subsection @kbd{C-A} +@kindex C-A +@cindex Cursor Movement +@cindex Point Movement +@cindex Start of Line, Moving the Point to + +@kbd{C-A} + +This keystroke will move the point to the start of the line. + + +@node C-E, C-D, C-A, Editing +@comment node-name, next, previous, up +@subsection @kbd{C-E} +@kindex C-E +@cindex Cursor Movement +@cindex Point Movement +@cindex End of Line, Moving the Point to + +@kbd{C-E} + +This keystroke will move the point to the end of the line. + + +@node C-D, C-H, C-E, Editing +@comment node-name, next, previous, up +@subsection @kbd{C-D} +@kindex C-D +@kindex Delete +@cindex Deleting Characters + +@kbd{C-D}, @kbd{Delete} + +Both of these keystrokes will delete the character under the point. + + +@node C-H, C-U, C-D, Editing +@comment node-name, next, previous, up +@subsection @kbd{C-H} +@kindex C-H +@kindex Backspace +@cindex Deleting Characters + +@kbd{C-H}, @kbd{Backspace} + +Both of these keystrokes will delete the character to the left of the +point. + + +@node C-U, Killing and Yanking Text, C-H, Editing +@comment node-name, next, previous, up +@subsection @kbd{C-U} +@kindex C-U +@cindex Entering Numerical Arguments +@cindex Numerical Arguments, Entering +@cindex Arguments, Numerical +@cindex Numerical Arguments + +@kbd{C-U} + +This command prompts for a number. After the number is entered, press +@kbd{Enter}, and then the desired key. If the key entered was @kbd{C-Y} +(@pxref{Killing and Yanking Text}), then text from the kill ring will be +entered. If @kbd{Enter} was pressed, then it will be just as if +@kbd{Enter} had been pressed without the argument (i.e. the command line +will be processed). Any other key will be repeated as many times as was +indicated by the number. + +For example, type + +@example +@kbd{C-U} @kbd{2} @kbd{0} @kbd{Enter} @kbd{a} +@end example + +@noindent +to insert 20 copies of the letter `a', or type + +@example +@kbd{C-U} @kbd{5} @kbd{Enter} @kbd{C-D} +@end example + +@noindent +to delete the character under the point and four to the right of it. + + +@node Killing and Yanking Text, C-T, C-U, Editing +@comment node-name, next, previous, up +@subsection Killing and Yanking Text +@kindex C-space +@kindex C-W +@kindex C-K +@kindex C-Y +@cindex Killing Text +@cindex Yanking Text +@cindex Kill Ring +@cindex Copying Text +@cindex Cutting Text +@cindex Pasting Text +@cindex Setting the Mark +@cindex Mark, Setting + +@kbd{C-space} Set the mark. + +@kbd{C-W} Kill the text from the mark to the point. + +@kbd{C-K} Kill the text from the mark to the end of the line. + +@kbd{C-Y} Yank from the kill ring and insert it at the point. + +Tap utilizes a kill ring for storage of text which has been killed using +the above commands. The single character delete commands will not +store anything to the ring. + +The @kbd{C-Y} command will only yank the most recent entry. In order to +yank older entries than that, it must be used in combination with the +@kbd{C-U} command (@pxref{C-U}). For example, type + +@example +@kbd{C-U} @kbd{3} @kbd{Enter} @kbd{C-Y} +@end example + +@noindent +to insert the text from the third to last kill. + + +@node C-T, C-L, Killing and Yanking Text, Editing +@comment node-name, next, previous, up +@subsection @kbd{C-T} +@kindex C-T +@cindex Transposing Characters +@cindex Characters, Transposing + +@kbd{C-T} + +This keystroke transposes the character under the point with the +character to its left. + + +@node C-L, tab, C-T, Editing +@comment node-name, next, previous, up +@subsection @kbd{C-L} +@kindex C-T +@cindex Clearing the Screen + +@kbd{C-L} + +This keystroke clears the screen and redraws the current line. + +@xref{clear}. + + +@node tab, , C-L, Editing +@comment node-name, next, previous, up +@subsection @kbd{tab} +@kindex tab +@cindex Command Line Completion +@cindex Completion, Command +@cindex Command Completion + +@kbd{tab} + +Pressing the tab key will complete the token under the point, if at all +possible. If the point is over the first token, then a command +completion will be attempted. If it is over any other token, a +completion will be attempted, based on the arguments that the command +takes. If only a partial completion is possible, the token is completed +as far as it can be, and all of the matching completions are printed +out. If no completion is possible, the program just beeps. + + +@node Command Overview, Input and Output, The Command Line, Top +@comment node-name, next, previous, up +@chapter Command Overview +@cindex Commands +@cindex Command Overview + +These are descriptions of all of the commands. Some commands are +documented elsewhere, so for them, there will be only a short +description. + +@menu +* alias:: Assign a different name to a command. +* capture:: Capture incoming data to a file or a register. +* clear:: Clear the input window. +* close:: Close an open serial port. +* help:: Get help on a command. +* open:: Open a serial port. +* out:: Write format controlled data to the serial port. +* print:: Print the contents of a file or a register. +* quit:: Quit the program. +* set:: Change the behavior of the program. +* unalias:: Remove an alias. +@end menu + + +@node alias, capture, Command Overview, Command Overview +@comment node-name, next, previous, up +@section @code{alias} +@findex alias, Command +@cindex Aliasing Command Names +@cindex Renaming Commands + +@code{alias} + +Invoking @code{alias} with no arguments will print out all of the +aliases which have been assigned. + +@code{alias} @var{alias} + +The @code{alias} command with one argument will print out the alias and +the command to which it is aliased. + +@code{alias} @var{alias} @var{command} + +With two options, @code{alias} will assign @var{alias} to @var{command} +so that when @var{alias} is entered, the program will act as if +@var{command} itself had been entered. + +This command can be very useful to decrease the amount of typing +necessary. If, for example, the @code{out} (@pxref{out}) command were to +be aliased to @code{o}, then rather than typing + +@example +out foo bar\n +@end example + +@noindent +it would be possible to merely type + +@example +o foo bar\n +@end example + +@noindent +which doesn't save that much typing, but does illustrate the point. + +However, @code{alias} is limited to aliasing commands only, so it is not +possible to type something like + +@example +alias bin 'set if bin' +@end example + +Also see @ref{unalias}. + + +@node capture, clear, alias, Command Overview +@comment node-name, next, previous, up +@section @code{capture} + +@code{capture} @option{file} @file{filename} + +When invoked in this manner, @code{capture} starts capturing data +recieved from the serial port to @file{filename}. Only one file may be +open at a time. + +@code{capture} @option{file} @option{off} + +This causes @code{Tap} to stop capturing data and to close the file. + +@code{capture} @option{register} @option{1--64} + +@code{capture}, when invoked like this, will cause @code{Tap} to start +capturing data to a register. Data is captured until it is turned off, +as described below, or the register is full. The size of the registers +may be changed by using the command @code{set}. + +@code{capture} @option{register} @option{off} + +This stops the capturing to the register. + + +@xref{set}, and @ref{The Set Command}. + +@node clear, close, capture, Command Overview +@comment node-name, next, previous, up +@section @code{clear} + +@code{clear} + +Invoking clear will clear the input window. + +@xref{C-L}. + + +@node close, help, clear, Command Overview +@comment node-name, next, previous, up +@section @code{close} + +@code{close} + +This command closes the currently open serial port. + + +@node help, open, close, Command Overview +@comment node-name, next, previous, up +@section @code{help} + +@code{help} + +When invoked without a command name, @code{help} prints a short +description of every command. + +@code{help} @option{command name} + +This provides help on individual commands. + + +@node open, out, help, Command Overview +@comment node-name, next, previous, up +@section @code{open} + +@code{open} @option{serial port} + +@code{open} opens a serial port and prepares it for communication. The +properties of the serial port may be changed with the command +@code{set}. + +@xref{set}. + + +@node out, print, open, Command Overview +@comment node-name, next, previous, up +@section @code{out} + +@code{out} @option{data} + +The @code{out} command writes data to the serial port. + +@xref{Input and Output}. + + +@node print, quit, out, Command Overview +@comment node-name, next, previous, up +@section @code{print} + +@code{print} @option{file} + +If a file is currently being captured to, this will print the contents +of that file. If no file is open, then an error will be thrown. + +@code{print} @option{file} @file{filename} + +This prints the contents of the file specified in @file{filename}. + +@code{print} @option{file} @file{filename} @option{bytes} + +This does the same as above, but only prints the first @option{bytes} +number of bytes. + +@code{print} @option{register} + +If a register is currently being captured to, this will print its +contents. If one isn't being used, then an error will be thrown. + +@code{print} @option{register} @option{register number} + +This will print the contents of the register specified. + +@code{print} @option{register} @option{register number} @option{bytes} + +This will print the first @option{bytes} number of bytes of the +specified register. + + +@node quit, set, print, Command Overview +@comment node-name, next, previous, up +@section @code{quit} + +@code{quit} + +This command quits the program, closing any open files and the serial +port, if one is open. + + +@node set, unalias, quit, Command Overview +@comment node-name, next, previous, up +@section @code{set} + +@code{set} @option{options} + +The @code{set} command adjusts various run time parameters of +@code{Tap}. @xref{The Set Command}, for a full explanation. + + +@node unalias, , set, Command Overview +@comment node-name, next, previous, up +@section @code{unalias} + +@code{unalias} @option{alias} + +The @code{unalias} command removes the alias @option{alias} from the +alias list. + + +@node Input and Output, The Set Command, Command Overview, Top +@comment node-name, next, previous, up +@chapter Input and Output + + + +@node The Set Command, Index, Input and Output, Top +@comment node-name, next, previous, up +@chapter The Set Command + +Often, while working with @code{Tap}, you will find that you might want +to change some of the operational parameters. + +@node Index, , The Set Command, Top +@comment node-name, next, previous, up +@unnumbered Command, Concept, and Keystroke Index + +@printindex cp + +@contents +@bye |