share/man/man9/microseq.9

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