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