feat: Added NetBSD man pages

1 files changed, 514 insertions, 0 deletions

diff --git a/static/netbsd/man9/microseq.9 b/static/netbsd/man9/microseq.9
new file mode 100644
index 00000000..39bb3c04
--- /dev/null
+++ b/static/netbsd/man9/microseq.9
@@ -0,0 +1,514 @@
+.\" $NetBSD: microseq.9,v 1.6 2017/07/03 21:28:48 wiz Exp $
+.\"
+.\" Copyright (c) 1998, 1999, Nicolas Souchu
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD: src/share/man/man9/microseq.9,v 1.9.2.5 2001/12/17 11:30:18 ru Exp $
+.\"
+.Dd December 29, 2003
+.Dt MICROSEQ 9
+.Os
+.Sh NAME
+.Nm microseq
+.Nd ppbus microseqencer developer's guide
+.Sh SYNOPSIS
+.In sys/types.h
+.In dev/ppbus/ppbus_conf.h
+.In dev/ppbus/ppbus_msq.h
+.Sh DESCRIPTION
+See
+.Xr ppbus 4
+for
+.Nm ppbus
+description and general info about the microsequencer.
+.Pp
+The purpose of this document is to encourage developers to use the
+microsequencer mechanism in order to have:
+.Bl -enum -offset indent
+.It
+a uniform programming model
+.It
+efficient code
+.El
+.Pp
+Before using microsequences, you are encouraged to look at the
+.Xr atppc 4
+microsequencer implementation and an example of how using it in
+.Xr vpo 4 .
+.Ss PPBUS register model
+.Ss Background
+The parallel port model chosen for
+.Xr ppbus 4
+is the PC parallel port model.
+Thus, any register described later has the same semantic than its
+counterpart in a PC parallel port.
+For more info about ISA/ECP programming, get the
+Microsoft standard referenced
+.Dq Tn "Extended Capabilities Port Protocol and ISA interface Standard" .
+Registers described later are standard parallel port registers.
+.Pp
+Mask macros are defined in the standard
+.Xr ppbus 4
+include files for each valid bit of parallel port registers.
+.Ss Data register
+In compatible or nibble mode, writing to this register will drive
+data to the parallel port data lines.
+In any other mode, drivers may be tri-stated by setting the direction
+bit (PCD) in the control register.
+Reads to this register return the value on the data lines.
+.Ss Device status register
+This read-only register reflects the inputs on the parallel port
+interface.
+.Pp
+.Bl -column "Bit" "Name" "Description" -compact
+.It Em Bit Ta Em Name Ta Em Description
+.It 7 Ta nBUSY Ta "inverted version of parallel port Busy signal"
+.It 6 Ta nACK Ta "version of parallel port nAck signal"
+.It 5 Ta PERROR Ta "version of parallel port PERROR signal"
+.It 4 Ta SELECT Ta "version of parallel port Select signal"
+.It 3 Ta nFAULT Ta "version of parallel port nFault signal"
+.El
+.Pp
+Others are reserved and return undefined result when read.
+.Ss Device control register
+This register directly controls several output signals as well as
+enabling some functions.
+.Pp
+.Bl -column "Bit" "Name    " "Description" -compact
+.It Em Bit Ta Em Name Ta Em Description
+.It 5 Ta PCD Ta "direction bit in extended modes"
+.It 4 Ta IRQENABLE Ta "1 enables an interrupt on the rising edge of nAck"
+.It 3 Ta SELECTIN Ta "inverted and driven as parallel port nSelectin signal"
+.It 2 Ta nINIT Ta "driven as parallel port nInit signal"
+.It 1 Ta AUTOFEED Ta "inverted and driven as parallel port nAutoFd signal"
+.It 0 Ta STROBE Ta "inverted and driven as parallel port nStrobe signal"
+.El
+.Sh MICROINSTRUCTIONS
+.Ss Description
+.Em Microinstructions
+are either parallel port accesses, program iterations, submicrosequence
+or C calls.
+The parallel port must be considered as the logical model described in
+.Xr ppbus 4 .
+.Pp
+Available microinstructions are:
+.Bd -literal
+#define MS_OP_GET       0	/* get <ptr>, <len>			*/
+#define MS_OP_PUT       1	/* put <ptr>, <len>			*/
+#define MS_OP_RFETCH	2	/* rfetch <reg>, <mask>, <ptr>		*/
+#define MS_OP_RSET	3	/* rset <reg>, <mask>, <mask>		*/
+#define MS_OP_RASSERT	4	/* rassert <reg>, <mask>		*/
+#define MS_OP_DELAY     5	/* delay <val>				*/
+#define MS_OP_SET       6	/* set <val>				*/
+#define MS_OP_DBRA      7	/* dbra <offset>			*/
+#define MS_OP_BRSET     8	/* brset <mask>, <offset>		*/
+#define MS_OP_BRCLEAR   9	/* brclear <mask>, <offset>		*/
+#define MS_OP_RET       10	/* ret <retcode>			*/
+#define MS_OP_C_CALL	11	/* c_call <function>, <parameter>	*/
+#define MS_OP_PTR	12	/* ptr <pointer>			*/
+#define MS_OP_ADELAY	13	/* adelay <val>				*/
+#define MS_OP_BRSTAT	14	/* brstat <mask>, <mask>, <offset>	*/
+#define MS_OP_SUBRET	15	/* subret <code>			*/
+#define MS_OP_CALL	16	/* call <microsequence>			*/
+#define MS_OP_RASSERT_P	17	/* rassert_p <iter>, <reg>		*/
+#define MS_OP_RFETCH_P	18	/* rfetch_p <iter>, <reg>, <mask>	*/
+#define MS_OP_TRIG	19	/* trigger <reg>, <len>, <array>	*/
+.Ed
+.Ss Execution context
+The
+.Em execution context
+of microinstructions is:
+.Bl -bullet -offset indent
+.It
+the
+.Em program counter
+which points to the next microinstruction to execute either in the
+main microsequence or in a subcall
+.It
+the current value of
+.Em ptr
+which points to the next char to send/receive
+.It
+the current value of the internal
+.Em branch register
+.El
+.Pp
+This data is modified by some of the microinstructions, not all.
+.Ss MS_OP_GET and MS_OP_PUT
+are microinstructions used to do either predefined standard
+.Tn IEEE1284-1994
+transfers or programmed non-standard I/O.
+.Ss MS_OP_RFETCH - Register FETCH
+is used to retrieve the current value of a parallel port register,
+apply a mask and save it in a buffer.
+.Pp
+Parameters:
+.Bl -enum -offset indent
+.It
+register
+.It
+character mask
+.It
+pointer to the buffer
+.El
+.Pp
+Predefined macro: MS_RFETCH(reg,mask,ptr)
+.Ss MS_OP_RSET - Register SET
+is used to assert/clear some bits of a particular parallel port
+register, two masks are applied.
+.Pp
+Parameters:
+.Bl -enum -offset indent
+.It
+register
+.It
+mask of bits to assert
+.It
+mask of bits to clear
+.El
+.Pp
+Predefined macro: MS_RSET(reg,assert,clear)
+.Ss MS_OP_RASSERT - Register ASSERT
+is used to assert all bits of a particular parallel port register.
+.Pp
+Parameters:
+.Bl -enum -offset indent
+.It
+register
+.It
+byte to assert
+.El
+.Pp
+Predefined macro: MS_RASSERT(reg,byte)
+.Ss MS_OP_DELAY - microsecond DELAY
+is used to delay the execution of the microsequence.
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+delay in microseconds
+.El
+.Pp
+Predefined macro: MS_DELAY(delay)
+.Ss MS_OP_SET - SET internal branch register
+is used to set the value of the internal branch register.
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+integer value
+.El
+.Pp
+Predefined macro: MS_SET(accum)
+.Ss MS_OP_DBRA - \&Do BRAnch
+is used to branch if internal branch register decremented by one result value
+is positive.
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+integer offset in the current executed (sub)microsequence.
+Offset is added to
+the index of the next microinstruction to execute.
+.El
+.Pp
+Predefined macro: MS_DBRA(offset)
+.Ss MS_OP_BRSET - BRanch on SET
+is used to branch if some of the status register bits of the parallel port
+are set.
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+bits of the status register
+.It
+integer offset in the current executed (sub)microsequence.
+Offset is added to
+the index of the next microinstruction to execute.
+.El
+.Pp
+Predefined macro: MS_BRSET(mask,offset)
+.Ss MS_OP_BRCLEAR - BRanch on CLEAR
+is used to branch if some of the status register bits of the parallel port
+are cleared.
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+bits of the status register
+.It
+integer offset in the current executed (sub)microsequence.
+Offset is added to the index of the next microinstruction to execute.
+.El
+.Pp
+Predefined macro: MS_BRCLEAR(mask,offset)
+.Ss MS_OP_RET - RETurn
+is used to return from a microsequence.
+This instruction is mandatory.
+This is the only way for the microsequencer to detect the end of
+the microsequence.
+The return code is returned in the integer pointed by the (int *)
+parameter of the ppb_MS_microseq().
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+integer return code
+.El
+.Pp
+Predefined macro: MS_RET(code)
+.Ss MS_OP_C_CALL - C function CALL
+is used to call C functions from microsequence execution.
+This may be useful when a non-standard I/O is performed to retrieve
+a data character from the parallel port.
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+the C function to call
+.It
+the parameter to pass to the function call
+.El
+.Pp
+The C function shall be declared as a
+.Ft int(*)(void *p, char *ptr) .
+The ptr parameter is the current position in the buffer currently
+scanned.
+.Pp
+Predefined macro: MS_C_CALL(func,param)
+.Ss MS_OP_PTR - initialize internal PTR
+is used to initialize the internal pointer to the currently scanned
+buffer.
+This pointer is passed to any C call (see above).
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+pointer to the buffer that shall be accessed by
+.Fn xxx_P
+microsequence calls.
+Note that this pointer is automatically incremented during
+.Fn xxx_P
+calls.
+.El
+.Pp
+Predefined macro: MS_PTR(ptr)
+.Ss MS_OP_ADELAY - do an Asynchronous DELAY
+is used to make a
+.Xr cv_timedwait 9
+during microsequence execution.
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+delay in ms
+.El
+.Pp
+Predefined macro: MS_ADELAY(delay)
+.Ss MS_OP_BRSTAT - BRanch on STATe
+is used to branch on status register state condition.
+.Pp
+Parameter:
+.Bl -enum -offset indent
+.It
+mask of asserted bits.
+Bits that shall be asserted in the status register
+are set in the mask
+.It
+mask of cleared bits.
+Bits that shall be cleared in the status register
+are set in the mask
+.It
+integer offset in the current executed (sub)microsequence.
+Offset is added
+to the index of the next microinstruction to execute.
+.El
+.Pp
+Predefined macro: MS_BRSTAT(asserted_bits,clear_bits,offset)
+.Ss MS_OP_SUBRET - SUBmicrosequence RETurn
+is used to return from the submicrosequence call.
+This action is mandatory before a RET call.
+Some microinstructions (PUT, GET) may not be callable
+within a submicrosequence.
+.Pp
+No parameter.
+.Pp
+Predefined macro: MS_SUBRET()
+.Ss MS_OP_CALL - submicrosequence CALL
+is used to call a submicrosequence.
+A submicrosequence is a microsequence with a SUBRET call.
+Parameter:
+.Bl -enum -offset indent
+.It
+the submicrosequence to execute
+.El
+.Pp
+Predefined macro: MS_CALL(microseq)
+.Ss MS_OP_RASSERT_P - Register ASSERT from internal PTR
+is used to assert a register with data currently pointed by the
+internal PTR pointer.
+Parameter:
+.Bl -enum -offset indent
+.It
+amount of data to write to the register
+.It
+register
+.El
+.Pp
+Predefined macro: MS_RASSERT_P(iter,reg)
+.Ss MS_OP_RFETCH_P - Register FETCH to internal PTR
+is used to fetch data from a register.
+Data is stored in the buffer currently pointed by the internal PTR
+pointer.
+Parameter:
+.Bl -enum -offset indent
+.It
+amount of data to read from the register
+.It
+register
+.It
+mask applied to fetched data
+.El
+.Pp
+Predefined macro: MS_RFETCH_P(iter,reg,mask)
+.Ss MS_OP_TRIG - TRIG register
+is used to trigger the parallel port.
+This microinstruction is intended to provide a very efficient
+control of the parallel port.
+Triggering a register is writing data, wait a while, write data,
+wait a while...
+This allows to write magic sequences to the port.
+Parameter:
+.Bl -enum -offset indent
+.It
+amount of data to read from the register
+.It
+register
+.It
+size of the array
+.It
+array of unsigned chars.
+Each couple of u_chars define the data to write to the register
+and the delay in us to wait.
+The delay is limited to 255 us to simplify and reduce the size of
+the array.
+.El
+.Pp
+Predefined macro: MS_TRIG(reg,len,array)
+.Sh MICROSEQUENCES
+.Ss C structures
+.Bd -literal
+union ppb_insarg {
+     int     i;
+     char    c;
+     void    *p;
+     int     (* f)(void *, char *);
+};
+
+struct ppb_microseq {
+     int                     opcode;         /* microins. opcode */
+     union ppb_insarg        arg[PPB_MS_MAXARGS];    /* arguments */
+};
+.Ed
+.Ss Using microsequences
+To instantiate a microsequence, just declare an array of ppb_microseq
+structures and initialize it as needed.
+You may either use predefined macros
+or code directly your microinstructions according to the ppb_microseq
+definition.
+For example,
+.Bd -literal
+     struct ppb_microseq select_microseq[] = {
+
+	     /* parameter list
+	      */
+	     #define SELECT_TARGET    MS_PARAM(0, 1, MS_TYP_INT)
+	     #define SELECT_INITIATOR MS_PARAM(3, 1, MS_TYP_INT)
+
+	     /* send the select command to the drive */
+	     MS_DASS(MS_UNKNOWN),
+	     MS_CASS(H_nAUTO | H_nSELIN |  H_INIT | H_STROBE),
+	     MS_CASS( H_AUTO | H_nSELIN |  H_INIT | H_STROBE),
+	     MS_DASS(MS_UNKNOWN),
+	     MS_CASS( H_AUTO | H_nSELIN | H_nINIT | H_STROBE),
+
+	     /* now, wait until the drive is ready */
+	     MS_SET(VP0_SELTMO),
+/* loop: */     MS_BRSET(H_ACK, 2 /* ready */),
+	     MS_DBRA(-2 /* loop */),
+/* error: */    MS_RET(1),
+/* ready: */    MS_RET(0)
+     };
+.Ed
+.Pp
+Here, some parameters are undefined and must be filled before
+executing the microsequence.
+In order to initialize each microsequence, one
+should use the
+.Fn ppb_MS_init_msq
+function like this:
+.Bd -literal -offset indent
+ppb_MS_init_msq(select_microseq, 2,
+		SELECT_TARGET, 1 << target,
+		SELECT_INITIATOR, 1 << initiator);
+.Ed
+.Pp
+and then execute the microsequence.
+.Ss The microsequencer
+The microsequencer is executed either at ppbus or adapter level
+(see
+.Xr ppbus 4
+for info about ppbus system layers).
+Most of the microsequencer is executed at
+.Xr atppc 4
+level to avoid
+.Xr ppbus 4
+to adapter function call overhead.
+But some actions like deciding whereas the transfer is
+.Tn IEEE1284-1994
+compliant are executed at
+.Xr ppbus 4
+layer.
+.Sh SEE ALSO
+.Xr atppc 4 ,
+.Xr ppbus 4 ,
+.Xr vpo 4
+.Sh HISTORY
+The
+.Nm
+manual page first appeared in
+.Fx 3.0 .
+.Sh AUTHORS
+This
+manual page is based on the
+.Fx
+.Nm microseq
+manual page and was update for the
+.Nx
+port by
+.An Gary Thorpe .
+.Sh BUGS
+Only one level of submicrosequences is allowed.
+.Pp
+When triggering the port, maximum delay allowed is 255 us.