diff options
author | nsouch <nsouch@FreeBSD.org> | 1999-01-30 15:32:41 +0000 |
---|---|---|
committer | nsouch <nsouch@FreeBSD.org> | 1999-01-30 15:32:41 +0000 |
commit | 211ce4145696984ed7c97a07f63052060e52ce1b (patch) | |
tree | c72c7f6eb7476acf597f456ec99bb967a160a662 /share | |
parent | d4cadee8f434479135d30eac0f66a25eee86614f (diff) | |
download | FreeBSD-src-211ce4145696984ed7c97a07f63052060e52ce1b.zip FreeBSD-src-211ce4145696984ed7c97a07f63052060e52ce1b.tar.gz |
Improve ppbus(4) microsequencer description. Remove ppbconf.9 which is
to rapidly depreciated.
Diffstat (limited to 'share')
-rw-r--r-- | share/man/man9/microseq.9 | 418 | ||||
-rw-r--r-- | share/man/man9/ppbconf.9 | 205 |
2 files changed, 381 insertions, 242 deletions
diff --git a/share/man/man9/microseq.9 b/share/man/man9/microseq.9 index 630f186..0d105de 100644 --- a/share/man/man9/microseq.9 +++ b/share/man/man9/microseq.9 @@ -1,4 +1,4 @@ -.\" Copyright (c) 1998, Nicolas Souchu +.\" Copyright (c) 1998, 1999, Nicolas Souchu .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -45,68 +45,412 @@ a uniform programming model .It efficient code .El -.Sh INTERFACE +.Pp +Before using microsequences, you are encouraged to look at +.Xr ppc 4 +microsequencer implementation and an example of how using it in +.Xr vpo 4 . +.Sh PPBUS register model +.Ss Background +The parallel port model chosen for ppbus 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 as "Extended Capabilities Port Protocol and +ISA interface Standard". Registers described later are standard parallel port +registers. +.Pp +Mask macros are defined in the standard ppbus 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 parellel 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 -item -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 IEEE1284-1994 +transfers or programed non-standard io. +.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 ident +.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 ident +.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 ident +.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 ident +.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 ident +.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 ident +.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 ident +.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 ident +.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 usefull +when a non-standard i/o is performed to retrieve a data character from the +parallel port. +.Pp +Parameter: +.Bl -enum -offset ident +.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 +.Fd 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 initilize the internal pointeur to the currently scanned buffer. +This pointer is passed to any C call (see above). +.Pp +Parameter: +.Bl -enum -offset ident +.It +pointer to the buffer that shall be accessed by xxx_P() microsequence calls. +Note that this pointer is automatically incremented during xxx_P() calls +.El +.Pp +Predefined macro: MS_PTR(ptr) +.Ss MS_OP_ADELAY - do an Asynchroneous DELAY +is used to make a tsleep() during microsequence execution. The tsleep is +executed at PPBPRI level. +.Pp +Parameter: +.Bl -enum -offset ident +.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 ident +.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 ident +.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 ident +.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 ident +.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 ident +.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 *); + int i; + char c; + void *p; + int (* f)(void *, char *); }; -.Ed -.Bd -literal + struct ppb_microseq { - int opcode; /* microins. opcode */ - union ppb_insarg arg[PPB_MS_MAXARGS]; /* arguments */ + int opcode; /* microins. opcode */ + union ppb_insarg arg[PPB_MS_MAXARGS]; /* arguments */ }; .Ed .Ss Using microsequences -.Pp To instanciate a microsequence, just declare an array of ppb_microseq -structures and initialize it as needed. You may either use defined macros +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[] = { + 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) + /* 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), + /* 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, 3 /* ready */), - MS_DBRA(-1 /* loop */), -/* error: */ MS_RET(1), -/* ready: */ MS_RET(0) - }; + /* 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 seach a microsequence, one should -use the ppb_MS_init_msq() function like this: +the microsequence. In order to initialize seach a microsequence, one +should use the ppb_MS_init_msq() function like this: .Bd -literal - ppb_MS_init_msq(select_microseq, 2, - SELECT_TARGET, 1 << target, - SELECT_INITIATOR, 1 << initiator); + 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). +for info about ppbus system layers). Most of the microsequencer is executed +at ppc level to avoid ppbus to adapter function call overhead. But some +actions like deciding whereas the transfer is IEEE1284-1994 compliant are +executed at ppbus layer. +.Sh BUGS +Only one level of submicrosequences is allowed. +.Pp +When triggering the port, maximum delay allowed is 255 us. .Sh SEE ALSO -.Xr ppbus 4 +.Xr ppbus 4 , +.Xr ppc 4 , +.Xr vpo 4 .Sh HISTORY The .Nm diff --git a/share/man/man9/ppbconf.9 b/share/man/man9/ppbconf.9 deleted file mode 100644 index 9b95e72..0000000 --- a/share/man/man9/ppbconf.9 +++ /dev/null @@ -1,205 +0,0 @@ -.\" Copyright (c) 1998, 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. -.\" -.\" -.Dd April 5, 1998 -.Dt PPBCONF 9 -.Os FreeBSD -.Sh NAME -.Nm ppbconf -.Nd -ppbus developer's guide -.Sh SYNOPSIS -.Fd "#include <dev/ppbus/ppbconf.h>" -.Sh DESCRIPTION -See -.Xr ppbus 4 -for ppbus description. -.Sh PPBUS STRUCTURES -Each ppbus layer -.Po -.Em adapter , -.Em ppbus -and -.Em device -.Pc -is described by one or more C structure. -.Ss The adapter layer -.Bd -literal -struct ppb_adapter { - - void (*intr_handler)(int); - void (*reset_epp_timeout)(int); - void (*ecp_sync)(int); - - int (*exec_microseq)(int, struct ppb_microseq *, int *); - - int (*setmode)(int, int); - - void (*outsb_epp)(int, char *, int); - void (*outsw_epp)(int, char *, int); - void (*outsl_epp)(int, char *, int); - void (*insb_epp)(int, char *, int); - void (*insw_epp)(int, char *, int); - void (*insl_epp)(int, char *, int); - - char (*r_dtr)(int); - char (*r_str)(int); - char (*r_ctr)(int); - char (*r_epp)(int); - char (*r_ecr)(int); - char (*r_fifo)(int); - - void (*w_dtr)(int, char); - void (*w_str)(int, char); - void (*w_ctr)(int, char); - void (*w_epp)(int, char); - void (*w_ecr)(int, char); - void (*w_fifo)(int, char); -}; -.Ed -.Pp -This structure is the interface between -.Xr ppc 4 -layer and upper ppbus system levels. For each ppc device, this -structure is filled with generic i/o functions that may be redefined if -needed for particular chipsets. -.Pp -Developers are really encouraged to use the -exec_microseq entry to avoid indirect function call overhead. See -.Xr microseq 9 -for more info. -.Ss The ppbus layer -.Bd -literal -struct ppb_driver -{ - struct ppb_device *(*probe)(struct ppb_data *ppb); - int (*attach)(struct ppb_device *pdp); - char *name; -}; -.Ed -.Bd -literal -struct ppb_data { - -#define PPB_PnP_PRINTER 0 -#define PPB_PnP_MODEM 1 -#define PPB_PnP_NET 2 -#define PPB_PnP_HDC 3 -#define PPB_PnP_PCMCIA 4 -#define PPB_PnP_MEDIA 5 -#define PPB_PnP_FDC 6 -#define PPB_PnP_PORTS 7 -#define PPB_PnP_SCANNER 8 -#define PPB_PnP_DIGICAM 9 -#define PPB_PnP_UNKNOWN 10 - int class_id; /* not a PnP device if class_id < 0 */ - - ushort mode; /* IEEE 1284-1994 mode - * NIBBLE, PS2, EPP, ECP */ - ushort avm; /* IEEE 1284-1994 available - * modes */ - - struct ppb_link *ppb_link; /* link to the adapter */ - struct ppb_device *ppb_owner; /* device which owns the bus */ - LIST_HEAD(, ppb_device) ppb_devs; /* list of devices on the bus */ - LIST_ENTRY(ppb_data) ppb_chain; /* list of busses */ -}; -.Ed -.Ss The device layer -.Bd -literal -/* microseqences used for GET/PUT operations */ -struct ppb_xfer { - struct ppb_microseq *prolog; /* loop prologue */ - struct ppb_microseq *body; /* loop body */ - struct ppb_microseq *epilog; /* loop epilogue */ -}; -.Ed -.Bd -literal -struct ppb_context { - int valid; /* 1 if the struct is valid */ - int mode; /* operating mode */ - - struct microseq *curpc; /* pc in curmsq */ - struct microseq *curmsq; /* currently executed microseq */ -}; -.Ed -.Bd -literal -struct ppb_device { - - int id_unit; /* unit of the device */ - char *name; /* name of the device */ - - ushort mode; /* current mode of the device */ - ushort avm; /* available modes of the device */ - - struct ppb_context ctx; /* context of the device */ - - /* mode dependent get msq. If NULL, - * IEEE1284 code is used */ - struct ppb_xfer - get_xfer[PPB_MAX_XFER]; - - /* mode dependent put msq. If NULL, - * IEEE1284 code is used */ - struct ppb_xfer - put_xfer[PPB_MAX_XFER]; - - void (*intr)(int); /* interrupt handler */ - - struct ppb_data *ppb; /* link to the ppbus */ - - LIST_ENTRY(ppb_device) chain; /* list of devices on the bus */ -}; -.Ed -.Ss Linking these structures all together -.Bd -literal -struct ppb_link { - - int adapter_unit; /* unit of the adapter */ - int base; /* base address of the port */ - int id_irq; /* != 0 if irq enabled */ - -#define EPP_1_9 0x0 /* default */ -#define EPP_1_7 0x1 - int epp_protocol; /* EPP protocol: 0=1.9, 1=1.7 */ - - struct ppb_adapter *adapter; /* link to the ppc adapter */ - struct ppb_data *ppbus; /* link to the ppbus */ -}; -.Ed -.Sh EXAMPLE -See vpo.c source file. -.Sh SEE ALSO -.Xr ppbus 4 , -.Xr ppi 4 , -.Xr microseq 9 -.Sh HISTORY -The -.Nm -manual page first appeared in -.Fx 3.0 . -.Sh AUTHOR -This -manual page was written by -.An Nicolas Souchu . |