diff options
Diffstat (limited to 'man/3')
| -rw-r--r-- | man/3/0intro | 69 | ||||
| -rw-r--r-- | man/3/INDEX | 54 | ||||
| -rw-r--r-- | man/3/arch | 63 | ||||
| -rw-r--r-- | man/3/audio | 169 | ||||
| -rw-r--r-- | man/3/boot | 41 | ||||
| -rw-r--r-- | man/3/cap | 92 | ||||
| -rw-r--r-- | man/3/cmd | 273 | ||||
| -rw-r--r-- | man/3/cons | 312 | ||||
| -rw-r--r-- | man/3/dbg | 384 | ||||
| -rw-r--r-- | man/3/draw | 816 | ||||
| -rw-r--r-- | man/3/ds | 145 | ||||
| -rw-r--r-- | man/3/dup | 60 | ||||
| -rw-r--r-- | man/3/dynld | 75 | ||||
| -rw-r--r-- | man/3/eia | 136 | ||||
| -rw-r--r-- | man/3/env | 48 | ||||
| -rw-r--r-- | man/3/ether | 134 | ||||
| -rw-r--r-- | man/3/flash | 157 | ||||
| -rw-r--r-- | man/3/floppy | 52 | ||||
| -rw-r--r-- | man/3/fpga | 97 | ||||
| -rw-r--r-- | man/3/fs | 114 | ||||
| -rw-r--r-- | man/3/ftl | 185 | ||||
| -rw-r--r-- | man/3/gpio | 94 | ||||
| -rw-r--r-- | man/3/i2c | 87 | ||||
| -rw-r--r-- | man/3/i82365 | 41 | ||||
| -rw-r--r-- | man/3/indir | 81 | ||||
| -rw-r--r-- | man/3/ip | 944 | ||||
| -rw-r--r-- | man/3/kprof | 88 | ||||
| -rw-r--r-- | man/3/logfs | 260 | ||||
| -rw-r--r-- | man/3/lpt | 51 | ||||
| -rw-r--r-- | man/3/mnt | 84 | ||||
| -rw-r--r-- | man/3/mpeg | 102 | ||||
| -rw-r--r-- | man/3/pbus | 60 | ||||
| -rw-r--r-- | man/3/pipe | 69 | ||||
| -rw-r--r-- | man/3/plap | 136 | ||||
| -rw-r--r-- | man/3/pnp | 150 | ||||
| -rw-r--r-- | man/3/pointer | 80 | ||||
| -rw-r--r-- | man/3/prof | 93 | ||||
| -rw-r--r-- | man/3/prog | 311 | ||||
| -rw-r--r-- | man/3/root | 45 | ||||
| -rw-r--r-- | man/3/rtc | 60 | ||||
| -rw-r--r-- | man/3/sd | 194 | ||||
| -rw-r--r-- | man/3/sign | 92 | ||||
| -rw-r--r-- | man/3/snarf | 29 | ||||
| -rw-r--r-- | man/3/srv | 88 | ||||
| -rw-r--r-- | man/3/srv9 | 108 | ||||
| -rw-r--r-- | man/3/ssl | 137 | ||||
| -rw-r--r-- | man/3/switch | 28 | ||||
| -rw-r--r-- | man/3/tinyfs | 45 | ||||
| -rw-r--r-- | man/3/tls | 276 | ||||
| -rw-r--r-- | man/3/touch | 138 | ||||
| -rw-r--r-- | man/3/tv | 179 | ||||
| -rw-r--r-- | man/3/usb | 143 | ||||
| -rw-r--r-- | man/3/vga | 247 | ||||
| -rw-r--r-- | man/3/vid | 64 |
54 files changed, 8080 insertions, 0 deletions
diff --git a/man/3/0intro b/man/3/0intro new file mode 100644 index 00000000..e379f9af --- /dev/null +++ b/man/3/0intro @@ -0,0 +1,69 @@ +.TH INTRO 3 +.SH NAME +intro \- introduction to the Inferno devices +.SH DESCRIPTION +An Inferno +.I device +implements a file tree for client processes. +A file name beginning with a hash (number) symbol, such as +.LR #c , +names the root of a file tree implemented by +a particular +.IR "kernel device driver" +identified by the character after the hash. +Such names are usually bound to conventional locations +in the name space. +For example, after +.IP +.EX +sys->bind("#c", "/dev", sys->MREPL) +.EE +.LP +an +.IR ls (1) +of +.B /dev +will list the files provided by the +.I console +device. +.PP +A kernel device driver is a +.I server +in the sense of the Inferno File Protocol, Styx (see Section 5), +but with the messages implemented by local +rather than remote procedure calls. +Also, several of the messages +.RI ( Nop , +.IR Flush , +and +.IR Error ) +have no subroutine equivalents. +.PP +When a system call is passed a file name beginning with +.L "#" +it looks at the next character, and if that is a valid +.I device character +it performs an +.IR attach (5) +on the corresponding device to get a channel representing the +root of that device's file tree. +If there are any characters after the device character but +before the next +.L "/" +or end of string, those characters are passed as parameter +.I aname +to the attach. +.PP +Each kernel device has a conventional place at which to be bound +to the name space. +The +.I SYNOPSIS +sections of the following pages includes a shell +.I bind +command to put the device in the conventional place. +Most of these binds are done automatically by the system when it initializes; +see +.IR init (8). +.SH SEE ALSO +.IR intro (5), +.IR intro (2) diff --git a/man/3/INDEX b/man/3/INDEX new file mode 100644 index 00000000..82bda96c --- /dev/null +++ b/man/3/INDEX @@ -0,0 +1,54 @@ +intro 0intro +arch arch +audio audio +boot boot +cap cap +cmd cmd +cons cons +dbg dbg +draw draw +ds ds +dup dup +dynld dynld +eia eia +env env +ether ether +flash flash +floppy floppy +fpga fpga +fs fs +ftl ftl +gpio gpio +i2c i2c +i82365 i82365 +indir indir +ip ip +kprof kprof +logfs logfs +lpt lpt +mnt mnt +mpeg mpeg +pbus pbus +pipe pipe +plap plap +pci pnp +pnp pnp +pointer pointer +prof prof +prog prog +root root +rtc rtc +sd sd +sign sign +snarf snarf +srv srv +srv9 srv9 +ssl ssl +switch switch +tinyfs tinyfs +tls tls +touch touch +tv tv +usb usb +vga vga +vid vid diff --git a/man/3/arch b/man/3/arch new file mode 100644 index 00000000..ffb03c69 --- /dev/null +++ b/man/3/arch @@ -0,0 +1,63 @@ +.TH ARCH 3 x86 +.SH NAME +arch \- x86 architecture-specific information and control +.SH SYNOPSIS +.nf +.B bind -a #P /dev + +.B /dev/cputype +.B /dev/ioalloc +.B /dev/iob +.B /dev/iol +.B /dev/iow +.B /dev/irqalloc +.SH DESCRIPTION +This device presents textual information about PC hardware and allows +user-level control of the I/O ports on x86-class machines. +.PP +Reads from +.I cputype +recover the processor type and clock rate. +.PP +Reads from +.I ioalloc +return I/O ranges used by each device, one line +per range. Each line contains three fields separated by white space: first address +in hexadecimal, +last address, name of device. +.PP +Reads from +.I irqalloc +return the enabled interrupts, one line per +interrupt. Each line contains three fields separated by white space: +the trap number, the IRQ it is assigned to, and the name of +the device using it. +.PP +Reads and writes to +.IR iob , +.IR iow , +and +.I iol +cause 8-bit wide, 16-bit wide, and 32-bit wide requests to +I/O ports. +The port accessed is determined by the byte offset of the +file descriptor. +.SH EXAMPLE +The following Limbo code reads from an x86 byte I/O port. +.IP +.EX +inportb(port: int): byte +{ + data := array[1] of byte; + + if(iobfd == nil) + iobfd = sys->open("#P/iob", Sys->ORDWR); + + sys->seek(iobfd, port, 0); + if(sys->read(iobfd, data, len data) != len data) + fatal(sys->sprint("inportb(16r%4.4x): %r\en", port)); + return data[0]; +} +.EE +.SH SOURCE +.B /os/pc/devarch.c diff --git a/man/3/audio b/man/3/audio new file mode 100644 index 00000000..17d9aa3e --- /dev/null +++ b/man/3/audio @@ -0,0 +1,169 @@ +.TH AUDIO 3 +.SH NAME +audio \- digital audio input and output +.SH SYNOPSIS +.B bind -a '#A' /dev +.PP +.B /dev/audio +.br +.B /dev/audioctl +.SH DESCRIPTION +The +.I audio +device serves a one-level directory containing two files, +giving access to the host or native audio device in a platform-independent way. +.PP +.B Audio +is the data file, which can be read or written to exchange data with the device. Audio +data is a sequence of stereo samples, left sample first, each of which is a 16 bit little-endian +two's complement integer. +.PP +.B Audioctl +is the associated control file, which sets the characteristics of the device. +Reads return lines of the form +.TP +.B "\fIsource\fP [in out] \fIvalue\fP" +.TP +.B "\fIsource\fP in \fIvalue\fP out \fIvalue\fP" +.TP +.B "\fIsource\fP [in out] left \fIvalue\fP right \fIvalue\fP" +.TP +.B "\fIsource\fP in left \fIvalue\fP right \fIvalue\fP out left \fIvalue\fP right \fIvalue\fP" +The qualifiers +.BR in , +.B out +and +.BR left , +.B right +are omitted if they +are not applicable or if the input/output and/or left/right values are +the same. +The +.I source +is one of +.BR audio , +.BR aux1 , +.BR aux2 , +.BR line , +.BR mono , +.BR mic , +.BR rate , +.B chans +or +.BR bits . +If +.I source +is one of the ports +.BR audio , +.BR aux1 , +.BR aux2 , +.BR line , +.B mono +or +.BR mic , +.I value +represents +the volume +on a scale of 0 (quiet) to 100 (loud). The default volume is 50 for the +.B audio +port and 0 for the +remainder. If the +.I source +is +.BR rate , +.I value +represents the +rate at which the data was recorded in Hz. The default is 22050. +If the +.I source +is +.BR chans , +.I value +is the number of channels of audio data - 2 (the default) for stereo, otherwise mono. If the +.I source +is +.BR bits , +.I value +is one of 4, 8 or 16, the sample size in bits. +.TP +.B [in out] enc \fIformat\fP +Outputs the recording format on the input and/or output channels. +.I Format +is one of +.BR ulaw , +.BR alaw , +.BR pcm , +.B pcm16 +or +.B adpcm +.TP +.B loop \fIvalue\fP +.I Value +is 0 or 1 to disable or enable loopback respectively. +.PP +Writes control the device with strings of a similar format as that for reads. +.TP +.B "\fIsource\fP [in out] \fIvalue\fP" +.TP +.B "\fIsource\fP in \fIvalue\fP out \fIvalue\fP" +.TP +.B "\fIsource\fP [in out] left \fIvalue\fP right \fIvalue\fP" +.TP +.B "\fIsource\fP in left \fIvalue\fP right \fIvalue\fP out left \fIvalue\fP right \fIvalue\fP" +Set the corresponding value/volume for the particular +.I source. +The same conventions apply +as in the read case above. The default value of +.I source +is +.BR audio . +.TP +.B reset +Set all attributes to their default value. +.TP +.B loop \fIvalue\fP +Enable (1) or disable (0) loopback mode. +.TP +.B [in out] enc \fIformat\fP +Set the recording format on the input and/or output channels to +.I format. +.I Format +is one of +.BR ulaw , +.BR alaw , +.BR pcm , +.BR adpcm . +.TP +.B [left right] dev \fIinput\fP +Set the input source of the left and/or right ADCs. +.I Input +is one of +.BR mic , +.BR line , +.BR aux1 , +.BR loop . +.SH SOURCE +.B /emu/port/devaudio*.c +.br +.B /emu/*/devaudio.c +.br +.B /os/*/devaudio.c +.br +.B /os/*/devcs4231.c +.SH SEE ALSO +.IR auplay (1) +.br +.IR audio (6) +.SH BUGS +The device has not been implemented on every platform that could provide it, +particularly hosted implementations. +.br +.B /os/port/devaudio.c +(a driver for the SB16) implements an older interface of broadly similar form, +but using +.B volume +not +.BR audioctl , +and supports a subset of the commands described above. +.br +The device is exclusive-use and cannot mix streams from several clients. diff --git a/man/3/boot b/man/3/boot new file mode 100644 index 00000000..cc9ea36a --- /dev/null +++ b/man/3/boot @@ -0,0 +1,41 @@ +.TH BOOT 3 +.SH NAME +boot \- reboot under program control +.SH SYNOPSIS +.B bind -a #B /dev +.PP +.B /dev/boot +.br +.B /dev/kexec +.br +.B /dev/mem +.SH DESCRIPTION +.I Boot +serves a directory containing three files that control a reboot of the system. +The files can only be opened by the host owner +(see +.IR eve (10.2)). +.PP +.B Boot +is a write-only file that accepts 4 bytes representing a kernel address, high-order byte first. +The system will transfer control to that address, which is assumed to be the start of low-level reboot code. +There is no return from the write on success or failure. +.PP +.B Kexec +is a write-only file to which an uncompressed kernel image can be written, a chunk at a time. +When the file is closed, the system will transfer control to the start of the image, which again +is assumed to be low-level reboot code. +.PP +.B Mem +copies data to and from kernel memory, taking the current file offset as an address therein. +.PP +.I Boot +flushes caches as necessary to ensure that writes to kernel memory through any +of these files will be visible when subsequently executed as instructions. +.SH SOURCE +.B /os/port/devboot.c +.SH SEE ALSO +.IR tftp (2), +.IR cons (3) +.SH DIAGNOSTICS +Invalid addresses are diagnosed, but otherwise there is no error return. diff --git a/man/3/cap b/man/3/cap new file mode 100644 index 00000000..afd7ef3d --- /dev/null +++ b/man/3/cap @@ -0,0 +1,92 @@ +.TH CAP 3 +.SH NAME +cap \- capability for changing user name +.SH SYNOPSIS +.BI "bind #¤ " dir +.PP +.IB dir /caphash +.br +.IB dir /capuse +.SH DESCRIPTION +.I Cap +allows a process owned by the host owner (see +.IR eve (10.2)) +to give another process on the same machine +a capability to set its user name to a specified user. +The capability is a string of the form: +.IP +[ +.IB fromuser @ +] +.IB touser @ key +.PP +where +.I fromuser +is a process's current user name, +.I touser +is its new user name, and +.I key +is a string of random characters +(eg, produced by +.IR security-random (2)). +.PP +.B Caphash +is a write-only file that can only be opened by the host owner. +A process enables the use of a capability by writing the keyed hash of +.IB fromuser @ touser +to +.BR caphash . +The hash is computed using +.B Keyring->hmac_sha1 +as follows: +.IP +.EX +kr := load Keyring Keyring->PATH; +IPint: import kr; +users := sys->sprint("%s@%s", fromuser, touser); +cap := sys->sprint("%s@%s", users, key); +digest := array[Keyring->SHA1dlen] of byte; +ausers := array of byte users; +kr->hmac_sha1(ausers, len ausers, array of byte key, digest, nil); +if(sys->write(caphashfd, digest, len digest) < 0) + error(); +.EE +.PP +The capability (eg, +.B cap +in the example) +can then be passed to another process. +.PP +.B Capuse +is a write-only file that can be opened by any process. +It can then write a capability string to change its user name, +provided that capability has previously been enabled by the host owner via +.BR caphash , +and if the capability included a +.IR fromuser , +the writing process currently has that user name. +After a successful write, the writing process will be owned by +.IR touser . +Any capability can be used at most once. +.PP +A capability enabled by +.B caphash +has a limited lifetime, on the order of 30 seconds. +.B Caphash +can be removed by the host owner to prevent its further use. +.SH SOURCE +.B /emu/port/devcap.c +.br +.B /os/port/devcap.c +.SH SEE ALSO +.IR keyring-sha1 (2), +.IR cons (3), +.IR intro (5), +.IR eve (10.2) +.SH DIAGNOSTICS +A write to +.B capuse +without a previous write to +.B caphash +sets the error string to +.RB `` "invalid capability" ''. diff --git a/man/3/cmd b/man/3/cmd new file mode 100644 index 00000000..83b4e245 --- /dev/null +++ b/man/3/cmd @@ -0,0 +1,273 @@ +.TH CMD 3 hosted +.SH NAME +cmd \- interface to host operating system commands +.SH SYNOPSIS +.B bind -a '#C' / +.PP +.B /cmd/clone +.br +.BI /cmd/ n /ctl +.br +.BI /cmd/ n /data +.br +.BI /cmd/ n /status +.br +.BI /cmd/ n /wait +.SH DESCRIPTION +.I Cmd +provides a way to run commands in the underlying operating system's +command interpreter when Inferno is running hosted, in +.IR emu (1). +It serves a three-level directory that is conventionally bound +behind the root directory. +The top of the hierarchy is a directory +.BR cmd , +that contains a +.B clone +file and zero or more numbered directories. +Each directory represents a distinct connection to the host's command interpreter. +The directory contains four files: +.BR ctl , +.BR data , +.B status +and +.BR wait , +used as described below. +Opening the +.B clone +file reserves a connection: it is equivalent to opening the +.B ctl +file of an unused connection directory, creating a new one if necessary. +.PP +The file +.B ctl +controls a connection. +When read, it returns the decimal number +.I n +of its connection directory. +Thus, opening and reading +.B clone +allocates a connection directory and reveals the number of the allocated directory, +allowing the other files to be named (eg, +.BI /cmd/ n /data\fR). +.PP +.B Ctl +accepts the following textual commands, allowing quoting as interpreted by +.IR parsecmd (10.2): +.TP +.BI "dir " wdir +Run the host command in directory +.IR wdir , +which is a directory +.I "on the host system" . +Issue this request before starting the command. +By default, commands are run in the Inferno root directory on the host system. +.TP +.BI "exec " "command args ..." +Spawn a host process to run the +.I command +with arguments as given. +The write returns with an error, setting the error string, if anything prevents +starting the command. +If write returns successfully, the command has started, and its input and +output may be accessed through +.B data +(see below). +If arguments containing white space are quoted (following the conventions of +.IR sh (1) +or +.IR parsecmd (10.2)), +they are requoted by +.I cmd +using the host command interpreter's conventions so that +.I command +sees exactly the same arguments as were written to +.BR ctl . +.TP +.B kill +Kill the host command immediately. +.TP +.B killonclose +Set the device to kill the host command when the +.B ctl +file is closed (normally all files must be closed, see below). +.TP +.BI nice " \fR[\fPn\fR]\fP" +Run the host command at less than normal scheduling priority. +Issue this request before starting the command. +The optional value +.IR n , +in the range 1 to 3, +indicates the degree of `niceness' (default: 1). +.PP +The +.B data +file provides a connection to the input and output of a previously-started +host command. +It must be opened separately for reading and for writing. +When opened for reading, it returns data that the command writes to its standard output and standard error (the +streams are merged); when closed, further writes by the command will receive the host +equivalent of `write to closed pipe'. +When opened for writing, data written to the file +can be read by the command on its standard input; when closed, further reads by +the command will see the host equivalent of `end of file'. +(Unfortunately there is no way to know when the command needs input.) +.PP +Once started, a host command runs until it terminates or until it is killed, +by using the +.B kill +or +.B killonclose +requests above, or by closing all +.BR ctl , +.B data +and +.B wait +files for a connection. +.PP +The read-only +.B status +file provides a single line giving the status of the connection (not the command), of the form: +.IP +.BI cmd/ "n opens state wdir arg0" +.PP +where the fields are separated by white space. The meaning of each field is: +.TP +.I n +The +.B cmd +directory number. +.TP +.I opens +The decimal number of open file descriptors for +.BR ctl , +.B data +and +.BR wait . +.TP +.I state +The status of the interface in directory +.IR n : +.RS +.TF Execute +.TP +.B Open +Allocated for use but not yet running a command. +.TP +.B Execute +Running a command. +.TP +.B Done +Command terminated: status available in the +.B status +file (or via +.BR wait ). +.TP +.B Close +Command completed. Available for reallocation via +.BR clone . +.RE +.PD +.TP +.I wdir +The command's initial working directory on the host. +.TP +.I arg0 +The host command name (without arguments). +.PP +The read-only +.B wait +file must be opened before starting a command via +.BR ctl . +When read, it blocks until the command terminates. +The read then returns with a single status line, to be +parsed using +.B String->unquote +(see +.IR string (2)). +There are five fields: +host process ID (or 0 if unknown); +time the command spent in user code in milliseconds (or 0); +time spent in system code in milliseconds (or 0); +real time in milliseconds (or 0); +and a string giving the exit status of the command. +The exit status is host-dependent, except that an empty string +means success, and a non-empty string contains a diagnostic. +.PP +.SS "Command execution" +In all cases, the command runs in the host operating system's +own file name space +in which +.IR emu (1) +was started. +All file names will be interpreted in that space, not Inferno's. +For example, on Unix and Plan 9, +.B / +refers to the host's file system root, not Inferno's; +the effects of mounts and binds will not be visible; +nor will Inferno services be available except by network connection. +.PP +On Unix systems, +the command is run by the +.B execvp +system call, +using the Unix user and group ID of +the user that started +.IR emu (1), +unless it was started by the super-user, in which case +.I cmd +attempts to set the Unix user ID and group ID to those of a Unix user corresponding to +the current Inferno user's name, and failing that, to user and group +.BR nobody . +.PP +On Plan 9, +the command is run with the system call +.BR exec , +first trying the +.I command +name as-is; +if that fails and the name does not start with +.BR # , +.BR / , +.B ./ +or +.BR ../ , +.I cmd +attempts to exec +.BI /bin/ command. +The command runs using the Plan 9 identity of +the user that started +.IR emu (1). +Each connection has its own name space. +.PP +On Windows systems, +the command must be a binary executable (not built into the command interpreter) in the current path. +It is always run with the same Windows user identity as started +.IR emu (1). +The arguments given to the +.B exec +request are requoted as described above so as to present the same +arguments to the command via the Windows command interpreter. +The arguments are otherwise unmodified. +In particular, no attempt is made to convert slashes to backslashes in a vain +attempt to convert file name syntax to Windows conventions. +(In fact, most Windows applications will accept +.B / +as a separate in file names, provided the drive letter precedes the whole +name to prevent its interpretation as a command option.) +.SH SOURCE +.B /emu/port/devcmd.c +.br +.B /emu/*/cmd.c +.SH "SEE ALSO" +.IR emu (1), +.IR os (1) +.SH BUGS +Standard output and standard error ideally should not be mingled. +.SH DIAGNOSTICS +A +.B write +to +.B ctl +returns with an error and sets the error string if +a command cannot be started or killed successfully. diff --git a/man/3/cons b/man/3/cons new file mode 100644 index 00000000..dacd73dd --- /dev/null +++ b/man/3/cons @@ -0,0 +1,312 @@ +.TH CONS 3 +.SH NAME +cons \- console device +.SH SYNOPSIS +.nf +.B bind #c /dev + +.B /dev/cons +.B /dev/consctl +.B /dev/drivers +.B /dev/jit +.B /dev/keyboard +.B /dev/klog +.B /dev/kprint +.B /dev/memory +.B /dev/msec +.B /dev/null +.B /dev/notquiterandom +.B /dev/pin +.B /dev/pointer +.B /dev/random +.B /dev/scancode +.B /dev/sysctl +.B /dev/sysname +.B /dev/time +.B /dev/user +.fi +.SH DESCRIPTION +The console device serves a one-level directory +giving access to the console and +miscellaneous information. +.PP +Reading the +.B cons +file returns characters typed on the keyboard. +Normally, characters are buffered to enable erase and kill processing. +A control-U, +.LR ^U , +typed at the keyboard +.I kills +the current input line (removes all characters +from the buffer of characters +not yet read via +.BR cons ), +and a backspace +.I erases +the previous non-kill, non-erase character from the input buffer. +Killing and erasing only delete characters back to, but not including, +the last newline. +Typed keystrokes produce 16-bit characters +that are translated into the variable-length +.SM UTF +encoding (see +.IR utf (6)) +before putting them into the buffer. +A +.B read +of length greater than zero causes the process to wait until a +newline or a +.L ^D +ends the buffer, and then returns as much of the buffer as the argument +to +.B read +allows, but only up to one complete line. +A terminating +.L ^D +is not put into the buffer. +If part of the line remains, the next +.B read +will return bytes from that remainder and not part of any new line +that has been typed since. A single line containing a +.L ^D +can be used as an end of file indication to programs that take interactive input. +.PP +If +the string +.B rawon +has been written to the +.B consctl +file and the file is still open, +.B cons +is in +.IR "raw mode" : +characters are not echoed as they are typed, +backspace and +.L ^D +are not treated specially, +and characters are available to +.B read +as soon as they are typed. +Ordinary mode is reentered when +.B rawoff +is written to +.B consctl +or this file is closed. +.PP +A +.B write +to +.B cons +causes the characters to be printed on the console screen. +.PP +The +.B keyboard +file returns the underlying tokens produced by the keyboard hardware as they +are produced; in the emulation environment, it is like an always-raw +.B cons +file. +.PP +The +.B null +file throws away anything written to it +and always returns zero bytes when read. +.PP +The +.B klog +file +returns the tail of messages written by the native kernel debugging function +.B kprint +(mainly used when debugging interrupt handlers in device drivers). +It is available only in native kernel implementations. +.PP +The +.B kprint +file +returns console output: messages written by kernel print statements and messages +written by processes to this driver's +.B cons +file. +Until +.B kprint +is opened, system console output is handled normally. +Once +.B kprint +has been opened, +if the machine's console is a serial line, the data is sent both to +the serial console and to +.BR kprint ; +if the console is a graphics screen, the data is sent only to +.BR kprint . +.PP +A read of the +.B pointer +file returns the status of the mouse or other pointing device: +its position and button state. +The read blocks until the state has changed since the last read. +The read returns 49 bytes: the letter +.B m +followed by four fields containing decimal integers, each 11 characters wide followed by a blank. +The integers are: x and y, +coordinates of the pointer on the screen; a bit mask with the +1, 2, and 4 bits when the pointer's left, middle, and right +buttons, respectively, are down; and a time stamp in units of milliseconds. +.PP +Writing to the +.B pointer +file, using the same format, +causes the pointer to move to the specified x, y position +(the button and millisecond fields are ignored, and optional). +If there is a visible image representing the pointer's position, +that will move too. +.PP +The +.B pin +file, when read, returns either the string +.B "no pin +if no PIN has been set for authentication, or +.B "pin set +if one has. +The +.B pin +file may be written once with a decimal representation of the PIN +to use on this Inferno machine. +.PP +The +.B random +device returns as many bytes of random data as are requested in the +.BR read . +.PP +The +.B notquiterandom +device returns as many bytes of pseudo-random data as are requested in the +.BR read ; +this is typically faster than +.B random +but the results are more predictable. +.PP +The +.B scancode +device provides access to the raw scan codes of the primary +.B keyboard . +While it is open, key strokes are diverted from +.B cons +and +.B keyboard . +The first +.IR read (2) +after opening returns an identifier string which defines the format of data delivered +by subsequent +reads. Known ones are defined in +.IR scancode (6). +The most common format is a single byte per scan code, where the top bit is 1 for +up and 0 for down, and the bottom 7 bits are the scan code. Some input devices +have a larger scan code space; in this case scan codes are often delivered as two byte +little endian quantities, where the top bit is the up/down signifier, and the bottom +15 bits are the scan code. In all cases the meaning of the individual scan codes is +device specific. +.PP +The rest of the files contain (mostly) read-only strings. +Each string has a fixed length: a +.I read +(see +.IR sys-read (2)) +of more than that gives a result of that fixed length (the result does not +include a terminating zero byte); +a +.I read +of less than that length leaves the file offset so the +rest of the string (but no more) will be read the next time. +To reread the file without closing it, +.I seek +must be used to reset the offset. +When the file contains numeric data, each number is formatted +in decimal as an 11-digit number with leading blanks and +one trailing blank: twelve bytes total. +.PP +The +.B sysctl +file can be read to return the current Inferno version. Writing the string +.B reboot +to it attempts to reboot the system, writing +.B halt +attempts to halt the system. Writing +.B nobroken +ensures that broken processes have all associated memory freed before +being destroyed, +writing +.B broken +ensures that they are left in this state to allow debugging (the default). +Only the privileged user is allowed to write to this file. +.PP +The +.B sysname +file holds the textual name of the machine. +It can only be written by the privileged user. +.PP +The +.B user +file contains the name of the user associated with the current process. +It can only be written by the privileged user. In the emulation environment, +writing to this file also attempts to set the user id in the host operating +system to the specified value. +.PP +The +.B memory +file returns a formatted presentation of the state of the memory +allocation pools in the system. +Each line of output returned reports, for a single pool, +the amount of memory in use, +the upper size limit, +the high water mark, +the number of allocations done, +the number of frees done, +the number of extensions done, +the largest chunk available +and the name of the pool. +.PP +The +.B drivers +file returns a list of the device drivers loaded in the system. +Each line gives the name of the device for +.IR bind (1), +such as +.BR #c , +followed by the name of the driver as used in the system configuration file. +.PP +The other files served by the +.I cons +device are all single numbers: +.TP +.B jit +non-zero if `just in time' compilation is configured (can be written to change the state). Writing 0 turns off JIT compilation, 1 turns it on and larger values give increasingly +detailed traces of the compilation for debugging purposes. +.TP +.B msec +the value of a millisecond counter +.TP +.B time +number of microseconds since the epoch 00:00:00 GMT, Jan. 1, 1970. +(Can be written once by the privileged user, to set at boot time.) +.SH SOURCE +.B /emu/port/devcons.c +.br +.B /os/port/devcons.c +.SH SEE ALSO +.IR draw (3), +.IR keyboard (6), +.IR utf (6), +.IR eve (10.2) +.SH BUGS +For debugging, on native systems only, +two control-T's followed by a letter +generate console output: +.L ^T^Tp +prints data about kernel processes, +.L ^T^Ts +prints the kernel stack, +.L ^T^Tx +prints data about memory allocation. +.PP +The system can be rebooted by typing +.LR ^T^Tr . diff --git a/man/3/dbg b/man/3/dbg new file mode 100644 index 00000000..ce91144f --- /dev/null +++ b/man/3/dbg @@ -0,0 +1,384 @@ +.TH DBG 3 +.SH NAME +dbg \- remote kernel debugging +.SH SYNOPSIS +.B "bind -b '#b' /dev" +.PP +.B /dev/dbgctl +.br +.B /dev/dbglog +.PP +.BI "echo r >/dev/dbgctl" +.SH DESCRIPTION +.I Dbg +allows a native kernel to be debugged remotely, +by means of a simple protocol, typically run on a serial port +(see +.IR eia (3)). +The +.IR acid (10.1) +debugger uses the protocol for instance; see its +.B -R +option. +.PP +.I Dbg +uses the values of several global variables set by the kernel configuration file (see +.IR conf (10.6)), +all of which default values. +The variables and default values are listed below: +.IP +.EX +int dbgstart = 0; +char *dbgdata = "#t/eia0"; +char *dbgctl = "#t/eia0ctl"; +char *dbgctlstart = "b19200"; +char *dbgctlstop = "h"; +char *dbgctlflush = "f"; +.EE +.PP +Different values can be set by including similar declarations, +with values as desired, in the +.B code +section of the configuration file. +.I Dbg +uses the values as follows: +.TP \w'\f5dbgctlflushxx\fP'u +.PD 0 +.B dbgstart +if non-zero, start the debugger protocol on the +configured connection during driver initialisation (system startup); +otherwise it must be started explicitly by the +.B r +control request (see below) +.TP +.B dbgdata +data file for the debugging connection +.TP +.B dbgctl +control file for the debugging connection +.TP +.B dbgctlstart +control request to initialise link (eg, baud rate) +.TP +.B dbgctlstop +control request to hang up link +.TP +.B dbgctlflush +control request to write to flush input and output on link +.PD +.PP +.I Dbg +serves two files that control and monitor its operation. +.PP +.B Dbgctl +accepts several textual commands; normally only +.B r +is needed: +.TP +.BI d " dbgdata" +set the value of +.B dbgdata +to the value given as an argument +.TP +.BI c " dbgctl" +.PD 0 +.TP +.BI i " dbgctlstart" +.TP +.BI h " dbgctlstop" +.TP +.BI f " dbgctlflush" +set the value of the corresponding control variable to the value of the first argument +.PD +.TP +.B r +start running the debugger protocol (not needed if +.B dbgstart +was non-zero at boot) +.TP +.B s +stop running the debugger protocol; stop and flush the link +.PP +When read, +.B dbgctl +yields a single line showing the status of the device +.RB (` running ' +or +.RB ` stopped ') +and the current values of the debugger control +variables listed above. +.PP +.B Dbglog +is a read-only text file containing lines representing debugger events, +one per line. +It is mainly useful for checking the operation of the device, or debugging new +.IR acid (10.1) +functions. +.SS Debug protocol +The protocol is subject to change. +The host running the debugger and the target to be debugged +exchange 10-byte messages containing a one byte message type +and 9 bytes of data. +Bytes unused by a given type are set to zero. +Normally the host sends one of the T-messages below and +receives the corresponding R-message, or +.BR Rerr . +(These are unrelated to the T-messages and R-messages of +.IR intro (5).) +Exceptionally, the target sends the first message, an +.B Rerr +to reset the protocol, and thus the debugger is notified if the target +is rebooted during a debugging session and can reset its own state. +Values, including addresses, are sometimes represented textually +in hexadecimal, but are usually in binary as a single byte, or an array of 4 bytes, +high-order byte first (big endian). +.PP +The term +.I process +here refers exclusively to those created directly or indirectly by +.IR kproc (10.2), +not to Limbo processes, which are not visible directly through +the protocol (although it is possible to write +.IR acid (10.1) +functions that interact through +.I dbg +with the Inferno data structures representing +the state of the Dis virtual machine). +Many requests read or write the memory or state of the +.IR "current process" +set by the +.B Tproc +message (see below). +Addresses are always 32 bits. +An address below the size of +.B Ureg +(saved register state) for the target is interpreted as an offset within the saved +state for the current process. +Otherwise it refers to an address in kernel virtual memory. +Currently in native Inferno all processes share the same address space. +.PP +The message type names used below +are assigned values by declarations in +.BR /include/rdbg.h . +The following messages are currently implemented: +.TP \w'Tstart'u +.PD 0 +.B Terr +unused +.TP +.BI Rerr " reason\fR[9]\fR" +The last message failed for the given +.IR reason , +a text string: +.BR reset , +the target or debug driver was restarted; +.BR count , +bad count; +.BR unk , +unknown command; +.BR inval , +invalid parameter; +.BR pid , +no such process; +.BR unsup , +unsupported action; +.BR notstop , +action requires process to be stopped first. +.TP +.BI Tmget " addr\fR[4]\fP n\fR[1]\fP" +Request +.I n +bytes of memory from +.IR addr ; +.I n +must be no greater than 9 +.TP +.BI Rmget " data\fR[9]\fP" +Return +.I data +requested by +.B Tmget +.TP +.BI Tmput " addr\fR[4]\fP n\fR[1]\fP data\fR[4]\fP" +Write the first +.I n +bytes of +.I data +to memory at +.IR addr , +and flush the data and instruction caches for that region; +.I n +must be no greater than 4 +.TP +.BI Rmput +Reply to a successful +.B Tmput +.TP +.BI Tproc " pid\fR[4]\fP" +Set the current process to the one with integer process ID +.I pid +for subsequent requests. +.TP +.BI Rproc " addr\fR[8]\fP" +.I Addr +is the address in hexadecimal text of the +.B Proc +structure for process +.I pid +in the corresponding +.BR Tproc . +.TP +.BI Tstatus " pid\fR[4]\fP" +Request the status of process +.I pid +leaving the current process ID unchanged. +.TP +.BI Rstatus " status\fR[9]\fP" +Return the textual status of the process +as a text string, currently one of: +.BR Dead , +.BR Moribund , +.BR Ready , +.BR Scheding , +.BR Running , +.BR Queueing , +.BR Wakeme , +.BR Broken , +.BR Stopped , +.BR Rendezvous , +or if invalid, the state value as a hexadecimal number. +.TP +.BI Trnote " pid\fR[4]\fP" +Retrieve the note (trap status) for the given +.I pid +.TP +.BI Rrnote " status\fR[9]\fP" +Provide the textual trap +.I status +for the requested process (currently always returns null status) +.TP +.BI Tstop " pid\fR[4]\fP" +Tell the kernel to stop running process +.I pid +in debugging state +.B Stopped +when it next appears in the scheduler. +.TP +.BI Rstop +Reply to successful +.B Tstop +.TP +.BI Tstart +Cancel a previous +.BR Tstop ; +if the process has already stopped, make it ready to run. +.TP +.BI Rstart +Reply to successful +.B Tstart +.TP +.BI Tcondbreak " val\fR[4]\fP op\fR[4]\fP" +If +.I op +is +.BR d , +remove and delete the breakpoint with ID +.IR val . +All other operations help +create a conditional breakpoint, providing a possibly empty list of operations +representing a conditional expression in Reverse Polish is followed +by a breakpoint request, +each expression element represented by a single +.B Tcondbreak +message. +.I Op +is a single character representing an operation, with +.I val +(integer, address, process ID) as a parameter. +The operator +.B n +should appear first; it assigns the +breakpoint an ID number +.I val +(no greater than 255). +Expression primaries are: +.BI k " val," +true if process +.I val +is at this breakpoint; +.BI b " val," +true if program counter is +.IR val ; +and +.BI p " val," +.I val +as a 32-bit literal. +Expression operators are: +unary +.B * +(indirect, yielding 32-bit value); +.B & +(bit-wise AND); +.B = +(values equal); +.B ! +(values not equal); +.B a +(logical AND); +.B o +(logical OR). +Although the expression is interpreted following Reverse Polish notation, +when transmitted, the +.B b +operation is sent last (to mark the end of the sequence and create the breakpoint), +but is moved to the start of the expression before evaluation. +.TP +.BI Rcondbreak +Reply to successful +.BR Tcondbreak . +.TP +.BI Tstartstop " pid\fR[4]\fP" +If the process +.I pid +is not stopped, return +.B Rerr +.BR notstop . +Otherwise, if the process is not stopped at +a breakpoint, start it, and wait for it to reach a breakpoint +that evaluates `true' +.TP +.BI Rstartstop " id\fR[1]\fP" +Process has stopped at breakpoint with the given +.I id +.TP +.BI Twaitstop +Unimplemented. See +.BR Tstartstop . +.TP +.BI Rwaitstop +Unused. +.TP +.BI Tkill " pid\fR[4]\fP note\fR[5]\fP" +Kill process +.I pid +with the given textual +.IR note . +Unimplemented. +.TP +.BI Rkill +Reply to successful +.BR Tkill . +Unused. +.PP +.SH SOURCE +.B /os/port/devdbg.c +.br +.B /os/*/*break.c +.br +.B /os/*/trap.c +.SH SEE ALSO +.IR acid (10.1) +.SH BUGS +The protocol is not itself error-detecting let alone error-correcting, although that normally does not +matter for debugging even +over a serial line, provided the connection is reasonably sound. diff --git a/man/3/draw b/man/3/draw new file mode 100644 index 00000000..db909291 --- /dev/null +++ b/man/3/draw @@ -0,0 +1,816 @@ +.TH DRAW 3 +.SH NAME +draw \- screen graphics +.SH SYNOPSIS +.EX +.B bind -a #i /dev + +.B /dev/draw/new + +.BI /dev/draw/ n /ctl +.BI /dev/draw/ n /data +.ig +.BI /dev/draw/ n /colormap +.. +.BI /dev/draw/ n /refresh + +.EE +.SH DESCRIPTION +The +.I draw +device serves a three-level file system +providing an interface to the graphics facilities of the system. +The Limbo Draw module (see +.IR draw-intro (2)) +implements its functions using this device. +Each client of the device connects by opening +.B /dev/draw/new +and reading 12 strings, each 11 characters wide followed by a blank: +the connection number +.RI ( n ), +the image id +.RI ( q.v. ) +of the display image (always zero), +the +channel format +of the image, +the +.BR min.x , +.BR min.y , +.BR max.x , +and +.B max.y +of the display image, +and the +.BR min.x , +.BR min.y , +.BR max.x , +and +.B max.y +of the clipping rectangle. +The channel format string is described in +.IR image (6), +and the other fields are decimal numbers. +.PP +The client can then open the directory +.BI /dev/draw/ n / +to access the +.BR ctl , +.BR data , +.ig +.BR colormap , +.. +and +.B refresh +files associated with the connection. +.PP +Via the +.B ctl +and +.B draw +files, the +.I draw +device provides access to +images and font caches +in its private storage, +as described in +.IR draw-intro (2). +Each image is identified by a 4-byte integer, its +.IR id . +.PP +Reading the +.B ctl +file yields 12 strings formatted as in +.BR /dev/draw/new , +but for the current image rather +than the display image. +The current image may be set by writing a +binary image id to the +.B ctl +file. +.PP +A process can write messages to +.B data +to allocate and free images, fonts, and subfonts; +read or write portions of the images; +and draw line segments and character +strings in the images. +All graphics requests are clipped to their images. +Some messages return a response to be recovered by +reading the +.B data +file. +.PP +The +.B draw +device provides three types of graphical resource: Images, Screens and Fonts. +Resource instances have an identification number. +Screen identifiers are global to the device. +All other identifiers are local to each client. +.PP +Image is the fundamental resource type on which all drawing primitives +are performed. +At client connection the physical display is represented by Image 0. +.PP +A Screen manages a set of (overlapping) Images, handling +Z-order and position manipulation and the refreshing of regions +uncovered by such operations. +When a Screen is created it is associated with an Image on which +to render itself. +New images can be associated with a screen when they are created; they +are then treated as windows on that screen. +Screens can be marked as +.IR public , +meaning that other clients can import their ID and create new windows +on them. +.PP +A Font is an image with associated character data. +The Font image provides the bitmap of all the characters in the +Font; the character data is used by the string command to render +characters from the image. +.SS "Command messages" +.PP +The format of messages written to +.B data +is a single letter +followed by binary parameters; +multibyte integers are transmitted with the low order byte first. +Points are two four-byte numbers: +.IR x , +.IR y . +Rectangles are four four-byte numbers: min +.IR x , +min +.IR y , +max +.IR x , +and max +.IR y . +Images, screens, and fonts have 32-bit identifiers. +In the discussion of the protocol below, +the distinction between identifier and actual image, screen, or font +is not made, so that +``the object +.IR id '' +should be interpreted as +``the object with identifier +.IR id ''. +The definitions of constants used in the description below can be found in +.BR /module/draw.m +or +.BR /include/draw.h . +.PP +The following requests are accepted by the +.B data +file. +The numbers in brackets give the length in bytes of the parameters. +.HP .5i +.B A +.IR id [4] +.IR imageid [4] +.IR fillid [4] +.IR public [1] +.br +Allocate a new +.B Screen +(see +.IR draw-display (2)) +with +screen identifier +.I id +using +backing store image +.IR imageid , +filling it initially +with data from image +.IR fillid . +If the +.I public +byte is non-zero, the screen can +be accessed from other processes +using the +.B publicscreen +interface. +.HP +.B b +.IR id [4] +.IR screenid [4] +.IR refresh [1] +.IR chan [4] +.IR repl [1] +.IR r [4*4] +.IR clipr [4*4] +.IR color [4] +.br +Allocate an image with a given +.I id +on the +screen named by +.IR screenid . +The image will have rectangle +.I r +and clipping rectangle +.IR clipr . +If +.I repl +is non-zero, the image's replicate +bit will be set (see +.IR draw (2)). +.IP +.I Refresh +specifies the method to be used to draw the window +when it is uncovered. +.B Refbackup +causes the server to maintain a backing store, +.B Refnone +does not refresh the image, +and +.B Refmesg +causes a message to be sent via +the +.B refresh +file +.RI ( q.v. ). +.IP +The image format is described by +.IR chan , +a binary version of the channel format string. +Specifically, the image format is the catenation of up to four +8-bit numbers, each describing a particular image channel. +Each of these 8-bit numbers contains a channel type in its +high nibble and a bit count in its low nibble. +The channel type is one of +.BR CRed , +.BR CGreen , +.BR CBlue , +.BR CGrey , +.BR CAlpha , +.BR CMap , +and +.BR CIgnore . +See +.IR image (6). +.IP +.I Color +is the catenation of four 8-bit numbers +specifying the red, green, blue, and alpha +channels of the color that the new image should +be initially filled with. +The red channel is in the highest 8 bits, and +the alpha in the lowest. +Note that color is always in this format, independent of +the image format. +.HP +.B c +.IR dstid [4] +.IR repl [1] +.IR clipr [4*4] +.br +Change the replicate bit and clipping rectangle of the +image +.IR dstid . +This overrides whatever settings were specified in +the allocate message. +.HP +.B d +.IR dstid [4] +.IR srcid [4] +.IR maskid [4] +.IR dstr [4*4] +.IR srcp [2*4] +.IR maskp [2*4] +.br +Use the +.B draw +operator to combine the rectangle +.I dstr +of +image +.I dstid +with a +rectangle of image +.IR srcid , +using a rectangle of image +.IR maskid +as an alpha mask to further control blending. +The three rectangles are congruent and aligned such that +the upper left corner +.I dstr +in image +.I dstid +corresponds to +the point +.I srcp +in image +.I srcid +and +the point +.I maskp +in image +.IR maskid . +See +.IR draw-image (2). +.HP +.B D +.IR debugon [1] +.br +If +.I debugon +is non-zero, enable debugging output. +If zero, disable it. +The meaning of ``debugging output'' is implementation dependent. +.HP +.B e +.IR dstid [4] +.IR srcid [4] +.IR c [2*4] +.IR a [4] +.IR b [4] +.IR thick [4] +.IR sp [2*4] +.IR alpha [4] +.IR phi [4] +.br +Draw an ellipse in image +.I dst +centered on the point +.I c +with horizontal and vertical semiaxes +.I a +and +.IR b . +The ellipse is drawn using the image +.IR src , +with +the point +.I sp +in +.I src +aligned with +.I c +in +.IR dst . +The ellipse is drawn with thickness +.RI 1+2× thick . +.IP +If the high bit of +.I alpha +is set, +only the arc of the ellipse from degree angles +.I alpha +to +.I phi +is drawn. +For the purposes of drawing the arc, +.I alpha +is treated as a signed 31-bit number +by ignoring its high bit. +.HP +.B E +.IR dstid [4] +.IR srcid [4] +.IR center [2*4] +.IR a [4] +.IR b [4] +.IR thick [4] +.IR sp [2*4] +.IR alpha [4] +.IR phi [4] +.br +Draws an ellipse or arc as the +.B e +message, but rather than outlining it, fills +the corresponding sector using the image +.IR srcid . +The +.I thick +field is ignored, but must be non-negative. +.HP +.B f +.IR id [4] +.br +Free the resources associated with the image +.IR id . +.HP +.B F +.IR id [4] +.br +Free the the screen with the specified +.IR id . +Windows on the screen must be freed separately. +.HP +.B i +.IR id [4] +.IR n [4] +.IR ascent [1] +.br +Treat the image +.I id +as a font cache of +.I n +character cells, each with +ascent +.IR ascent . +.HP +.B l +.IR cacheid [4] +.IR srcid [4] +.IR index [2] +.IR r [4*4] +.IR sp [2*4] +.IR left [1] +.IR width [1] +.br +Load a character into the font cache associated with image +.I cacheid +at cache position +.IR index . +The character data is drawn in rectangle +.I r +of the font cache image +and is fetched from +the congruent rectangle in image +.I srcid +with upper left corner +.IR sp . +.I Width +specifies the width of the character\(emthe spacing from this character to the next\(emwhile +.I left +specifies +the horizontal distance from the left side +of the character to the left side of the cache image. +The dimensions of the image of the character are defined by +.IR r . +.HP +.B L +.IR dstid [4] +.IR p0 [2*4] +.IR p1 [2*4] +.IR end0 [4] +.IR end1 [4] +.IR thick [4] +.IR srcid [4] +.IR sp [2*4] +.br +Draw a line of thickness +.RI 1+2× thick +in image +.I dstid +from point +.I p0 +to +.IR p1 . +The line is drawn using the image +.IR srcid , +translated so that point +.I sp +in +.I srcid +aligns with +.I p0 +in +.IR dstid . +The +.I end0 +and +.I end1 +fields specify whether the corresponding +line end should be a square, a disc, +or an arrow head. +See +.I line +in +.IR draw-image (2) +for more details. +.HP +.B N +.IR id [4] +.IR in [1] +.IR j [1] +.IR name [ j ] +.br +If +.I in +is non-zero, associate the image +.I id +with the string +.IR name . +If +.I in +is zero and +.I name +already corresponds to the +image +.IR id , +the association is deleted. +.HP +.B n +.IR id [4] +.IR j [1] +.IR name [ j ] +.br +Introduce the identifier +.I id +to correspond to the image named +by the string +.IR name . +.HP +.B o +.IR id [4] +.IR r.min [2*4] +.IR scr [2*4] +.br +Position the window +.I id +so that its upper left corner is at the +point +.I scr +on its screen. +Simultaneously change its internal (logical) coordinate system +so that the point +.I log +corresponds to the upper left corner of the window. +.HP +.B p +.IR dstid [4] +.IR n [2] +.IR end0 [4] +.IR end1 [4] +.IR thick [4] +.IR srcid [4] +.IR sp [2*4] +.IR dp [2*2*(n+1)] +.br +Draw a polygon of thickness +.RI 1+2× thick . +It is conceptually equivalent to a series of +.I n +line-drawing messages (see +.B L +above) +joining adjacent points in the list of points +.IR dp . +The source image +.I srcid +is translated so that the point +.I sp +in +.I srcid +aligns with the first point +in the list +.IR dp . +The polygon need not be closed: +.I end0 +and +.I end1 +specify the line endings for the first and +last point on the polygon. +All interior lines have rounded ends +to make smooth joins. +.HP +.B P +.IR dstid [4] +.IR n [2] +.IR wind [4] +.IR ignore [2*4] +.IR srcid [4] +.IR sp [2*4] +.IR dp [2*2*(n+1)] +.br +Draw a polygon as the +.B p +message, but +fill it rather than outlining it. +The winding rule parameter +.I wind +resolves ambiguities about what to fill if the polygon is self-intersecting. +If +.I wind +is +.BR ~0 , +a pixel is inside the polygon if the polygon's winding number about the point +is non-zero. +If +.I wind +is +.BR 1 , +a pixel is inside if the winding number is odd. +Complementary values (0 or ~1) cause outside pixels to be filled. +The meaning of other values is undefined. +The polygon is closed with a line if necessary. +.HP +.B r +.IR id [4] +.IR r [4*4] +.br +Cause the next read of the +.B data +file to return the image pixel data corresponding to the +rectangle +.I r +in image +.IR id . +.HP +.B s +.IR dstid [4] +.IR srcid [4] +.IR fontid [4] +.IR p [2*4] +.IR clipr [4*4] +.IR sp [2*4] +.IR n [2] +.IR n*(index [2]) +.br +Draw in the image +.I dstid +the text string specified by the +.I n +cache +.I indices +into font +.IR fontid , +starting with the upper left corner at point +.I p +in image +.IR dstid . +The image drawn is taken from image +.IR srcid , +translated to align +.I sp +in +.I srcid +with +.I dp +in +.IR dstid. +All drawing is confined to the clipping rectangle +.I clipr +in +.IR dstid . +.HP +.B x +.IR dstid [4] +.IR srcid [4] +.IR fontid [4] +.IR dp [2*4] +.IR clipr [4*4] +.IR sp [2*4] +.IR n [2] +.IR bgid [4] +.IR bp [2*4] +.IR n*(index [2]) +.br +Like the string drawing +.B s +command, but fill the background of each character +with pixels from image +.IR bgid . +The image +.I bgid +is translated so that the point +.I bp +aligns with the +point +.I dp +in +.IR dstid . +.HP +.B S +.IR id [4] +.IR chan [4] +Attach to the public screen with the specified +.IR id . +It is an error if the screen does not exist, is not public, or does not +have the channel descriptor +.I chan +for its associated image. +.HP +.B t +.IR top [1] +.IR n [2] +.IR n*id [4] +.br +Send +.I n +windows to the top (if +.I t +is non-zero) or bottom (if +.I t +is zero) of the window stack. +The window is specified by the list of +.I n +image +.IR id s +are moved as a group, maintaining their own order within the stack. +.HP +.B v +.br +Flush changes from a soft screen, if any, to the display buffer. +.HP +.B y +.IR id [4] +.IR r [4*4] +.IR buf [x*1] +.br +.ti -0.5i +.B Y +.IR id [4] +.IR r [4*4] +.IR buf [x*1] +.br +Replace the rectangle +.I r +of pixels in image +.I id +with the pixel data in +.IR buf . +The pixel data must be in the format dictated by +.IR id 's +image channel descriptor (see +.IR image (6)). +The +.B y +message uses uncompressed data, +while the +.B Y +message uses compressed data. +In either case, +it is an error to include more data than necessary. +.ig +.PP +Reading the +.B colormap +returns the system color map used on 8-bit displays. +Each color map entry consists of a single line containing +four space-separated decimal strings. +The first is an index into the map, and the remaining three are +the red, green, and blue values associated with that index. +The color map can be changed by writing entries in the +above format to +the +.B colormap +file. +Note that changing the system color map +does not change the color map used for +calculations involving +.B m8 +images, which is immutable. +.. +.PP +The +.B refresh +file is read-only. +As windows owned by the client are uncovered, +if they cannot be refreshed by the server (such as when they have +refresh functions associated with them), a message is made available +on the +.B refresh +file reporting what needs to be repainted by the client. +The message has five decimal integers formatted as in the +.B ctl +message: the image id of the window and the coordinates of the rectangle +that should be refreshed. +.SH SOURCE +.B /emu/port/devdraw.c +.br +.B /emu/*/win.c +.br +.B /os/port/devdraw.c +.br +.B /os/*/screen.c +.br +.B /libmemdraw +.SH SEE ALSO +.IR draw-intro (2), +.IR colour (6), +.IR image (6), +.IR font (6) +.SH DIAGNOSTICS +Most messages to +.B draw +can return errors; +these can be detected by a system call error +on the +.IR write (see +.IR sys-read (2)) +of the data containing the erroneous message. +The most common error is a failure to allocate +because of insufficient free resources. Most other errors occur +only when the protocol is mishandled by the application. +The error string (see +.IR sys-intro (2)) +will report details. +.SH BUGS +The +.B Refmesg +refresh method is not fully implemented. +.ig +.br +The +.B colormap +files only reference the system color map, and as +such should be called +.B /dev/colormap +rather than +.BI /dev/draw/ n /colormap\f1. +.. diff --git a/man/3/ds b/man/3/ds new file mode 100644 index 00000000..6d766698 --- /dev/null +++ b/man/3/ds @@ -0,0 +1,145 @@ +.TH DS 3 +.SH NAME +ds \- compound device subsystems +.SH SYNOPSIS +.nf +.B bind -b #k /dev + +.B /dev/ds +.B /dev/ds/ctl +.B /dev/ds/... +.fi +.SH DESCRIPTION +.I Ds +builds complex block storage subsystems out of simpler ones. +Inspired by the Plan 9 file server kernel's configuration strings, +it provides device mirroring, partitioning, interleaving, and catenation +for block-oriented file systems. +.PP +It serves a two-level directory. +The top level contains a single directory +.BR ds , +which contains a control file +.B ctl +and one file per configured device. +.PP +The control messages each introduce a new device, here named +.IR new . +The +.I file +arguments are interpreted in the name space of the writer. +.TP +.BI mirror " new files" \fR... +The device +.I new +corresponds to a RAID 1 mirroring of +.IR files . +Writes to +.BI new +are handled by sequentially writing to the +.I files +from right to left (the reverse of +of the order in the control message). +If any write fails, the write is aborted. +Reads from +.BI new +are handled by sequentially reading from the +.I files +from left to right until one succeeds. +The length of the mirror device is the minimum of the lengths of the +.IR files . +.TP +.BI part " new file offset length" +The device +.I new +corresponds to the +.I length +bytes starting at +.I offset +in +.IR file . +If +.IR offset + length +reaches past the end of +.IR file , +.I length +is silently reduced to fit. +.TP +.BI inter " new files" \fR... +The device +.I new +corresponds to the block interleaving of +.IR files ; +an 8192-byte block size is assumed. +.TP +.BI cat " name files" \fR... +The device +.I new +corresponds to the catenation of +.IR files . +.PD +.LP +If the variable +.B fsconfig +is set in +.IR plan9.ini (8) +then +.I ds +will read its configuration from the file +.B $fsconfig +on the first attach. +This is useful when the machine boots +from a local file server that uses +.IR fs . +.SH EXAMPLE +Mirror the two disks +.B /dev/sdC0/data +and +.B /dev/sdD0/data +as +.BR /dev/ds/m0 ; +similarly, mirror +.B /dev/sdC1/data +and +.B /dev/sdD1/data +as +.BR /dev/ds/m1 : +.IP +.EX +echo mirror m0 /dev/sdC0/data /dev/sdD0/data >/dev/ds/ctl +echo mirror m1 /dev/sdC1/data /dev/sdD1/data >/dev/ds/ctl +.EE +.LP +Interleave the two mirrored disks to create +.BR /dev/ds/data : +.IP +.EX +echo inter data /dev/ds/m0 /dev/ds/m1 >/dev/ds/ctl +.EE +.LP +Run +.IR kfs (4) +on the interleaved device: +.IP +.EX +disk/kfs -f /dev/ds/data +.EE +.LP +Save the configuration: +.IP +.EX +cp /dev/ds/ctl /dev/fd0disk +.EE +To load the configuration automatically at boot time, +add this to +.IR plan9.ini : +.IP +.EX +fsconfig=/dev/fd0disk +.EE +.SH "SEE ALSO" +.IR dossrv (4) +.SH SOURCE +.B /os/port/devds.c +.SH BUGS +Should be able to select block size for interleaved devices. diff --git a/man/3/dup b/man/3/dup new file mode 100644 index 00000000..034501dd --- /dev/null +++ b/man/3/dup @@ -0,0 +1,60 @@ +.TH DUP 3 +.SH NAME +dup \- dups of open files +.SH SYNOPSIS +.nf +.B bind #d /fd + +.B /fd/0 +.B /fd/0ctl +.B /fd/1 +.B /fd/1ctl +\&... +.fi +.SH DESCRIPTION +The +.I dup +device serves a one-level directory containing files whose +names are decimal numbers. +Each such file also has an associated control file. +A file of name +.I n +corresponds to open file descriptor +.I n +in the current process. +.PP +A +.IR sys-open (2) +of file +.I n +results in a file descriptor identical to +what would be returned from a system call +.BI sys->dup( n, +.BR -1) . +Note that the result is no longer a file in the +.I dup +device. +.PP +The +.I stat +operation returns information about the device file, not the open file it points to. +A stat of +.BI #d/ n +will contain +.I n +for the name, 0 for the length, and 400, 200, or 600 (octal) +for the mode, depending on whether the dup target is open +for reading, writing, or both. +.PP +A file of name +.IB n ctl +may be read to discover the properties of the associated file descriptor, in format identical to that of the +.B fd +file in +.IR prog (3). +.SH SEE ALSO +.IR sys-dup (2) +.SH SOURCE +.B /usr/inferno/emu/port/devdup.c +.br +.B /usr/inferno/os/port/devdup.c diff --git a/man/3/dynld b/man/3/dynld new file mode 100644 index 00000000..dbd31d8f --- /dev/null +++ b/man/3/dynld @@ -0,0 +1,75 @@ +.TH DYNLD 3 +.SH NAME +dynld \- load kernel module dynamically +.SH SYNOPSIS +.B bind -a #L /dev +.PP +.B /dev/dynld +.br +.B /dev/dynsyms +.SH DESCRIPTION +.I Dynld +serves a directory containing two files that control dynamic loading of modules. +When a module is loaded, +.IR dynld (10.2)), +checks the module's type against a type provided by the driver; +the types must match. +Currently the only supported module type is that of a device driver, +.B Dev +defined in +.IR dev (10.2)). +.PP +The control file +.B dynld +can only be opened by the host owner +(see +.IR eve (10.2)). +It accepts the following commands: +.TP +.BI "load dev" " name file \fR[\fP \fR[\fP tag \fR] dep ... ]\fP" +Load a module for device driver +.I name +from the given +.IR file . +The optional +.I tag +is typically the MD5 or SHA1 hash of the file's contents, to identify a particular version of the driver. +.TP +.BI "unload dev" " name \fR[\fP file \fR[\fP tag \fR] ]\fP" +Unload the device driver identified by the given +.IR name , +optionally qualified by the other parameters. +.PP +When read, +.B dynld +returns a list of the currently-loaded drivers, one per line, most recent first. +Each line contain: the module's device type +.BI # x +used in +.IR bind (1); +its kernel address; +its total text and data size in bytes; +its +.I name +when loaded; +the name of the +.I file +from which it was loaded; +and its +.IR tag . +.PP +.B Dynsyms +is a read-only text file that lists, one per line, +the symbols exported by the running kernel for use by modules it loads. +Each line contains: +the symbol's kernel address, +its type signature, +and its name. +.SH SOURCE +.B /os/port/devdynld.c +.SH SEE ALSO +.IR dynld (10.2), +.IR a.out (10.6), +.SH BUGS +.I Dynld +does not currently check that a driver is no longer in use before unloading it. diff --git a/man/3/eia b/man/3/eia new file mode 100644 index 00000000..2499d320 --- /dev/null +++ b/man/3/eia @@ -0,0 +1,136 @@ +.TH EIA 3 +.SH NAME +eia \- serial communication control +.SH SYNOPSIS +.nf +.B bind -a '#t' /dev + +.B /dev/eia0 +.B /dev/eia0ctl +.B /dev/eia0status +.B /dev/eia1 +.B /dev/eia1ctl +.B /dev/eia1status +\&... +.fi +.SH DESCRIPTION +.PP +The serial line device serves a one-level directory that gives access to the serial ports. +Each file set +.BI eia "n ..." +represents one serial port +and includes a data file +(eg, +.BR eia0 ), +a control file +(eg, +.BR eia0ctl ), +and a status file +(eg, +.BR eia0status ). +.PP +The +.B data +file can be read and written to access the corresponding serial port. +Reads will block until at least one character is available. +.PP +The +.B ctl +file accepts textual commands, via +.I write +(see +.IR sys-read (2)), +that control or condition +the serial port for subsequent IO: +.TP +.BI b n +Set the baud rate to +.IR n . +.TP +.BI c n +If +.I n +is non-zero, cause a hangup if the remote drops DCD. +.TP +.BI d n +Set DTR if +.I n +is non-zero; +otherwise clear it. +.TP +.BI e n +If +.I n +is non-zero, +cause a hangup if the remote drops DSR. +.TP +.B f +Flush the output queue. +.TP +.B h +Hangup both input and output queues. +.TP +.BI k n +Send a break lasting +.I n +milliseconds. +.TP +.BI l n +Set number of bits per byte to +.IR n . +Legal values are 5, 6, 7, or 8. +.TP +.BI m n +Obey modem CTS signal if +.I n +is non-zero; otherwise clear it. +.TP +.BI n n +Set the output queue to non-blocking, if +.I n +is non-zero; otherwise mark it as blocking (the default). +In non-blocking mode, if the output queue is full, new output is discarded +rather than block the writer until the queue drains. +.TP +.BI p c +Set parity to odd if +.I c +is +.BR o , +to even if +.I c +is +.BR e ; +otherwise set no parity. +.TP +.BI q n +Set the limit on input and output queues to +.IR n ; +both queues are initially set to 4k bytes. +.TP +.BI r n +Set RTS if +.I n +is non-zero; otherwise clear it. +.TP +.BI s n +Set number of stop bits to +.IR n . +Legal values are 1 or 2. +.TP +.BI x n +Enable XON/XOFF flow control if +.I n +is non-zero; otherwise disable it (the default). +.PP +Changes to port settings persist between a subsequent close and reopen. +.PP +The +.B status +file can be read for a report of the serial port status. +.SH SOURCE +.B /os/port/devns16552.c +.br +.B /os/*/devuart.c +.br +.B /os/*/devscc.c diff --git a/man/3/env b/man/3/env new file mode 100644 index 00000000..1d3ff79d --- /dev/null +++ b/man/3/env @@ -0,0 +1,48 @@ +.TH ENV 3 +.SH NAME +env \- environment device +.SH SYNOPSIS +.nf +.B bind #e /env + +.BI /env/ name +.fi +.SH DESCRIPTION +The environment device serves a one-level directory giving access to environment variables +and their values. +It is conventionally bound to +.BR /env . +The value of an environment variable +.I name +may be obtained by reading the file +.BI /env/ name. +If the file does not exist, the variable is unset and has the value nil. The +maximum length of a variable name is 127 bytes. +.PP +New environment variables are set by creating the corresponding file +in +.B /env +and writing the required value to that file. Similarly environment variables are destroyed (unset) by +removing the corresponding file. +.PP +Processes sharing an `environment group' see the same files and contents; +changes made by one process are seen by the others. +A process can insulate itself from further changes using the +.L FORKENV +option to +.IR sys-pctl (2), +which creates a new environment group that is a copy of the old, +but further changes in each are independent. +A new empty environment group is created by the +.L NEWENV +option to +.IR sys-pctl (2). +.SH SOURCE +.B /os/port/devenv.c +.br +.B /emu/port/devenv.c +.SH SEE ALSO +.IR env (1), +.IR sh (1), +.IR env (2), +.IR sys-pctl (2) diff --git a/man/3/ether b/man/3/ether new file mode 100644 index 00000000..3a8aa00c --- /dev/null +++ b/man/3/ether @@ -0,0 +1,134 @@ +.TH ETHER 3 +.SH NAME +ether \- Ethernet device +.SH SYNOPSIS +.nf +.BI "bind -a #l" n " /net" + +.BI /net/ether n /clone +.BI /net/ether n /[0-7] +.BI /net/ether n /[0-7]/data +.BI /net/ether n /[0-7]/ctl +.BI /net/ether n /[0-7]/stats +.BI /net/ether n /[0-7]/type +.BI /net/ether n /[0-7]/ifstats +.fi +.SH DESCRIPTION +The Ethernet device +.BI #l n +serves a three-level directory representing a physical Ethernet interface: +AMD LANCE, 3Com 3C509, 3Com 3C905, Intel 82557, and others. +If +.I n +is not given it is taken to be 0. +.PP +The top level directory +has a single directory named +.BI ether n, +where +.I n +is the interface number, starting from 0, +assigned in some platform-dependent way. +That directory contains a conversation directory for each of 8 Ethernet packet types, +and a +.B clone +file. +.PP +Opening the +.B clone +file returns a file descriptor open on the +.B ctl +file of an unused conversation directory. +Reading the +.B ctl +file returns a text +string representing the number of the +connection. +The connection is controlled by writing textual commands to the associated +.B ctl +file: +.TP +.BI connect " type" +Set the +.I type +of Ethernet packets received on the connection; the type is +expressed +as an integer constant +(in hexadecimal if it has a leading +.BR 0x , +octal if it has a leading +.BR 0 , +and otherwise decimal). +For instance, Ethernet packets carrying IP version 4 use type +.BR 0x800 . +The value +.B \-1 +stands for all types. +The value +.B \-2 +causes at most the first 64 bytes of all types of packets to be copied +to the conversation. +If several conversations are assigned the same packet type, +a copy of the packet is given to each. +.TP +.B promiscuous +Set the interface to capture all packets regardless of destination address. +An interface normally receives only packets whose +destination address is that of the interface or is the +broadcast address, +.BR ffffffffffff . +The interface remains promiscuous until the control file is +closed. +The extra packets are received only by conversations of the same type +as the incoming packet (or of type -1). +.TP +.BI addmulti " address" +Add the given MAC multicast +.I address +to the set of multicast addresses accepted by the interface. +.I Address +is a twelve digit MAC address in hexadecimal. +.TP +.BI remmulti " address" +Remove +.I address +from the set of multicast addresses accepted by the interface. +.PP +Incoming Ethernet packets are demultiplexed by destination address and +packet type and queued +for reading by the corresponding open connection(s). +Each read of the +.B data +file returns each packet in turn, including the Ethernet header. +A read will terminate at packet boundaries. +Each write to the +.B data +file causes a packet to be sent. +The Ethernet address of the interface is inserted into +the packet header as the source address. +.PP +Reading the +.B type +file returns the decimal value of the assigned Ethernet packet type. +.PP +Reading the +.B stats +file returns status information, the value +of counters, the `promiscuous' state, +and the Ethernet MAC address of the +interface. +.PP +Reading the +.B ifstats +file returns statistics and status information specific to a given +hardware interface. +.SH SOURCE +.B /os/port/devlance.c +.br +.B /os/port/netif.c +.br +.B /os/*/devether.c +.br +.B /os/*/ether*.c +.SH SEE ALSO +.IR ip (3) diff --git a/man/3/flash b/man/3/flash new file mode 100644 index 00000000..65acf528 --- /dev/null +++ b/man/3/flash @@ -0,0 +1,157 @@ +.TH FLASH 3 +.SH NAME +flash \- flash memory +.SH SYNOPSYS +.nf +.BI "bind -a #F" \fR[\fPn\fR]\fP " /dev" + +.B /dev/flash +.BI /dev/flash/ part +.BI /dev/flash/ part ctl +.fi +.SH DESCRIPTION +The flash memory device serves a two-level directory, +giving access to files representing part or all of a bank of flash memory. +A platform might have more than one bank of flash, numbered starting from 0. +The attach specifier +.I n +is a decimal integer that selects a particular bank of flash (default: 0). +Both NOR and NAND flash is supported. +For both types of flash, the driver gives a read/write/erase interface to the raw flash device, +which can impose constraints on operations beyond those imposed by the driver. +Other drivers such as +.IR ftl (3) +or +.IR logfs (3) +implement any higher-level format required, including ECC for NAND flash, for instance. +.PP +The top level directory contains a single directory named +.B flash +for bank 0, and +.BI flash n +for each other bank +.IR n . +It contains two files for each partition: +a data file +.I part +and an associated control file +.IB part ctl , +where +.I part +is the name of the partition. +Each partition represents a region of flash memory that starts and ends on a flash segment (erase unit) boundary. +The system initially creates a single standard partition +.B flash +representing the whole of flash memory, and the corresponding control file +.BR flashctl . +Other partitions can be created by writing to +.B flashctl +as described below. +.PP +The data file +.I part +provides read and write access to the bytes on the system's flash memory. +Bytes can be read and written on any byte boundary: +the interface hides any alignment restrictions. +A read returns the value of the bytes at the current file offset, where zero is the start of the partition. +A write reprograms the flash to the given byte values, at the current +file offset (relative to the start of the partition), using the physical +device's reprogramming algorithm. +An erased flash byte is logically +.B 16rFF +(regardless of the conventions of the physical flash device). +A write can change a bit with value 1 to a 0, +but cannot change a 0 bit to 1; +that can only be done by erasing one or more flash segments. +NAND flash typically has restrictions on the number of writes allowed to a page before requiring a block erase. +Reads and writes are unbuffered. +.PP +The control file +.BI part ctl +can be read and written. +A read returns several lines containing decimal and hexadecimal numbers +(separated by white space) +revealing the characteristics of memory within the partition. +The first line gives the +the manufacturer ID, the flash device ID, the memory width in bytes, and a string giving the flash type +(currently either +.B nor +or +.BR nand ). +Subsequent lines give characteristics of each group of erase units within the partition, +where the erase units within a group have the same properties. +Each line gives the start and end (as byte addresses) of the erase units in the region +that lie within the partition, followed by the size in bytes of each erase unit, which is followed +for NAND flash by the size in bytes of a page. +The sizes for NAND flash include the extra bytes per page typically used to hold an ECC and block status. +A write contains one of the following textual commands: +.TF erasexx +.TP +.BI add " name start end" +Create a new partition that ranges from +.I start +to +.I end +within the current partition. +Each value must be numeric (decimal, octal or hexadecimal) and a multiple of the erase unit size. +.I Name +must not be the name of an existing partition. +On success, new files +.I name +and +.IB name ctl +will appear in the parent +.B flash +directory. +.TP +.B erase all +Erase the whole flash partition, setting all bytes to +.BR 16rFF , +except those that are hardware write-protected. +.TP +.BI erase " offset" +Erase the segment that begins at the given +.I offset +within the partition, +setting all bytes to +.BR 16rFF , +except those that are hardware write-protected. +The +.I offset +is given in bytes, but must be a multiple +of the segment (erase unit) size. +.TP +.BR protectboot [ " off " ] +By default the system prevents erase unit 0 of the flash from being +erased or written, assuming it +contains the primary bootstrap. +Writing this command with parameter +.B off +removes that protection. +Writing +.B protectboot +with any other parameter (or none) restores the protection. +Note that a manufacturer might also have locked the flash in hardware, +and that protection must be removed in a device-dependent way. +.TP +.B sync +If the underlying device must buffer or cache (current devices do not), flush the buffer(s). +.PD +.PP +The syntax of all numbers is that of +.BR strtoul (10.2) ; +the default base is 10. +.SH SOURCE +.B /os/*/devflash.c +.br +.B /os/*/flash*.c +.SH SEE ALSO +.IR ftl (3) +.SH DIAGNOSTICS +A write will return an error if +an attempt is made to change a 0 bit to 1, +or if the flash memory fails to be programmed correctly. +.SH BUGS +The flash cannot be written if the kernel is executing directly from flash, +because the physical flash cannot be read during programming, +and the driver does not copy the programming code to DRAM. diff --git a/man/3/floppy b/man/3/floppy new file mode 100644 index 00000000..4a424571 --- /dev/null +++ b/man/3/floppy @@ -0,0 +1,52 @@ +.TH FLOPPY 3 +.SH NAME +floppy \- floppy disk interface +.SH SYNOPSIS +.nf +.B bind -a '#f' /dev + +.B /dev/fd0disk +.B /dev/fd0ctl +.B /dev/fd1disk +.B /dev/fd1ctl +.B /dev/fd2disk +.B /dev/fd2ctl +.B /dev/fd3disk +.B /dev/fd3ctl +.fi +.SH DESCRIPTION +.PP +The floppy disk interface serves a one-level directory giving access to up +to four floppy disk drives. +Each drive is represented by a data and control file. +There are no partitions. +.PP +Messages accepted by the +.B ctl +file include: +.TF format +.TP +.B eject +Eject the floppy, if possible. +.TP +.B reset +Reset the drive. +.TP +.BI format " type +Format the floppy. The +.I type +sets the density and +type of disk to be formatted; see +.IR format (8). +.PD +.PP +A read of the +.B ctl +file returns a string describing the form factor of the disk, one of +.BR 3½DD , +.BR 3½HD , +.BR 5¼DD , +or +.BR 5¼HD . +.SH SOURCE +.B /os/pc/devfloppy.c diff --git a/man/3/fpga b/man/3/fpga new file mode 100644 index 00000000..5396ab2a --- /dev/null +++ b/man/3/fpga @@ -0,0 +1,97 @@ +.TH FPGA 3 +.SH NAME +fpga \- interface to on-board FPGA +.SH SYNOPSIS +.B "bind -a #F /dev" +.PP +.B /dev/fpgaclk +.br +.B /dev/fpgactl +.br +.B /dev/fpgamemb +.br +.B /dev/fpgamemw +.br +.B /dev/fpgaprog +.br +.B /dev/fpgastatus +.SH DESCRIPTION +.I Fpga +allows configuration of an on-board FPGA (eg, the Altera Flex6000 on the Bright Star Engineering ip-Engine), +control of its clocks and environment, and raw access to any devices presented in the FPGA address space. +On booting, the FPGA subsystem is normally left powered down and the system's external clocks are not directed to +the processor's output pins, to conserve power if the subsystem is unused. +.PP +The control file +.B fpgactl +accepts the following requests: +.TF "power off" +.TP +.BI bclk " n" +Set BCLK output to +.I n +MHz, +where +.I n +must be a divisor of the system clock frequency (eg, of 48 if the system is running at 48 MHz). +.TP +.BI power +Power up the FPGA subsystem (that is automatically done when +.B fpgaprog +is accessed). +.TP +.B "power off" +Power down the FPGA subsystem. +.TP +.B reset +Reset the FPGA, forcing it into configuration mode (automatically done when +.B fpgaprog +is accessed). +.TP +.BI vclk " n m v r" +Program the clock synthesiser with the given parameters, and enable its output as VCLK. +.TP +.B "vclk off" +Disable output from the clock synthesiser. +.PD +.PP +The files +.B fpgamemb +and +.B fpgamemw +give 8-bit and 16-bit access respectively to the address space interpreted by the FPGA. +The file offset is the address read or written within that space; +offset and count must both be even for +.BR fpgamemw . +The interpretation of the data, including the data format and +whether byte or word access is required, is completely determined +by the program configured into the FPGA. +.PP +The write-only file +.B fpgaprog +configures the device. +A single write provides an FPGA configuration in raw binary format. +The FPGA subsystem is given power, the processor's clocks are made visible externally, and the +device is configured with the data written. +The write returns an error if configuration fails. +.PP +The read-only file +.B fpgastatus +contains a single line of text giving the state of the two status bits in the FPGA interface. +The word +.B config +appears if +.B CONFIG_DONE +is set, and +.B !config +otherwise; the word +.B status +appears if +.B nSTATUS +is set, and +.B !status +otherwise. +.SH SOURCE +.B /os/ipengine/devfpga.c +.SH SEE ALSO +.IR fpgaload (8) diff --git a/man/3/fs b/man/3/fs new file mode 100644 index 00000000..6bcfa6e2 --- /dev/null +++ b/man/3/fs @@ -0,0 +1,114 @@ +.TH FS 3 emu +.SH NAME +fs \- host file system interface +.SH SYNOPSIS +.EX +bind #U\fIspec\fP / + +sys->bind("#U\fIspec\fP", "/", Sys->MAFTER|Sys->MCREATE); +.EE +.SH DESCRIPTION +.I Fs +provides an interface to the host file system when running +.IR emu (1). +The device is automatically bound to the root of the Inferno namespace when +.I emu +starts. +.I Fs +maps filenames from the Inferno namespace to the real host filesystem +namespace. The mapping is determined by the host system directory that +.I emu +serves (see the description of the +.B -r +option in +.IR emu (1)). +.PP +The plain name +.B #U +always refers to the root of the Inferno tree within the host file system. +An optional +.I spec +string can select a different tree using conventions peculiar to the host system type. +Currently, on Unix and Plan 9, a +.I spec +of +.B * +(ie, +.BR #U* ) +refers to the root of the host system; +on Windows, the +.I spec +can give a device letter (eg, +.BR #Uc: ) +to refer to the Windows tree on that device. +.PP +When there is nothing but +.IR root (3) +in the name space, the device can only be bound from Limbo using +.IR sys-bind (2) +as shown above, since there is nothing in the name space +to support either +.IR bind (1) +or +.IR newns (2). +It can later be rebound elsewhere in the name space using +.IR bind (1). +.PP +.I Fs +provides only an approximation to the +file ownership and permissions checking defined in +.IR intro (5) +and other entries in this manual. +.IR Emu (1) +typically runs as the user that starts it, and that user will own all newly-created +files and directories, and that user's host system access rights control access +to any file. +Other details are specific to the host system, as given below. +.SS Unix +When checking owner, group and other permissions, the intent in Inferno is that +each is tried in turn, in that order. +Unix checks just the first that applies, so that if group +permission disallows access but other allows it, the access is still denied. +If +.IR emu (1) +is run as the super-user, Inferno's rules for ownership and permission checking are enforced by +.I fs +itself; otherwise, Unix's permission checking prevails. +.PP +On MacOS X, file names might be case insensitive, depending on file system settings. +.SS FAT file system (Windows9x and Windows/NT) +The values of +.B uid +and +.B gid +are +.BR Everyone . +.PP +Files and directories always have read and execute permission, +which cannot be changed. +Files without write permission cannot be removed. +.SS NTFS file system (Windows/NT, 2000, XP) +Permissions for read, write and execute operates as described in +.IR sys-stat (2). +.IR Emu (1) +attempts to maintain a limited +but consistent map between Inferno and NT worlds, specifically between Inferno names +and NT security IDs. +Special NT group +.B Everyone +represents `other' for file permissions. +The Inferno +.B uid +is the file owner under NT; +the Inferno +.B gid +reported is the first user in the file's ACL +that is neither the owner nor +.BR Everyone ; +failing that, the +.B gid +is the file's owner. +.SH SOURCE +.B /emu/*/devfs.c +.br +.B /emu/port/devfs-posix.c diff --git a/man/3/ftl b/man/3/ftl new file mode 100644 index 00000000..ec3856c4 --- /dev/null +++ b/man/3/ftl @@ -0,0 +1,185 @@ +.TH FTL 3 +.SH NAME +ftl \- flash translation layer +.SH SYNOPSIS +.EX +.B bind -a '#X' /dev + +.B /dev/ftlctl +.B /dev/ftldata +.EE +.SH DESCRIPTION +.PP +The flash translation layer device +provides the interface for management of +rewritable blocks on a flash memory device. +Flash memory differs from normal disc +or memory in that it is organised in large blocks (erase units), +typically 64k bytes or more in size, +and although writes can reset bits they cannot set them; +instead an entire erase unit must be erased at once. +These properties make it unsuitable for direct use by +a conventional block-oriented file system. +The flash translation layer compensates by +implementing a logical to physical +mapping that allows 512-byte blocks to be read or written +in the same way as rewritable disc blocks. +The translation layer manages the details of +block remapping, copying erase units to reclaim obsolete physical versions +of rewritten logical blocks, erase unit load wearing, etc. +.PP +The flash translation device serves a one-level directory, +giving access to two files. +The control file +.B ftlctl +receives commands to format a flash device +or initialise access to an already formatted device. +.B Ftldata +is the data file, giving access to the logical blocks on the formatted flash. +For example, it can be given to +.IR kfs (3) +for use as a file system. +The length of the +.B ftldata +file as returned by +.B Sys->stat +shows the total logical (formatted) space available for +use by the driver's clients. +.PP +The target flash device is identified to this driver +by name +(eg, +.BR #F/flash ) +in a control message defined below. +The flash device must have the following properties: +.IP 1. +It must have a corresponding control file +.IB device ctl +(eg, +.BR #F/flashctl ), +which must be writable. +.IP 2. +The flash control file must accept a command of the +form +.DS +.BI erase " offset" +.DE +which must cause the flash erase unit +starting at the given byte +.I offset +to be erased. +.IP 3. +The device +must allow reads and writes of any number of bytes +on arbitrary byte boundaries (file offset). +(In other words, the flash driver must hide alignment restrictions.) +.IP 4. +A write request +must allow previously-written regions to be updated provided +the new data does not change any 0 bit to 1 +(ie, writes can clear bits to 0 but will not change any 0 bits to 1). +.PP +The following control messages can be written to +.BR ftlctl : +.TP +.BI format " device [ offset [ n [ erasesize ] ] ]" +.br +Erase +.I n +bytes of +the given flash +.I device +starting at the given byte +.IR offset , +and format the erased region +for use by the flash translation layer. Omitting the +optional parameters is equivalent to setting them to +.BR 0xffffffff . +.I Erasesize +is the number of bytes in the flash device's erase unit; setting +to +.B 0xffffffff +takes the value from the underlying device. +If +.I offset +is +.BR 0xffffffff , +then the underlying device is searched from the +start for an existing flash translation layer header, and the remaining +parameters are taken from there. If +.I n +is +.BR 0xffffffff , +then everywhere from +.I offset +to the end of the +underlying device is erased. Otherwise, +.I offset +and +.I n +must be multiples of +.IR erasesize . +Make the newly formatted device's contents available on +.BR ftldata . +.TP +.BI init " device [ offset [ n [ erasesize ] ] ]" +.br +Make available on +.B ftldata +the logical blocks (with existing content) of a previously-formatted +.IR device . +The parameters are as defined for the +.B format +command, above. +.TP +.BI part " name start [ limit ]" +.br +Add a partition. This creates a new data file +.BI ftl name +with similar properties to +.BR ftldata , +but which constrains the range of the formatted data accessed to +begin at +.IR start , +and end at +.IR limit-1 , +or the last byte of the formatted data if +.I limit +is omitted. +.TP +.BI delpart " name" +.br +Removes a partition. +.TP +.B detach +Stop flash translation on +the corresponding flash device, +and close it. +An error results instead if +.B ftldata +is open. +.TP +.B scavenge +Force scavenging of reusable blocks (mainly intended to be used when +testing flash or debugging the driver). +.TP +.BI trace " n" +.br +Trace the actions of the flash translation driver. +No tracing is done if +.I n +is zero. +Larger values of +.I n +increase the level of detail. +.SH SOURCE +.B /os/*/devftl.c +.SH SEE ALSO +.IR flash (3) +.SH BUGS +Reads and writes of +.B ftldata +must be multiples of 512 bytes in length +and start on a 512-byte block boundary. +.br +Only one flash device can be active. diff --git a/man/3/gpio b/man/3/gpio new file mode 100644 index 00000000..73b26a48 --- /dev/null +++ b/man/3/gpio @@ -0,0 +1,94 @@ +.TH GPIO 3 SA1100 +.SH NAME +gpio \- access to GPIO registers +.SH SYNOPSIS +.B bind -a +.B #G +.B /dev +.PP +.nf +.B /dev/gpioclear +.B /dev/gpioctl +.B /dev/gpioedge +.B /dev/gpioset +.B /dev/gpiostatus +.fi +.SH DESCRIPTION +.PP +The GPIO interface +serves a one-level directory with five files +that give access to the GPIO registers in the SA1100. +See the SA1100 handbook for details of the function +of the various registers. +.PP +The control file +.B gpioctl +accepts commands to set individual bits in the edge detect +registers. +Each control message has three space-separated fields: +.IP +.EX +.I "reg pin value" +.EE +.LP +where +.I reg +is a single character +denoting a register, +.I pin +a bit within it, and +.I val +the value (0 or 1) for that bit. +Valid choices for +.I reg +are: +.B d +(GPDR), +.B r +(GRER), +.B f +(GFER), +and +.B a +(GAFR). +For example, the control message +.IP +.EX +d 10 1 +.EE +.LP +sets bit 10 (following the handbook's bit-numbering conventions) in the GPIO pin +direction register GPDR. +.PP +The read-only file +.B gpiostatus +shows the names and values (in hexadecimal) of all GPIO registers. +.PP +The remaining data files +allow bits to be read by +.B Sys->read +requests +and set by +.B Sys->write +requests. +When read, each file returns the value of a given +register as a single 8 digit hexadecimal number: +.B gpioset +and +.B gpioclear +both give the value of the level register, GPLR; +and +.B gpioedge +gives the value of the edge dectect register, GEDR. +Each write request +should present a single number in textual form, which +is assumed to be hexadecimal by default. +The value is written to a GPIO register: +.B gpioset +corresponds to GPSR, +.B gpioclear +corresponds to GPCR, and +.B gpioedge +corresponds to GEDR. +.SH SOURCE +.B /os/sa1100/devgpio.c diff --git a/man/3/i2c b/man/3/i2c new file mode 100644 index 00000000..c321ee02 --- /dev/null +++ b/man/3/i2c @@ -0,0 +1,87 @@ +.TH I2C 3 +.SH NAME +i2c \- basic I2C interface +.SH SYNOPSIS +.B bind -a +.BI #J n +.B /dev +.PP +.BI /dev/i2c. n .ctl +. br +.BI /dev/i2c. n .data +.fi +.SH DESCRIPTION +.I I2c +serves a one-level directory with two files +that give access to the target device with address +.I n +(given in hexadecimal) +on the system's I2C bus. +.I N +is usually determined by the I2C device manufacturer. +I2C gives address 0 special meaning as the `general call' address. +See an I2C specification for details. +.PP +The control file +.BI i2c. n .ctl +accepts commands to set the valid address range and +subaddressing mode for the corresponding data file. +The following control messages can be written to it: +.TP +.B a10 +Force 10-bit addressing instead of 7-bit addressing. +Otherwise 10-bit addressing is used only if the device address +.I n +is bigger than 255. +.TP +.BI size " nbytes" +.br +Set the logical size of the target device to +.IR nbytes . +(By default when opened, it is 256 bytes, enough for most small I2C devices.) +IO requests will be kept within this limit. +This value is also returned by +.B Sys->stat +as the length of the data file. +.TP +.BI subaddress " \fR[\fP n \fR]\fP" +.br +Cause subsequent reads and writes +on the data file to use I2C subaddressing +with +.I n +byte subaddresses (default: 1 byte). +.I N +must be no larger than 4. +The target device must support subaddressing. +By default, the device is not subaddressed. +Setting +.I n +to zero switches off subaddressing. +.PP +When read, +the control file displays the current settings. +.PP +The data file +.BI i2c. n .data +can be read or written to +exchange data with the slave device with address +.I n +(where +.I n +is given in hexadecimal). +Each write request transmits the given data +to the device. +Each read request sends a receive +request to the device and returns the resulting data. +If the I2C target is subaddressed, the current file offset +is used as the subaddress; +otherwise the file offset is ignored, and the device typically starts at 0 for each transfer request. +Read and write requests are trimmed to the declared +size of the device. +.SH SOURCE +.B /os/port/devi2c.c +.br +.B /os/*/i2c.c +.br +.B /os/cerf405/iic.c diff --git a/man/3/i82365 b/man/3/i82365 new file mode 100644 index 00000000..e1ee6c52 --- /dev/null +++ b/man/3/i82365 @@ -0,0 +1,41 @@ +.TH I82365 3 +.SH NAME +i82365 \- Personal Computer Memory Card Interface Association (PCMCIA) device +.SH SYNOPSIS +.nf +.B bind -a #y /dev + +.B /dev/pcm0attr +.B /dev/pcm0ctl +.B /dev/pcm0mem +.B /dev/pcm1attr +.B /dev/pcm1ctl +.B /dev/pcm1mem +.fi +.SH DESCRIPTION +The +.I i82365 +driver provides an interface to an Intel +82365-compatible PCMCIA interface chip. +This chip supports up to 2 PCMCIA slots, 0 +and 1. +Reading +.B pcm[01]attr +returns the contents of attribute memory. +Reading or writing +.B pcm[01]mem +reads or writes RAM on the card. +Reading +.B pcm[01]ctl +returns the card's status. +.PP +This driver must be included to use PCMCIA +devices such as the NE4100 Ethernet card. +The individual card drivers make calls to routines +in the PCMCIA driver. +.SH SOURCE +.B /os/pc/devi82365.c +.SH "SEE ALSO" +.IR plan9.ini (10.8) +.SH BUGS +There is no driver for the Databook PCMCIA interface chip. diff --git a/man/3/indir b/man/3/indir new file mode 100644 index 00000000..04e6386b --- /dev/null +++ b/man/3/indir @@ -0,0 +1,81 @@ +.TH INDIR 3 +.SH NAME +indir \- attach to device indirectly by name +.SH SYNOPSIS +.BI "bind #*" name +[\c +.BI ! spec\c +] +.I " dir" +.SH DESCRIPTION +.I Indir +allows any other device to be referred to by its name instead of its perhaps arbitrary single character type; +.I indir +itself has the type character +.RB ` * '. +It has no name space of its own. +On attach (see +.IR attach (5)) +.I indir +interprets its device specifier string as the +.I name +of a device to which it should attach, optionally followed by specifier +.I spec +for that device, separated from the +.I name +by an exclamation mark. +Attaching to +.I indir +(eg, by +.IR sys-bind (2)), +effectively attaches to the device with the given +.I name +and +.IR spec , +and all subsequent operations in the resulting name space access that +device, not +.I indir +itself. +.PP +For example, to access +.IR cap (3), +one could write: +.IP +.B "bind -a '#*cap' /dev" +.PP +The following commands both list the second instance of +.IR ether (3), +first directly, then using +.IR indir : +.IP +.B "ls '#l1'" +.br +.B "ls '#*ether!1'" +.PP +The file +.B /dev/drivers +(see +.IR cons (3)) +lists the names of currently configured devices. +.SS Credit +Invented by Bruce Ellis for Lucent's internal Research Inferno to help name dynamically-loaded device drivers. +This is a re-implementation. +.SH SOURCE +.B /emu/port/devindir.c +.br +.B /os/port/devindir.c +.SH SEE ALSO +.IR bind (1), +.IR sys-bind (2), +.IR cons (3) +.SH DIAGNOSTICS +If +.I name +is not configured, +.I indir +returns a suitable diagnostic in the error string. +.SH BUGS +Arguably the kernel +could simply look up the +.I name +itself. diff --git a/man/3/ip b/man/3/ip new file mode 100644 index 00000000..e5318691 --- /dev/null +++ b/man/3/ip @@ -0,0 +1,944 @@ +.TH IP 3 +.SH NAME +ip \- network protocols over IP +.SH SYNOPSIS +.nf +.B bind -a #I\f1[\f5\f2ifn\f1]\f5 /net + +.B /net/arp +.B /net/bootp +.B /net/iproute +.B /net/ipselftab +.B /net/iprouter +.B /net/log + +.B /net/ipifc/clone +.B /net/ipifc/stats +.BI /net/ipifc/ n +.BI /net/ipifc/ n /data +.BI /net/ipifc/ n /ctl +.BI /net/ipifc/ n /local +.BI /net/ipifc/ n /status + +.BI /net/ proto /clone +.BI /net/ proto /stats +.BI /net/ proto / n +.BI /net/ proto / n /ctl +.BI /net/ proto / n /data +.BI /net/ proto / n /err +.BI /net/ proto / n /local +.BI /net/ proto / n /remote +.BI /net/ proto / n /status +.BI /net/ proto / n /listen +\&... +.fi +.SH DESCRIPTION +The IP device serves a directory representing a self-contained +collection of IP interfaces. +There may be several instances, identified by the decimal interface number +.IR ifn , +that follows the +.B #I +device name; +.B #I0 +is assumed by default. +Each instance +has a disjoint collection of IP interfaces, routes and address resolution maps. +A physical or virtual device, or +.IR medium , +that produces IP packets is associated +with a logical IP network using the mechanisms described under +.I "Physical and logical interfaces" +below. +Commonly all IP media on a host are assigned to a single +instance of +.BR #I , +which is conventionally bound to +.BR /net , +but other configurations are possible: interfaces might be assigned +to different device instances forming separate +logical IP networks +to partition networks in firewall or +gateway applications. +.PP +Hosted Inferno provides a subset of the interface described here that gives +to the TCP/IP and UDP/IP of the host system's own IP subsystem. +See +.IR "Hosted interfaces" +below for a summary of the differences. +.SS Protocols +Within each instance, +the IP device provides +an interface to each IP protocol configured into the system, such as TCP/IP or UDP/IP. +.PP +Each of the protocols is served by the IP device, which represents a +connection by a set of device files. +The top level directory, +.I proto +in the +.SM SYNOPSIS +above, +is named after a protocol (eg, +.BR tcp , +.BR il , +.BR udp ) +and contains a +.B clone +file, a +.B stats +file, +and subdirectories numbered from zero to the number of connections +configured for this protocol. +.PP +The read-only +.B stats +file contains protocol-specific statistics as one or more lines of text. +There is no particular format, but the values are often a superset +of those required by the SNMP MIB. +.PP +Opening the +.B clone +file reserves a connection, represented by +one of the numbered subdirectories. The resulting file descriptor +will be open on the control file, +.BR ctl , +of the newly allocated connection. +Reading the +.B ctl +file returns a text +string representing the number of the +connection. +Connections may be used either to listen for incoming calls +or to initiate calls to other machines. +.PP +A connection is controlled by writing text strings to the associated +.B ctl +file. +After a connection has been established data may be read from +and written to the data file. +.PP +Before sending data, remote and local addresses must be set for the connection. +For outgoing calls the local port number will be allocated randomly if none is set. +Addresses are set by writing control messages to the +.B ctl +file of the connection. +The connection is not established until the data file is opened. +There are two models depending on the nature of the protocol. +For connection-oriented protocols, the process will block on open +until the remote host has acknowledged the connection, +either accepting it, causing a successful return from open, +or rejecting it, causing open to return an appropriate error. +For connectionless protocols, the open always succeeds; +the `connect' request sets local parameters for the source and destination fields +for use by subsequent read and write requests. +.PP +The following control messages are provided by this interface +to all protocols. +A particular protocol can provide additional commands, or +change the interpretation or even syntax of those below, +as described in the manual page for that protocol. +The description below shows +the standard commands with the default argument syntax and interpretation: +.TP +.BI connect\ ipaddress ! port "[!r]\ [\f2lport\f5]" +Set the remote IP address and port number for the connection. +If the +.B r +flag +is supplied and the optional local port +.I lport +has not been specified the system will allocate +a restricted port number (between 600 and 1024) for the connection to allow communication +with Unix machines' +.B login +and +.B exec +services. +.TP +.BI "announce\ [" ipaddress !] port +Set the local port +number to +.I port +and accept calls to that port. +.I Port +is a decimal port number or +.LR * . +If +.I port +is zero, assign a port number +(the one assigned can be read from the +.B local +address file). +If +.I port +is +.LR * , +accept +calls for any port that no process has explicitly announced. +If the optional +.I ipaddress +is given, set the local IP address for the connection +to that address, and accept only those incoming calls to +.I port +that are addressed to +.IR ipaddress . +.B Announce +fails if the connection is already announced or connected. +.TP +.BI bind\ port +.I Port +is a decimal port number or +.LR * . +Set the local port number to +.IR port . +This request exists to support emulation of +of BSD sockets and is otherwise neither needed nor used in Inferno. +.TP +.BI tos " \f1[\f2 n \f1]\f2" +Set the type-of-service value in outgooing packets to +.I n +(default: 0). +.TP +.BI ttl " \f1[\f2 n \f1]\f2" +Set the time-to-live (TTL) value in packets transmitted on this conversation +to +.I n +(default: 255). +.PP +Port numbers must be in the range 1 to 32767. +.PP +Several read-only files report the status of a +connection. +The +.B remote +and +.B local +files contain the IP address and port number for the remote and local side of the +connection. +The +.B status +file contains protocol-dependent information to help debug network connections. +The first word on the first line gives the status of the +connection. +.PP +Having announced, a process may accept incoming connections by calling +.B open +on the +.B listen +file. +The +.B open +will block until a new connection request arrives; +it will then +return an open file descriptor that points to the control file of the +newly accepted connection. +Repeating this procedure will accept all calls for the +given protocol. +.PP +In general it should not be necessary to use the file system interface to the +networks. +The +.BR dial , +.BR announce , +and +.BR listen +functions described in +.IR sys-dial (2) +perform the necessary I/O to establish and +manipulate network connections. +.SS TCP protocol +The TCP protocol is the standard Internet +protocol for reliable stream communication; it does not preserve +read/write +boundaries. +.PP +A connection is controlled by writing text strings to the associated +.B ctl +file. +After a connection has been established data may be read from +and written to the data file. +The TCP protocol provides a stream connection that does not preserve +read/write +boundaries. +.PP +For outgoing calls the local port number will be allocated randomly if none is set. +Addresses are set by writing control messages to the +.B ctl +file of the connection. +The connection is not established until the data file is opened. +For TCP the +process will block until the remote host has acknowledged the connection. +.PP +As well as the standard control messages above, +TCP accepts the following: +.TP +.BI hangup +Send a TCP reset (RST) to the remote side and end the conversation, +without waiting for untransmitted data to be acknowledged, +unlike a normal close of the device. +.TP +.BI keepalive\ [ "n" ] +Enable `keep alive' +mode: +if no traffic crosses the link within a given period, send a +packet to check that the remote party is still there, and remind +it that the local connection is still live. +The optional value +.I n +gives the keep-alive time in milliseconds (default: 120000). +.PP +The +.B status +file has many lines, each containing a labelled number, giving the values +of parameters and statistics such as: +maximum allowed connections, outgoing calls, incoming calls, established but later reset, +active calls, input segments, output segments, retransmitted segments, retransmitted timeouts, +input errors, transmitted reset. +.SS UDP protocol +.PP +UDP provides the standard Internet +protocol for unreliable datagram +communication. +.PP +UDP opens always succeed. +Before sending data, remote and local addresses must be set for the connection. +Alternatively, the following special control requests can be used: +.TP +.B headers +Set the connection to use an address header with IPv6 addressing +on reads and writes of the data file, +allowing a single connection to send datagrams to converse with +many different destination addresses and ports. +The 52 byte binary header appears before the data +read or written. +It contains: remote IP address, local IP address, interface IP address, remote port, and local port. +The IP addresses are 16 bytes each in IPv6 format, and +the port addresses are 2 bytes each, all written in network (big-endian) order. +On reads, the header gives the values from the incoming datagram, +except that if the remote used a multicast destination address, the IP address +of the receiving interface is substituted. +On writes, the header provides the destination for the resulting datagram, +and if the local IP address corresponds to a valid local unicast interface, +that address is used, otherwise the IP address of the transmitting interface +is substituted. +.TP +.B oldheaders +Set the connection to use an address header with IPv6 addressing +on reads and writes of the data file, +allowing a single connection to send datagrams to converse with +many different destination addresses and ports. +The 36 byte binary header appears before the data +read or written. +It contains: remote IP address, local IP address, remote port, and local port. +The IP addresses are 16 bytes each in IPv6 format, +the port addresses are 2 bytes each, all written in network (big-endian) order. +On reads, the header gives the values from the incoming datagram, +except that if the remote used a multicast destination address, the IP address +of the receiving interface is substituted. +On writes, the header provides the destination for the resulting datagram, +and if the local IP address corresponds to a valid local unicast interface, +that address is used, otherwise the IP address of the transmitting interface +is substituted. +.TP +.B headers4 +Set the connection to use an address header with IPv4 addresses +on reads and writes of the data file, +allowing a single connection to send datagrams to converse with +many different destination addresses and ports. +The 12 byte binary header appears before the data +read or written. +It contains: remote IP address, local IP address, remote port, and local port. +The IP addresses are 4 bytes each, +the port addresses are 2 bytes each, all written in network (big-endian) order. +On reads, the header gives the values from the incoming datagram. +On writes, the header provides the destination for the resulting datagram. +This mode is obsolete and destined for oblivion. +.PP +A read of less than +the size of the datagram will cause the entire datagram to be consumed. +Each write to the data file will send a single datagram on the network. +.PP +In replies, in connection-oriented mode, if the remote address +has not been set, the first arriving packet sets the following +based on the source of the incoming datagram: +the remote address and port for the conversation, +and the local address is set to the destination address in the +datagram unless that is a multicast address, and then the address +of the receiving interface is used. +.PP +If a conversation is in +.B headers +mode, only the local port is relevant. +.PP +Connection-oriented UDP is hungup if an ICMP error (eg, host or port unreachable, +or time exceeded) arrives with matching port. +.PP +The +.I udp +.B status +file contains four lines, each containing a labelled number counting an event: +input datagrams, datagrams on unannounced ports, datagrams with wrong checksum, and output datagrams. +.SS IL Protocol +IL provides a reliable point-to-point datagram service for communication between Plan 9 and +native Inferno machines. +Each read and write transfers a single datagram, as for UDP. +The datagrams are delivered reliably and in order. +Conversations are addressed and established as for TCP. +.SS Routing +.PP +The +.B iproute +file can be read and written. +When read, it returns the contents of the IP routing tables, +one line per entry, +with six fields giving the +destination host or network address, address mask, +gateway address, route type, tag (see below), and the number of the +.B ipifc +interface owning the route +(or +.RB ` - ' +if none). +The route type is up to four characters: +.B 4 +or +.B 6 +(IPv4 or IPv6 route); +.B i +(route is interface); +one of +.B u +(unicast), +.B b +(broadcast), +or +.B m +(multicast); +and lastly +.B p +if the route is point-to-point. +.PP +Commands can also be written to control the routing: +.TP +.BI add " ip mask gw \f1[\f2 tag \f1]\f2" +Add a route via the gateway identified by IP address +.I gw +to the address specified by +.I ip +and subnet mask +.IR mask . +Tag the resulting table entry with the +.I tag +provided, or the current +.I tag +(see +.B tag +below), +or the tag +.BR none . +.TP +.BI flush " \f1[\f2 tag \f1]\f2" +Remove all routes with the given +.I tag +that do not correspond to a local interface. +If +.I tag +is not given, flush all routes. +.TP +.BI remove " ip mask" +Remove routes to the given address. +.TP +.BI tag " tag" +Tag the routes generated by writes on the current file descriptor with +the given +.IR tag +of up to 4 characters. +The default is +.BR none , +set when +.B iproute +is opened. +.PP +The +.B ipselftab +file summarises the addresses and routes that refer to the local host. +It gives an address, the number of logical interfaces, and the interface type +in the same form as the route type of +.BR iproute . +.PP +The +.B iprouter +file is provided for use by a user-level application acting as an IP gateway. +It is effective only when the kernel-level gateway is not enabled +(see the +.B iprouting +interface control request below). +Once opened, packets that are not addressed to a +local address can be read from this device. +The packet contents are preceded by a 16 byte binary header that +gives the IPv6 address of the local interface that received the packet. +.SS Bootstrap +.PP +The read-only +.B bootp +file contains the results of the last BOOTP +request transmitted on any interface (see +.I "Physical and logical interfaces" +below) +as several lines of text, +with two fields each. +The first field names an entity and the second field gives its value in IPv4 address format. +The current entities are: +.IP +.RS +.TF ipaddr +.TP +.B auip +Authentication server address +.TP +.B fsip +File server address +.TP +.B gwip +Address of an IP gateway out of this (sub)net. +.TP +.B ipaddr +Local IP address +.TP +.B ipmask +Subnet mask for the local IP address +.RE +.PD +.PP +If any value is unknown (no reply to BOOTP, or value unspecified), +the value will be zero, represented as +.BR 0.0.0.0 . +.SS Address resolution +The +.B arp +file can be read and written. +When read, +it returns the contents of the current ARP cache as a sequence of lines, +one per map entry, giving +type, state, IP address and corresponding MAC address. +Several textual commands can be written to it: +.TP +.BI add " \f1[\f2 medium \f1]\f2 ip mac" +Add a mapping from IP address +.I ip +to the given +.I mac +address (a sequence of bytes in hexadecimal) +on the given +.IR medium . +It must support address resolution (eg, Ethernet). +If the +.I medium +is not specified, find the one associated with a route to +.I ip +(which must be IPv4). +.TP +.B flush +Clear the cache. +.SS Logging +.PP +The +.B log +file provides protocol tracing and debugging data. +While the file is held open, the system +saves, in a small circular buffer, error messages logged by selected protocols. +When read, it returns data not previously read, +blocking until there is data to read. +The following commands can be written to determine what is logged: +.TP +.BI set " proto ..." +Enable logging of messages from each source +.IR proto , +one or more of: +.BR ppp , +.BR ip , +.BR fs , +.BR tcp , +.BR il , +.BR icmp , +.BR udp , +.BR compress , +.BR ilmsg , +.BR gre , +.BR tcpmsg , +.BR udpmsg , +.BR ipmsg +and +.BR esp . +.TP +.BI clear " proto ..." +Disable logging of messages from the given sources. +.SS Physical and logical interfaces +The configuration of the physical and logical IP interfaces +in a given instance of +.B #I +uses +a virtual protocol +.B ipifc +within that instance, +that adds, controls and removes +IP interfaces. +It is represented by the protocol directory +.BR ipifc . +Each connection corresponds to an interface to a physical or virtual medium on +which IP packets can be sent and received. +It has a set of associated values: +minimum and maximum transfer unit, +MAC address, and a set of logical IP interfaces. +Each logical IP interface has local and remote addresses and an address mask. +.PP +Opening the +.B clone +file returns a file descriptor open on the +.B ctl +file for a new connection. +A medium is then attached using a +.B bind +request; +logical interfaces are associated by +.B connect +or +.BR add ; +they are removed by +.BR remove ; +and finally +.B unbind +detaches the medium from the connection. +For certain types of media, the +.B unbind +is automatic when the connection itself is closed. +With most media, including Ethernet, +the +.B ipifc +connection files can be closed after configuration, and later +reopened if need be to add or remove logical interfaces, +or set other parameters. +.PP +The +.B ctl +file responds to the following text commands, including interface-specific variants +of standard +IP device +requests: +.TP +.BI bind " medium " "[ \f5\f2name\f5 [ \f2arg ...\f5 ]" +Attach device +.I medium +to the interface, which must not already be bound to a device. +The +.I name +and subsequent arguments are interpreted by the driver for the +.IR medium . +The device name associated with the interface is +.IR name , +if given, or a generated name otherwise. +.TP +.BR connect " \f2ip\f5 [\f2mask \f5[\f2remote \f5[\f2mtu \f5]]]" +Remove all existing logical interfaces and create a new one as if by +.B add +(see below). +The connection must be bound to a medium. +.TP +.BR add " \f2ip\f5 [\f2 mask \f5[\f2 remote \f5[\f2 mtu \f5] ] ]" +Add a logical interface with local IP address +.IR ip . +The default for +.I mask +is the mask for +.IR ip 's +address class; +for the +.IR remote +address, +.IR ip 's +network; and for +.IR mtu , +the largest MTU allowed by the medium. +The new interface is registered in the IP routing tables. +.TP +.B bootp +Broadcast a BOOTP packet (using +.BR udp ). +If a valid response is received, set the interface's IP address and mask, +and the IP stack's default gateway to the results obtained from BOOTP. +The results are also available to applications by reading +the +.B bootp +file above. +Note that this mechanism is now deprecated in favour of +.IR dhcpclient (2). +.TP +.BI remove " ip mask" +Remove the logical interface determined by +.I ip +and +.IR mask . +.TP +.BI iprouting\ [ "n" ] +Control the use of IP routing on this +.IR ip (3) +instance. +If +.I n +is missing or non-zero, allow use as a gateway, +rerouting via one interface packets received on another. +By default, +or if +.I n +is zero, use as a gateway is not allowed: if a packet received +is not addressed to any local interface, either pass it to +a gateway application if active (see +.B iprouter +in +.IR ip (3)), +and otherwise drop the packet. +.TP +.BI mtu " n" +.br +Set the maximum transmit unit (MTU) on this interface to +.I n +bytes, which must be valid for the medium. +.TP +.BI addmulti " multi" +Add the multicast address +.I multi +to the interface. +.TP +.BI remmulti " multi" +Remove the multicast address +.I multi +from the interface. +.TP +.BI unbind +Remove any association between +the current medium (device) and the connection: +remove all routes using this interface, detach the device, +stop packet transport, and +remove all logical interfaces. +The connection is ready for re-use. +.PP +The +.B local +file contains one line for each logical interface, of the form: +.IP +.IB local -> self ... +.PP +where +.I local +is the local address associated with the interface and each +.I self +is a broadcast or multicast address that can address that interface, +including subnet addresses, if any. +.PP +The +.B status +file contains many fields: +the first two give the device name and the value of the current MTU, +followed by 7 fields per line for each logical interface: +local address, address mask, remote address, packets in, packets out, input errors, and output errors. +.PP +The following sections describe the media drivers available. +Each is separately configurable into a kernel. +.SS Ethernet medium +Ethernet devices as described in +.IR ether (3) +can be bound to an IP interface. +The bind request has the form: +.IP +.BI "bind ether " device +.PP +The interface opens two conversations on the given Ethernet +.IR device , +for instance +.BR ether0 , +using an internal version of +.BR dial , +with the addresses +.IB device !0x800 +(IPv4) +and +.IB device !0x806 +(ARP). +See +.IR sys-dial (2) +for the interpretation of such addresses. +The interface runs until a process does an explicit +.BR unbind . +Multicast settings made on the interface are propagated to the +.IR device . +.SS Point-to-point medium +An asynchronous serial device as described in +.IR eia (3) +can be bound to an interface as a Point-to-Point protocol (PPP) device. +The bind request has the form: +.IP +.BI "bind ppp " "serial ip remote mtu framing username secret" +.PP +All parameters except +.I serial +are optional. +The character +.RB ` - ' +can appear as a placeholder for any parameter. +Except for authentication data, an attempt is made to negotiate +suitable values for any missing parameter values, including network addresses. +The parameters are interpreted as follows: +.IP +.RS +.TF username +.TP +.I serial +Name of the device that will run PPP. +.TP +.I ip +Local IP address for the interface. +.TP +.I remote +IP address of the other end of the link. +.TP +.I mtu +Initial MTU value for negotiation (default: 1450) +.TP +.I framing +If +.I framing +is zero, do not provide asynch. framing (on by default). +Unimplemented. +.TP +.I username +Identification string used in PAP or CHAP authentication. +.TP +.I secret +Secret used in authentication; with CHAP it never crosses the link. +.PD +.RE +.PP +If the name +.I serial +contains +.RB ` ! ' +a connection will be opened using +.B dial +(see +.IR sys-dial (2)). +Otherwise the name will be opened as-is; +usually it is the name of a serial device +(eg, +.BR "#t/eia0" ). +In the latter case, a companion +.B ctl +file will also be opened if possible, to set serial characteristics for PPP +(flow control, 64kbyte queue size, nonblocking writes). +An attempt is made to start the PPP link immediately. +The write of the +.B bind +control message returns with an error if the link cannot be started, +or if negotiation fails. +The PPP link is automatically unbound if the line hangs up (eg, modem drops carrier), +or an unrecoverable error occurs when reading or writing the connection. +.PP +The PPP implementation can use either PAP and CHAP authentication, +as negotiated, provided an appropriate +.I username +and +.I secret +is given in the +.B bind +request. +It does not yet support the Microsoft authentication scheme. +.SS Packet medium +The packet medium allows an application to be source and sink +for IP packets. +It is bound to an interface by the simple request: +.IP +.B "bind pkt" +.PP +All other interface parameters including its IP address are +set using the standard +.I ipifc +requests described above. +Once that has been done, the application reads the +.B data +file of the interface to receive packets addressed to the interface, +and it writes to the file to inject packets into the IP network. +The interface is automatically unbound when all interface files are closed. +.SS Hosted interfaces +Native Inferno and Plan 9 have related IP implementations. +Plan 9 +.I emu +therefore simply imports Plan 9's +.BR /net , +and in the absence of version-specific differences, what is described +above still applies. +.PP +On all other hosted platforms, +the IP device gives applications +within +.IR emu (1) +a portable interface to TCP/IP and UDP/IP, even through it +is ultimately using the host system's own TCP/IP and UDP/IP implementations +(usually but not always socket based). +The interface remains the same: for instance by +.B /net/tcp +and +.BR /net/udp , +but is currently more limited in the set of services and control requests. +Both IPv4 and IPv6 address syntax may be used, but the IPv6 form must +still map to the IPv4 address space. +Only TCP and UDP are generally available, and a limited interface to ARP on some platforms (see below). +The set of TCP/UDP control requests is limited to: +.BR connect , +.BR announce , +.BR bind , +.BR ttl , +.BR tos , +.BR ignoreadvice , +.BR headers4 , +.BR oldheaders , +.BR headers , +.BR hangup +and +.BR keepalive . +.PP +The write-only +.B arp +file is implemented only on some Unix systems, and +is intended to allow the implementation of +the BOOTP protocol +using Inferno, on hosted systems. +It accepts a single textual control request: +.TP +.BI add " ip ether" +Add a new ARP map entry, or replace an existing one, for IP address +.IR ip , +associating it with the given +.I ether +MAC address. +The +.I ip +address is expressed in the usual dotted address notation; +.I ether +is a 12 digit hexadecimal number. +.PP +An error results if the host system does not allow the ARP map +to be set, or the current user lacks the privileges to set it. +.SH SOURCE +.B /emu/port/devip.c +.br +.B /os/ip/devip.c +.br +.BI /os/ip/ proto .c +.br +.B /os/ip/ipifc.c +.br +.br +.B /os/ip/*medium.c +.SH "SEE ALSO" +.IR sys-dial (2) +.\" joinmulti and leavemulti are unimplemented +.\" many media are only partly implemented diff --git a/man/3/kprof b/man/3/kprof new file mode 100644 index 00000000..fbddc3b0 --- /dev/null +++ b/man/3/kprof @@ -0,0 +1,88 @@ +.TH KPROF 3 +.SH NAME +kprof \- kernel profiling +.SH SYNOPSIS +.nf +.B bind -a #T /dev +.sp +.B /dev/kpctl +.B /dev/kpdata +.fi +.SH DESCRIPTION +The +.I kprof +device provides simple profiling +data for the operating system kernel. The data accumulates by +recording the program counter of the kernel at each `tick' of a +profiling clock. Often this is just the system clock, but may be an +independent higher priority timer which allows profiling of interrupt +handlers, dependent on implementation. +.PP +The file +.B kpdata +holds the accumulated counts in big-endian +byte order. +The size of the file depends on the size of kernel text, and the +size of the individual counts. +The first six counts are 4 bytes in size, and are special. The +first holds the total number of ticks, the second the number of +ticks which fell outside the kernel text, the third the number +of microseconds per tick, the fourth the number of sample buckets, +the fifth the size in bytes of each sample bucket, and sixth the +log base 2 of the sample bucket size. Typically the sample size +is 4, and the log base 2 of the bucket size 3 (8 bytes). The remainder +of the file holds the sample buckets. The entire file has size +.I "sample bucket size" +times +.IR "number of sample buckets" . +That is, the first six sample buckets are replaced with the special +numbers. +.PP +The file +.B kpctl +controls profiling. +Writing the string +.B start +to +.B kpctl +begins profiling; +.B stop +terminates it. The message +.B startclr +restarts profiling after zeroing the array of counts. +.PP +.IR Kprof (10.1) +formats the data for presentation. +.SH EXAMPLE +The following +.IR sh (1) +commands define and invoke a +function +.B sample +that runs a given test program with kernel profiling enabled, +and copies the result to a server presumed to be mounted on +.BR /n/remote . +.sp +.EX +fn sample { + echo start >/dev/kpctl + $1 + echo stop >/dev/kpctl + cp /dev/kpdata /n/remote/tmp/kpdata +} +bind -a '#T' /dev +sample {cp sound /dev/audio} +.EE +.PP +On the server, the +.IR kprof (10.1) +command is used to analyse the data: +.EX + kprof /usr/inferno/os/mpc/impc /tmp/kpdata +.EE +.SH SOURCE +.B /os/port/devkprof.c +.SH SEE ALSO +.IR kprof (10.1) +.SH BUGS +It cannot provide times for each node in the dynamic call graph (dynamic profiling). diff --git a/man/3/logfs b/man/3/logfs new file mode 100644 index 00000000..5e60b308 --- /dev/null +++ b/man/3/logfs @@ -0,0 +1,260 @@ +.TH LOGFS 3 +.SH NAME +logfs \- log-structured file system for flash devices +.SH SYNOPSIS +.B bind -b '#ʟ' /dev +.PP +.B /dev/logfsctl +.br +.B /dev/logfsusers +.br +.BI /dev/logfs name +.br +.BI /dev/logfs name boot +.PP +.B echo fsys +.I name +.B config +.I flash-device +.B "> /dev/logfsctl" +.br +.B echo fsys +.I name +.B format +.I boot-area-size +.B "> /dev/logfsctl" +.br +.B echo fsys +.I name +.B open +.B "> /dev/logfsctl" +.br +.BI "mount -Ac /dev/logfs" name +.I dir +.SH DESCRIPTION +.I Logfs +is a driver level implementation of the Inferno log structured +filesystem, a file system designed with modern flash devices +(such as NAND flash) in mind. +.I Logfs +is itself hardware independent, requiring other +devices to provide the physical medium. Currently only +.IR flash (3) +devices are supported. +.PP +The file system maintains two storage regions on the same medium: +a log-structured hierarchical file system that implements all the +functionality communicable by the Styx protocol +(see +.IR intro (5)), +and a boot +partition that offers a fixed amount of flat storage suitable for +holding such things as a kernel boot image, boot parameters etc. The +boot partition can be accessed and updated without understanding all +but the simplest facts about the hierarchical file system, making it +easy to implement boot loaders with small footprints. +.PP +The physical layout of the file system varies from medium to medium, +so that the specialised features of the medium can be accounted for. +.PP +The user table is maintained in memory; there is one table, shared between +all file systems supported by this driver. There is no distinction between +users and groups: a user is a group with one member. +The user table records a mapping +between uids +and +unames, +as well as recording the leader and members of each group. A +.I uid +is a string naming a user or group that is stored in the file system. A +.I uname +is the string naming a user or group that is used in +file system protocol messages (see +.IR intro (5)). +There is a distinction so that +unames +can be safely reused, even though +uids +cannot. +.PP +Configuration and control of the file systems is by writing commands to +.BR /dev/logfsctl : +.TP +.BI fsys " name" +.br +Sets the current file system to +.IR name , +which must be configured. Subsequent commands, not prefixed with +.BI fsys name\fR, +will by applied to the name file system. +.TP +.BI [fsys " name\f5] config\fI flash-device" +.br +Configures file system +.I name +to be written to +.BI flash (3) +device +.IR flash-device . +This does not initialise or format the filesystem, but simply bind +.I name +to +.IR flash-device . +For each configured +.IR name , +two files appear in the device name space, +.BI /dev/logfs name +and +.BI /dev/logfs name\f5boot\fI. +The former serves the Styx protocol giving access to the hierarchical file system; +the latter is a fixed size file that represents the boot partition. +.TP +.BI [fsys " name\f5] format \fIbootsize" +.br +Formats the underlying medium as a +.I logfs +format file system. Sufficent storage is set aside to create a boot partition of at +least +.I bootsize +bytes. Some medium implementations (eg, for NAND flash) store file system +parameters (eg, location, size and boot partition size) to enable automatic +location of file systems and improve bad block detection. These must +be part of the boot partition so that they are easily accessible to boot loaders, +so such medium implementations may also enforce a minimum size for the +boot partition. +.TP +.BI [fsys " name\f5] open [-P] [-W]" +.br +Initialises the specified file system, and makes it available for use. The file +system structure is verified, bad blocks are repaired and, in the case of the +log structured file system, and the log replayed to regenerate the directory structure. +The +.B -W +option reduces the permission control on +.IR wstat (5) +requests. Specifically it allows the +.BR uid , +.BR gid , +.BR mtime , +and +.B perm +to be changed by anyone. +The +.B -P +option removes all file access controls, allowing anyone to open any file in +any mode. +.TP +.BI [fsys " name\f5] sweep" +.br +Forces the log to be swept, if it has been written to since last being swept. +The log is normally swept automatically when space is low. +.TP +.BI [fsys " name\f5] sync" +.br +Flush any buffered log or data to the underlying device. +Use before shutting down the system if the device is not unmounted. +(See notes below.) +.TP +.BI [fsys " name\f5] trace [\fIlevel\f5]" +.br +If +.I +level +is non-zero, internal diagnostics for the log file system are enabled at the +given level. If +.I level +is zero, or missing, tracing is disabled. +.TP +.BI [fsys " name\f5] unconfig" +.br +removes the configuration. The file system must not be mounted, or the +boot partition open, before doing this. +.TP +.BI uname " uname uid" +.TP +.BI uname " uname \f5:\fPuid" +.br +adds the user with uname +.I uname +and uid +.I uid +to the in-memory table +.TP +.BI uname " uname \f5%\fPnewname" +.br +renames +.I uname +to +.IR newname , +throughout the user table +.TP +.BI uname " uname \f5=\fPleader" +.br +sets the group leader to the uname +.I leader +.TP +.BI uname " uname \f5=" +.br +removes the group leader; then all members are leaders +.TP +.BI uname " uname \f5+\fPmember" +.br +add the uname +.I +member +to the group +.TP +.BI uname " uname \f5-\fPmember" +.br +removes the uname +.I +member +from the group +.SS Notes +The file system log may be subject to a small amount of buffering for efficiency +purposes; therefore, it is necessary to unmount the file system before disconnecting +the power to avoid losing recent updates. Failure to do this does not result in +inconsistencies in the file system, but some recent changes will be lost. +Equivalently, a +.IR wstat (5) +of any file or directory, with all fields set to +.I no change +(also known as a +.I wstat +.IR flush) +will cause the log to be written to disk. Note that during a dismount, and also a +.I wstat +.IR flush , +a +.I wstat +flush +is also applied to the underlying +.IR flash (3) +device. Furthermore, since some buffering is used on the log, +needless use of +.I wstat flush +will consume log space more rapidly than normal, although it will be recovered during +the next sweep. +.PP +The log is automatically swept when space is low, so there is not normally any +need to use the +.B sweep +command. +.SH SOURCE +.B /liblogfs +.br +.B /libnandfs +.br +.B /emu/port/devlogfs.c +.br +.B /os/port/devlogfs.c +.SH SEE ALSO +.IR flash (3), +.IR ftl (3), +.IR kfs (4) +.SH BUGS +The only medium currently supported is NAND flash. This is detected by +recognising the manufacturer and device ids supplied by the status file of +the +.IR flash (3) +device. diff --git a/man/3/lpt b/man/3/lpt new file mode 100644 index 00000000..0d149699 --- /dev/null +++ b/man/3/lpt @@ -0,0 +1,51 @@ +.TH LPT 3 +.SH NAME +lpt \- parallel port interface +.SH SYNOPSIS +.nf +.B bind -a #L[123] /dev + +.B /dev/lpt[123]data +.B /dev/lpt[123]dlr +.B /dev/lpt[123]pcr +.B /dev/lpt[123]psr +.fi +.SH DESCRIPTION +The +.I lpt +driver provides an interface to the parallel +interface normally used for printers. +The specifiers +.BR 1 , +.BR 2 , +and +.BR 3 +correspond to +the parallel interfaces at PC ports 0x378, 0x3bc, and 0x278 +respectively. +.PP +.B Lpt?data +is write only. +Writing to it sends data to the interface. +This file is sufficient for communicating with most printers. +.PP +.BR Lpt?dlr , +.BR lpt?pcr , +and +.B lpt?psr +are used for fine control of the parallel port. +Reading or writing these files corresponds to +reading and writing the data latch register, +printer control register, and printer status +register. +These are used by programs to drive special devices. +The data is written as a hexadecimal +(leading +.BR 0x ), +octal +(leading +.BR 0 ) +or decimal number. +Reads return a hexadecimal number representing the value of the register. +.SH SOURCE +.B /os/*/devlpt.c diff --git a/man/3/mnt b/man/3/mnt new file mode 100644 index 00000000..7efc0c8d --- /dev/null +++ b/man/3/mnt @@ -0,0 +1,84 @@ +.TH MNT 3 +.SH NAME +mnt \- attach to Styx servers +.SH SYNOPSIS +.nf +.B #M +.fi +.SH DESCRIPTION +The +.I mount driver +is used by +.B Sys->mount +(but not +.BR Sys->bind ; +see +.IR sys-bind (2)) +to connect the name space of a process to +the service provided by a Styx server over a communications channel. +After the +.BR mount , +file operations in that portion of the name space will +be converted by the mount driver into the appropriate +Styx messages to the server, and its Styx replies returned +as the status of the system calls. +.PP +Any authentication must precede +.IR mount , +which does none itself; +see +.IR security-intro (2) +for a discussion of the authentication and security +mechanisms provided `ready made' by Inferno, but +any other scheme can be agreed between client and server. +The +.I mount +system call does, however, issue an +.IR attach (5) +message to the server to identify the user of the connection. +Each distinct user of a connection must mount it separately; +the mount driver multiplexes the access of the various users and their +processes to the service. +.PP +File-oriented system calls are converted by the kernel into messages in the Styx protocol. +Within the kernel, Styx is implemented by procedure calls to the +various kernel device drivers, as described in +.IR intro (10) +and +.IR dev (10.2). +The mount driver translates these procedure calls into remote procedure calls +to be transmitted as messages over the communication channel to the server. +Each message is implemented by a write +of the corresponding protocol message to the server channel +followed by a read on the server channel to get the reply. +Errors in the reply message are turned into system call error returns. +.PP +A +.IR sys-read (2) +or +.I Sys->write +system call on a file served by the mount driver +may be translated +into more than one +message, +since there is a maximum data size for a Styx message. +The system call +will return when the specified number of bytes have been transferred +or a short reply is returned. +.PP +The string +.L #M +is an illegal file name, +so this device can be accessed directly only by the kernel. +.SH "SEE ALSO" +.IR bind (1), +.IR sys-bind (2) +.SH SOURCE +.B /emu/port/devmnt.c +.br +.B /os/port/devmnt.c +.SH BUGS +When mounting a service through the mount driver, +that is, when the channel being multiplexed is itself +a file being served by the mount driver, +large messages may be broken in two. diff --git a/man/3/mpeg b/man/3/mpeg new file mode 100644 index 00000000..8fc7bd52 --- /dev/null +++ b/man/3/mpeg @@ -0,0 +1,102 @@ +.TH MPEG 3 +.SH NAME +mpeg \- Boffin mpeg decoder +.SH SYNOPSIS +.B +bind -b #E /dev +.PP +.B /dev/mpeg +.br +.B /dev/mpegctl +.SH DESCRIPTION +The +.I mpeg +device serves two files giving access to a Boffin MPEG-1 decoder. +.PP +The control file +.B mpegctl +when read returns lines of text giving the device's properties. +Each line starts +.B video +or +.B audio +followed by a list of capabilities. +The current device returns a fixed set: +.IP +.EX +video mpeg1,sif +.br +audio musicam,I musicam,II +.EE +.PP +The control file accepts the following commands: +.TF pause +.PD +.TP +.B init +Reinitialise the device's video and audio subsystems; +cancel the effect of +.B stop +or +.B pause +.TP +.B stop +Stop the display immediately. +.TP +.B pause +Suspend display. +.TP +.B video iso11172 mpeg1,sif +Set the output video mode and formats; only this precise setting is valid. +.TP +.BI audio " format rate" +There are two choices for +.IR format : +.B musicam,I +(MPEG audio layer 1), +with +.I rate +from 64000 to 448000 Hz, +and +.B musicam,II +(MPEG audio layer 2) +with +.I rate +from 48000 to 384000. +.TP +.BI window " minx miny maxx maxy" +Sets the overlay window on the screen, in screen coordinates. +If the window size exceeds 320x240, the image is scaled accordingly, +separately in each dimension. +.PP +The data file +.B mpeg +is an exclusive-use device. +Once the device has been initialised and an output window +set using the +.B init +and +.B window +commands to the control file, +and an audio format selected by the +.B audio +command, +MPEG data can be written in the agreed format to the +.B mpeg +file, +for display in the output window. +The driver buffers the data written and implements flow control between application +and the hardware. +When closed, the device waits for the last block of data to display +before returning to the application. +.SH SOURCE +.B /os/pc/devmpeg.c +.SH CONFIGURATION +.B "mpeg0=port=0x1e0 irq=15 dma=6 +.SH SEE ALSO +.IR mpeg (2), +.I stream +in +.IR sys-read (2) +.SH DIAGNOSTICS +An error results on a write to the device once stopped. diff --git a/man/3/pbus b/man/3/pbus new file mode 100644 index 00000000..619cd420 --- /dev/null +++ b/man/3/pbus @@ -0,0 +1,60 @@ +.TH PBUS 3 +.SH NAME +pbus \- USR/3Com Edgeserver packet bus +.SH SYNOPSIS +.B bind -a '#Y' /dev +.PP +.B /dev/pbus +.br +.B /dev/pbusctl +.SH DESCRIPTION +The packet bus driver serves a directory containing two files, +giving MAC-level access to the EPB version of the packet bus +of the US Robotics (3Com) Edgeserver chassis. +.PP +The read-only file +.B pbusctl +contains a single integer that gives the chassis slot occupied by the Edge server +(its address on the packet bus). +.PP +The file +.B pbus +is read and written to communicate on the bus. +Each write +transmits a single packet on the bus. +The driver expects a four byte header in each write: +.IP +.IB "slot chan" " 0 0" +.PP +where +.I slot +is the destination chassis slot number and +.I chan +identifies a logical receiver in that slot. +Including the header, the largest write accepted is 128 bytes. +The driver completes the header as the bus firmware requires; +it also pads each packet with zero bytes to a hardware packet boundary +as it puts it on the bus. +It flashes green in the `Wan TX' LED as packets are transmitted. +.PP +Each read of the +.B pbus +file returns the contents of a single packet received from the bus. +The read will block if necessary until a packet arrives. +The data includes a four byte header +as above, and padding to a hardware packet boundary. +Normally a higher-level protocol will provide its own headers including +an actual length. +.PP +At reset, the driver downloads firmware to the controller if required. +All invalid packets received are quietly discarded. +Packets are also dropped whenever an internal input queue overflows +because the reader has not kept up with arriving traffic. +.SH SOURCE +.B /os/pc/devpbus.c +.SH SEE ALSO +.IR plap (3) +.SH BUGS +The driver detects but does not recover from bus clock loss +.br +The driver cannot be included in the public distribution. diff --git a/man/3/pipe b/man/3/pipe new file mode 100644 index 00000000..494e57db --- /dev/null +++ b/man/3/pipe @@ -0,0 +1,69 @@ +.TH PIPE 3 +.SH NAME +pipe \- two-way interprocess communication +.SH SYNOPSIS +.nf +.BI "bind '#|'" dir +.IB dir /data +.IB dir /data1 +.fi +.SH DESCRIPTION +A pipe provides a mechanism for interprocess I/O by +reading and writing file descriptors (see +.IR sys-read (2)). +An +.IR attach (5), +typically via +.IR sys-pipe (2) +or +.IR sys-bind (2), +allocates two files that are cross-connected: +data written to one can be read back from the other, in the same order. +.PP +Write boundaries are preserved: each read terminates when the read buffer +is full or after reading the last byte of a write, whichever comes first. +In particular, a write of zero bytes will result in a zero-length read, +which is usually interpreted by readers as end-of-file, but could be used +to delimit the data stream for other purposes. +.PP +Written data is buffered by the kernel and stored on internal queues +(see +.IR qio (10.2)). +The maximum block size is 128k bytes; +larger writes will be split across several blocks, which are queued separately. +Each read will return data from at most one block. +Concurrent writers are therefore guaranteed that their data will not be interleaved +with data from other writers (ie, will be written atomically) only when +each write is less than the maximum buffer size. +Writers to pipe interfaces on remotely mounted portions of the namespace have their guarantee of atomicity lowered to +.BR Sys->ATOMICIO +bytes by +.IR mnt (3). +.PP +The system mediates between producer and consumer. +Writers will block when buffered data reaches a high-water mark, currently 32k bytes, +until a reader has reduced it by half. +The length returned by +.IR sys-stat (2) +on each name +gives the number of bytes waiting to be read on the corresponding end of the pipe. +.PP +When all file descriptors on +one side of the pipe have been closed, and after any remaining data has +been read, +a reader on the other side sees end-of-file (count of zero) on a subsequent read. +Once both ends are closed, the pipe can be reused. +.PP +A pipe persists until it is unmounted and no processes have either end open. +.SH SOURCE +.B /emu/port/devpipe.c +.br +.B /os/port/devpipe.c +.SH "SEE ALSO" +.IR sys-file2chan (2), +.IR sys-pipe (2) +.SH DIAGNOSTICS +Writes to a closed pipe generate an exception +.RB ` "write on closed pipe" '. +Persistently reading a closed pipe after reading end-of-file +will result in a read error. diff --git a/man/3/plap b/man/3/plap new file mode 100644 index 00000000..63eb417c --- /dev/null +++ b/man/3/plap @@ -0,0 +1,136 @@ +.TH PLAP 3 +.SH NAME +plap \- USR/3Com Edgeserver packet bus link access protocol +.SH SYNOPSIS +.B bind -a '#X' /net +.PP +.nf +.B /net/plap/clone +.BI /net/plap/ n /ctl +.BI /net/plap/ n /data +.BI /net/plap/ n /local +.BI /net/plap/ n /remote +.BI /net/plap/ n /status +.BI /net/plap/ n /listen +.SH DESCRIPTION +The +.I plap +driver serves a three-level directory giving access to the link level +protocol used by an Edgeserver card to communicate with +other cards in a USR/3Com chassis. +On first +.I attach +(usually by a +.IR bind (1) +to +.BR /net ) +the driver opens a connection to the packet bus device +.B #Y +described in +.IR pbus (3). +It multiplexes that connection using a specialised member of the LAP family +of protocols. +.PP +The top level directory contains a single directory naming the protocol, +.BR plap . +It contains a +.B clone +file and a set of conversation directories numbered from 0 to 127; +only active conversation directories are present. +.PP +Opening the +.B clone +file allocates a new conversation directory +.IR n . +The file descriptor will point to the control file, +.BR ctl , +of that directory. +Reading the file returns a text string giving the conversation number. +.PP +Each conversation directory contains six files. +The connection is controlled by writing text strings to the +.B ctl +file. +Once a connection has been established, data is exchanged with the +remote peer by reading and writing the +.B data +file. +.PP +A +.I plap +address has the form: +.IP +[ +.IB slot . +] +.IB chan ! sap +.PP +where +.I slot +is a chassis slot number, +.I chan +is a logical channel (eg, a modem number), +and +.I sap +is a number representing a `service access point'. +.PP +The following control messages are supported: +.TP +.BI connect " remoteaddr \fP\fR[\fP \fIlocaladdr\fP ]\fI " +Make a connection to the given +remote address (of the form given above). +If a local address is not specified, the +system will assign an unused address dynamically +(the local chassis slot number is of course fixed). +Connect fails if the connection is already announced or connected, +or +.I localaddr +is already in use. +.TP +.BI announce address +Set the local address to +.I address +and accept incoming calls to that address. +If no address is specified, all incoming calls to addresses not explicitly announced +will be accepted by this connection. +Announce fails if the connection is already announced or connected, +or the local +.I address +specified is already in use. +.PP +The +.B remote +and +.B local +files contain the remote and local addresses for the connection +in the full address form +.IB slot . chan ! sap. +The +.B status +file returns a line giving the directory name, number of active opens, and the state +of the connection. +.PP +A process listens for incoming calls by opening the +.B listen +file using +.IR sys-open (2). +The open will block until a call arrives, when it will return a file descriptor +open on the +.B ctl +file of the newly accepted connection, which can be read to find the directory +number and thus the other files. +.PP +The device follows the conventions that allow +.BR dial , +.BR announce +and +.B listen +of +.IR sys-dial (2) +to do the work needed to establish and manipulate network connections. +.SH SOURCE +.B /os/pc/devplap.c +.SH SEE ALSO +.IR pbus (3) +.SH BUGS +The driver cannot be included in the public distribution. diff --git a/man/3/pnp b/man/3/pnp new file mode 100644 index 00000000..f2eab7dc --- /dev/null +++ b/man/3/pnp @@ -0,0 +1,150 @@ +.TH PNP 3 +.SH NAME +pnp, pci \- Plug 'n' Play ISA and PCI Interfaces +.SH SYNOPSIS +.nf +.B bind -a '#$' /dev + +.BI /dev/pci/ bus\fL.\fPdev\fL.\fPfn ctl +.BI /dev/pci/ bus\fL.\fPdev\fL.\fPfn raw + +.BI /dev/pnp/ctl +.BI /dev/pnp/csn n ctl +.BI /dev/pnp/csn n raw +\&... + +.fi +.SH DESCRIPTION +This device provides a limited interface to the PCI bus and +Plug 'n' Play ISA devices. +Both are present on most PC platforms; on others, only the +.B pci +interface is present (because there is no ISA bus). +.SS PCI Interface +.PP +PCI devices are addressed logically by a bus number, +a device number on that bus, and a function number +within the device. +The set of all such device functions may be enumerated +by traversing the +.B /dev/pci +directory; the driver serves two files for each function. +These are a control file +.RL ( /dev/pci/\fIbus\fP.\fIdev\fP.\fIfn\fPctl ) +which may be read for a textual summary of the device function, +and a `raw' file +.RL ( /dev/pci/\fIbus\fP.\fIdev\fP.\fIfn\fPraw ) +which may be read to obtain the raw contents of PCI configuration space. +.PP +The first field of a PCI control file contains the class, sub-class and +programming interface values for the device function, expressed +as 2-digit hexadecimal values, and separated by periods. +The second field yields the vendor ID and device ID, each as 4-digit +hex numbers, separated by a slash. +The third field is the associated interrupt line in decimal. +The remainder of the line enumerates any valid base address +registers for the function, using two fields for each. +In the first field, the index of the register is followed by +a colon, and then the value of the register itself. +The following field gives the associated size of the memory +(or I/O space) that is mapped by the register. +.SS Plug 'n' Play +.PP +Plug 'n' Play ISA devices are discovered by sending a fixed `unlock' sequence +over an I/O port, and then reading back data from another port. +An arbitration algorithm is used to separate out the individual +cards and enumerate them in turn. +Each card is assigned a unique number, called a CSN, in the range 1-255 as a +result of enumeration. +Cards also have a fixed 64 bit identification number, set by the +manufacturer, which is used by the arbitration algorithm to +resolve conflicts. +The first 32 bits describe the type of the card, and the second +32 bits form a serial number for the particular instance of that card type. +When formatted textually, it appears as 3 upper-case letters +(typically representing the manufacturer), +followed by 4 hex digits, then a period, then 8 hex digits. +The substring before the period is the card type, and the substring +after the period is the serial number. +.PP +The enumeration algorithm needs to be enabled by specifying the +port number to write the unlock sequence out on. +This can be configured to take place at boot time by adding a line +like the following to +.IR plan9.ini : +.IP +.EX +pnp0=port=0x203 +.EE +.PP +Here +.B port +should be chosen to not conflict with any existing devices. +It must be in the range +.BR 0x203-0x3ff . +Alternatively, one can use the following command: +.IP +.EX +echo port 0x203 >/dev/pnp/ctl +.EE +.PP +Note that a side-effect of PnP enumeration is to reset the configuration +state of all such cards; any settings made by a Plug and Play BIOS will be lost. +Reading the file +.B /dev/pnp/ctl +returns one of the strings +.B "enabled\fI port\fP" +or +.BR "disabled" . +.PP +For each enumerated card, two files are served in +.BR /dev/pnp . +A control file +.RL ( /dev/pnp/csn\fIn\fPctl ) +may be read to determine the ID of the card, and a raw file +.RL ( /dev/pnp/csn\fIn\fPraw ) +may be read to obtain the configuration data associated with the card. +It is intended that the control file should take commands which set the +various configurable resources of the card, but this has not been +implemented yet. +.PP +A mechanism is provided for configuring cards via +.IR plan9.ini (10.6). +A line of the form +.BI pnp n = "idstring ..." +will cause the driver to look for the card named by +.I idstring +and, if found, assign it the CSN +.IR n . +The intention is that +any additional text after the idstring is interpreted as if it +was written to the card's +.B ctl +file, but this is not yet implemented. +.SH EXAMPLES +.PP +To list all PCI functions: +.IP +.EX +cat /dev/pci/*ctl +.EE +.PP +To find just the PCI video card (class 3): +.IP +.EX +grep '^03' /dev/pci/*ctl +.EE +.SH SOURCE +.B /os/pc/devpnp.c +.br +.B /os/port/devpci.c +.SH BUGS +There is currently no way to write to PCI configuration space, +or to perform reads of less than 32 bits. +Access to the I/O and memory regions of a PCI device is not provided. +.PP +The ability to set a Plug 'n' Play card's configurable settings has not been +implemented. +.PP +There should be a user program for identifying and configuring +Plug 'n' Play cards. diff --git a/man/3/pointer b/man/3/pointer new file mode 100644 index 00000000..3c90fde3 --- /dev/null +++ b/man/3/pointer @@ -0,0 +1,80 @@ +.TH POINTER 3 +.SH NAME +pointer \- mouse and stylus interface +.SH SYNOPSIS +.B "bind -a #m /dev" +.PP +.B /dev/cursor +.br +.B /dev/pointer +.SH DESCRIPTION +The +.I pointer +device is the interface to input from a mouse, stylus, or some other device +for pointing at positions on a display. +On some platforms, the pointer is associated with a cursor +on the display, that is displayed at the current pointer position. +There often are buttons associated with the pointer, whether on +the pointing device or elsewhere. +For instance, some of the buttons on a PDA might be associated +with the stylus not a keypad, to allow modification of stylus actions +when there are are no buttons on the stylus itself. +In the hosted environment of +.IR emu (1), +the pointer is associated with the host system's own pointing device. +.PP +Reading the +.B pointer +file returns the current pointer position and the state of any buttons associated with the pointer. +The read blocks until the state has changed since the last read. +Each read returns a 49 byte record: +.IP +.BI m "x y buttons msec" +.PP +Each record has the letter +.B m +immedlately followed by four 11-character decimal numbers, each number ended by a blank. +.I X +and +.I y +give the coordinates of the pointer in display coordinates; +the value +.I buttons +has bit +.RI "(1<<" b ) +set when button +.I b +is down; and +.I msec +is a time stamp in milliseconds. +.PP +Writing a record of the above form to +.B pointer +moves the displayed cursor to the given +.I x +and +.I y +position; +.I buttons +and +.I msec +are ignored. +.PP +Writing an +.IR image (6) +file to the +.B cursor +file sets the image of the cursor on the display. +Reading +.B cursor +returns the current cursor image, again in +.IR image (6) +format. +.SH SOURCE +.B /emu/port/devpointer.c +.br +.B /os/port/devpointer.c +.SH SEE ALSO +.IR wm (1), +.IR draw-intro (2), +.IR image (6) diff --git a/man/3/prof b/man/3/prof new file mode 100644 index 00000000..db08e07f --- /dev/null +++ b/man/3/prof @@ -0,0 +1,93 @@ +.TH PROF 3 +.SH NAME +prof \- profiling device +.SH SYNOPSIS +.nf +.B bind #P /prof + +.BI /prof/ctl +.BI /prof/ n /name +.BI /prof/ n /path +.BI /prof/ n /histogram +.BI /prof/ n /pctl +.fi +.SH DESCRIPTION +The +.B prof +device serves a two-level directory structure. The first level contains a control file +.B ctl +and zero or more numbered directories each corresponding to a module being +profiled. Inside each of these numbered directories are further files which describe +the particular module being profiled. +.PP +The write-only control file +.B ctl +provides the facilities to profile a module. Messages written to this file initiate and +control the profiling. +.TP 10n +.BI module " name" +Add the module or the module whose path is +.I name +to the list of modules to be profiled. +.TP 10n +.B start +Start profiling all modules in the above list or, if the list is empty, start profiling all +modules loaded by the kernel. The profiling is done by sampling. +.TP 10n +.B startcp +As above but do coverage profiling. All instructions executed in the wanted modules +are counted. +.TP 10n +.B startmp +As above but do memory profiling. All heap memory allocations are associated +with a line of limbo source and all deallocations with the line that did the allocation. +.TP 10n +.B stop +Stop all profiling. +.TP 10n +.B end +Stop all profiling and free all memory associated with the modules being profiled. +The profiler returns to it's initial state with no modules under profile. +.TP 10n +.BI interval " i" +Change the sampling interval to +.I i +ms. The default sampling rate is 100 ms. +.PP +The second level directories contain information about each module under profile. +.PP +The read-only file +.B name +contains the name of the module in the form it appears in it's module source file. +.PP +The read-only file +.B path +contains the path of the dis file that implements the module. +.PP +The write-only control file +.B pctl +allows finer control of the profiling of a module. It is not used at present. +.PP +The read-only file +.B histogram +contains statistics about the profiled module. The file contains a list of pairs +of integers seperated by a space. The first number of the pair is a program counter +value representing the address of a dis instruction. Addresses start from 0 and the +list is in order of increasing address. The +second number is the frequency with which this address was sampled. Each read +of this file returns the next pair in the list. The frequency is guaranteed to be non-zero. +.PP +When coverage profiling the second number of each pair is the number of times +that dis instruction was executed, when memory profiling it's the amount of memory in bytes. +.SH SOURCE +.B /emu/port/devprof.c +.SH BUGS +The device profiles on a global basis and therefore does not distinguish between multiple profilers running at once. +.PP +The coverage profiling can only be done on dis instructions. +.PP +The device can do only one of time, coverage or memory profiling at once. + + + + diff --git a/man/3/prog b/man/3/prog new file mode 100644 index 00000000..675652f2 --- /dev/null +++ b/man/3/prog @@ -0,0 +1,311 @@ +.TH PROG 3 +.SH NAME +prog \- running programs +.SH SYNOPSIS +.nf +.B bind #p /prog + +.BI /prog/ n /ctl +.BI /prog/ n /dbgctl +.BI /prog/ n /exception +.BI /prog/ n /fd +.BI /prog/ n /heap +.BI /prog/ n /ns +.BI /prog/ n /nsgrp +.BI /prog/ n /pgrp +.BI /prog/ n /stack +.BI /prog/ n /status +.BI /prog/ n /text +.BI /prog/ n /wait +\&... +.fi +.SH DESCRIPTION +The +.B prog +device serves a two-level directory structure. +The first level contains numbered directories +corresponding to pids of live Limbo processes; +each such directory contains a set of files +representing the corresponding process. +All files operate on +.I UTF +(see +.IR utf (6)) +strings. +.PP +The read-only +.B status +file contains seven space-separated fields. +The fields are: the process and process group identifiers, each 8 characters right justified; +the user name, at least 10 characters left justified; +cpu time in minutes, seconds and tenths of seconds; +the process state, 10 characters left justified; +the amount of memory used by the process in units of 1024 bytes, +at least 5 characters, right justified, followed by a +.BR K ; +and the name of the current program module, +up to 28 characters, left justified. +.PP +The read-only +.B pgrp +file contains the process group identifier, in decimal. +.PP +The read-only +.B nsgrp +file contains the namespace group identifier, in decimal. +.PP +The read-only +.B ns +file contains a set of mount and bind commands +which describe the +.IR sys-bind (2) +and +.B mount +operations used to construct the name space, in +the format of +.IR namespace (6). +The last +line of the file is a +.B cd +command indicating the working directory. +.PP +The read-only +.B wait +file may be read to recover +information about the exiting children of the process. +A read of +.B wait +will block until a child of the process, created after +.B wait +was opened, exits. +When such a child exits, it produces a string with three fields: +the pid of the exiting process, a space, +module name, enclosed in +.B +\&"\c +\&'s, +and a possibly empty error message. +The error message will contain at most 64 characters. +.PP +The read-only +.B fd +file +describes the open file descriptors in the +file descriptor group of the process. +Each line describes an open file. +The fields are: the file descriptor index, the open mode +.RB ( r , +.BR w , +.BR rw ); +the type and number of the device; +the path, version and type of the file's +.I qid +(see +.IR intro (5)); +the file's atomic I/O unit, as defined in +.IR sys-iounit (2)); +the file I/O offset in bytes; +and the name with which it was opened. +.PP +The read-only +.B exception +file gives details of the last exception to occur in the process, if any. The fields +are the program counter value when the exception occurred, the module it +occurred in and the exception itself, each separated by a space. If none, the +result is the empty string. +.PP +Messages written to the +.B ctl +file control the execution of the process. +.TF killgrp +.PD +.TP +.B kill +Kill the process. +.TP +.B killgrp +Kill all processes in the same group as the process. +A process writing to its own ctl file does not kill itself. +.TP +.B exceptions propagate +Applies to process group leaders only (ie any process that executes a system +call +.I sys->pctl(Sys->NEWPGRP, ... +). +If any process in the same group as the leader incurs an exception which it +does not handle, atomically raise the exception in all processes in the group. +In this case exceptions are generated for killed processes as well. This mechanism allows +all processes in a process group to perfom error recovery when one of them +faults. +.TP +.B exceptions notifyleader +Applies to process group leaders only. +If any process in the same group as the leader incurs an exception which it +does not handle, atomically destroy all processes in the group except for the +leader and raise the exception in the leader. This error recovery mechanism might +be appropriate when a fault occurs amongst a group of processes and the group +leader takes sole responsibilty for recovery. +.TP +.B restricted +Mark all processes that the process spawns in future as restricted. A restricted +process is one which can run out of memory when a configured limit has been +reached and before total memory is exhausted. An unrestricted process can +allocate memory until memory is truly exhausted. Typically a window manager +or server might be unrestricted as they are processes fundamental to the +running of a system. +.PP +The +.B dbgctl +file provides facilities for debugging a process. +Messages written to the file control the execution of the process. +.TP 10n +.BI step " n" +Step the interpreter for at most +.I n +instructions, or until a breakpoint is reached. +.TP 10n +.B toret +Step the interpreter until a return from the current activation frame +or a breakpoint is reached. +.TP 10n +.B cont +Step the interpreter until a breakpoint is reached. +.TP 10n +.B stop +Stop the process as soon as possible. +Do not allow the process to execute again until an +.B unstop +message is received. +.TP 10n +.B unstop +Cancel the effect of any previous +.BR stop . +.TP 10n +.BI "bpt set " "path pc" +Set a breakpoint at +.I pc +for the module given by +.IR path . +.TP 10n +.BI "bpt del " "path pc" +Clear a breakpoint if one exists. +.PP +Reading +.B +dbgctl +gives updates for some state transitions while the process is being debugged. +Each update is terminated by a newline. +.TP 10n +.B exited +The process exited without error. +.TP 10n +.BI broken: " error" +The process died due to +.IR error , +a string with up to 64 characters. +.TP 10n +.B send +The process is blocked sending on a channel. +.TP 10n +.B recv +The process is blocked receiving on a channel. +.TP 10n +.B alt +The process is blocked in an +.B alt +statement. +.TP 10n +.B run +The process is unblocked and now ready to run. +.TP 10n +.BI new " pid" +The process has spawned a new process identified by +.IR pid . +.PP +The read-only +.B stack +file contains the dynamic call stack trace. +Each activation frame is described by one line with six fields, separated by a space: +the frame pointer, program counter, +module data pointer, and module code pointer, +each 8 hexadecimal digits; +the execution method for the module (0 means interpreted, 1 compiled); +and the path name of the module. +The top activation frame starts at offset 0. +.PP +The +.B heap +file may be queried to examine the state of the process. +A data query contains an address, a period, a format character, +and a count. +An instruction query contains a pc, a plus, a mode address, a period, +the format +.BR I , +and a count. +The addresses in the query may be decimal, +hexadecimal preceded by +.B 0x +or +.BR 0X , +or octal preceded by +.BR 0 . +Count gives the number of consecutive +data items retrieved by reading +.B heap +starting at offset 0; +the format varies according to the format character. +All data items other than strings are terminated by a newline. +.TP 10n +.B W +32-bit decimal ints. +.TP 10n +.B B +8-bit unsigned decimal bytes. +.TP 10n +.B V +64-bit decimal bytes. +.TP 10n +.B R +64-bit reals. +.TP 10n +.B I +Disassembled Dis instructions. +.TP 10n +.B P +32-bit hexadecimal address, or +.BR nil . +.PP +The following formats examine properties of specific 32-bit pointers. +.TP 10n +.B L +Examine a list, yielding +a pair of hexadecimal addresses separated by a period, +giving the address of the head and tail of a list. +It is an error to use +.B L +on +.BR nil . +.TP 10n +.B A +Examine an array, yielding +a decimal length, a period, and the address of the 0th element of an array, +or +.BR nil . +.TP 10n +.B C +Examine a string, yielding +the decimal length in characters, a period, and the +.IR utf (6) +representation of the string. +.TP 10n +.B M +Examine a module reference, yielding the address of its global data or +.BR nil . +.PP +The +.B text +file is currently unimplemented. +.SH SOURCE +.B /emu/port/devprog.c +.br +.B /os/port/devprog.c diff --git a/man/3/root b/man/3/root new file mode 100644 index 00000000..c4a0a845 --- /dev/null +++ b/man/3/root @@ -0,0 +1,45 @@ +.TH ROOT 3 +.SH NAME +root \- the root file system +.SH SYNOPSIS +.nf +.B / +.B /chan +.B /dev +.B /env +.B /fd +.B /net +.B /net.alt +.B /nvfs +.B /prog +.B /root +.B /srv +.B /osinit.dis +.fi +.SH DESCRIPTION +This device is set up by the kernel to be the initial root of +the name space. +In the emulation environment, +the names in the one-level tree shown above are mostly just place-holders, +to allow a place on which to +.I bind +(see +.IR sys-bind (2)). +.PP +In the native environment, an arbitrary initial directory structure and +file content can be built-in +when the kernel is configured, but it will typically include at least +the names above, to act as mount points. +The required file +.B /osinit.dis +(not present in the emulation environment) +provides an executable Dis binary when read, +and is the first program invoked when initialising the system. +Other files needed for bootstrap +might also reside in this device. +.SH SOURCE +.B /emu/port/devroot.c +.br +.B /os/port/devroot.c +.SH SEE ALSO +.IR init (8) diff --git a/man/3/rtc b/man/3/rtc new file mode 100644 index 00000000..72d32400 --- /dev/null +++ b/man/3/rtc @@ -0,0 +1,60 @@ +.TH RTC 3 +.SH NAME +rtc \- real-time clock and non-volatile memory +.SH SYNOPSIS +.B bind -b '#r' /dev +.PP +.B /dev/rtc +.br +.B /dev/rtcid +.br +.B /dev/nvram +.SH DESCRIPTION +The +.I rtc +device provides access to the real-time clock and any associated non-volatile memory. +Physical devices supported include the Mostek MK48T12-15 Zeropower/Timekeeper, +the Dallas Semiconductor DS1687 real-time clock, +and the IBM PC real-time clock on various platforms. +.PP +The +.B rtc +file when read returns the time as a decimal number, expressed as the number of seconds since the epoch, +1 January 1970 00:00 GMT. +The clock is set by writing the desired number of seconds since the epoch to the file. +Setting the time in this device has no effect on system time returned by +.B /dev/time +(see +.IR cons (3)), +which must be set separately if desired. +For example, when +.I rtc +is available +.I osinit +(see +.IR init (8)) +uses it to set +.BR /dev/time . +.PP +The +.B nvram +file provides access to the non-volatile memory commonly implemented +by these clock chips. +There are no cross-platform standards for the range of addresses that +can be safely used by Inferno, or for the content and format of the data. +.PP +The +.B rtcid +file holds a decimal number giving the serial number of the device, +set during manufacturing. +The file exists only if a particular device provides such a number. +.SH SOURCE +.B /os/*/devrtc.c +.SH SEE ALSO +.IR cons (3) +.SH BUGS +The +.B rtc +file returns seconds but +.B /dev/time +returns microseconds: it's history. diff --git a/man/3/sd b/man/3/sd new file mode 100644 index 00000000..fb9d4555 --- /dev/null +++ b/man/3/sd @@ -0,0 +1,194 @@ +.TH SD 3 +.SH NAME +sd \- storage device interface +.SH SYNOPSIS +.nf +.B bind #S /dev + +.BI /dev/sd Cu /ctl +.BI /dev/sd Cu /raw +.BI /dev/sd Cu /data +\&... +.fi +.SH DESCRIPTION +The storage device interface serves a two-level directory +giving access to multiple storage units, +typically ATA(PI) or SCSI discs. +Each unit +is accessed via files in the directory named by the controller +to which it is attached, +.IR C , +and by its unit number +.IR u . +The controller naming convention for ATA(PI) units starts +with the first controller being named +.LR C , +the second +.LR D , +etc. up to a maximum of 4 controllers +.RB ([ C-F ]); +legacy controllers are always 'C' and 'D'. +There can be a maximum of 2 units per ATA(PI) controller +.RB ([ 01 ]). +The controller naming convention for SCSI units starts with +the first controller being named +.LR 0 , +the second +.LR 1 , +etc. up to a maximum of 16 controllers +.RB ([ 0-9a-f ]). +There can be a maximum of 16 units per SCSI controller +.RB ([ 0-9a-f ]). +.PP +Units are not accessed before the first attach. +Units may be individually attached using the attach specifier, +for example +.IP +.EX +bind -a '#SsdD0' /dev +.EE +.PP +An attach without a specifier will cause the driver to scan for all possible +units before processing the rest of the name. +.PP +The subdirectory for each unit contains two files, +.I ctl +and +.IR raw . +In addition, +if the unit is a direct-access disc of some type +it may be split into partitions and +the subdirectory may contain a file per partition. +By default, +the partition +.I data +will exist for such media. +.PP +Partitions are added and deleted by writing to the +.I ctl +file +.IP +.EX +part \f2name start-sector end-sector\fP +delpart \f2name\fP +.EE +.PP +The default +.I data +partition may be deleted. +A partition cannot be deleted if a process has it open. +If a change of removable media is detected, +the new media cannot be opened until all open partitions +on the old media are closed. +.PP +Reading the +.I ctl +file returns at least one line of textual information about +the unit. +The first line will always be prefixed by +.B inquiry +and will give a manufacturer and model number if possible. +A line prefixed by +.B config +will be returned for appropriate media, +e.g. for ATA(PI) units the remainder of the line contains +configuration information from the device's +.I identify +command (config and capabilities) +and also the available I/O transfer options; +this is a diagnostic aid. +A line prefixed by +.B geometry +will be returned for appropriate media; +at least two numbers will follow, +the first being the number of sectors contained in the unit +and the second the sector size in bytes. +Any remaining information on the +.B geometry +line is unit-dependent, +for instance, head, +cylinder and sector counts for ATA discs. +If any partitions are defined for the media, +their name, start-sector and end-sector will be returned, +prefixed by +.BR part . +.IP +.EX +% cat /dev/sdD0/ctl +inquiry KENWOOD CD-ROM UCR-421 208E10/20/99 7.39 2 M0 +config 85C0 capabilities 0F00 dma 00550004 dmactl 00000000 +geometry 242725 2352 +part data 0 242725 +% +.EE +.PP +The use of DMA and multi-sector read/write commands may be +enabled and disabled on ATA(PI) units by writing to the +.B ctl +file +.B dma +and +.B rwm +respectively followed by +.B on +or +.BR off . +For example, to enable DMA on a unit that supports it: +.IP +.EX +% echo 'dma on'>/dev/sd00/ctl +.EE +.PP +If supported by the unit, +the standby timer may be enabled: +.IP +.EX +% echo 'standby \f2T\fP'>/dev/sdC0/ctl +.EE +.PP +where +.I T +is the standby timer period in seconds. +.I T +must be between 30 and 1200, +or can be 0 to disable the timer. +.PP +The +.B raw +file is used to execute an arbitrary command on the unit at +a low level. +This is used by programs +to manipulate devices that do not fit the simple storage model +or using special commands for maintenance purposes. +The following steps may be used to execute a command +.IP +\- Write the command to the +.I raw +file; +.IP +\- Read or write data associated with the command, according to the direction of the transfer. +.IP +\- Read the +.I raw +file to retrieve the status of the command, +returned as a text integer. +.SH SOURCE +.B /os/port/devsd.c +.br +.B /os/*/sd*.[hc] +.SH SEE ALSO +.IR ds (3), +.IR floppy (3) +.SH BUGS +.PP +Still in development. +.PP +No LUNs. +.PP +The 4 controller limit for ATA(PI) is not enforced. +.PP +No account is taken of some buggy ATA PCI controllers +such as the CMD640. +.PP +ATA(PI) units come up with DMA and multi-sector read/write +capability disabled. diff --git a/man/3/sign b/man/3/sign new file mode 100644 index 00000000..c992c296 --- /dev/null +++ b/man/3/sign @@ -0,0 +1,92 @@ +.TH SIGN 3 +.SH NAME +sign \- control use of signed modules +.SH SYNOPSIS +.B "bind -a #Σ /dev" +.PP +.B /dev/signerkey +.br +.B /dev/signctl +.SH DESCRIPTION +.I Sign +is a device, still experimental, to +control the use of signed Dis modules. +After system initialisation, any process can load any module. +Using +.IR sign , +.B load +operations can subsequently be restricted for a process and its descendents. +.PP +.B Signerkey +is a file that can be opened for writing only by the host owner +(see +.IR eve (10.2)) +(but any process holding the file descriptor can write to it). +The data written must be the textual representation of a public key in the form produced by +.B Keyring->pktostr +(see +.IR keyring-certtostr (2)). +After a successful write, subsequent +.B load +operations will be limited to Dis modules in any of the following sets: +.IP • +built-in modules +.IP • +unsigned modules found in the kernel's +.IR root (3) +file system +.IP • +currently loaded unsigned modules +.IP • +acceptable signed modules +.PP +A signed Dis module contains a signature in its header, as specified by +.IR dis (6). +The signature contains the result of signing the +remaining data in the file (or more precisely, a cryptographically secure hash of it), using +a configured public key algorithm and the signer's secret key +(for instance using +.BR Keyring->sign , +see +.IR keyring-sha1 (2)). +.PP +A signed module is `acceptable' if it was signed by the secret key corresponding to one +of the public keys written to +.BR signerkey . +There can be up to 8 such keys. +The set of keys and the secured status is shared across +.BR spawn . +.PP +.B Signerkey +is generally readable, and when read yields a list of the keys installed, one per line, +showing +.BR owner , +.BR alg , +and other attributes in +.IB attr = value +format, space separated. +The actual key value is not currently shown. +.PP +.B Signctl +can be read or written only by the host owner. +Each write contains a textual control request. +(Currently there are none such.) +If security is not enabled, it is empty when read. +Otherwise, it contains the number of keys loaded, as a decimal integer. +.SH SOURCE +.B /emu/port/devsign.c +.br +.B /os/port/devsign.c +.SH SEE ALSO +.B wm/rt +in +.IR wm-misc (2), +.IR sys-pctl (2), +.IR dis (6), +.IR createsignerkey (8), +.IR eve (10.2) +.SH DIAGNOSTICS +If the text is not a valid public key or uses an algorithm that is not configured, +a write to +.B signer +fails and sets the error string. diff --git a/man/3/snarf b/man/3/snarf new file mode 100644 index 00000000..810504d1 --- /dev/null +++ b/man/3/snarf @@ -0,0 +1,29 @@ +.TH SNARF 3 hosted +.SH NAME +snarf \- host window system clipboard +.SH SYNOPSIS +.B bind -a #^ /dev +.br +.B bind -b #^ /chan +.PP +.B /dev/snarf +.br +.B /chan/snarf +.SH DESCRIPTION +.I Snarf +serves a single file, +.BR snarf . +Reading the file returns the current +contents of the host window system's own clipboard (equivalent to +the Inferno window system's `snarf buffer'). +If the file is opened for writing, subsequent writes append to an internal buffer; +when the file is closed, that buffer's contents are written to the host window system's clipboard. +.PP +.IR Emu (1) +automatically binds the device to both +.B /dev +and +.B /chan +when it starts up, if a window system is configured. +.SH SEE ALSO +.IR wm (1) diff --git a/man/3/srv b/man/3/srv new file mode 100644 index 00000000..70261be4 --- /dev/null +++ b/man/3/srv @@ -0,0 +1,88 @@ +.TH SRV 3 +.SH NAME +srv \- server registry +.SH SYNOPSIS +.BI "bind #s" +[ +.I spec +] +.B /chan +.PP +.EX +sys->bind("#s\fIspec\fP", "/chan", Sys->MREPL); +.EE +.SH DESCRIPTION +.I Srv +converts between file system operations by applications +and messages on channels, as described in +.IR sys-file2chan (2). +Each attach that does not include a +.I spec +produces a new instance: an empty directory owned +by the current user in which only files +may be created, and then only by +.IR sys-file2chan , +using a special internal interface. +Each such file initially has the same owner as the +directory, and permissions +.B 8r600 +(read-write for the owner only), +but the permissions can be changed by +.BR Sys->wstat +(see +.IR sys-stat (2)) +and thus +.IR chmod (1). +If mode +.B Sys->DMEXCL +is thereby set, the file becomes exclusive-use and can be opened by +only one process at a time. +The file length and +mode bit +.B Sys->DMAPPEND +may also be set by +.B wstat +but are not interpreted by the system. +.PP +Files may be removed, directly using +.IR sys-remove (2) +(and thus +.IR rm (1)), +or indirectly by opening them with mode +.B Sys->ORCLOSE +(see +.IR sys-open (2)). +.I File2chan +also removes the corresponding file when the last references +to the server's read and write channels have gone +(eg, on server exit). +.PP +A +.I spec +may be given to name specific instances of +.IR srv , +so that a new name space can bind in a service created in another. +Only the owner (original creator) of the instance may attach to it, +unless the mode of the service directory is changed +using +.B Sys->wstat +(see +.IR sys-stat (2)) +to have general access. +.SH FILES +.TF /chan +.TP +.B /chan +directory to which +.I srv +is conventionally bound by various applications +.SH SOURCE +.B /emu/port/devsrv.c +.br +.B /os/port/devsrv.c +.SH SEE ALSO +.IR plumb (1), +.IR wm (1), +.IR sys-file2chan (2) +.SH BUGS +A client with a read or write pending can remain blocked if the server exits before reply. diff --git a/man/3/srv9 b/man/3/srv9 new file mode 100644 index 00000000..e6dff525 --- /dev/null +++ b/man/3/srv9 @@ -0,0 +1,108 @@ +.TH SRV9 3 "Plan 9" +.SH NAME +srv9 \- plan 9 server registry +.SH SYNOPSIS +.nf +.B bind -c #₪ /srv + +.BI /srv/ service1 +.BI /srv/ service2 + ... +.fi +.SH DESCRIPTION +On Inferno hosted on Plan 9, +.I srv9 +serves a one-level directory that gives Inferno applications +direct access to Plan 9 services posted in its +.B #s +server registry, +and allows Inferno applications to post services for access by Plan 9 applications. +A service is represented by a file descriptor, usually serving the common file service +protocol described in +.IR intro (5), +allowing it to be mounted (see +.IR bind (1) +and +.IR sys-bind (2)) +in the name space of an application in the other system. +.PP +To access a Plan 9 service in Inferno, open the desired service file; +the resulting file descriptor is connected to the associated Plan 9 service. +When that service is a shared Plan 9 file service, +.I srv9 +automatically starts Plan 9's +.I exportfs +with appropriate options to make the service accessible from Inferno. +It can safely be shared with Plan 9 applications, but note that any path names +mentioned in the attach specifier (see +.IR mount (1) +and +.IR attach (5)) +will be in the Plan 9 application's name space, not the Inferno application's. +(Indeed, a similar caveat applies in Plan 9 itself.) +.PP +To export an Inferno service to Plan 9, create a new file such as +.BR /srv/myserv +using +.B Sys->create +with mode +.B Sys->ORDWR +(see +.IR sys-open (2)) +and any desired permissions for the new service file. +(Note that the +.B #₪ +device must have been bound in with the +.B -c +option, as shown above, to allow file creation.) +If the create is successful, Plan 9's service registry will have a new entry +.BR myserv , +and the file descriptor returned from +.B create +acts as a pipe to any Plan 9 application +that opens the associated service file in Plan 9. +Typically on the Inferno side the file descriptor is passed to +.IR sys-export (2) +or made the standard input of an Inferno file service +(see +.IR intro (4)). +The Plan 9 service file is automatically removed when the Inferno file descriptor is no longer referenced. +.SH EXAMPLES +To make Plan 9's factotum available in Inferno: +.IP +.EX +mount -Aa /srv/factotum /mnt +.EE +.PP +(Note the +.B -A +option to suppress Inferno authentication.) +.PP +To mount the Plan 9 file service from which a Plan 9 machine booted: +.IP +.EX +mount -9 /srv/boot /n/local +.EE +.PP +The +.B -9 +option to +.IR mount (1) +requests Plan 9 authentication; that could also have been used instead of +.B -A +in the previous example. +.PP +To make the environment variables of the current Inferno name space available to Plan 9: +.IP +.EX +fd := sys->create("/srv/infenv", Sys->ORDWR, 8r600); +sys->export(fd, "/env", Sys->EXPWAIT); +.EE +.SH SOURCE +.B /emu/Plan9/devsrv9.c +.SH SEE ALSO +.IR sys-bind (2), +.IR sys-open (2), +.IR sys-export (2), +.IR import (4), +.IR 9srvfs (4) diff --git a/man/3/ssl b/man/3/ssl new file mode 100644 index 00000000..eb53aa2e --- /dev/null +++ b/man/3/ssl @@ -0,0 +1,137 @@ +.TH SSL 3 +.SH NAME +ssl \- secure sockets layer device +.SH SYNOPSIS +.B bind '#D' /n/ssl +.PP +.B /n/ssl/clone +.br +.BI /n/ssl/ n +.br +.BI /n/ssl/ n /data +.br +.BI /n/ssl/ n /ctl +.br +.BI /n/ssl/ n /secretin +.br +.BI /n/ssl/ n /secretout +.SH DESCRIPTION +The +.I ssl +device provides access to a Secure Socket Layer that implements the record layer protocol +of SSLv2. +The device provides encrypting and digesting for many independent connections. +Once associated with a network connection, the +.I ssl +device can be thought of as a filter for the connection. +.I Ssl +can send data in the clear, digested or encrypted. In all cases, if +.I ssl +is associated with both ends of a connection, all messages are delimited. +As long as reads always specify buffers that are of equal or greater lengths than the writes at the other end of the connection, one write will correspond to one read. +.PP +The top-level directory contains a +.B clone +file and numbered directories, each representing a connection. +Opening the +.B clone +file reserves a connection; the file descriptor resulting from the +.IR \%sys-open (2) +will be open on the control file, +.BR ctl , +in the directory that represents the new connection. +Reading the control file will return a text string giving the connection number +(and thus the directory name). +.PP +Writing to +.B ctl +controls the corresponding connection. +The following control messages are possible: +.TP +.BI fd " n" +Associate the network connection on file descriptor +.I n +with the +.I ssl +device. +.TP +.B alg clear +Allow data to pass in the clear with only message delimiters added. The device starts in this mode. +.TP +.B alg sha +Append a SHA digest to each buffer written to +.BR data . +The digest covers the outgoing secret (written to +.BR secretout ), +the message, and a message number which starts at 0 and increments by one for each message. +Messages read have their appended digests compared to a digest computed using the incoming secret (written to +.BR secretin ). +If the comparison fails, so will the read. +.TP +.B alg md4 +Like +.B sha +but using the MD4 message digest algorithm. +.TP +.B alg md5 +Like +.B sha +but using the MD5 message digest algorithm. +.TP +.B alg rc4 +.PD0 +.TP +.B alg rc4_40 +.TP +.B alg rc4_128 +.TP +.B alg rc4_256 +RC4 encrypt each message written to +.B data +with the key written to +.BR secretout , +using the key length as indicated (40-bit keys by default). +.PD +.TP +.B alg des_56_cbc +Encrypt the stream using DES and Cipher Block Chaining (CBC) +.TP +.B alg des_56_ecb +Encrypt the stream using DES and Electronic Code Book (ECB) +.TP +.B alg ideacbc +Encrypt the stream using IDEA and CBC +.TP +.B alg ideaecb +Encrypt the stream using IDEA and ECB +.TP +.BI alg " digest" / crypt +Combine the use of the given +.I digest +algorithm and the stream encryption algorithm +.IR crypt +.PP +Files +.B secretin +and +.B secretout +must be written before digesting or encryption is turned on. If only one is written, they are both assumed to be the same. +.PP +The mode may be changed at any time during a connection. +.PP +The list of algorithms supported by a given implementation of +.I ssl +may be read from the read-only text files +.B encalgs +(encryption algorithms) +and +.B hashalgs +(hashing algorithms for digests). +Each contains a space-separated list of algorithm names. +.PP +.SH "SEE ALSO" +.IR security-ssl (2) +.br +B. Schneier, +.IR "Applied Cryptography , +1996, J. Wiley & Sons, Inc. diff --git a/man/3/switch b/man/3/switch new file mode 100644 index 00000000..4c74db66 --- /dev/null +++ b/man/3/switch @@ -0,0 +1,28 @@ +.TH SWITCH 3 MPC8xx +.SH NAME +switch \- hardware option switch +.SH SYNOPSYS +.nf +.B bind -a '#r' /dev + +.B /dev/switch +.fi +.SH DESCRIPTION +.PP +The switch device serves a one-level directory, +giving access to one read-only file, +.BR switch . +A read returns the value of the development board's +option switch (DS1), represented as a decimal number +from 0 to 15, representing four bits, +each corresponding to one of the four toggles. +Each toggle produces the value 0 when it +is set `ON' and 1 when it is off. +Toggle 1 corresponds to bit +.B 1<<3 +in the number, +toggle 2 corresponds to bit +.BR 1<<2 , +and so on +.SH SOURCE +.B /os/mpc/devrtc.c diff --git a/man/3/tinyfs b/man/3/tinyfs new file mode 100644 index 00000000..cbabe2b5 --- /dev/null +++ b/man/3/tinyfs @@ -0,0 +1,45 @@ +.TH TINYFS 3 +.SH NAME +tinyfs \- file system for miniscule devices +.SH SYNOPSIS +.EX +bind -c #F\fIname\fP /nvfs +.EE +.SH DESCRIPTION +.I Tinyfs +provides file system access to the contents of low-capacity devices, +ranging from several hundred bytes (at least 144 bytes) to at most the order of a kilobyte. +It is provided to support file system access to small non-volatile memories, +as for instance are found in some real-time clock chips, +where IDs, keys, PINs, certificates and the like might be stored by either client or server. +.PP +The file system has only one directory, its root, which can contain only files. +Once created, a write can only append to a file; random updates are not allowed, +although the file could be truncated and rewritten. +.PP +The device specifier following the +.B #F +device name is the +.I name +of a file in +.B /dev +on which the tiny file system will live. +For instance, +.B #Fnvram +refers to +.BR /dev/nvram . +The device must allow seek and write. +During the +.IR attach , +the system scans the device, checking the file system structure +by building a table of files, and checking a checksum stored +in each block; inconsistent structure is reinitialised, and thus +a previously unused device will emerge correctly formatted as an empty tiny file system. +.SH FILES +.TF /nvfs +.TP +.B /nvfs +conventional mount point used by +.IR init (8) +.SH SOURCE +.B /os/port/devtinyfs.c diff --git a/man/3/tls b/man/3/tls new file mode 100644 index 00000000..267afdea --- /dev/null +++ b/man/3/tls @@ -0,0 +1,276 @@ +.TH TLS 3 +.SH NAME +tls \- TLS1 and SSL3 record layer +.SH SYNOPSIS +.nf +.B bind -a #a /net + +.B /net/tls/clone +.B /net/tls/encalgs +.B /net/tls/hashalgs +.BI /net/tls/ n +.BI /net/tls/ n /ctl +.BI /net/tls/ n /data +.BI /net/tls/ n /hand +.BI /net/tls/ n /stats +.BI /net/tls/ n /status +.fi +.SH DESCRIPTION +The TLS device implements the record layer protocols +of Transport Layer Security version 1.0 and Secure Sockets Layer version 3.0. +It does not implement the handshake protocols, which are responsible for +mutual authentication and key exchange. +The +.I tls +device can be thought of as filters providing optional encryption and anti-tampering. +.PP +The top level directory contains a +.B clone +file and subdirectories numbered from zero through at least the last active filter. +Opening the +.B clone +file reserves a filter. +The file descriptor returned from the +.IR sys-open (2) +will point to the control file, +.BR ctl , +of the newly allocated filter. +Reading the +.B ctl +file returns a text string containing the number of the filter directory. +.PP +The filter initially cannot be used to pass messages +and will not encrypt or digest messages. +It is configured and controlled by writing commands to +.BR ctl . +.PP +The following commands are supported: +.TP +.BI fd \ open-fd\ vers +Pass record messages over the communications channel +.IR open-fd . +Initially, outgoing messages use version +.I vers +format records, but incoming messages of either version are accepted. +Valid versions are +.B 0x300 +for SSLv3.0 and +.B 0x301 +for TLSv1.0 (which could be known as SSLv3.01.) +This command must be issued before any other command +and before reading or writing any messages; +it may only be executed once. +.TP +.BI version \ vers +Use +.I vers +format records for all future records, +both outgoing and incoming. +This command may only be executed once. +.TP +.BI secret \ hashalg\ encalg\ isclient\ secretdata +Set up the digesting and encryption algorithms and secrets. +.I Hashalg +and +.I encalg +must be algorithm names returned by the corresponding files. +.I Secretdata +is the base-64 encoded (see +.IR encode (2)) +secret data used for the algorithms. +It must contain at least enough data to populate the +secrets for digesting and encrypting. +These secrets are divided into three categories: digest secrets, keys, and initialization vectors. +The secrets are packed in this order, with no extra padding. +Within each category, the secret for data traveling from the client to the server comes first. +The incoming and outgoing secrets are automatically selected by devtls based on the +.I isclient +argument, which must be non-zero for the client of the TLS handshake, +and zero for the server. +.br +This command must be issued after +.BR version , +and may be issued more than once. +At least one new +.I secret +command must be issued before each +.I changecipher +command; similarly, at least one new +.I secret command +must precede each incoming changecipher message. +.TP +.BI changecipher +Enable outgoing encryption and digesting as configured by the previous +.I secret +command. +This command sends a +.I changecipher +message. +.TP +.BI opened +Enable data messages. +This command may be issued any number of times, +although only the first is significant. +It must follow at least one successful +.I changecipher +command. +.TP +.BI alert \ alertno +Send an alert message. +.I Alertno +may be a valid alert code for either SSLv3.0 or TLSv1.0, +and is mapped to an appropriate code for the protocol in use. +If it is a fatal alert, the filter is set into an error state. +.PP +Application messages and handshake messages are communicated using +.I data +and +.IR hand , +respectively. +Only one +.IR sys-open (2) +of +.I hand +is allowed at a time. +.PP +Any record layer headers and trailers are inserted and +stripped automatically, and are not visible from the outside. +The device tries to synchronize record boundaries with reads and writes. +Each read will return data from exactly one record, +and will return all of the data from the record as long as +the buffer is big enough. +Each write will be converted into an integral number of records, +with all but potentially the last being maximal size. +The maximum record length supported is 16384 bytes. +This behavior is not specified in the protocols, +and may not be followed by other implementations. +.PP +If a fatal alert message is received, or a fatal +.I alert +command issued, the filter is set into an error state. +All further correspondence is halted, +although some pending operations may not be terminated. +Operations on +.I data +will fail with a +.BR "'tls error'" , +and operations on +.I hand +will fail with a textual decoding of the alert. +The current non-fatal alert messages are +.BR "'close notify'" , +.BR "'no renegotiation'" , +and +.BR "'handshake canceled by user'" . +Receipt of one of these alerts cause the next read on +.I hand +to terminate with an error. +If the alert is +.BR "'close notify'", +all future reads will terminate with a +.B "tls hungup" +error. +A +.B "'close notify'" +.I alert +command will terminate all future writes or reads from +.I data +with a +.B "'tls hungup'" +error. +.PP +If an error is encountered while reading or writing +the underlying communications channel, the error is returned +to the offending operation. +If the error is not +.BR "'interrupted'" , +the filter is set into the error state. +In this case, all future operations on +.I hand +will fail with a +.BR "'channel error'" . +.PP +When all file descriptors for a filter have been closed, +the session is terminated and the filter reclaimed for future use. +A +.B "'close notify'" +alert will be sent on the underlying communications channel +unless one has already been sent or the filter is in the error state. +.PP +Reading +.I stats +or +.I status +returns information about the filter. +Each datum is returned on a single line of the form +.IB tag ": " data . +.I Stats +returns the number of bytes communicated by the +.B data +and +.B hand +channels. +The four lines returned are tagged by, in order, +.BR DataIn , +.BR DataOut , +.BR HandIn , +and +.BR HandOut . +.I Status +returns lines following tags: +.BR State , +.BR Version , +.BR EncIn , +.BR HashIn , +.BR NewEncIn , +.BR NewHashIn , +.BR EncOut , +.BR HashOut , +.BR NewEncOut , +and +.BR NewHashOut . +.BR State 's +value is a string describing the status of the connection, +and is one of the following: +.BR 'Handshaking' , +.BR 'Established' , +.BR 'RemoteClosed' , +.BR 'LocalClosed' , +.BR 'Alerting' , +.BR 'Errored' , +or +.BR 'Closed' . +.BR Version 's +give the hexadecimal record layer version in use. +The +.B Enc +and +.B Hash +fields return name of the current algorithms in use +or ready to be used, if any. +.PP +Reading +.I encalgs +and +.I hashalgs +will give the space-separated list of algorithms implemented. +This will always include +.BR clear , +meaning no encryption or digesting. +Currently implemented encryption algorithms are +.B 'rc4_128' +and +.BR '3des_ede_cbc' . +Currently implemented hashing algorithms are +.B 'md5' +and +.BR 'sha1' . +.SH "SEE ALSO" +.IR listen (1), +.IR sys-dial (2), +.IR ssl (3) +\".IR pushtls (2) +.SH SOURCE +.B /emu/port/devtls.c +.br +.B /os/port/devtls.c diff --git a/man/3/touch b/man/3/touch new file mode 100644 index 00000000..d86933d1 --- /dev/null +++ b/man/3/touch @@ -0,0 +1,138 @@ +.TH TOUCH 3 +.SH NAME +touch \- touch screen +.SH SYNOPSIS +.EX +bind -a '#T' /dev + +/dev/touchcal +/dev/touchctl +/dev/touchstat +/dev/touch +.EE +.SH DESCRIPTION +The touch screen driver +serves a one-level directory giving access to a touch panel. +The driver attempts to compensate +for the warped nature of the panels we have used: +amongst other things, +it repeatedly samples the panel to obtain a stable reading, +and applies a transformation to the +.RI ( "x, y" ) +coordinates obtained to account for the peculiar distortions of individual panels. +A panel should be calibrated by +.IR touchcal (8) +before use. +.PP +There are two variants of the driver. +One drives a +DynaPro touch panel +on a York Electronics Centre BRD/98/024 interface (Version A) +accessed via the Motorola MPC8xx SPI interface. +The other drives a different pressure-sensitive touch panel on a webphone reference design. +.PP +The driver initialisation starts a kernel process to read samples from the +touch screen and provide them to the system through the interface used +for mouse events. +The events generated mark +`mouse button' 1 as down as long as the panel is touched and up otherwise. +Other `mouse buttons' are always up. +This is adequate for many applications (but not +.IR acme (1)). +.PP +The data file +.B touch +is read-only. +Each read samples the touch panel +and returns two decimal numbers, separated by a space, +giving the +.I x +and +.I y +coordinates read. +The values are both -1 if a consistent reading could not be made. +This file is used only for debugging; the window system should not be running. +.PP +The control file +.B touchctl +accepts commands to set driver parameters: +.TF "X a b c" +.PD +.TP +.BI X " a b c" +(MPC8xx only) Set the parameters for a transformation of the X-coordinates received from the +panel: +.RS +.IP +.IR "x' = a*x+b*y+c" +.PP +The values are fixed-point: 1.0 is represented by 2\u\s-216\s0\d. +.RE +.TP +.BI Y " d e f" +(MPC8xx only) Set the parameters for a similar transformation of Y-coordinates: +.RS +.IP +.IR "y' = d*x+e*y+f" +.RE +.TP +.BI s n +Sample every +.I n +milliseconds. +.TP +.BI c "p sx sy" +(SA1100) Wait for the screen to be touched and sample parameters for point +.IR p , +0\(<=\fIp\fP\(<=3, +corresponding to one of the four corners of the screen. +Save the sample parameters for calibration. +.TP +.B C +(SA1100) Compute calibration parameters based on previously stored samples. +.TP +.BI r n +Sets delay between touch reads. +.TP +.BI R n +Average +.RI 2 ^n +readings each sample. +.TP +.BI f n +Set the filter level (-1024 \(<=\fIn\fP\(<=1024). +.TP +.BI e "x y" +Set error term for +.I x +and +.IR y ; +normally calculated by +.BR C . +.TP +.BI t "p r" +Set pressure threshold for press and release +.PP +Reads of +.B touchctl +return all current parameters in the same form as the commands +(allowing settings to be read from the file and later restored by simply writing them back). +.PP +The read-only file +.B touchstat +contains four decimal values separated by spaces or newlines: +the number of raw samples, the number of valid samples, +microseconds waiting for samples, and microseconds spent processing samples. +.PP +The SA1100 driver +provides a file +.B /dev/touchcal +that holds the calibration results as a set of +decimal numbers for each of the four sample points, one set per line. +The results can be saved and written back to restore the same calibration. +.SH SOURCE +.B /os/mpc/devtouch.c +.br +.B /os/sa1100/devtouch.c +.SH SEE ALSO +.IR touchcal (8) diff --git a/man/3/tv b/man/3/tv new file mode 100644 index 00000000..bc3fb378 --- /dev/null +++ b/man/3/tv @@ -0,0 +1,179 @@ +.TH TV 3 +.SH NAME +tv \- Hauppage TV device +.SH NAME +.B +bind -b #V /dev +.PP +.B /dev/tv +.br +.B /dev/tvctl +.SH DESCRIPTION +The +.I tv +device serves two files giving access to a Hauppage television card +in NTSC mode (only). +.PP +The control device +.B tvctl +accepts the following commands to control +tuning and image processing: +.TP +.B init +Reset the device to the default settings. +.TP +.BI window " minx miny maxx maxy" +Set the display window size (default: none). +.TP +.BI colorkey " rl rh gl gh bl bh" +Set the key limits for chromakey display to +the given `low' and `high' values for +each of red, green and blue +(default: 15 63 255 15 15 63), and enable +use of the colour key. +The value 255 for a lower limit disables the limit. +.TP +.BI capture " minx miny maxx maxy" +Set the capture window (default: none); +see the description of reading the +.B tv +file, below. +.TP +.BI capbrightness " n" +Set the brightness of a captured frame to +.IR n , +on a scale from 0 to 100 +(default: 13). +.TP +.BI capcontrast " n" +Set the contrast of a captured frame to +.IR n , +on a scale from 0 to 100 +(default: 57). +.TP +.BI capsaturation " n" +Set the saturation of a captured frame to +.IR n , +on a scale from 0 to 100 +(default: 51). +.TP +.BI caphue " n" +Set the hue of a captured frame to +.IR n , +on a scale from 0 to 100 +(default: 0). +.TP +.BI capbw " n" +Capture colour +.RI ( n=0 ) +or monochrome +.RI ( n=1 ); +(default: 0). +.TP +.BI brightness " n" +Set the image brightness to +.IR n , +on a scale from 0 to 100 +(default: 0) +.TP +.BI contrast " n" +Set the image contrast to +.IR n , +on a scale from 0 to 100 +(default: 54) +.TP +.BI saturation " n" +Set image saturation to +.IR n , +on a scale from 0 to 100 +(default: 54) +.TP +.BI source " n" +Set the input source to +.I n +(default: video input 0). +.TP +.BI svideo " n" +If +.I n +is non-zero, set the input capture format to +S-Video. +.TP +.BI format " n" +Set the input format to +.I n +(0, NTSC-M; 1, NTSC-443; 2, external control). +Default: 0. +.TP +.BI channel " c f" +Sets the right frequency for HRC CATV channel +.IR c , +with fine tuning by signed offset +.I f +(in MHz). +.TP +.BI volume " m" [ " n " ] +Set the volume of left and right channels to +.I m +and +.IR n , +on a scale from 0 to 100 +(default: 80). +If only +.I m +is given, set both left and right volumes to +.IR m . +.TP +.BI bass " n" +Set the bass to +.IR n , +on a scale from 0 to 100 (default: 50). +.TP +.BI treble " n" +Set the treble to +.IR n , +on a scale from 0 to 100 (default: 50). +.TP +.BI freeze " n" +If +.I n +is non-zero, freeze the current frame; +if +.I n +is zero, unfreeze the video. +.PP +The data file +.B tv +is read-only. +Reading is valid only after a capture window has been set +(see +.B capture +above). +Each read at file offset 0 causes the contents of the input video image +within the previously-set capture window to be +captured. +The frame data is successively returned +in this and subsequent reads until a short read signals that +all frame data has been transferred. +The data is returned in Plan 9 +.I picfile +format, with a two line textual header followed by an empty +line, followed by the image data in binary format. +The header has the form: +.IP +.B "TYPE=ccir601" +.br +.BI "WINDOW=" "minx miny maxx maxy" +.PP +The +.B WINDOW +coordinates are those of the capture window. +The image data is organised as interleaved scan lines from top to bottom of the window, +with UY0 and VY1 values alternating, with two bytes per value, stored high-order byte +first, encoded according to the IEEE digital component video standard. +.SH SOURCE +.B /os/port/devtv.c +.br +.B /os/pc/tv.h +.SH SEE ALSO +.IR audio (3) diff --git a/man/3/usb b/man/3/usb new file mode 100644 index 00000000..90ebc851 --- /dev/null +++ b/man/3/usb @@ -0,0 +1,143 @@ +.TH USB 3 MPC823 +.SH NAME +usb \- USB device interface +.SH SYNOPSYS +.nf +.B bind -a '#U' /dev + +.B /dev/usbctl +.B /dev/usbdata +.B /dev/usbstat +.B /dev/usbaddr +.B /dev/usbframe +.B /dev/usbsetup +.fi +.SH DESCRIPTION +.PP +The USB device serves a one-level directory, +giving access to six files. +They provide an interface to the device (slave) mode of the 823/850 USB controller, +allowing an Inferno system to provide services to the USB host. +The controller's endpoints are configured as follows. +Endpoint 0 is the default USB control endpoint, as required by the USB standard. +Endpoint 1 responds to bulk output requests from the host; +endpoint 2 responds to bulk input requests from the host; +endpoint 3 is unused. +.PP +The data file +.B usbdata +provides read and write access to endpoints 1 and 2. +When the file is read, it returns data written to endpoint 1 by the USB host. +Data written to the file is provided in response to the host's read requests +on endpoint 2. +Output data is converted to packets limited to the maximum packet +length for the endpoint (see the +.B maxpkt +control request, below), which is 1023 bytes by default. +Note that zero length records can be transmitted and +received on USB. +.PP +The file +.B usbsetup +provides read and write access to endpoint 0. +When the file is read, it returns +SETUP +requests from the host. +If a given request requires a reply, the reply must be written to the file +(host requests will automatically be NAKd until then). +Requests and replies are in binary form as defined in the USB specification, +except for the reset message described below. +The driver itself interprets all +SET_ADDRESS +requests from the host, and sets the controller's address accordingly. +That request will therefore not be visible on the +.B usbsetup +file. +.PP +A USB bus or device reset sets the controller's USB address to zero, +the USB `default address' for configuration. +It also resets all data toggles to DATA0. +A subsequent read of +.B usbsetup +will return the following special 8-byte reset message: +.IP +.EX +byte 16rFF, byte 16rFF, byte 'r', byte 'e', +.br +byte 's', byte 'e', byte 't', byte '\en' +.EE +.PP +which does not resemble a normal SETUP message. +Further reads and writes on +.B usbdata +will return errors until that file has been closed and reopened. +.PP +The control file +.B usbctl +receives textual commands to set device parameters and responses: +.TP +.BI maxpkt "n nb" +Set the maximum packet size for endpoint +.I n +to +.I nb +bytes. +.I Nb +must be between 8 and 64 bytes for the control endpoint 0, +and between 1 and 1023 bytes for the other endpoints. +The default is 8 bytes for endpoint 0 and 1023 bytes for the others. +.TP +.BI rdtog "n t" +Set the data toggle for input in endpoint +.I n +to +.IR t , +which must be either 0 (DATA0) or 1 (DATA1). +.TP +.BI stall "n" +Cause endpoint +.I n +to respond to host IN and OUT tokens by stalling. +.TP +.BI unstall "n" +Cancel the effect of a previous +.B stall +request on endpoint +.IR n . +.TP +.BI wrtog "n t" +Set the data toggle for the next packet output by endpoint +.I n +to +.IR t , +which must be either 0 (DATA0) or 1 (DATA1). +.PP +Stalling an endpoint causes IN and OUT +transactions from the host to return a `stalled' error status. +On the control endpoint (endpoint 0), however, +SETUP transactions will still arrive on +.BR usbsetup , +and the arrival of a SETUP will automatically clear the `stalled' status +for the endpoint, +allowing an application to reject a +control request (by stalling the subsequent status transaction) +without stalling the control endpoint by rejecting subsequent +SETUP transactions. +.PP +The status file +.B usbstat +is a read-only file, +containing one line of statistics for each endpoint, giving: +endpoint number; data toggles; maximum packet size; +count of input and output bytes and packets; and counts +of various error conditions. +.PP +The read-only file +.B usbaddr +contains a single number giving the current device address. +.PP +The read-only file +.B usbframe +contains a single line giving the current USB frame number. +.SH SOURCE +.B /os/mpc/devusb.c diff --git a/man/3/vga b/man/3/vga new file mode 100644 index 00000000..526d5231 --- /dev/null +++ b/man/3/vga @@ -0,0 +1,247 @@ +.TH VGA 3 +.SH NAME +vga \- VGA controller device +.SH SYNOPSIS +.B bind #v /dev +.PP +.B /dev/vgactl +.br +.B /dev/vgaovlctl +.br +.B /dev/vgaovl +.SH DESCRIPTION +The VGA device allows configuration of a graphics controller +on a PC (and any other platform with VGA devices). +.B Vgactl +allows control over higher-level settings such as display height, width, depth, +controller and hardware-cursor type. +Along with the I/O-port registers +provided by +.IR arch (3), +it is used to implement configuration and setup of VGA controller cards. +....This is usually performed by +.....IR vga (8). +.PP +Writing strings to +.B vgactl +configures the VGA device. +The following are valid commands. +.TP +.BI size " X" x Y x "Z chan" +Set the size of the screen image to be +.I X +pixels wide +and +.I Y +pixels high. +Each pixel is +.I Z +bits as specified by +.IR chan , +whose format is described in +.IR image (6). +.TP +.BI actualsize " X" x Y +Set the physical size of the display to be +.I X +pixels wide by +.I Y +pixels high. +This message is optional; +it is used to implement panning and to accommodate +displays that require the in-memory screen image +to have certain alignment properties. +For example, a 1400x1050 screen with a 1408x1050 in-memory image +will use +.B "size 1408x1050 +but +.BR "actualsize 1400x1050" . +.TP +.BI panning " mode" +Depending on whether +.I mode +is +.B on +or +.BR off , +enable or disable panning in a virtual screen. +If panning is on and the screen's +.B size +is larger than its +.BR actualsize , +the displayed portion of the screen will pan to follow the mouse. +Setting the panning mode after the first attach of the +.B #i +driver has no effect. +.TP +.BI type " ctlr" +Set the type of VGA controller being used. +.I Ctlr +is one of +.BR ark200pv , +.BR clgd542x , +.BR clgd546x , +.BR ct65545 , +.BR cyber938x , +.BR hiqvideo , +.BR mach64xx , +.BR mga2164w , +.BR neomagic , +.BR s3 , +and +.BR t2r4 . +.IP +Note that this list does not indicate the full set of VGA chips +supported. For example, +.B s3 +includes the 86C801/5, 86C928, Vision864, and Vision964. +It is the job of a user-level program +....IR vga (8) +to recognise which particular chip is being used and to initialize it +appropriately. +.TP +.BI hwgc " gc" +Set the type of hardware graphics cursor being used. +.I Gc +is one of +.BR ark200pvhwgc , +.BR bt485hwgc , +.BR clgd542xhwgc , +.BR clgd546xhwgc , +.BR ct65545hwgc , +.BR cyber938xhwgc , +.BR hiqvideohwgc , +.BR mach64xxhwgc , +.BR mga2164whwgc , +.BR neomagichwgc , +.BR rgb524hwgc , +.BR s3hwgc , +.BR t2r4hwgc , +.BR tvp3020hwgc , +and +.BR tvp3026hwgc . +A value of +.B off +disables the cursor. +There is no software cursor. +.TP +.BI palettedepth " d" +Set the number of bits of precision used by the +VGA palette to +.IR d , +which must be either +.B 6 +or +.BR 8 . +.TP +.B blank +Blank the screen. +This consists of setting the hardware +color map to all black as well as, on some controllers, setting the +VGA hsync and vsync signals so as to turn off +VESA DPMS-compliant monitors. +The screen also blanks after 30 minutes of inactivity. +The screen can be unblanked by moving the mouse. +.TP +.BI blanktime " minutes" +Set the timeout before the +screen blanks; the default is 30 minutes. +If +.I minutes +is zero, blanking is disabled. +.TP +.BI hwaccel " mode" +Depending on whether +.I mode +is +.B on +or +.BR off , +enable or disable whether hardware acceleration +(currently for rectangle filling and moving) +used by the graphics engine. +The default setting is +.BR on . +.TP +.BI hwblank " mode" +Depending on whether +.I mode +is +.B on +or +.BR off , +enable or disable the use of DPMS blanking +(see +.B blank +above). +.TP +.BI linear " size align" +Use a linear screen aperture of size +.I size +aligned on an +.IR align -byte +boundary. +.TP +.B drawinit +Initialize the graphics hardware. +This must be sent after setting the +.BR type . +.PP +Reading +.B vgactl +returns the current settings, one per line. +.PP +Some VGA cards support overlay graphics. +Writing strings to +.B vgaovlctl +configures such cards. +The following are valid overlay control commands: +.TP +.BI openctl +opens the overlay device. +.TP +.BI configure " w h format" +allocates resources inside the driver to support an overlay area +of width +.I w +and height +.I h +pixels. Currently, the only supported +.I format +is +.B YUYV +packed. +In +.B YUYV +two pixels are encoded by their separate Y values +and their combined U and V values. +The size of the two pixels is 32 bits. +.TP +.BI enable " x y w h" +enables drawing data on the display through the overlay mode. The data +is drawn at position +.IR x , y +and has a width and height of +.IR w , h +respectively. +.TP +.BI closectl +terminates overlay control. +.PP +Overlay data can be written to +.BR vgaovl . +.SH EXAMPLES +The following disables hardware acceleration. +.IP +.EX +echo hwaccel off > /dev/vgactl +.EE +.SH SOURCE +.B /os/pc/devvga.c +.SH SEE ALSO +.IR arch (3) +....IR vga (8) +.SH BUGS +The hardware graphics cursor on the +.B et4000 +does not work in 2x8-bit mode. diff --git a/man/3/vid b/man/3/vid new file mode 100644 index 00000000..e21645e6 --- /dev/null +++ b/man/3/vid @@ -0,0 +1,64 @@ +.TH VID 3 MPC823 +.SH NAME +vid \- Motorola 823 video output +.SH SYNOPSIS +.B bind -b #v /dev +.PP +.B /dev/viddata +.br +.B /dev/vidctl +.br +.B /dev/vidcram +.SH DESCRIPTION +The +.I vid +device serves two +files giving basic access +to the on-chip video output of the Motorola 823. +It assumes a video hardware configuration exactly like that of the 823FADS +board, with an I²C interface to an off-chip ADV7176 NTSC/PAL converter +at I²C address 0x54. +.PP +The control device +.B vidctl +accepts the following commands: +.TP +.B on +Disable LCD panel (if present) and enable output from the video frame buffer. +.TP +.B off +Stop display from the video frame buffer and re-enable the LCD panel (if present). +.TP +.BI mode " m" +Set the video output format to +.IR m , +which is one of: +.BR ntsc , +.BR pal-i , +.B pal-m +or +.BR pal-n . +This command is only effective when video output is off. +When next switched on, the both the video controller RAM and +ADV7176 are reprogrammed to the new format. +.PP +Video data can be written to the video frame buffer +by writes of the +.B viddata +file. +The file offset selects the starting byte within the frame buffer. +Reads return the corresponding data from the frame buffer. +The application is responsible for formatting the data as the 823's video +encoder requires, for the selected video format. +.PP +The file +.B vidcram +gives read and write access to the contents of the +video control RAM. +The file offset addresses bytes in the RAM; values can be read from or +written to the RAM in groups of 4-byte big-endian words. +.SH SOURCE +.B /os/mpc/devvid.c +.SH BUGS +Square pixel mode cannot be used on the FADS board: +no suitable video clock source is available. |