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