1.\" Copyright (c) 1998, 1999, Nicolas Souchu 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/share/man/man9/microseq.9,v 1.9.2.6 2002/12/29 16:35:39 schweikh Exp $ 26.\" $DragonFly: src/share/man/man9/microseq.9,v 1.5 2008/11/23 21:55:52 swildner Exp $ 27.\" 28.Dd June 6, 1998 29.Dt MICROSEQ 9 30.Os 31.Sh NAME 32.Nm microseq 33.Nd ppbus microsequencer developer's guide 34.Sh SYNOPSIS 35.In sys/types.h 36.In bus/ppbus/ppbconf.h 37.In bus/ppbus/ppb_msq.h 38.Sh DESCRIPTION 39See 40.Xr ppbus 4 41for ppbus description and general info about the microsequencer. 42.Pp 43The purpose of this document is to encourage developers to use the 44microsequencer mechanism in order to have: 45.Bl -enum -offset indent 46.It 47a uniform programming model 48.It 49efficient code 50.El 51.Pp 52Before using microsequences, you are encouraged to look at 53.Xr ppc 4 54microsequencer implementation and an example of how using it in 55.Xr vpo 4 . 56.Sh PPBUS register model 57.Ss Background 58The parallel port model chosen for ppbus is the PC parallel port model. 59Thus, any register described later has the same semantic than its counterpart 60in a PC parallel port. 61For more info about ISA/ECP programming, get the 62Microsoft standard referenced as "Extended Capabilities Port Protocol and 63ISA interface Standard". Registers described later are standard parallel port 64registers. 65.Pp 66Mask macros are defined in the standard ppbus include files for each valid 67bit of parallel port registers. 68.Ss Data register 69In compatible or nibble mode, writing to this register will drive data to the 70parallel port data lines. 71In any other mode, drivers may be tri-stated by 72setting the direction bit (PCD) in the control register. 73Reads to this register 74return the value on the data lines. 75.Ss Device status register 76This read-only register reflects the inputs on the parallel port interface. 77.Pp 78.Bl -column "Bit" "Name" "Description" -compact 79.It Em Bit Ta Em Name Ta Em Description 80.It 7 Ta nBUSY Ta "inverted version of parallel port Busy signal" 81.It 6 Ta nACK Ta "version of parallel port nAck signal" 82.It 5 Ta PERROR Ta "version of parallel port PERROR signal" 83.It 4 Ta SELECT Ta "version of parallel port Select signal" 84.It 3 Ta nFAULT Ta "version of parallel port nFault signal" 85.El 86.Pp 87Others are reserved and return undefined result when read. 88.Ss Device control register 89This register directly controls several output signals as well as enabling 90some functions. 91.Pp 92.Bl -column "Bit" "Name " "Description" -compact 93.It Em Bit Ta Em Name Ta Em Description 94.It 5 Ta PCD Ta "direction bit in extended modes" 95.It 4 Ta IRQENABLE Ta "1 enables an interrupt on the rising edge of nAck" 96.It 3 Ta SELECTIN Ta "inverted and driven as parallel port nSelectin signal" 97.It 2 Ta nINIT Ta "driven as parallel port nInit signal" 98.It 1 Ta AUTOFEED Ta "inverted and driven as parallel port nAutoFd signal" 99.It 0 Ta STROBE Ta "inverted and driven as parallel port nStrobe signal" 100.El 101.Sh MICROINSTRUCTIONS 102.Ss Description 103.Em Microinstructions 104are either parallel port accesses, program iterations, submicrosequence or 105C calls. 106The parallel port must be considered as the logical model described in 107.Xr ppbus 4 . 108.Pp 109Available microinstructions are: 110.Bd -literal 111#define MS_OP_GET 0 /* get <ptr>, <len> */ 112#define MS_OP_PUT 1 /* put <ptr>, <len> */ 113#define MS_OP_RFETCH 2 /* rfetch <reg>, <mask>, <ptr> */ 114#define MS_OP_RSET 3 /* rset <reg>, <mask>, <mask> */ 115#define MS_OP_RASSERT 4 /* rassert <reg>, <mask> */ 116#define MS_OP_DELAY 5 /* delay <val> */ 117#define MS_OP_SET 6 /* set <val> */ 118#define MS_OP_DBRA 7 /* dbra <offset> */ 119#define MS_OP_BRSET 8 /* brset <mask>, <offset> */ 120#define MS_OP_BRCLEAR 9 /* brclear <mask>, <offset> */ 121#define MS_OP_RET 10 /* ret <retcode> */ 122#define MS_OP_C_CALL 11 /* c_call <function>, <parameter> */ 123#define MS_OP_PTR 12 /* ptr <pointer> */ 124#define MS_OP_ADELAY 13 /* adelay <val> */ 125#define MS_OP_BRSTAT 14 /* brstat <mask>, <mask>, <offset> */ 126#define MS_OP_SUBRET 15 /* subret <code> */ 127#define MS_OP_CALL 16 /* call <microsequence> */ 128#define MS_OP_RASSERT_P 17 /* rassert_p <iter>, <reg> */ 129#define MS_OP_RFETCH_P 18 /* rfetch_p <iter>, <reg>, <mask> */ 130#define MS_OP_TRIG 19 /* trigger <reg>, <len>, <array> */ 131.Ed 132.Ss Execution context 133The 134.Em execution context 135of microinstructions is: 136.Bl -bullet -offset indent 137.It 138the 139.Em program counter 140which points to the next microinstruction to execute either in the main 141microsequence or in a subcall 142.It 143the current value of 144.Em ptr 145which points to the next char to send/receive 146.It 147the current value of the internal 148.Em branch register 149.El 150.Pp 151This data is modified by some of the microinstructions, not all. 152.Ss MS_OP_GET and MS_OP_PUT 153are microinstructions used to do either predefined standard IEEE1284-1994 154transfers or programmed non-standard io. 155.Ss MS_OP_RFETCH - Register FETCH 156is used to retrieve the current value of a parallel port register, apply a 157mask and save it in a buffer. 158.Pp 159Parameters: 160.Bl -enum -offset indent 161.It 162register 163.It 164character mask 165.It 166pointer to the buffer 167.El 168.Pp 169Predefined macro: MS_RFETCH(reg,mask,ptr) 170.Ss MS_OP_RSET - Register SET 171is used to assert/clear some bits of a particular parallel port register, 172two masks are applied. 173.Pp 174Parameters: 175.Bl -enum -offset indent 176.It 177register 178.It 179mask of bits to assert 180.It 181mask of bits to clear 182.El 183.Pp 184Predefined macro: MS_RSET(reg,assert,clear) 185.Ss MS_OP_RASSERT - Register ASSERT 186is used to assert all bits of a particular parallel port register. 187.Pp 188Parameters: 189.Bl -enum -offset indent 190.It 191register 192.It 193byte to assert 194.El 195.Pp 196Predefined macro: MS_RASSERT(reg,byte) 197.Ss MS_OP_DELAY - microsecond DELAY 198is used to delay the execution of the microsequence. 199.Pp 200Parameter: 201.Bl -enum -offset indent 202.It 203delay in microseconds 204.El 205.Pp 206Predefined macro: MS_DELAY(delay) 207.Ss MS_OP_SET - SET internal branch register 208is used to set the value of the internal branch register. 209.Pp 210Parameter: 211.Bl -enum -offset indent 212.It 213integer value 214.El 215.Pp 216Predefined macro: MS_SET(accum) 217.Ss MS_OP_DBRA - \&Do BRAnch 218is used to branch if internal branch register decremented by one result value 219is positive. 220.Pp 221Parameter: 222.Bl -enum -offset indent 223.It 224integer offset in the current executed (sub)microsequence. 225Offset is added to 226the index of the next microinstruction to execute. 227.El 228.Pp 229Predefined macro: MS_DBRA(offset) 230.Ss MS_OP_BRSET - BRanch on SET 231is used to branch if some of the status register bits of the parallel port 232are set. 233.Pp 234Parameter: 235.Bl -enum -offset indent 236.It 237bits of the status register 238.It 239integer offset in the current executed (sub)microsequence. 240Offset is added to 241the index of the next microinstruction to execute. 242.El 243.Pp 244Predefined macro: MS_BRSET(mask,offset) 245.Ss MS_OP_BRCLEAR - BRanch on CLEAR 246is used to branch if some of the status register bits of the parallel port 247are cleared. 248.Pp 249Parameter: 250.Bl -enum -offset indent 251.It 252bits of the status register 253.It 254integer offset in the current executed (sub)microsequence. 255Offset is added to 256the index of the next microinstruction to execute. 257.El 258.Pp 259Predefined macro: MS_BRCLEAR(mask,offset) 260.Ss MS_OP_RET - RETurn 261is used to return from a microsequence. 262This instruction is mandatory. 263This 264is the only way for the microsequencer to detect the end of the microsequence. 265The return code is returned in the integer pointed by the (int *) parameter 266of the 267.Fn ppb_MS_microseq 268function. 269.Pp 270Parameter: 271.Bl -enum -offset indent 272.It 273integer return code 274.El 275.Pp 276Predefined macro: MS_RET(code) 277.Ss MS_OP_C_CALL - C function CALL 278is used to call C functions from microsequence execution. 279This may be useful 280when a non-standard i/o is performed to retrieve a data character from the 281parallel port. 282.Pp 283Parameter: 284.Bl -enum -offset indent 285.It 286the C function to call 287.It 288the parameter to pass to the function call 289.El 290.Pp 291The C function shall be declared as a 292.Ft int(*)(void *p, char *ptr) . 293The ptr parameter is the current position in the buffer currently scanned. 294.Pp 295Predefined macro: MS_C_CALL(func,param) 296.Ss MS_OP_PTR - initialize internal PTR 297is used to initialize the internal pointer to the currently scanned buffer. 298This pointer is passed to any C call (see above). 299.Pp 300Parameter: 301.Bl -enum -offset indent 302.It 303pointer to the buffer that shall be accessed by xxx_P() microsequence calls. 304Note that this pointer is automatically incremented during xxx_P() calls 305.El 306.Pp 307Predefined macro: MS_PTR(ptr) 308.Ss MS_OP_ADELAY - do an Asynchronous DELAY 309is used to make a tsleep() during microsequence execution. 310The tsleep is 311executed at PPBPRI level. 312.Pp 313Parameter: 314.Bl -enum -offset indent 315.It 316delay in ms 317.El 318.Pp 319Predefined macro: MS_ADELAY(delay) 320.Ss MS_OP_BRSTAT - BRanch on STATe 321is used to branch on status register state condition. 322.Pp 323Parameter: 324.Bl -enum -offset indent 325.It 326mask of asserted bits. 327Bits that shall be asserted in the status register 328are set in the mask 329.It 330mask of cleared bits. 331Bits that shall be cleared in the status register 332are set in the mask 333.It 334integer offset in the current executed (sub)microsequence. 335Offset is added 336to the index of the next microinstruction to execute. 337.El 338.Pp 339Predefined macro: MS_BRSTAT(asserted_bits,clear_bits,offset) 340.Ss MS_OP_SUBRET - SUBmicrosequence RETurn 341is used to return from the submicrosequence call. 342This action is mandatory 343before a RET call. 344Some microinstructions (PUT, GET) may not be callable 345within a submicrosequence. 346.Pp 347No parameter. 348.Pp 349Predefined macro: MS_SUBRET() 350.Ss MS_OP_CALL - submicrosequence CALL 351is used to call a submicrosequence. 352A submicrosequence is a microsequence with 353a SUBRET call. 354Parameter: 355.Bl -enum -offset indent 356.It 357the submicrosequence to execute 358.El 359.Pp 360Predefined macro: MS_CALL(microseq) 361.Ss MS_OP_RASSERT_P - Register ASSERT from internal PTR 362is used to assert a register with data currently pointed by the internal PTR 363pointer. 364Parameter: 365.Bl -enum -offset indent 366.It 367amount of data to write to the register 368.It 369register 370.El 371.Pp 372Predefined macro: MS_RASSERT_P(iter,reg) 373.Ss MS_OP_RFETCH_P - Register FETCH to internal PTR 374is used to fetch data from a register. 375Data is stored in the buffer currently 376pointed by the internal PTR pointer. 377Parameter: 378.Bl -enum -offset indent 379.It 380amount of data to read from the register 381.It 382register 383.It 384mask applied to fetched data 385.El 386.Pp 387Predefined macro: MS_RFETCH_P(iter,reg,mask) 388.Ss MS_OP_TRIG - TRIG register 389is used to trigger the parallel port. 390This microinstruction is intended to 391provide a very efficient control of the parallel port. 392Triggering a register 393is writing data, wait a while, write data, wait a while... 394This allows to 395write magic sequences to the port. 396Parameter: 397.Bl -enum -offset indent 398.It 399amount of data to read from the register 400.It 401register 402.It 403size of the array 404.It 405array of unsigned chars. 406Each couple of u_chars define the data to write to 407the register and the delay in us to wait. 408The delay is limited to 255 us to 409simplify and reduce the size of the array. 410.El 411.Pp 412Predefined macro: MS_TRIG(reg,len,array) 413.Sh MICROSEQUENCES 414.Ss C structures 415.Bd -literal 416union ppb_insarg { 417 int i; 418 char c; 419 void *p; 420 int (* f)(void *, char *); 421}; 422 423struct ppb_microseq { 424 int opcode; /* microins. opcode */ 425 union ppb_insarg arg[PPB_MS_MAXARGS]; /* arguments */ 426}; 427.Ed 428.Ss Using microsequences 429To instantiate a microsequence, just declare an array of ppb_microseq 430structures and initialize it as needed. 431You may either use predefined macros 432or code directly your microinstructions according to the ppb_microseq 433definition. 434For example, 435.Bd -literal 436 struct ppb_microseq select_microseq[] = { 437 438 /* parameter list 439 */ 440 #define SELECT_TARGET MS_PARAM(0, 1, MS_TYP_INT) 441 #define SELECT_INITIATOR MS_PARAM(3, 1, MS_TYP_INT) 442 443 /* send the select command to the drive */ 444 MS_DASS(MS_UNKNOWN), 445 MS_CASS(H_nAUTO | H_nSELIN | H_INIT | H_STROBE), 446 MS_CASS( H_AUTO | H_nSELIN | H_INIT | H_STROBE), 447 MS_DASS(MS_UNKNOWN), 448 MS_CASS( H_AUTO | H_nSELIN | H_nINIT | H_STROBE), 449 450 /* now, wait until the drive is ready */ 451 MS_SET(VP0_SELTMO), 452/* loop: */ MS_BRSET(H_ACK, 2 /* ready */), 453 MS_DBRA(-2 /* loop */), 454/* error: */ MS_RET(1), 455/* ready: */ MS_RET(0) 456 }; 457.Ed 458.Pp 459Here, some parameters are undefined and must be filled before executing 460the microsequence. 461In order to initialize each microsequence, one 462should use the 463.Fn ppb_MS_init_msq 464function like this: 465.Bd -literal 466 ppb_MS_init_msq(select_microseq, 2, 467 SELECT_TARGET, 1 << target, 468 SELECT_INITIATOR, 1 << initiator); 469.Ed 470.Pp 471and then execute the microsequence. 472.Ss The microsequencer 473The microsequencer is executed either at ppbus or adapter level (see 474.Xr ppbus 4 475for info about ppbus system layers). Most of the microsequencer is executed 476at ppc level to avoid ppbus to adapter function call overhead. 477But some 478actions like deciding whereas the transfer is IEEE1284-1994 compliant are 479executed at ppbus layer. 480.Sh SEE ALSO 481.Xr ppbus 4 , 482.Xr ppc 4 , 483.Xr vpo 4 484.Sh HISTORY 485The 486.Nm 487manual page first appeared in 488.Fx 3.0 . 489.Sh AUTHORS 490This 491manual page was written by 492.An Nicolas Souchu . 493.Sh BUGS 494Only one level of submicrosequences is allowed. 495.Pp 496When triggering the port, maximum delay allowed is 255 us. 497