microseq —
ppbus microseqencer developer's guide
See ppbus(4) for
  ppbus description and general info about the
  microsequencer.
The purpose of this document is to encourage developers to use the
    microsequencer mechanism in order to have:
  - a uniform programming model
- efficient code
Before using microsequences, you are encouraged to look at the
    atppc(4) microsequencer
    implementation and an example of how using it in
    vpo(4).
The parallel port model chosen for
  ppbus(4) is the PC parallel port
  model. Thus, any register described later has the same semantic than its
  counterpart in a PC parallel port. For more info about ISA/ECP programming,
  get the Microsoft standard referenced “Extended Capabilities Port
  Protocol and ISA interface Standard”. Registers described later are
  standard parallel port registers.
Mask macros are defined in the standard
    ppbus(4) include files for each
    valid bit of parallel port registers.
In compatible or nibble mode, writing to this register will drive data to the
  parallel port data lines. In any other mode, drivers may be tri-stated by
  setting the direction bit (PCD) in the control register. Reads to this
  register return the value on the data lines.
This read-only register reflects the inputs on the parallel port interface.
  
    | Bit | Name | Description | 
  
    | 7 | nBUSY | inverted version of parallel port Busy signal | 
  
    | 6 | nACK | version of parallel port nAck signal | 
  
    | 5 | PERROR | version of parallel port PERROR signal | 
  
    | 4 | SELECT | version of parallel port Select signal | 
  
    | 3 | nFAULT | version of parallel port nFault signal | 
Others are reserved and return undefined result when read.
This register directly controls several output signals as well as enabling some
  functions.
  
    | Bit | Name | Description | 
  
    | 5 | PCD | direction bit in extended modes | 
  
    | 4 | IRQENABLE | 1 enables an interrupt on the rising edge of nAck | 
  
    | 3 | SELECTIN | inverted and driven as parallel port nSelectin signal | 
  
    | 2 | nINIT | driven as parallel port nInit signal | 
  
    | 1 | AUTOFEED | inverted and driven as parallel port nAutoFd signal | 
  
    | 0 | STROBE | inverted and driven as parallel port nStrobe signal | 
Microinstructions are either parallel port accesses, program
  iterations, submicrosequence or C calls. The parallel port must be considered
  as the logical model described in
  ppbus(4).
Available microinstructions are:
#define MS_OP_GET       0	/* get <ptr>, <len>			*/
#define MS_OP_PUT       1	/* put <ptr>, <len>			*/
#define MS_OP_RFETCH	2	/* rfetch <reg>, <mask>, <ptr>		*/
#define MS_OP_RSET	3	/* rset <reg>, <mask>, <mask>		*/
#define MS_OP_RASSERT	4	/* rassert <reg>, <mask>		*/
#define MS_OP_DELAY     5	/* delay <val>				*/
#define MS_OP_SET       6	/* set <val>				*/
#define MS_OP_DBRA      7	/* dbra <offset>			*/
#define MS_OP_BRSET     8	/* brset <mask>, <offset>		*/
#define MS_OP_BRCLEAR   9	/* brclear <mask>, <offset>		*/
#define MS_OP_RET       10	/* ret <retcode>			*/
#define MS_OP_C_CALL	11	/* c_call <function>, <parameter>	*/
#define MS_OP_PTR	12	/* ptr <pointer>			*/
#define MS_OP_ADELAY	13	/* adelay <val>				*/
#define MS_OP_BRSTAT	14	/* brstat <mask>, <mask>, <offset>	*/
#define MS_OP_SUBRET	15	/* subret <code>			*/
#define MS_OP_CALL	16	/* call <microsequence>			*/
#define MS_OP_RASSERT_P	17	/* rassert_p <iter>, <reg>		*/
#define MS_OP_RFETCH_P	18	/* rfetch_p <iter>, <reg>, <mask>	*/
#define MS_OP_TRIG	19	/* trigger <reg>, <len>, <array>	*/
 
The execution context of microinstructions is:
  - the program counter which points to the next
      microinstruction to execute either in the main microsequence or in a
      subcall
- the current value of ptr which points to the next char
      to send/receive
- the current value of the internal branch register
This data is modified by some of the microinstructions, not
  all.
are microinstructions used to do either predefined standard IEEE1284-1994
  transfers or programmed non-standard I/O.
is used to retrieve the current value of a parallel port register, apply a mask
  and save it in a buffer.
Parameters:
  - register
- character mask
- pointer to the buffer
Predefined macro: MS_RFETCH(reg,mask,ptr)
is used to assert/clear some bits of a particular parallel port register, two
  masks are applied.
Parameters:
  - register
- mask of bits to assert
- mask of bits to clear
Predefined macro: MS_RSET(reg,assert,clear)
is used to assert all bits of a particular parallel port register.
Parameters:
  - register
- byte to assert
Predefined macro: MS_RASSERT(reg,byte)
is used to delay the execution of the microsequence.
Parameter:
  - delay in microseconds
Predefined macro: MS_DELAY(delay)
is used to set the value of the internal branch register.
Parameter:
  - integer value
Predefined macro: MS_SET(accum)
is used to branch if internal branch register decremented by one result value is
  positive.
Parameter:
  - integer offset in the current executed (sub)microsequence. Offset is added
      to the index of the next microinstruction to execute.
Predefined macro: MS_DBRA(offset)
is used to branch if some of the status register bits of the parallel port are
  set.
Parameter:
  - bits of the status register
- integer offset in the current executed (sub)microsequence. Offset is added
      to the index of the next microinstruction to execute.
Predefined macro: MS_BRSET(mask,offset)
is used to branch if some of the status register bits of the parallel port are
  cleared.
