MICROSEQ(9)

💖 microseq — ppbus microsequencer developer's guide 💖

okay bestie, welcome to MICROSEQ(9), the ppbus microsequencer developer's guide from the Kernel Developer's Manual. this one's a chonker so buckle up 🎀

---

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <dev/ppbus/ppbconf.h>
#include <dev/ppbus/ppb_msq.h>

---

🌸 DESCRIPTION 🌸

so first things first, if you want the ppbus description and the general tea about the microsequencer, go read ppbus(4). that's your homework. 📚

the whole point of this document? it's giving recruiting. like, the goal is to encourage developers to actually use the microsequencer mechanism so we get:

1. a uniform programming model
2. efficient code

and before you even think about touching microsequences, bestie, please go look at the ppc(4) microsequencer implementation, plus an example of how to use it over in vpo(4). do your research, it's free 💅

---

👑 PPBUS register model 👑

🌈 Background 🌈

the parallel port model we picked for ppbus? it's the PC parallel port model. so literally every register described down below has the exact same semantic as its counterpart in a PC parallel port. no cap. if you want more info about ISA/ECP programming, go grab the Microsoft standard referenced as "Extended Capabilities Port Protocol and ISA interface Standard". and just so we're clear — the registers described later on are standard parallel port registers.

mask macros are defined in the standard ppbus include files for each valid bit of the parallel port registers. they're right there for you, use them 🫶

🍓 Data register 🍓

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. and reading from this register gives you back the value on the data lines. simple as ✨

🦋 Device status register 🦋

this one's read-only, and it reflects the inputs on the parallel port interface. here's the lineup:

• bit 7 — nBUSY — inverted version of parallel port Busy signal
• bit 6 — nACK — version of parallel port nAck signal
• bit 5 — PERROR — version of parallel port PERROR signal
• bit 4 — SELECT — version of parallel port Select signal
• bit 3 — nFAULT — version of parallel port nFault signal

the others are reserved and return an undefined result when read. so like, don't build your whole personality on reading those bits, okay? 💀

🧚 Device control register 🧚

this register directly controls several output signals and enables some functions. main character energy honestly:

• bit 5 — PCD — direction bit in extended modes
• bit 4 — IRQENABLE — 1 enables an interrupt on the rising edge of nAck
• bit 3 — SELECTIN — inverted and driven as parallel port nSelectin signal
• bit 2 — nINIT — driven as parallel port nInit signal
• bit 1 — AUTOFEED — inverted and driven as parallel port nAutoFd signal
• bit 0 — STROBE — inverted and driven as parallel port nStrobe signal

---

okay that's the register model section done and dusted, but we are SO not finished yet — more parts incoming, don't go anywhere bestie 🌸

🌈 MICROINSTRUCTIONS 🌈

✨ Description ✨

okay so every microinstruction is one of these four things: a parallel port access, a program iteration, a submicrosequence, or a C call. and the parallel port? bestie, you must think of it as the logical model described in ppbus(4). that's the whole vibe, no cap.

here's the entire lineup of microinstructions you get to play with:

#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>        */

---

🧠 Execution context 🧠

the execution context of microinstructions is, like, the little state bundle the sequencer carries around:

• the program counter, which points at the next microinstruction to execute — either in the main microsequence or inside a subcall
• the current value of ptr, which points at the next char to send/receive
• the current value of the internal branch register

and here's the tea: this data gets modified by some of the microinstructions. not all of them. just some. 🙈

---

💌 MS_OP_GET and MS_OP_PUT

these two are the microinstructions you use to do either predefined standard IEEE1284-1994 transfers or programmed non-standard io. pick your fighter. 💅

---

💖 MS_OP_RFETCH — Register FETCH 💖

grabs the current value of a parallel port register, slaps a mask on it, and saves the result into a buffer. iconic.

Parameters:

1. register
2. character mask
3. pointer to the buffer

Predefined macro: MS_RFETCH(reg,mask,ptr)

---

💖 MS_OP_RSET — Register SET 💖

asserts and/or clears some bits of a particular parallel port register. two masks get applied. double the masking, double the slay.

Parameters:

1. register
2. mask of bits to assert
3. mask of bits to clear

Predefined macro: MS_RSET(reg,assert,clear)

---

💖 MS_OP_RASSERT — Register ASSERT 💖

asserts all the bits of a particular parallel port register. no holding back, full send.

Parameters:

1. register
2. byte to assert

Predefined macro: MS_RASSERT(reg,byte)

---

⏳ MS_OP_DELAY — microsecond DELAY ⏳

delays the execution of the microsequence. yes it's in microseconds, yes it's tiny, yes it matters.

Parameter:

1. delay in microseconds

Predefined macro: MS_DELAY(delay)

---

🎀 MS_OP_SET — SET internal branch register 🎀

sets the value of the internal branch register. that's it, that's the whole job.

Parameter:

1. integer value

Predefined macro: MS_SET(accum)

---

🔁 MS_OP_DBRA — Do BRAnch 🔁

branches if the internal branch register, decremented by one, comes out positive. countdown behaviour fr fr.

Parameter:

1. 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)

---

🦋 MS_OP_BRSET — BRanch on SET 🦋

branches if some of the status register bits of the parallel port are set.

Parameter:

1. bits of the status register
2. 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)

---

🦋 MS_OP_BRCLEAR — BRanch on CLEAR 🦋

