IOASIC(9)

📦 version 11.0, in nixpkgs unstable

Bestie, welcome to IOASIC(9) from the Kernel Developer’s Manual 💅 — this is the page for the baseboard I/O control ASIC for DEC TURBOchannel systems, and we’re gonna get through every single detail together. 🎀

🌸 NAME 🌸

The whole squad of names on this page: IOASIC, ioasic_intr_establish, ioasic_intr_disestablish, ioasic_intr_evcnt, ioasic_attach_devs, and ioasic_submatch — it’s literally the baseboard I/O control ASIC for DEC TURBOchannel systems. Periodt. 👑

✨ SYNOPSIS ✨

Okay so here’s the exact include-and-signature situation, no cap:

#include <sys/bus.h>
#include <dev/tc/tcvar.h>
#include <dev/tc/ioasicreg.h>
#include <dev/tc/ioasicvar.h>

void
ioasic_intr_establish(struct device *dev, void *cookie, int level,
    int (*handler)(void *), void *arg);

void
ioasic_intr_disestablish(struct device *dev, void *cookie);

const struct evcnt *
ioasic_intr_evcnt(struct device *dev, void *cookie);

void
ioasic_attach_devs(struct ioasic_softc *sc,
    struct ioasic_dev *ioasic_devs, int ioasic_ndevs);

int
ioasic_submatch(struct cfdata *match, struct ioasicdev_attach_args *ia);

💖 DESCRIPTION 💖

The IOASIC device provides support for the DEC proprietary IOCTL ASIC found on all DEC TURBOchannel machines with MIPS (DECstation 5000 series, excluding the 5000/200) and Alpha (3000-series) systems. It’s giving very specific legacy-hardware main character energy, and honestly? Iconic. 💅

The IOASIC is memory-mapped into the TURBOchannel system slot to interface up to sixteen I/O devices. It connects the TURBOchannel to a 16-bit wide I/O bus and supplies various control signals to the devices that share this bus. ✨

The IOASIC provides hardware DMA channels and interrupt support. DMA transfers are between one and four 32-bit words (16 bytes) in length, depending on the device. The IOASIC stores the data in internal data registers. The data is transferred to and from the registers in 16-bit words to the device. Various interrupts are signalled on DMA pointer-related conditions. 🦋

🎀 DATA TYPES 🎀

Drivers for devices attached to the IOASIC will make use of these data types — learn them, love them, they’re your new besties:

🦋 struct ioasicdev_attach_args

A structure used to inform the driver of the IOASIC device properties. It contains the following members:

char                    iada_modname
tc_offset_t             iada_offset
tc_addr_t               iada_addr
void                    *iada_cookie;

🦋 struct ioasic_softc

The parent structure which contains the following members that are useful for drivers:

bus_space_tag_t         sc_bst;
bus_space_handle_t      sc_bsh;
bus_dma_tag_t           sc_dmat;

🦋 struct ioasic_dev

A structure describing the machine-dependent devices attached to the IOASIC containing the following members:

char                    *iad_modname;
tc_offset_t             iad_offset;
void                    *iad_cookie;
uint32_t                iad_intrbits;

💅 FUNCTIONS 💅

  • ioasic_intr_establish(dev, cookie, level, handler, arg) — Establish an interrupt handler with device dev for the interrupt described completely by cookie. The priority of the interrupt is specified by level. When the interrupt occurs the function handler is called with argument arg. Slay. 🔥
  • ioasic_intr_disestablish(dev, cookie) — Dis-establish the interrupt handler with device dev for the interrupt described completely by cookie. Bye-bye, handler. 👋
  • ioasic_intr_evcnt(dev, cookie) — Do interrupt event counting with device dev for the event described completely by cookie. Numbers girlies rise. 📊
  • ioasic_attach_devs(sc, ioasic_devs, ioasic_ndevs) — Configure each of the ioasic_ndevs devices in ioasic_devs. Get ’em all set up, bestie. 🫶
  • ioasic_submatch(match, ia) — Check that the device offset is not OASIC_OFFSET_UNKNOWN. Yes, that’s exactly how it’s spelled there — keep it. 👀

The ioasic_intr_establish(), ioasic_intr_disestablish(), and ioasic_intr_evcnt() functions are likely to be used by all IOASIC device drivers. The ioasic_attach_devs() function is used by ioasic driver internally and is of interest to driver writers because it must be aware of your device for it to be found during autoconfiguration. No cap, that part matters. 💖

🌈 AUTOCONFIGURATION 🌈

The IOASIC is a direct-connection bus. During autoconfiguration, machine-dependent code will provide an array of struct ioasic_devs describing devices attached to the IOASIC to be used by the ioasic driver. The ioasic driver will pass this array to ioasic_attach_devs() to attach the drivers with the devices. ✨

Drivers match the device using iada_modname. 🎯

During attach, all drivers should use the parent’s bus_space and bus_dma resources, and map the appropriate bus_space region using bus_space_subregion() with iada_offset. That’s the vibe check for attach time. 🦋

🔥 DMA SUPPORT 🔥

No additional support is provided for IOASIC DMA beyond the facilities provided by the bus_dma(9) interface. Lowkey minimalist, honestly. 💅

The IOASIC provides two pairs of DMA address pointers (transmitting and receiving) for each DMA-capable device. The pair of address pointers point to consecutive (but not necessarily contiguous) DMA blocks of size IOASIC_DMA_BLOCKSIZE. Upon successful transfer of the first block, DMA continues to the next block and an interrupt is posted to signal an address pointer update. DMA transfers are enabled and disabled by bits inside the IOASIC status (CSR) register. 🎀

The interrupt handler must update the address pointers to point to the next block in the DMA transfer. The address pointer update must be completed before the completion of the second DMA block, otherwise a DMA overrun error condition will occur.

⚠️ Bestie, this is the dramatic part: if the address pointer update is not completed before the completion of the second DMA block, you get a DMA overrun error condition. Not cute. 😭

⭐ CODE REFERENCES ⭐

The IOASIC subsystem itself is implemented within the file sys/dev/tc/ioasic_subr.c. Machine-dependent portions can be found in sys/arch/<arch>/tc/ioasic.c. Go read the source, it’s giving lore. 📚

💜 SEE ALSO 💜

And that’s the whole manual page, bestie — brought to you by Debian, dated August 6, 2000, and filed under IOASIC(9). Mwah! 💋💖✨

📦 where this page comes from