Parameter:
  - bits of the status register
- integer offset in the current executed (sub)microsequence. Offset is added
      to the index of the next microinstruction to execute.
Predefined macro: MS_BRCLEAR(mask,offset)
is used to return from a microsequence. This instruction is mandatory. This is
  the only way for the microsequencer to detect the end of the microsequence.
  The return code is returned in the integer pointed by the (int *) parameter of
  the ppb_MS_microseq().
Parameter:
  - integer return code
Predefined macro: MS_RET(code)
is used to call C functions from microsequence execution. This may be useful
  when a non-standard I/O is performed to retrieve a data character from the
  parallel port.
Parameter:
  - the C function to call
- the parameter to pass to the function call
The C function shall be declared as a int(*)(void
    *p, char *ptr). The ptr parameter is the current position in the
    buffer currently scanned.
Predefined macro: MS_C_CALL(func,param)
is used to initialize the internal pointer to the currently scanned buffer. This
  pointer is passed to any C call (see above).
Parameter:
  - pointer to the buffer that shall be accessed by
      xxx_P() microsequence calls. Note that this
      pointer is automatically incremented duringxxx_P() calls.
Predefined macro: MS_PTR(ptr)
is used to make a
  cv_timedwait(9) during
  microsequence execution.
Parameter:
  - delay in ms
Predefined macro: MS_ADELAY(delay)
is used to branch on status register state condition.
Parameter:
  - mask of asserted bits. Bits that shall be asserted in the status register
      are set in the mask
- mask of cleared bits. Bits that shall be cleared in the status register
      are set in the mask
- integer offset in the current executed (sub)microsequence. Offset is added
      to the index of the next microinstruction to execute.
Predefined macro: MS_BRSTAT(asserted_bits,clear_bits,offset)
is used to return from the submicrosequence call. This action is mandatory
  before a RET call. Some microinstructions (PUT, GET) may not be callable
  within a submicrosequence.
No parameter.
Predefined macro: MS_SUBRET()
is used to call a submicrosequence. A submicrosequence is a microsequence with a
  SUBRET call. Parameter:
  - the submicrosequence to execute
Predefined macro: MS_CALL(microseq)
is used to assert a register with data currently pointed by the internal PTR
  pointer. Parameter:
  - amount of data to write to the register
- register
Predefined macro: MS_RASSERT_P(iter,reg)
is used to fetch data from a register. Data is stored in the buffer currently
  pointed by the internal PTR pointer. Parameter:
  - amount of data to read from the register
- register
- mask applied to fetched data
Predefined macro: MS_RFETCH_P(iter,reg,mask)
is used to trigger the parallel port. This microinstruction is intended to
  provide a very efficient control of the parallel port. Triggering a register
  is writing data, wait a while, write data, wait a while... This allows to
  write magic sequences to the port. Parameter:
  - amount of data to read from the register
- register
- size of the array
- array of unsigned chars. Each couple of u_chars define the data to write
      to the register and the delay in us to wait. The delay is limited to 255
      us to simplify and reduce the size of the array.
Predefined macro: MS_TRIG(reg,len,array)
union ppb_insarg {
     int     i;
     char    c;
     void    *p;
     int     (* f)(void *, char *);
};
struct ppb_microseq {
     int                     opcode;         /* microins. opcode */
     union ppb_insarg        arg[PPB_MS_MAXARGS];    /* arguments */
};
 
To instantiate a microsequence, just declare an array of ppb_microseq structures
  and initialize it as needed. You may either use predefined macros or code
  directly your microinstructions according to the ppb_microseq definition. For
  example,
     struct ppb_microseq select_microseq[] = {
	     /* parameter list
	      */
	     #define SELECT_TARGET    MS_PARAM(0, 1, MS_TYP_INT)
	     #define SELECT_INITIATOR MS_PARAM(3, 1, MS_TYP_INT)
	     /* send the select command to the drive */
	     MS_DASS(MS_UNKNOWN),
	     MS_CASS(H_nAUTO | H_nSELIN |  H_INIT | H_STROBE),
	     MS_CASS( H_AUTO | H_nSELIN |  H_INIT | H_STROBE),
	     MS_DASS(MS_UNKNOWN),
	     MS_CASS( H_AUTO | H_nSELIN | H_nINIT | H_STROBE),
	     /* now, wait until the drive is ready */
	     MS_SET(VP0_SELTMO),
/* loop: */     MS_BRSET(H_ACK, 2 /* ready */),
	     MS_DBRA(-2 /* loop */),
/* error: */    MS_RET(1),
/* ready: */    MS_RET(0)
     };
 
Here, some parameters are undefined and must be filled before
    executing the microsequence. In order to initialize each microsequence, one
    should use the ppb_MS_init_msq() function like
  this:
ppb_MS_init_msq(select_microseq, 2,
		SELECT_TARGET, 1 << target,
		SELECT_INITIATOR, 1 << initiator);
 
and then execute the microsequence.
The microsequencer is executed either at ppbus or adapter level (see
  ppbus(4) for info about ppbus
  system layers). Most of the microsequencer is executed at
  atppc(4) level to avoid
  ppbus(4) to adapter function call
  overhead. But some actions like deciding whereas the transfer is IEEE1284-1994
  compliant are executed at
  ppbus(4) layer.
The microseq manual page first appeared in
  FreeBSD 3.0.
This manual page is based on the FreeBSD
  microseq manual page and was update for the
  NetBSD port by Gary Thorpe.
Only one level of submicrosequences is allowed.
When triggering the port, maximum delay allowed is 255 us.