1 .\" Copyright (c) 1998, 1999, Nicolas Souchu
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
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 $
33 .Nd ppbus microsequencer developer's guide
37 .In bus/ppbus/ppbconf.h
38 .In bus/ppbus/ppb_msq.h
42 for ppbus description and general info about the microsequencer.
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
48 a uniform programming model
53 Before using microsequences, you are encouraged to look at
55 microsequencer implementation and an example of how using it in
57 .Sh PPBUS register model
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
67 Mask macros are defined in the standard ppbus include files for each valid
68 bit of parallel port registers.
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.
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"
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
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"
102 .Sh MICROINSTRUCTIONS
104 .Em Microinstructions
105 are either parallel port accesses, program iterations, submicrosequence or
107 The parallel port must be considered as the logical model described in
110 Available microinstructions are:
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> */
133 .Ss Execution context
135 .Em execution context
136 of microinstructions is:
137 .Bl -bullet -offset indent
141 which points to the next microinstruction to execute either in the main
142 microsequence or in a subcall
146 which points to the next char to send/receive
148 the current value of the internal
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.
161 .Bl -enum -offset indent
167 pointer to the buffer
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.
176 .Bl -enum -offset indent
180 mask of bits to assert
182 mask of bits to clear
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.
190 .Bl -enum -offset indent
197 Predefined macro: MS_RASSERT(reg,byte)
198 .Ss MS_OP_DELAY - microsecond DELAY
199 is used to delay the execution of the microsequence.
202 .Bl -enum -offset indent
204 delay in microseconds
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.
212 .Bl -enum -offset indent
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
223 .Bl -enum -offset indent
225 integer offset in the current executed (sub)microsequence.
227 the index of the next microinstruction to execute.
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
236 .Bl -enum -offset indent
238 bits of the status register
240 integer offset in the current executed (sub)microsequence.
242 the index of the next microinstruction to execute.
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
251 .Bl -enum -offset indent
253 bits of the status register
255 integer offset in the current executed (sub)microsequence.
257 the index of the next microinstruction to execute.
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.
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
272 .Bl -enum -offset indent
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.
281 when a non-standard i/o is performed to retrieve a data character from the
285 .Bl -enum -offset indent
287 the C function to call
289 the parameter to pass to the function call
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.
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).
302 .Bl -enum -offset indent
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
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.
312 executed at PPBPRI level.
315 .Bl -enum -offset indent
320 Predefined macro: MS_ADELAY(delay)
321 .Ss MS_OP_BRSTAT - BRanch on STATe
322 is used to branch on status register state condition.
325 .Bl -enum -offset indent
327 mask of asserted bits.
328 Bits that shall be asserted in the status register
331 mask of cleared bits.
332 Bits that shall be cleared in the status register
335 integer offset in the current executed (sub)microsequence.
337 to the index of the next microinstruction to execute.
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
345 Some microinstructions (PUT, GET) may not be callable
346 within a submicrosequence.
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
356 .Bl -enum -offset indent
358 the submicrosequence to execute
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
366 .Bl -enum -offset indent
368 amount of data to write to the register
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.
379 .Bl -enum -offset indent
381 amount of data to read from the register
385 mask applied to fetched data
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...
396 write magic sequences to the port.
398 .Bl -enum -offset indent
400 amount of data to read from the register
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.
413 Predefined macro: MS_TRIG(reg,len,array)
421 int (* f)(void *, char *);
424 struct ppb_microseq {
425 int opcode; /* microins. opcode */
426 union ppb_insarg arg[PPB_MS_MAXARGS]; /* arguments */
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
437 struct ppb_microseq select_microseq[] = {
441 #define SELECT_TARGET MS_PARAM(0, 1, MS_TYP_INT)
442 #define SELECT_INITIATOR MS_PARAM(3, 1, MS_TYP_INT)
444 /* send the select command to the drive */
446 MS_CASS(H_nAUTO | H_nSELIN | H_INIT | H_STROBE),
447 MS_CASS( H_AUTO | H_nSELIN | H_INIT | H_STROBE),
449 MS_CASS( H_AUTO | H_nSELIN | H_nINIT | H_STROBE),
451 /* now, wait until the drive is ready */
453 /* loop: */ MS_BRSET(H_ACK, 2 /* ready */),
454 MS_DBRA(-2 /* loop */),
455 /* error: */ MS_RET(1),
456 /* ready: */ MS_RET(0)
460 Here, some parameters are undefined and must be filled before executing
462 In order to initialize each microsequence, one
467 ppb_MS_init_msq(select_microseq, 2,
468 SELECT_TARGET, 1 << target,
469 SELECT_INITIATOR, 1 << initiator);
472 and then execute the microsequence.
473 .Ss The microsequencer
474 The microsequencer is executed either at ppbus or adapter level (see
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.
479 actions like deciding whereas the transfer is IEEE1284-1994 compliant are
480 executed at ppbus layer.
488 manual page first appeared in
492 manual page was written by
495 Only one level of submicrosequences is allowed.
497 When triggering the port, maximum delay allowed is 255 us.