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