branches if some of the status register bits of the parallel port are cleared.

Parameter:

1. bits of the status register
2. 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)

---

🛑 MS_OP_RET — RETurn 🛑

returns from a microsequence. and listen — this instruction is mandatory. it's literally the only way the microsequencer can detect the end of the microsequence. skip it and you're lost in the sauce forever, no exaggeration. 😭

the return code comes back in the integer pointed at by the (int *) parameter of the ppb_MS_microseq().

Parameter:

1. integer return code

Predefined macro: MS_RET(code)

---

📞 MS_OP_C_CALL — C function CALL 📞

calls C functions from microsequence execution. super handy when a non-standard i/o is being performed to grab a data character off the parallel port.

Parameter:

1. the C function to call
2. 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)

---

📍 MS_OP_PTR — initialize internal PTR 📍

initializes the internal pointer to the currently scanned buffer. this pointer gets passed to any C call (see above, bestie, keep up 💅).

Parameter:

1. pointer to the buffer that shall be accessed by xxx_P() microsequence calls. Note that this pointer is automatically incremented during xxx_P() calls

Predefined macro: MS_PTR(ptr)

---

😴 MS_OP_ADELAY — do an Asynchronous DELAY 😴

makes a tsleep() happen during microsequence execution. and the tsleep is executed at PPBPRI level, just so you know exactly where you're napping.

Parameter:

1. delay in ms

Predefined macro: MS_ADELAY(delay)

---

🔍 MS_OP_BRSTAT — BRanch on STATe 🔍

branches on a status register state condition.

Parameter:

1. mask of asserted bits. Bits that shall be asserted in the status register are set in the mask
2. mask of cleared bits. Bits that shall be cleared in the status register are set in the mask
3. 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)

---

↩️ MS_OP_SUBRET — SUBmicrosequence RETurn ↩️

returns from the submicrosequence call. this action is mandatory before a RET call — do not skip it, it's giving "I read the docs and I respect them". also heads up: some microinstructions (PUT, GET) may not be callable within a submicrosequence.

No parameter.

Predefined macro: MS_SUBRET()

---

📲 MS_OP_CALL — submicrosequence CALL 📲

calls a submicrosequence. and a submicrosequence is just a microsequence with a SUBRET call in it. that's the definition, periodt.

Parameter:

1. the submicrosequence to execute

Predefined macro: MS_CALL(microseq)

---

🫶 MS_OP_RASSERT_P — Register ASSERT from internal PTR 🫶

asserts a register with data currently pointed at by the internal PTR pointer.

Parameter:

1. amount of data to write to the register
2. register

Predefined macro: MS_RASSERT_P(iter,reg)

---

🫶 MS_OP_RFETCH_P — Register FETCH to internal PTR 🫶

fetches data from a register, and the data lands in the buffer currently pointed at by the internal PTR pointer.

Parameter:

1. amount of data to read from the register
2. register
3. mask applied to fetched data

Predefined macro: MS_RFETCH_P(iter,reg,mask)

---

⚡ MS_OP_TRIG — TRIG register ⚡

triggers the parallel port. this microinstruction exists to give you very efficient control of the parallel port, and honestly? it's the main character. triggering a register is: writing data, waiting a while, writing data, waiting a while… which is exactly how you get magic sequences out to the port. ✨

Parameter:

1. amount of data to read from the register
2. register
3. size of the array
4. 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)

---

🌸 MICROSEQUENCES 🌸

🧱 C structures 🧱

here's the shape of the things, exactly as they are:

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 */
};

---

🛠️ Using microsequences 🛠️

to instantiate a microsequence, just declare an array of ppb_microseq structures and initialize it however you need. you can either use the predefined macros, or code your microinstructions directly according to the ppb_microseq definition. either way works, you're valid. 💅

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)
};

see how some of those parameters are left undefined? they must be filled in before you execute the microsequence. to initialize each microsequence, you'd 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 you execute the microsequence. in that order. obviously. 🎀

---

🏃 The microsequencer 🏃

the microsequencer runs either at ppbus or adapter level (go peek at ppbus(4) if you want the info about the ppbus system layers). most of the microsequencer is executed at ppc level, specifically to avoid the ppbus-to-adapter function call overhead. but some actions — like deciding whether the transfer is IEEE1284-1994 compliant — are executed at ppbus layer instead. ✨

💀 BUGS 💀

okay bestie, listen, even iconic code has its little quirks, and this page is legally required to tell you about them, so here we go 🙈

• submicrosequences? one level only, babe. you get one level of submicrosequences and that is IT. no nesting a submicrosequence inside a submicrosequence inside a submicrosequence. the recursion stops here. it's giving "we ran out of stack and also patience." 💀
• triggering the port has a delay ceiling. when you trigger the port, the maximum delay allowed is 255 us. that's the cap, that's the limit, do not pass go, do not collect a longer delay. 255 us and not one microsecond more, periodt. 💅

fr fr, remember both of these before you go writing your microsequences, because these aren't suggestions, they're the actual constraints of the thing. lowkey important. ✨

---

and that's the whole page, bestie!! 🫶 you now know microseq better than most people who claim they know microseq. go forth and sequence your micros responsibly. 🌸

this little love letter to the FreeBSD kernel came from the Debian crew, dated June 6, 1998 — yes it's older than most of us and it still ate 💖✨ go drink some water and reread the BUGS section one more time, iykyk 🎀