TechPubs Wiki - User contributions [en]

Irixstat

2026-03-02T17:59:29Z

Raion: Created page with "a screencap of irixstat on winterm '''irixstat''' is a program under development by Raion of IRIX Network that acts as an ncurses-based osview clone for IRIX. == Program Overview == At the top each load average is printed on its own line, then total RAM of the system, then free RAM, CPU usage graph with delta calculations and a graph for memory..."

[[File:Irixstat winterm.jpg|alt=irixstat, an ncurses application showing off load, memory and processes|thumb|a screencap of irixstat on winterm]]
'''irixstat''' is a program under development by [[User:Raion|Raion]] of IRIX Network that acts as an ncurses-based osview clone for IRIX.

== Program Overview ==
At the top each load average is printed on its own line, then total RAM of the system, then free RAM, CPU usage graph with delta calculations and a graph for memory usage. Below that, a top process chart.

'''As of 2026, irixstat does not perform any process management or system management tools. It's merely a viewer.'''

== Building irixstat ==
'''irixstat is packaged in nekoware''', however it is buildable as well. To do so, install ncurses, [https://codeberg.org/SolusRaion/irixstat download the code], and adjust the Makefile.

File:Irixstat winterm.jpg

2026-03-02T17:54:14Z

Raion:

irixstat application in winterm/xwsh

Kernel: Ethernet Drivers

2026-02-06T07:05:43Z

Raion:

This document describes the architecture and common patterns for Ethernet network drivers in IRIX based on analysis of three production drivers: Alteon Tigon (high-end), TI ThunderLAN (mid-range O2), and IOC3 (integrated ASIC). Understanding these patterns is essential for porting modern Ethernet controllers to IRIX.

== Overview ==

IRIX Ethernet drivers follow a consistent architecture across all hardware:
* '''PCI infrastructure integration''' via pciio_* APIs
* '''Hardware graph (hwgraph) registration''' for device discovery
* '''Etherif framework''' providing standard network interface
* '''Descriptor ring management''' for DMA transfers
* '''Interrupt handling''' at splimp() level
* '''MII/PHY management''' for link negotiation
* '''Packet scheduling''' (RSVP) support

== Driver Initialization Flow ==

=== Module Loading ===

All drivers follow this initialization sequence:

# '''if_XXinit()''' - Called once at boot by edtinit()
#* Registers PCI vendor/device IDs via pciio_driver_register()
#* Registers idbg debug functions
# '''if_XXattach()''' - Called for each matching PCI device
#* Creates hwgraph vertices
#* Maps PCI memory regions
#* Allocates descriptor rings
#* Initializes hardware
#* Registers interrupt handlers
# '''if_XXopen()''' - Called when interface is configured
#* Gets unit number from device_controller_num_get()
#* Calls ether_attach() to register with network stack

=== Critical Initialization Order ===

<pre>
1. pciio_driver_register() - Register with PCI subsystem
2. Allocate private state structure (ei/ti/ei_info)
3. hwgraph_char_device_add() - Create device vertex
4. pciio_piotrans_addr() - Map register spaces
5. Allocate DMA-able memory via contig_memalloc()
6. Initialize hardware (reset, PHY, MAC)
7. pciio_intr_alloc() + pciio_intr_connect()
8. ether_attach() - Final registration
</pre>

== Memory Management ==

=== DMA Memory Allocation ===

IRIX requires '''physically contiguous memory''' for DMA descriptor rings. Use contig_memalloc() with specific alignment requirements:

'''Descriptor Ring Requirements:'''
* Alteon TX ring: 64K alignment for 512-entry ring
* IOC3 TX ring: 64K alignment for 512-entry ring
* IOC3 RX ring: 4K alignment
* ThunderLAN: Page-aligned

'''Example (IOC3):'''
<source lang="c">
size = NTXD * TXDSZ; // 512 * 128 bytes
npgs = (size + NBPP - 1) / NBPP;
pgno = contig_memalloc(npgs, ALIGNMENT_PAGES, VM_DIRECT);
ei->txd = (struct eftxd*)small_pfntova_K0(pgno);
</source>

=== Cache Coherency - CRITICAL ===

IRIX systems (especially Origin/Octane with Heart chipset) require '''explicit cache management''':

'''Heart Coherency WAR:'''
<source lang="c">
#if HEART_COHERENCY_WAR
#define CACHE_WB(addr, len) heart_dcache_wb_inval((addr), (len))
#else
#define CACHE_WB(addr, len)
#endif

#if HEART_INVALIDATE_WAR
#define CACHE_INVAL(addr, len) heart_invalidate_war((addr), (len))
#else
#define CACHE_INVAL(addr, len)
#endif
</source>

'''When to flush caches:'''
* '''Before DMA read (RX):''' CACHE_INVAL() on receive buffers
* '''Before DMA write (TX):''' CACHE_WB() on transmit data
* '''After descriptor update:''' CACHE_WB() on descriptor memory
* '''IP32 (O2) specific:''' Always use __vm_dcache_inval() and dki_dcache_wb()

== PCI Infrastructure Integration ==

=== Address Translation ===

IRIX requires explicit DMA address translation for 64-bit capable devices:

'''Command DMA (descriptors, control):'''
<source lang="c">
#define KVTOIOADDR_CMD(ei, addr) \
pciio_dmatrans_addr((ei)->conn_vhdl, 0, \
kvtophys((caddr_t)(addr)), sizeof(int), \
PCIIO_DMA_A64 | PCIIO_DMA_CMD)
</source>

'''Data DMA (packet buffers):'''
<source lang="c">
// Fast path using pre-allocated DMA map
#define KVTOIOADDR_DATA(ei, addr) \
pciio_dmamap_addr((ei)->fastmap, \
kvtophys((caddr_t)(addr)), sizeof(int))

// Allocate fast map during init:
ei->fastmap = pciio_dmamap_alloc(conn_vhdl, dev_desc,
sizeof(int), PCIIO_DMA_DATA | PCIIO_DMA_A64 | PCIIO_FIXED);
</source>

=== Interrupt Registration ===

<source lang="c">
// Set interrupt name and priority
device_desc_intr_name_set(dev_desc, "Ethernet");
device_desc_intr_swlevel_set(dev_desc, (ilvl_t)splimp);

// Allocate and connect interrupt
ei->intr = pciio_intr_alloc(conn_vhdl, dev_desc,
PCIIO_INTR_LINE_A, enet_vhdl);
pciio_intr_connect(ei->intr, (intr_func_t)if_XXintr,
(intr_arg_t)ei, NULL);
</source>

== Descriptor Ring Architecture ==

All three drivers use '''producer/consumer ring buffers''' with hardware/software indices:

=== Common Ring Structure ===

<source lang="c">
struct driver_info {
// TX ring
struct txd *txd; // TX descriptor array
struct mbuf **txm; // Pending TX mbufs
int txhead; // SW produce index
int txtail; // SW consume index

// RX ring
struct rxd *rxd; // RX descriptor array
struct mbuf **rxm; // Posted RX mbufs
int rxhead; // SW consume index
int rxtail; // SW produce index
};
</source>

=== Ring Index Management ===

'''Critical macro patterns:'''
<source lang="c">
#define NEXTTXD(i) (((i) + 1) & (NTXD - 1)) // Ring must be power-of-2
#define DELTATXD(h,t) ((h - t) & (NTXD - 1)) // Free descriptors
</source>

'''IOC3-specific gotcha:''' Hardware compares RX indices modulo-16, so allocate 15 extra buffers:
<source lang="c">
#define NRBUFADJ(n) (n + 15) // Required for IOC3 only
</source>

== Transmit Path ==

=== Etherif Transmit Function ===

The transmit function must handle:
# Mbuf chain validation and coalescing
# Ethernet header insertion
# DMA address setup
# Descriptor programming
# Hardware checksum offload (if supported)
# Self-snoop for packet capture

'''Typical signature:'''
<source lang="c">
static int XX_transmit(
struct etherif *eif,
struct etheraddr *edst, // Destination MAC
struct etheraddr *esrc, // Source MAC
u_short type, // EtherType
struct mbuf *m0) // Packet chain
</source>

=== Mbuf Alignment Requirements ===

Different hardware has different alignment constraints:

'''IOC3 requirements:'''
* Data0 (in descriptor): must be even length if buf1 is used
* Buf1 pointer: must be 2-byte aligned
* Buf2 pointer: must be 128-byte aligned AND buf1 must be even length
* No buffer may cross page boundary

'''Solution patterns:'''
<source lang="c">
// Check alignment
#define MALIGN2(m) ALIGNED(mtod((m), u_long), 2)
#define MALIGN128(m) ALIGNED(mtod((m), u_long), 128)

// Copy if misaligned
if (!MALIGN2(m0) || mbuf_crosses_page(m0))
goto copyall;

copyall:
m = m_vget(M_DONTWAIT, mlen, MT_DATA);
m_datacopy(m0, 0, mlen, mtod(m, caddr_t));
m_freem(m0);
m0 = m;
</source>

=== Hardware Checksum Offload ===

'''IOC3 TX checksum:'''
<source lang="c">
if (m0->m_flags & M_CKSUMMED) {
struct ip *ip = mtod(m0, struct ip*);
int hlen = ip->ip_hl << 2;

// Compute pseudo-header checksum
__uint32_t cksum = ((ip->ip_len - hlen)
+ htons((ushort)ip->ip_p)
+ (ip->ip_src.s_addr >> 16)
+ (ip->ip_src.s_addr & 0xffff)
+ (ip->ip_dst.s_addr >> 16)
+ (ip->ip_dst.s_addr & 0xffff));

// Subtract ethernet header contribution
cksum += 0xffff ^ (type + MAC_checksum_contrib);

// Store adjustment in TCP/UDP header
mtod(m0, u_short*)[sumoff/2] = fold_checksum(cksum);

// Set descriptor flags
txd->cmd |= (sumoff << ETXD_CHKOFF_SHIFT) | ETXD_DOCHECKSUM;
}
</source>

'''Errata:''' IOC3 rev 0 has a bug - it fails to take one's complement. Disable TX checksum for rev 0 chips.

=== Descriptor Update Pattern ===

<source lang="c">
// Fill descriptor fields
txd->cmd = flags | length;
txd->bufcnt = total_length;
txd->p1 = KVTOIOADDR_DATA(ei, mbuf_data);

// CRITICAL: Writeback cache before hardware sees it
CACHE_WB((void *)txd, TXDSZ);

// Save mbuf for later freeing
ei->txm[ei->txhead] = m0;

// Update software index
ei->txhead = NEXTTXD(ei->txhead);

// Notify hardware (write produce register)
W_REG(ei->regs->etpir, (ei->txhead * TXDSZ));
</source>

== Receive Path ==

=== RX Buffer Posting ===

Drivers must maintain a pool of posted receive buffers:

<source lang="c">
static void ef_fill(struct ef_info *ei) {
int head = ei->rxhead;
int tail = ei->rxtail;
int n = ei->nrbuf - DELTARXD(head, tail);

for (i = 0; i < n; i++) {
m = m_vget(M_DONTWAIT, sizeof(struct rxbuf), MT_DATA);
if (!m) break;

rb = mtod(m, struct rxbuf*);
ei->rxm[tail] = m;
ei->rxd[tail] = KVTOIOADDR_DATA(ei, rb);

// Invalidate for DMA
CACHE_INVAL(rb, sizeof(struct rxbuf));
CACHE_WB(mtod(m, caddr_t), sizeof(struct rxbuf));

tail = NEXTRXD(tail);
}

ei->rxtail = tail;
W_REG(ei->regs->erpir, (ERPIR_ARM | (tail * RXDSZ)));
}
</source>

=== Interrupt Handler ===

IRIX interrupt handlers run at '''splimp()''' priority and must:
# Read/clear interrupt status
# Process received packets
# Reclaim completed TX descriptors
# Rearm interrupt

'''Typical pattern:'''
<source lang="c">
static void if_XXintr(struct XX_info *ei) {
int s;
struct mbuf *mact, *m;

s = mutex_bitlock(&ei->flags, EIF_LOCK);

// Read and clear interrupt status
isr = R_REG(ei->regs->eisr);
W_REG(ei->regs->eisr, isr);

// Process RX
if (isr & EISR_RXTHRESH) {
mact = ef_recv(ei);
}

// Reclaim TX
if (isr & EISR_TXDONE) {
ef_reclaim(ei);
}

// Handle errors
if (isr & EISR_ERROR) {
handle_errors(ei);
}

// Rearm
W_REG(ei->regs->erpir, ERPIR_ARM | produce_index);

mutex_bitunlock(&ei->flags, EIF_LOCK, s);

// Send packets up AFTER releasing lock
while (mact) {
m = mact;
mact = mact->m_act;
ether_input(&ei->eif, 0, m);
}
}
</source>

=== RX Checksum Validation ===

<source lang="c">
if ((ntohs(eh->ether_type) == ETHERTYPE_IP)
&& (rlen >= 60)
&& ((ip->ip_off & (IP_OFFMASK|IP_MF)) == 0)
&& ((ip->ip_p == IPPROTO_TCP) || (ip->ip_p == IPPROTO_UDP))) {

// IOC3 provides checksum in descriptor
cksum = rxd->w0 & ERXBUF_IPCKSUM_MASK;

// Finish calculation (add pseudo-header, subtract ether header)
// ...

if (cksum == 0xffff)
m->m_flags |= M_CKSUMMED;
}
</source>

== PHY Management (MII Interface) ==

=== PHY Detection and Reset ===

<source lang="c">
static int ef_phyprobe(struct ef_info *ei) {
int i, r2, r3, val;

for (i = 0; i < 32; i++) {
ei->phyunit = i;
r2 = ef_phyget(ei, MII_PHY_ID_HI);
r3 = ef_phyget(ei, MII_PHY_ID_LO);
val = (r2 << 12) | (r3 >> 4);

switch (val) {
case PHY_QS6612X:
case PHY_ICS1889:
case PHY_DP83840:
ei->phytype = val;
ei->phyrev = r3 & 0xf;
return val;
}
}
return -1;
}
</source>

=== MII Read/Write ===

Hardware provides two main approaches:

'''Approach 1: Dedicated MII registers (IOC3, ThunderLAN):'''
<source lang="c">
static int ef_phyget(struct ef_info *ei, int reg) {
// Wait for ready
while (regs->micr & MICR_BUSY)
DELAYBUS(1);

// Trigger read
regs->micr = MICR_READTRIG |
(ei->phyunit << MICR_PHYADDR_SHIFT) | reg;

// Wait for completion
while (regs->micr & MICR_BUSY)
DELAYBUS(1);

return (regs->midr_r & MIDR_DATA_MASK);
}
</source>

'''Approach 2: GPIO bit-banging (Alteon, ThunderLAN alt):'''
<source lang="c">
// Send sync pattern (32 cycles of 1)
// Send start bits (01)
// Send opcode (10=read, 01=write)
// Send PHY address (5 bits)
// Send register (5 bits)
// Turnaround and read data (16 bits)
</source>

=== Auto-negotiation ===

<source lang="c">
static void ef_autonego(struct ef_info *ei) {
int timeout = 20000;

// Enable auto-negotiation
ef_phyput(ei, MII_CTRL, MII_CTRL_AUTOEN | MII_CTRL_RESTART);

// Wait for completion
while (!(ef_phyget(ei, MII_STATUS) & MII_STATUS_ANDONE)) {
DELAY(100);
if (timeout-- <= 0) {
// Default to 10Mbit half-duplex
ei->speed100 = 0;
ei->fullduplex = 0;
return;
}
}

// Parse negotiation result
r4 = ef_phyget(ei, MII_AN_ADV);
r5 = ef_phyget(ei, MII_AN_LPAR);

if ((r4 & MII_TXFD) && (r5 & MII_TXFD)) {
ei->speed100 = 1;
ei->fullduplex = 1;
} else if ((r4 & MII_TX) && (r5 & MII_TX)) {
ei->speed100 = 1;
ei->fullduplex = 0;
}
// ... etc
}
</source>

== Watchdog and Error Handling ==

=== Periodic Watchdog ===

<source lang="c">
static void ef_watchdog(struct ifnet *ifp) {
struct ef_info *ei = eiftoei(ifptoeif(ifp));

// Update statistics
ef_getcdc(ei); // Collision/defer counters

// Check PHY status
ef_phyerr(ei);

// Reclaim TX descriptors
ef_reclaim(ei);

// Refill RX buffers
ef_fill(ei);

// Check for missed interrupts
ef_intr(ei);

// Reschedule
ei->if_timer = WATCHDOG_INTERVAL;
}
</source>

=== Link State Monitoring ===

<source lang="c">
static void ef_phyerr(struct ef_info *ei) {
int reg1 = ef_phyget(ei, MII_STATUS);

// Link status (latched low, read twice)
if (!(reg1 & MII_STATUS_LINK)) {
if (!(ei->flags & EIF_LINKDOWN)) {
cmn_err(CE_WARN, "ef%d: link fail - check cable",
ei->unit);
ei->flags |= EIF_LINKDOWN;
}
} else {
if (ei->flags & EIF_LINKDOWN) {
cmn_err(CE_NOTE, "ef%d: link ok", ei->unit);
ei->flags &= ~EIF_LINKDOWN;
ef_reinit(ei); // May need to adjust speed/duplex
}
}

// Check for remote fault, jabber, etc.
}
</source>

== RSVP/Packet Scheduling ==

IRIX supports packet scheduling for QoS. Drivers must:
# Report available TX descriptors
# Signal when descriptors become available
# Optionally interrupt on each TX completion when scheduling active

<source lang="c">
static int ef_txfree_len(struct ifnet *ifp) {
struct ef_info *ei = eiftoei(ifptoeif(ifp));
return (NTXD - DELTATXD(ei->txhead, ei->txtail));
}

static void ef_setstate(struct ifnet *ifp, int setting) {
struct ef_info *ei = eiftoei(ifptoeif(ifp));
if (setting)
ei->flags |= EIF_PSENABLED;
else
ei->flags &= ~EIF_PSENABLED;
}

// In transmit path:
if ((ei->flags & EIF_PSENABLED) &&
((ei->txhead & ei->intfreq) == 0)) {
txd->cmd |= ETXD_INTWHENDONE;
}

// In interrupt handler:
if (ei->flags & EIF_PSENABLED) {
ps_txq_stat(eiftoifp(&ei->eif), ef_txfree_len(&ei->if));
}

// During init:
struct ps_parms ps_params;
ps_params.bandwidth = ei->speed100 ? 100000000 : 10000000;
ps_params.flags = 0;
ps_params.txfree = NTXD;
ps_params.txfree_func = ef_txfree_len;
ps_params.state_func = ef_setstate;
ps_init(eiftoifp(&ei->eif), &ps_params);
</source>

== Locking and Synchronization ==

IRIX uses '''bitlocks''' for driver synchronization:

<source lang="c">
// Initialize lock during attach
init_bitlock(&ei->flags, EIF_LOCK, "ef drv lock", 0);

// Acquire in all paths that touch hardware
s = mutex_bitlock(&ei->flags, EIF_LOCK);
// ... critical section ...
mutex_bitunlock(&ei->flags, EIF_LOCK, s);

// Check if locked (for assertions)
ASSERT(ei->flags & EIF_LOCK);
</source>

'''Lock hierarchy:'''
# '''ifnet lock''' (IFNET_LOCK) - Highest level, held during ioctl
# '''Driver bitlock''' - Protects hardware access and descriptor rings
# '''Separate TX/RX locks''' - Some drivers use separate locks for TX and RX paths

'''Critical sections that need locking:'''
* Descriptor ring manipulation
* Hardware register access
* mbuf list operations
* Statistics updates

'''Operations outside lock:'''
* ether_input() - Network stack must be called without driver lock
* m_freem() - Can be called outside lock

== Common Pitfalls and Gotchas ==

=== Cache Coherency ===
'''Problem:''' Forgetting cache flushes causes random packet corruption.

'''Solution:''' Always CACHE_WB before DMA write, CACHE_INVAL before DMA read.

=== Descriptor Alignment ===
'''Problem:''' Hardware silently uses wrong memory if alignment is incorrect.

'''Solution:''' Use contig_memalloc with correct alignment parameter.

=== mbuf Chain Fragmentation ===
'''Problem:''' Each mbuf may require a separate DMA descriptor, exhausting hardware resources.

'''Solution:''' Coalesce into single mbuf if chain too long or poorly aligned.

=== Register Write Ordering ===
'''Problem:''' Posted writes may not complete before hardware starts DMA.

'''Solution:''' Read back critical registers to force write completion:
<source lang="c">
W_REG(ei->regs->emcr, EMCR_RST);
R_REG(ei->regs->emcr); // Force write to complete
</source>

=== IOC3 RX Index Comparison ===
'''Problem:''' Hardware compares RX indices modulo-16, causing premature ring full condition.

'''Solution:''' Post 15 extra buffers (NRBUFADJ macro).

=== Interrupt Re-arming ===
'''Problem:''' Forgetting to rearm causes no more interrupts.

'''Solution:''' Always write to interrupt rearm register at end of handler.

=== Link State During Init ===
'''Problem:''' Reading MII status during PHY reset gives false link-down errors.

'''Solution:''' Delay link state checking until after auto-negotiation completes.

=== Multicast Filter Collisions ===
'''Problem:''' Multiple multicast addresses may hash to same filter bit.

'''Solution:''' Maintain collision counter; keep filter bit set if any addresses hash to it.

== Hardware-Specific Considerations ==

=== Alteon Tigon ===
* '''Firmware loading''' - Must load code/data into on-chip SRAM
* '''Event ring''' - Asynchronous events in addition to interrupts
* '''Large SRAM''' - Can hold many packets on-chip
* '''Sophisticated coalescing''' - Configurable interrupt coalescing

=== TI ThunderLAN ===
* '''List-based DMA''' - Multiple fragments per packet
* '''Integrated PHY''' - On-chip 10Mbit PHY plus MII for external PHY
* '''EEPROM access''' - Complex protocol for reading MAC address
* '''Dual channels''' - Separate TX/RX channels with independent DMA

=== IOC3 ===
* '''Integrated PCI-X bridge''' - Shares functions with serial/parallel ports
* '''Hardware checksumming''' - TX and RX checksum offload
* '''SSRAM buffer''' - On-chip packet buffer (64KB or 128KB)
* '''Parity checking''' - Optional parity on SSRAM
* '''NIC EEPROM''' - Number-in-a-can for MAC address

== Testing and Debugging ==

=== Debug Print Macros ===
<source lang="c">
#define DBG_PRINT(a) if (ei->if_flags & IFF_DEBUG) printf a

// Usage:
DBG_PRINT(("ef%d: txhead=%d txtail=%d\n", unit, txhead, txtail));
</source>

=== Dump Functions ===
Every driver should provide idbg dump functions:
<source lang="c">
idbg_addfunc("ef_dump", (void (*)())ef_dump);

static void ef_dump(int unit) {
ef_dumpif(ifp); // Interface statistics
ef_dumpei(ei); // Driver private state
ef_dumpregs(ei); // Hardware registers
ef_dumpphy(ei); // PHY registers
}
</source>

=== Common Debug Points ===
* RX ring full - Check if ef_fill() is being called
* TX ring full - Check if ef_reclaim() is working
* Checksum failures - Verify pseudo-header calculation
* Link flapping - Check PHY registers and cable
* DMA errors - Verify descriptor alignment and cache flushing
* Interrupt storms - Ensure status register is being cleared

== Porting Checklist ==

When porting a new Ethernet controller to IRIX:

=== 1. PCI Infrastructure ===
* Register vendor/device ID in if_XXinit()
* Map register spaces with pciio_piotrans_addr()
* Enable bus master and memory space in PCI config
* Set cache line size and latency timer

=== 2. Memory Management ===
* Allocate descriptor rings with contig_memalloc()
* Verify alignment requirements met
* Allocate mbuf tracking arrays with kmem_zalloc()
* Create fast DMA map with pciio_dmamap_alloc()

=== 3. Hardware Initialization ===
* Reset chip and verify self-test passes
* Probe and initialize PHY
* Configure MAC address from EEPROM/NIC
* Set up descriptor ring base addresses
* Configure DMA parameters (burst size, etc.)
* Enable checksumming if supported

=== 4. Descriptor Management ===
* Implement ring index macros (NEXT, DELTA)
* Handle cache coherency (CACHE_WB/CACHE_INVAL)
* Translate addresses with KVTOIOADDR_CMD/DATA
* Post initial RX buffers

=== 5. Interrupt Handling ===
* Register handler with pciio_intr_alloc/connect
* Read and clear interrupt status
* Process RX and TX completions
* Handle error conditions
* Rearm interrupts

=== 6. Network Integration ===
* Implement etherif operations vector
* Call ether_attach() with correct inventory type
* Support multicast filtering
* Implement SIOCADDMULTI/SIOCDELMULTI ioctls
* Handle IFF_PROMISC and IFF_ALLMULTI

=== 7. Packet Scheduling ===
* Implement txfree_len callback
* Implement setstate callback
* Call ps_init() during initialization
* Optionally interrupt per-packet when PS enabled

=== 8. Testing ===
* Basic ping test (small packets)
* Large transfer test (TCP bulk data)
* Multicast functionality
* Promiscuous mode (tcpdump)
* Link up/down handling
* Error recovery (cable unplug/replug)
* Performance testing (ttcp, netperf)

== Summary ==

IRIX Ethernet drivers follow a well-defined architecture that balances hardware flexibility with software consistency. Key principles:

* '''Explicit cache management''' for DMA coherency
* '''Physically contiguous''' descriptor rings
* '''Producer/consumer rings''' with power-of-2 sizes
* '''Bitlocks''' for synchronization
* '''PHY auto-negotiation''' with error recovery
* '''Hardware/software index split''' for lock-free updates
* '''PCI infrastructure integration''' for portability

Understanding these patterns enables efficient porting of modern Ethernet controllers to the IRIX platform while avoiding common pitfalls around cache coherency, alignment, and interrupt handling.

Kernel: Ethernet Drivers

2026-02-06T07:04:28Z

Raion: Initial Commit

This document describes the architecture and common patterns for Ethernet network drivers in IRIX based on analysis of three production drivers: Alteon Tigon (high-end), TI ThunderLAN (mid-range O2), and IOC3 (integrated ASIC). Understanding these patterns is essential for porting modern Ethernet controllers to IRIX.

== Overview ==

IRIX Ethernet drivers follow a consistent architecture across all hardware:
* '''PCI infrastructure integration''' via pciio_* APIs
* '''Hardware graph (hwgraph) registration''' for device discovery
* '''Etherif framework''' providing standard network interface
* '''Descriptor ring management''' for DMA transfers
* '''Interrupt handling''' at splimp() level
* '''MII/PHY management''' for link negotiation
* '''Packet scheduling''' (RSVP) support

== Driver Initialization Flow ==

=== Module Loading ===

All drivers follow this initialization sequence:

# '''if_XXinit()''' - Called once at boot by edtinit()
#* Registers PCI vendor/device IDs via pciio_driver_register()
#* Registers idbg debug functions
# '''if_XXattach()''' - Called for each matching PCI device
#* Creates hwgraph vertices
#* Maps PCI memory regions
#* Allocates descriptor rings
#* Initializes hardware
#* Registers interrupt handlers
# '''if_XXopen()''' - Called when interface is configured
#* Gets unit number from device_controller_num_get()
#* Calls ether_attach() to register with network stack

=== Critical Initialization Order ===

<pre>
1. pciio_driver_register() - Register with PCI subsystem
2. Allocate private state structure (ei/ti/ei_info)
3. hwgraph_char_device_add() - Create device vertex
4. pciio_piotrans_addr() - Map register spaces
5. Allocate DMA-able memory via contig_memalloc()
6. Initialize hardware (reset, PHY, MAC)
7. pciio_intr_alloc() + pciio_intr_connect()
8. ether_attach() - Final registration
</pre>

== Memory Management ==

=== DMA Memory Allocation ===

IRIX requires '''physically contiguous memory''' for DMA descriptor rings. Use contig_memalloc() with specific alignment requirements:

'''Descriptor Ring Requirements:'''
* Alteon TX ring: 64K alignment for 512-entry ring
* IOC3 TX ring: 64K alignment for 512-entry ring
* IOC3 RX ring: 4K alignment
* ThunderLAN: Page-aligned

'''Example (IOC3):'''
<source lang="c">
size = NTXD * TXDSZ; // 512 * 128 bytes
npgs = (size + NBPP - 1) / NBPP;
pgno = contig_memalloc(npgs, ALIGNMENT_PAGES, VM_DIRECT);
ei->txd = (struct eftxd*)small_pfntova_K0(pgno);
</source>

=== Cache Coherency - CRITICAL ===

IRIX systems (especially Origin/Octane with Heart chipset) require '''explicit cache management''':

'''Heart Coherency WAR:'''
<source lang="c">
#if HEART_COHERENCY_WAR
#define CACHE_WB(addr, len) heart_dcache_wb_inval((addr), (len))
#else
#define CACHE_WB(addr, len)
#endif

#if HEART_INVALIDATE_WAR
#define CACHE_INVAL(addr, len) heart_invalidate_war((addr), (len))
#else
#define CACHE_INVAL(addr, len)
#endif
</source>

'''When to flush caches:'''
* '''Before DMA read (RX):''' CACHE_INVAL() on receive buffers
* '''Before DMA write (TX):''' CACHE_WB() on transmit data
* '''After descriptor update:''' CACHE_WB() on descriptor memory
* '''IP32 (O2) specific:''' Always use __vm_dcache_inval() and dki_dcache_wb()

== PCI Infrastructure Integration ==

=== Address Translation ===

IRIX requires explicit DMA address translation for 64-bit capable devices:

'''Command DMA (descriptors, control):'''
<source lang="c">
#define KVTOIOADDR_CMD(ei, addr) \
pciio_dmatrans_addr((ei)->conn_vhdl, 0, \
kvtophys((caddr_t)(addr)), sizeof(int), \
PCIIO_DMA_A64 | PCIIO_DMA_CMD)
</source>

'''Data DMA (packet buffers):'''
<source lang="c">
// Fast path using pre-allocated DMA map
#define KVTOIOADDR_DATA(ei, addr) \
pciio_dmamap_addr((ei)->fastmap, \
kvtophys((caddr_t)(addr)), sizeof(int))

// Allocate fast map during init:
ei->fastmap = pciio_dmamap_alloc(conn_vhdl, dev_desc,
sizeof(int), PCIIO_DMA_DATA | PCIIO_DMA_A64 | PCIIO_FIXED);
</source>

=== Interrupt Registration ===

<source lang="c">
// Set interrupt name and priority
device_desc_intr_name_set(dev_desc, "Ethernet");
device_desc_intr_swlevel_set(dev_desc, (ilvl_t)splimp);

// Allocate and connect interrupt
ei->intr = pciio_intr_alloc(conn_vhdl, dev_desc,
PCIIO_INTR_LINE_A, enet_vhdl);
pciio_intr_connect(ei->intr, (intr_func_t)if_XXintr,
(intr_arg_t)ei, NULL);
</source>

== Descriptor Ring Architecture ==

All three drivers use '''producer/consumer ring buffers''' with hardware/software indices:

=== Common Ring Structure ===

<source lang="c">
struct driver_info {
// TX ring
struct txd *txd; // TX descriptor array
struct mbuf **txm; // Pending TX mbufs
int txhead; // SW produce index
int txtail; // SW consume index

// RX ring
struct rxd *rxd; // RX descriptor array
struct mbuf **rxm; // Posted RX mbufs
int rxhead; // SW consume index
int rxtail; // SW produce index
};
</source>

=== Ring Index Management ===

'''Critical macro patterns:'''
<source lang="c">
#define NEXTTXD(i) (((i) + 1) & (NTXD - 1)) // Ring must be power-of-2
#define DELTATXD(h,t) ((h - t) & (NTXD - 1)) // Free descriptors
</source>

'''IOC3-specific gotcha:''' Hardware compares RX indices modulo-16, so allocate 15 extra buffers:
<source lang="c">
#define NRBUFADJ(n) (n + 15) // Required for IOC3 only
</source>

== Transmit Path ==

=== Etherif Transmit Function ===

The transmit function must handle:
# Mbuf chain validation and coalescing
# Ethernet header insertion
# DMA address setup
# Descriptor programming
# Hardware checksum offload (if supported)
# Self-snoop for packet capture

'''Typical signature:'''
<source lang="c">
static int XX_transmit(
struct etherif *eif,
struct etheraddr *edst, // Destination MAC
struct etheraddr *esrc, // Source MAC
u_short type, // EtherType
struct mbuf *m0) // Packet chain
</source>

=== Mbuf Alignment Requirements ===

Different hardware has different alignment constraints:

'''IOC3 requirements:'''
* Data0 (in descriptor): must be even length if buf1 is used
* Buf1 pointer: must be 2-byte aligned
* Buf2 pointer: must be 128-byte aligned AND buf1 must be even length
* No buffer may cross page boundary

'''Solution patterns:'''
<source lang="c">
// Check alignment
#define MALIGN2(m) ALIGNED(mtod((m), u_long), 2)
#define MALIGN128(m) ALIGNED(mtod((m), u_long), 128)

// Copy if misaligned
if (!MALIGN2(m0) || mbuf_crosses_page(m0))
goto copyall;

copyall:
m = m_vget(M_DONTWAIT, mlen, MT_DATA);
m_datacopy(m0, 0, mlen, mtod(m, caddr_t));
m_freem(m0);
m0 = m;
</source>

=== Hardware Checksum Offload ===

'''IOC3 TX checksum:'''
<source lang="c">
if (m0->m_flags & M_CKSUMMED) {
struct ip *ip = mtod(m0, struct ip*);
int hlen = ip->ip_hl << 2;

// Compute pseudo-header checksum
__uint32_t cksum = ((ip->ip_len - hlen)
+ htons((ushort)ip->ip_p)
+ (ip->ip_src.s_addr >> 16)
+ (ip->ip_src.s_addr & 0xffff)
+ (ip->ip_dst.s_addr >> 16)
+ (ip->ip_dst.s_addr & 0xffff));

// Subtract ethernet header contribution
cksum += 0xffff ^ (type + MAC_checksum_contrib);

// Store adjustment in TCP/UDP header
mtod(m0, u_short*)[sumoff/2] = fold_checksum(cksum);

// Set descriptor flags
txd->cmd |= (sumoff << ETXD_CHKOFF_SHIFT) | ETXD_DOCHECKSUM;
}
</source>

'''Errata:''' IOC3 rev 0 has a bug - it fails to take one's complement. Disable TX checksum for rev 0 chips.

=== Descriptor Update Pattern ===

<source lang="c">
// Fill descriptor fields
txd->cmd = flags | length;
txd->bufcnt = total_length;
txd->p1 = KVTOIOADDR_DATA(ei, mbuf_data);

// CRITICAL: Writeback cache before hardware sees it
CACHE_WB((void *)txd, TXDSZ);

// Save mbuf for later freeing
ei->txm[ei->txhead] = m0;

// Update software index
ei->txhead = NEXTTXD(ei->txhead);

// Notify hardware (write produce register)
W_REG(ei->regs->etpir, (ei->txhead * TXDSZ));
</source>

== Receive Path ==

=== RX Buffer Posting ===

Drivers must maintain a pool of posted receive buffers:

<source lang="c">
static void ef_fill(struct ef_info *ei) {
int head = ei->rxhead;
int tail = ei->rxtail;
int n = ei->nrbuf - DELTARXD(head, tail);

for (i = 0; i < n; i++) {
m = m_vget(M_DONTWAIT, sizeof(struct rxbuf), MT_DATA);
if (!m) break;

rb = mtod(m, struct rxbuf*);
ei->rxm[tail] = m;
ei->rxd[tail] = KVTOIOADDR_DATA(ei, rb);

// Invalidate for DMA
CACHE_INVAL(rb, sizeof(struct rxbuf));
CACHE_WB(mtod(m, caddr_t), sizeof(struct rxbuf));

tail = NEXTRXD(tail);
}

ei->rxtail = tail;
W_REG(ei->regs->erpir, (ERPIR_ARM | (tail * RXDSZ)));
}
</source>

=== Interrupt Handler ===

IRIX interrupt handlers run at '''splimp()''' priority and must:
# Read/clear interrupt status
# Process received packets
# Reclaim completed TX descriptors
# Rearm interrupt

'''Typical pattern:'''
<source lang="c">
static void if_XXintr(struct XX_info *ei) {
int s;
struct mbuf *mact, *m;

s = mutex_bitlock(&ei->flags, EIF_LOCK);

// Read and clear interrupt status
isr = R_REG(ei->regs->eisr);
W_REG(ei->regs->eisr, isr);

// Process RX
if (isr & EISR_RXTHRESH) {
mact = ef_recv(ei);
}

// Reclaim TX
if (isr & EISR_TXDONE) {
ef_reclaim(ei);
}

// Handle errors
if (isr & EISR_ERROR) {
handle_errors(ei);
}

// Rearm
W_REG(ei->regs->erpir, ERPIR_ARM | produce_index);

mutex_bitunlock(&ei->flags, EIF_LOCK, s);

// Send packets up AFTER releasing lock
while (mact) {
m = mact;
mact = mact->m_act;
ether_input(&ei->eif, 0, m);
}
}
</source>

=== RX Checksum Validation ===

<source lang="c">
if ((ntohs(eh->ether_type) == ETHERTYPE_IP)
&& (rlen >= 60)
&& ((ip->ip_off & (IP_OFFMASK|IP_MF)) == 0)
&& ((ip->ip_p == IPPROTO_TCP) || (ip->ip_p == IPPROTO_UDP))) {

// IOC3 provides checksum in descriptor
cksum = rxd->w0 & ERXBUF_IPCKSUM_MASK;

// Finish calculation (add pseudo-header, subtract ether header)
// ...

if (cksum == 0xffff)
m->m_flags |= M_CKSUMMED;
}
</source>

== PHY Management (MII Interface) ==

=== PHY Detection and Reset ===

<source lang="c">
static int ef_phyprobe(struct ef_info *ei) {
int i, r2, r3, val;

for (i = 0; i < 32; i++) {
ei->phyunit = i;
r2 = ef_phyget(ei, MII_PHY_ID_HI);
r3 = ef_phyget(ei, MII_PHY_ID_LO);
val = (r2 << 12) | (r3 >> 4);

switch (val) {
case PHY_QS6612X:
case PHY_ICS1889:
case PHY_DP83840:
ei->phytype = val;
ei->phyrev = r3 & 0xf;
return val;
}
}
return -1;
}
</source>

=== MII Read/Write ===

Hardware provides two main approaches:

'''Approach 1: Dedicated MII registers (IOC3, ThunderLAN):'''
<source lang="c">
static int ef_phyget(struct ef_info *ei, int reg) {
// Wait for ready
while (regs->micr & MICR_BUSY)
DELAYBUS(1);

// Trigger read
regs->micr = MICR_READTRIG |
(ei->phyunit << MICR_PHYADDR_SHIFT) | reg;

// Wait for completion
while (regs->micr & MICR_BUSY)
DELAYBUS(1);

return (regs->midr_r & MIDR_DATA_MASK);
}
</source>

'''Approach 2: GPIO bit-banging (Alteon, ThunderLAN alt):'''
<source lang="c">
// Send sync pattern (32 cycles of 1)
// Send start bits (01)
// Send opcode (10=read, 01=write)
// Send PHY address (5 bits)
// Send register (5 bits)
// Turnaround and read data (16 bits)
</source>

=== Auto-negotiation ===

<source lang="c">
static void ef_autonego(struct ef_info *ei) {
int timeout = 20000;

// Enable auto-negotiation
ef_phyput(ei, MII_CTRL, MII_CTRL_AUTOEN | MII_CTRL_RESTART);

// Wait for completion
while (!(ef_phyget(ei, MII_STATUS) & MII_STATUS_ANDONE)) {
DELAY(100);
if (timeout-- <= 0) {
// Default to 10Mbit half-duplex
ei->speed100 = 0;
ei->fullduplex = 0;
return;
}
}

// Parse negotiation result
r4 = ef_phyget(ei, MII_AN_ADV);
r5 = ef_phyget(ei, MII_AN_LPAR);

if ((r4 & MII_TXFD) && (r5 & MII_TXFD)) {
ei->speed100 = 1;
ei->fullduplex = 1;
} else if ((r4 & MII_TX) && (r5 & MII_TX)) {
ei->speed100 = 1;
ei->fullduplex = 0;
}
// ... etc
}
</source>

== Watchdog and Error Handling ==

=== Periodic Watchdog ===

<source lang="c">
static void ef_watchdog(struct ifnet *ifp) {
struct ef_info *ei = eiftoei(ifptoeif(ifp));

// Update statistics
ef_getcdc(ei); // Collision/defer counters

// Check PHY status
ef_phyerr(ei);

// Reclaim TX descriptors
ef_reclaim(ei);

// Refill RX buffers
ef_fill(ei);

// Check for missed interrupts
ef_intr(ei);

// Reschedule
ei->if_timer = WATCHDOG_INTERVAL;
}
</source>

=== Link State Monitoring ===

<source lang="c">
static void ef_phyerr(struct ef_info *ei) {
int reg1 = ef_phyget(ei, MII_STATUS);

// Link status (latched low, read twice)
if (!(reg1 & MII_STATUS_LINK)) {
if (!(ei->flags & EIF_LINKDOWN)) {
cmn_err(CE_WARN, "ef%d: link fail - check cable",
ei->unit);
ei->flags |= EIF_LINKDOWN;
}
} else {
if (ei->flags & EIF_LINKDOWN) {
cmn_err(CE_NOTE, "ef%d: link ok", ei->unit);
ei->flags &= ~EIF_LINKDOWN;
ef_reinit(ei); // May need to adjust speed/duplex
}
}

// Check for remote fault, jabber, etc.
}
</source>

== RSVP/Packet Scheduling ==

IRIX supports packet scheduling for QoS. Drivers must:
# Report available TX descriptors
# Signal when descriptors become available
# Optionally interrupt on each TX completion when scheduling active

<source lang="c">
static int ef_txfree_len(struct ifnet *ifp) {
struct ef_info *ei = eiftoei(ifptoeif(ifp));
return (NTXD - DELTATXD(ei->txhead, ei->txtail));
}

static void ef_setstate(struct ifnet *ifp, int setting) {
struct ef_info *ei = eiftoei(ifptoeif(ifp));
if (setting)
ei->flags |= EIF_PSENABLED;
else
ei->flags &= ~EIF_PSENABLED;
}

// In transmit path:
if ((ei->flags & EIF_PSENABLED) &&
((ei->txhead & ei->intfreq) == 0)) {
txd->cmd |= ETXD_INTWHENDONE;
}

// In interrupt handler:
if (ei->flags & EIF_PSENABLED) {
ps_txq_stat(eiftoifp(&ei->eif), ef_txfree_len(&ei->if));
}

// During init:
struct ps_parms ps_params;
ps_params.bandwidth = ei->speed100 ? 100000000 : 10000000;
ps_params.flags = 0;
ps_params.txfree = NTXD;
ps_params.txfree_func = ef_txfree_len;
ps_params.state_func = ef_setstate;
ps_init(eiftoifp(&ei->eif), &ps_params);
</source>

== Locking and Synchronization ==

IRIX uses '''bitlocks''' for driver synchronization:

<source lang="c">
// Initialize lock during attach
init_bitlock(&ei->flags, EIF_LOCK, "ef drv lock", 0);

// Acquire in all paths that touch hardware
s = mutex_bitlock(&ei->flags, EIF_LOCK);
// ... critical section ...
mutex_bitunlock(&ei->flags, EIF_LOCK, s);

// Check if locked (for assertions)
ASSERT(ei->flags & EIF_LOCK);
</source>

'''Lock hierarchy:'''
# '''ifnet lock''' (IFNET_LOCK) - Highest level, held during ioctl
# '''Driver bitlock''' - Protects hardware access and descriptor rings
# '''Separate TX/RX locks''' - Some drivers use separate locks for TX and RX paths

'''Critical sections that need locking:'''
* Descriptor ring manipulation
* Hardware register access
* mbuf list operations
* Statistics updates

'''Operations outside lock:'''
* ether_input() - Network stack must be called without driver lock
* m_freem() - Can be called outside lock

== Common Pitfalls and Gotchas ==

=== Cache Coherency ===
'''Problem:''' Forgetting cache flushes causes random packet corruption.

'''Solution:''' Always CACHE_WB before DMA write, CACHE_INVAL before DMA read.

=== Descriptor Alignment ===
'''Problem:''' Hardware silently uses wrong memory if alignment is incorrect.

'''Solution:''' Use contig_memalloc with correct alignment parameter.

=== mbuf Chain Fragmentation ===
'''Problem:''' Each mbuf may require a separate DMA descriptor, exhausting hardware resources.

'''Solution:''' Coalesce into single mbuf if chain too long or poorly aligned.

=== Register Write Ordering ===
'''Problem:''' Posted writes may not complete before hardware starts DMA.

'''Solution:''' Read back critical registers to force write completion:
<source lang="c">
W_REG(ei->regs->emcr, EMCR_RST);
R_REG(ei->regs->emcr); // Force write to complete
</source>

=== IOC3 RX Index Comparison ===
'''Problem:''' Hardware compares RX indices modulo-16, causing premature ring full condition.

'''Solution:''' Post 15 extra buffers (NRBUFADJ macro).

=== Interrupt Re-arming ===
'''Problem:''' Forgetting to rearm causes no more interrupts.

'''Solution:''' Always write to interrupt rearm register at end of handler.

=== Link State During Init ===
'''Problem:''' Reading MII status during PHY reset gives false link-down errors.

'''Solution:''' Delay link state checking until after auto-negotiation completes.

=== Multicast Filter Collisions ===
'''Problem:''' Multiple multicast addresses may hash to same filter bit.

'''Solution:''' Maintain collision counter; keep filter bit set if any addresses hash to it.

== Hardware-Specific Considerations ==

=== Alteon Tigon ===
* '''Firmware loading''' - Must load code/data into on-chip SRAM
* '''Event ring''' - Asynchronous events in addition to interrupts
* '''Large SRAM''' - Can hold many packets on-chip
* '''Sophisticated coalescing''' - Configurable interrupt coalescing

=== TI ThunderLAN ===
* '''List-based DMA''' - Multiple fragments per packet
* '''Integrated PHY''' - On-chip 10Mbit PHY plus MII for external PHY
* '''EEPROM access''' - Complex protocol for reading MAC address
* '''Dual channels''' - Separate TX/RX channels with independent DMA

=== IOC3 ===
* '''Integrated PCI-X bridge''' - Shares functions with serial/parallel ports
* '''Hardware checksumming''' - TX and RX checksum offload
* '''SSRAM buffer''' - On-chip packet buffer (64KB or 128KB)
* '''Parity checking''' - Optional parity on SSRAM
* '''NIC EEPROM''' - Number-in-a-can for MAC address

== Testing and Debugging ==

=== Debug Print Macros ===
<source lang="c">
#define DBG_PRINT(a) if (ei->if_flags & IFF_DEBUG) printf a

// Usage:
DBG_PRINT(("ef%d: txhead=%d txtail=%d\n", unit, txhead, txtail));
</source>

=== Dump Functions ===
Every driver should provide idbg dump functions:
<source lang="c">
idbg_addfunc("ef_dump", (void (*)())ef_dump);

static void ef_dump(int unit) {
ef_dumpif(ifp); // Interface statistics
ef_dumpei(ei); // Driver private state
ef_dumpregs(ei); // Hardware registers
ef_dumpphy(ei); // PHY registers
}
</source>

=== Common Debug Points ===
* RX ring full - Check if ef_fill() is being called
* TX ring full - Check if ef_reclaim() is working
* Checksum failures - Verify pseudo-header calculation
* Link flapping - Check PHY registers and cable
* DMA errors - Verify descriptor alignment and cache flushing
* Interrupt storms - Ensure status register is being cleared

== Porting Checklist ==

When porting a new Ethernet controller to IRIX:

=== 1. PCI Infrastructure ===
* [ ] Register vendor/device ID in if_XXinit()
* [ ] Map register spaces with pciio_piotrans_addr()
* [ ] Enable bus master and memory space in PCI config
* [ ] Set cache line size and latency timer

=== 2. Memory Management ===
* [ ] Allocate descriptor rings with contig_memalloc()
* [ ] Verify alignment requirements met
* [ ] Allocate mbuf tracking arrays with kmem_zalloc()
* [ ] Create fast DMA map with pciio_dmamap_alloc()

=== 3. Hardware Initialization ===
* [ ] Reset chip and verify self-test passes
* [ ] Probe and initialize PHY
* [ ] Configure MAC address from EEPROM/NIC
* [ ] Set up descriptor ring base addresses
* [ ] Configure DMA parameters (burst size, etc.)
* [ ] Enable checksumming if supported

=== 4. Descriptor Management ===
* [ ] Implement ring index macros (NEXT, DELTA)
* [ ] Handle cache coherency (CACHE_WB/CACHE_INVAL)
* [ ] Translate addresses with KVTOIOADDR_CMD/DATA
* [ ] Post initial RX buffers

=== 5. Interrupt Handling ===
* [ ] Register handler with pciio_intr_alloc/connect
* [ ] Read and clear interrupt status
* [ ] Process RX and TX completions
* [ ] Handle error conditions
* [ ] Rearm interrupts

=== 6. Network Integration ===
* [ ] Implement etherif operations vector
* [ ] Call ether_attach() with correct inventory type
* [ ] Support multicast filtering
* [ ] Implement SIOCADDMULTI/SIOCDELMULTI ioctls
* [ ] Handle IFF_PROMISC and IFF_ALLMULTI

=== 7. Packet Scheduling ===
* [ ] Implement txfree_len callback
* [ ] Implement setstate callback
* [ ] Call ps_init() during initialization
* [ ] Optionally interrupt per-packet when PS enabled

=== 8. Testing ===
* [ ] Basic ping test (small packets)
* [ ] Large transfer test (TCP bulk data)
* [ ] Multicast functionality
* [ ] Promiscuous mode (tcpdump)
* [ ] Link up/down handling
* [ ] Error recovery (cable unplug/replug)
* [ ] Performance testing (ttcp, netperf)

== Summary ==

IRIX Ethernet drivers follow a well-defined architecture that balances hardware flexibility with software consistency. Key principles:

* '''Explicit cache management''' for DMA coherency
* '''Physically contiguous''' descriptor rings
* '''Producer/consumer rings''' with power-of-2 sizes
* '''Bitlocks''' for synchronization
* '''PHY auto-negotiation''' with error recovery
* '''Hardware/software index split''' for lock-free updates
* '''PCI infrastructure integration''' for portability

Understanding these patterns enables efficient porting of modern Ethernet controllers to the IRIX platform while avoiding common pitfalls around cache coherency, alignment, and interrupt handling.

Kindler

2026-01-28T04:05:11Z

Raion: Replaced content with "'''Kindler''' is a flexible, declarative build system that is cross-platform. In fact, it was designed by Raion to explicitly support both modern Unix-likes and IRIX alike. == Availability == Kindler is going to be included in Nekoware but it can also be used with the Nekoware SDK, which offers Lua. == Why Use Kindler for an IRIX project == Kindler understands mipspro. So does Autotools, but CMake? No. Meson? No. Kindler understands IRIX's lim..."

'''Kindler''' is a flexible, declarative build system that is cross-platform. In fact, it was designed by [[User:Raion|Raion]] to explicitly support both modern Unix-likes and IRIX alike.

== Availability ==
Kindler is going to be included in [[Nekoware]] but it can also be used with the Nekoware SDK, which offers Lua.

== Why Use Kindler for an IRIX project ==
Kindler understands mipspro. So does Autotools, but CMake? No. Meson? No.

Kindler understands IRIX's limitations and gives verbose diagnostic info.

Kindler can coexist with Meson or CMake in the same project.

Kindler

2026-01-26T05:45:52Z

Raion: Created page with "= Kindler Build System Specification = '''Version:''' 0.1.0 (Draft) '''Last Updated:''' January 2026 '''Status:''' Design Phase '''AI Disclosure:''' Claude and Grok provided assistance ---- == 1. Overview == '''Kindler''' is a declarative, cached, bootstrapped build system for UNIX-like platforms. It does not build software directly—instead, it generates build files (Makefiles, Ninja files) that native build tools execute. === Core Philosophy === # '''Portable:''..."

= Kindler Build System Specification =
'''Version:''' 0.1.0 (Draft)

'''Last Updated:''' January 2026

'''Status:''' Design Phase

'''AI Disclosure:''' Claude and Grok provided assistance
----

== 1. Overview ==
'''Kindler''' is a declarative, cached, bootstrapped build system for UNIX-like platforms. It does not build software directly—instead, it generates build files (Makefiles, Ninja files) that native build tools execute.

=== Core Philosophy ===

# '''Portable:''' Runs on any POSIX-compliant system with Lua 5.1+
# '''Declarative:''' Project files describe ''what'' to build, not ''how''
# '''Non-blocking:''' Warns about problems but never prevents builds
# '''Generator-based:''' Outputs to Make/Ninja, doesn't reinvent the wheel
# '''Cached:''' Bootstraps once per system, reuses platform knowledge
# '''Interoperable:''' Plays nice with other build systems

=== What Kindler IS ===

* A project description parser (UCL format)
* A platform/compiler database (hint files + cache)
* A discovery tool (bootstrap scanner)
* A build file generator (POSIX Make, GNU Make, Ninja)
* A module loader (Lua hooks for complex tasks)

=== What Kindler IS NOT ===

* A compiler (it doesn't compile anything)
* A package manager (it doesn't fetch dependencies)
* A scripting language (no Turing-complete logic in project files)
* A build executor (Make/Ninja do the actual building)
* A replacement for CMake/Meson for all use cases

----

== 2. Architecture ==

=== 2.1 Bootstrap Phase ===
'''Purpose:''' One-time system profiling to build a knowledge cache.

'''Steps:'''

# Detect OS via <code>uname</code> and match against OS hints
# Load OS-specific hints file (<code>hints/os/<osname>.lua</code>)
# Scan for compilers listed in OS hints
# Detect available libraries (via pkg-config/pkgconf)
# Optionally scan system headers
# Serialize all findings to cache (<code>~/.config/kindler/cache/<hostname>.lua</code>)

'''Cache Format:''' Lua source files (portable, debuggable)

'''Cache Invalidation:''' 30-day TTL or manual re-bootstrap
----

=== 2.2 Project Files (UCL Format) ===
Projects are described in UCL (Universal Configuration Language), a human-readable, non-Turing-complete format.

'''Example:'''

ucl
<code>project {
name = "myapp";
lang = "c99";
version = "1.0.0";
}

dependencies {
requires = ["mbedtls >= 2.16", "pthread"];
prefer = "static"; # or "shared", "any"
}

build {
sources = ["main.c", "net.c", "util.c"];
output = "myapp";
type = "executable"; # or "static", "shared"
}

config {
debug {
cflags = ["-g", "-O0"];
defines = ["DEBUG=1"];
};
release {
cflags = ["-O2"];
defines = ["NDEBUG"];
};
}</code>
'''Key Sections:'''

* <code>project</code> — Name, language, metadata
* <code>dependencies</code> — External libraries (resolved via pkg-config + OS hints)
* <code>build</code> — Source files, output, artifact type
* <code>config</code> — Build configurations (debug, release, custom)
* <code>modules</code> — Optional Lua modules for complex tasks

----

=== 2.3 Hints System ===
Hints are Lua tables that describe platform/compiler capabilities.

==== OS Hints (<code>hints/os/<osname>.lua</code>) ====
lua
<code>return {
irix65 = {
posix = "yes",
architectures = {"sgi-mips", "sgi-mips64"},
compilers = {"mipspro", "gcc"}, ''-- native first''
endian = "big",
abi_list = {"n32", "o32", "n64"}, ''-- default first''
include_path = "/usr/include",
library_search_paths = {"/usr/lib", "/usr/lib32", "/usr/lib64"},
standard_libs = {"c", "m", "pthread"},
headers = {"stdio.h", "stdlib.h", "unistd.h", ...},
}
}</code>

==== Compiler Hints (<code>hints/compiler/<compiler>.lua</code>) ====
lua
<code>return {
mipspro = {
architecture = {"sgi-mips", "sgi-mips64"},
["compiler.drivers"] = {"/usr/bin/cc", "/usr/bin/c99", "/usr/bin/CC"},
languages = {"ansi-c", "c99", "c++98", "c++03"},
["ansi-c.driver"] = "cc", ''-- Use `cc` for ANSI C''
["c99.driver"] = "c99", ''-- Use `c99` for C99 (NOT cc -std=c99!)''
["c++98.driver"] = "CC",
version_flag = "-version",
warning_flags = "-fullwarn",
pic_flag = "-KPIC",
shared_link_flags = "-shared",
rpath_flag = "-rpath",
uses_ranlib = "no",
atomic_builtins = "no",
thread_local = "no",
}
}
```

**Key Principle:** Hints describe *capabilities*, not build commands. The generator converts hints → build rules.

''---''

### 2.4 Dependency Resolution

**Strategy:**
1. Parse `dependencies.requires` from project file
2. Check OS hints for `library_mappings` (platform-specific knowledge)
3. Query pkg-config/pkgconf for library flags
4. Fall back to generic search in `library_search_paths`
5. Respect `dependencies.prefer` (static/shared/any)
6. Warn if library not found, but don't block

**Example Flow:**
```
User requests: "mbedtls >= 2.16"
↓
Check OS hints: library_mappings.mbedtls → {pkg_config = "mbedtls"}
↓
Run: pkg-config ''--modversion mbedtls → "2.28.0" ✓''
↓
Run: pkg-config ''--libs --static mbedtls → "-lmbedtls -lmbedx509 -lmbedcrypto"''
↓
Cache result: mbedtls.libs = {...}</code>
----

=== 2.5 Build File Generation ===
'''Supported Targets:'''

* POSIX Make (maximum portability)
* GNU Make (extensions like pattern rules)
* Ninja (fast incremental builds)

'''Generator Responsibilities:'''

* Read project file + cache
* Resolve dependencies
* Select compiler based on language + OS hints
* Construct CFLAGS/LDFLAGS from hints + config
* Output build rules to target format

'''Example Output (POSIX Make):'''

make
<code># Generated by Kindler v0.1.0
# Config: debug

CC = /usr/bin/c99
CFLAGS = -g -O0 -DDEBUG=1 -fullwarn
LDFLAGS =
LIBS = -lmbedtls -lmbedx509 -lmbedcrypto -lpthread

OBJS = main.o net.o util.o

all: myapp

myapp: $(OBJS)
$(CC) $(OBJS) $(LIBS) -o myapp $(LDFLAGS)

.c.o:
$(CC) $(CFLAGS) -c $

clean:
rm -f $(OBJS) myapp</code>
----

=== 2.6 Module System ===
For complex tasks that exceed UCL's capabilities, users write '''Lua modules''' that hook into build phases.

'''Module Example:'''

lua
<code>''-- modules/version_gen.lua''
return {
name = "version_gen",
hooks = {"pre-build"},

["pre-build"] = function(context)
''-- Generate version.h from git tags''
local handle = io.popen("git describe --tags")
local version = handle:read("*a"):gsub("\n", "")
handle:close()

local f = io.open("version.h", "w")
f:write('#define VERSION "' .. version .. '"\n')
f:close()

print("Generated version.h: " .. version)
end
}</code>
'''Hook Phases:'''

* <code>pre-parse</code> — Before reading project file
* <code>post-parse</code> — After parsing, before generation
* <code>pre-build</code> — After Makefile generation

'''Loading Modules:'''

ucl
<code>modules {
load = ["version_gen", "custom_checks"];
}</code>
----

== 3. Supported Platforms (v0.1.0) ==
'''Target Systems:'''

* IRIX 6.5.x (MIPS, MIPS64)
* GNU/Linux (glibc 2.17+)
* NetBSD 9.0+
* FreeBSD 13.0+
* Solaris 11+ / OpenIndiana (if testable)

'''Required Tools:'''

* Lua 5.1, 5.2, 5.3, or 5.4
* POSIX shell (<code>/bin/sh</code>)
* <code>uname</code>, <code>test</code>, <code>mkdir</code>
* pkg-config or pkgconf (recommended)
* Make or Ninja

----

== 4. Design Decisions ==

=== 4.1 Why UCL? ===

* Human-readable (better than JSON, simpler than YAML)
* Not Turing-complete (forces separation of config vs. logic)
* Lua-parseable (no external dependencies)

=== 4.2 Why Generate, Not Build? ===

* Leverage decades of Make/Ninja optimization
* Interoperate with existing toolchains
* Users get native incremental builds "for free"

=== 4.3 Why Lua Source Caches? ===

* Portable across architectures (unlike bytecode)
* Fast to parse (Lua's parser is optimized)
* Debuggable (users can inspect/edit caches)

=== 4.4 Why Non-Blocking Warnings? ===

* Developers know their toolchains better than Kindler does
* Experimental builds should be possible
* Kindler provides info, humans make decisions

=== 4.5 Why Per-Driver Language Selection? ===

* Compilers like MIPSpro use ''different binaries'' for C89 vs C99
* GCC-style <code>-std=</code> flags are not universal
* Hints encode the "right way" per compiler

----

== 5. Limitations & Non-Goals ==
'''Limitations:'''

* No dependency fetching (use system packages or vendor code)
* No cross-compilation auto-detection (user must bootstrap target system)
* No built-in testing framework (integrate with existing tools)
* No IDE integration (yet)

'''Non-Goals:'''

* Replace CMake/Meson for GUI apps or complex projects
* Compete with Bazel/Buck for monorepos
* Support Windows natively (WSL/Cygwin maybe)
* Implement a package manager

----

== 6. Workflow Example ==
bash
<code>''# One-time bootstrap (per machine)''
$ kindler bootstrap
Detecting OS... IRIX 6.5.30
Found compilers: mipspro (/usr/bin/cc), gcc (/usr/local/bin/gcc)
Scanning headers... 342 found
Cache written: ~/.config/kindler/cache/sgi-onyx.lua

''# Generate build files''
$ cd myproject/
$ kindler generate --config=debug --target=make
Reading: project.ucl
Resolving dependencies... mbedtls [OK], pthread [OK]
Generating: Makefile (POSIX)

''# Build (using native tools)''
$ make
cc -g -O0 -DDEBUG=1 -c main.c
cc -g -O0 -DDEBUG=1 -c net.c
cc main.o net.o -lmbedtls -lpthread -o myapp

''# Switch configs''
$ kindler generate --config=release --target=ninja
Generating: build.ninja (Ninja)
$ ninja
[2/2] Linking myapp</code>
----

== 7. Future Considerations (Post-v1.0) ==

* IDE plugins (VSCode, Vim)
* CI/CD templates
* Cross-compilation wizard
* Hint database versioning
* Community hint repository

Main Page

2026-01-22T05:34:21Z

Raion:

<div id="mf-home">
<div id="MainPage">
<div id="mp-LeftColumn">
<div id="mp-Welcome" class="mp-box mp-wide">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''Welcome to The TechPubs Wiki''' </div>
<div class="mp-content">
<center>[[Special:Statistics|{{NUMBEROFARTICLES}}]] [[Special:AllPages|articles]]<p>

Tech-Pubs.net, or TechPubs, is a public wiki cataloging the hardware of the former Silicon Graphics Corporation.</center><div class="sharethis-inline-follow-buttons"></div>
</div>
</div>
</div>

<div id="mp-WorksColumns" class="mp-box mp-wide">
<div id="mp-Games" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''Getting Started''' </div>
<div class="mp-content">

===== Setting up IRIX/Familiarization =====
• [[IRIX 101]]

• [[Installing IRIX]]

• [[IRIX Setup 101]]

===== Setting up Software =====
• [[How To Find Commercial Software]]

• [[Open Source Software|Open Source Software (See Software Section)]]

===== Communities for Help =====
• [[IRIXNet]]

• [[Reddit]]

• [[SGUG]]

===== Peripherals =====
• [[Nvme|NVME]]

• [[Firewire]]

• [[USB]]

• [[Serial Tablets]]

• [[Tape Drives]]

===== Events =====
• [[Vintage Computer Festival]]

• [[IRIXNet Proposed Swap Meet]]

'''Resellers'''

• [[SGIDepot]]

• [[Mashek]]
</div>
</div>
</div>

<div id="mp-Music" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-header incell_top"> '''Hardware''' </div>
<div class="mp-image mw-no-invert"></div>
<div class="mp-content">

==== 68k-based SGIs (GL2 era) ====
• [[68k-based SGIs (IRIS Series)]]

==== MIPS-based SGIs (IRIX era) ====
• [[Professional IRIS]]

• [[Personal IRIS]]

• [[IRIS Indigo]]

• [[Power Series]]

• [[Crimson]]

• [[Indy]]

• [[Challenge S]]

• [[Indigo 2]]

• [[Challenge L]]

• [[Onyx]]

• [[Origin 200]]

• [[Onyx2]]

• [[Origin 2000]]

• [[Octane]]

• [[O2]]

• [[Origin 3000]]

• [[Fuel]]

• [[Origin 300]]

• [[Origin 350]]

• [[Tezro]]

• [[Onyx4]]

==== x86-based SGIs ====
• [[Visual Workstation 320]]

• [[Visual Workstation 540]]

• [[Visual Workstation Rebrands]]

===== Itanium (IA-64) based SGIs =====
• [[SGI 750]]

• [[Altix 330]]

• [[Altix 350]]

• [[Prism]]<br />
</div>
</div>
</div>

<div id="mp-PrintWorks" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-header incell_top"> '''Software''' </div>
<div class="mp-image mw-no-invert"></div>
<div class="mp-content">

===== IRIX Major Versions =====
• [[IRIX 6.5]]

• [[IRIX 6.2]]

• [[IRIX 5.3]]

• [[IRIX 4.0]]

===== 4D1 Versions =====
• [[4D1-3.x]]

• [[4D1-2.x]]

===== GL2 Versions =====
• [[GL2-3.x]]

• [[GL2-2.x]]

• [[GL2-1.x]]

===== RISC/OS =====
• [[RISC/OS]]

===== Development Information =====
• [[IRIS Development Option|IRIS Development Option (IRIX 6.2 and prior)]]

• [[MIPSPro|MIPSPro (IRIX 6.5)]]

• [[GCC]]

• [[Dbx|dbx (debugger)]]

• [[optxeno]]

• [[Nekoware SDK]]

===== Open Source Distributions =====
• [[SGI Freeware]]

• [[Nekoware]]

• [[SGUG RSE]]

'''IRIX Minor Versions'''

• [[IRIX 5.0 and 5.1]]

• [[IRIX 6.0 and 6.1]]
</div>

===== Subsystems =====
• [[:Category:Filesystems|Filesystems]]
</div>
</div>
</div>
</div>
<div id="mp-RightColumn">
<div id="mp-News" class="mp-box mp-wide">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''News''' </div>'''01/22/2026'''

Performance issues resolved -- moved to LSWS and got rid of varnish.

'''11/14/2025'''

100 articles! We're working hard to provide the highest quality SGI resource on the web!</div>
</div>
<div id="mp-Info" class="mp-box"><div class="mp-innerBox">
<div id="mp-Encyclopedia" class="mp-subBox">
<div class="mp-header incell_top"> '''Policies and Information''' </div>[[Style Guide]]
[[TechPubs Wiki:About|About The TechPubs Wiki]]

[[TechPubs Wiki:Copyrights|Copyright Information]]
</div>
<div id="mp-OtherArticles" class="mp-subBox">
<div class="mp-header incell"> '''Tutorials''' </div>• [[IRIX 101]]

• [[Setting Up NFS]]

• [[How To Find Commercial Software]]

• [[Porting Software to IRIX]]

• [[SSH Setup for 6.5]]

• [[IRIX Gigabit Card Hack]]
</div>
<div id="mp-AttentionArticles" class="mp-subBox">
<div class="mp-header incell"> '''Articles Needing Attention''' </div>
<div class="mp-content">
[[:Category:Stubs|Stub Articles]]

[[:Category:No Images|Articles Needing Images]]

<div class="mp-header incell"> '''SGI in Popular Culture''' </div>

[[Jurassic Park]]

[[Nintendo 64]]
</div>
</div>
</div>
</div>
</div>
</div>
</div>

__NOTOC__

Main Page

2026-01-22T02:13:19Z

Raion:

<div id="mf-home">
<div id="MainPage">
<div id="mp-LeftColumn">
<div id="mp-Welcome" class="mp-box mp-wide">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''Welcome to The TechPubs Wiki''' </div>
<div class="mp-content">
<center>[[Special:Statistics|{{NUMBEROFARTICLES}}]] [[Special:AllPages|articles]]<p>

Tech-Pubs.net, or TechPubs, is a public wiki cataloging the hardware of the former Silicon Graphics Corporation.</center><div class="sharethis-inline-follow-buttons"></div>
</div>
</div>
</div>

<div id="mp-WorksColumns" class="mp-box mp-wide">
<div id="mp-Games" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''Getting Started''' </div>
<div class="mp-content">

===== Setting up IRIX/Familiarization =====
• [[IRIX 101]]

• [[Installing IRIX]]

• [[IRIX Setup 101]]

===== Setting up Software =====
• [[How To Find Commercial Software]]

• [[Open Source Software|Open Source Software (See Software Section)]]

===== Communities for Help =====
• [[IRIXNet]]

• [[Reddit]]

• [[SGUG]]

===== Peripherals =====
• [[Nvme|NVME]]

• [[Firewire]]

• [[USB]]

• [[Serial Tablets]]

• [[Tape Drives]]

===== Events =====
• [[Vintage Computer Festival]]

• [[IRIXNet Proposed Swap Meet]]

'''Resellers'''

• [[SGIDepot]]

• [[Mashek]]
</div>
</div>
</div>

<div id="mp-Music" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-header incell_top"> '''Hardware''' </div>
<div class="mp-image mw-no-invert"></div>
<div class="mp-content">

==== 68k-based SGIs (GL2 era) ====
• [[68k-based SGIs (IRIS Series)]]

==== MIPS-based SGIs (IRIX era) ====
• [[Professional IRIS]]

• [[Personal IRIS]]

• [[IRIS Indigo]]

• [[Power Series]]

• [[Crimson]]

• [[Indy]]

• [[Challenge S]]

• [[Indigo 2]]

• [[Challenge L]]

• [[Onyx]]

• [[Origin 200]]

• [[Onyx2]]

• [[Origin 2000]]

• [[Octane]]

• [[O2]]

• [[Origin 3000]]

• [[Fuel]]

• [[Origin 300]]

• [[Origin 350]]

• [[Tezro]]

• [[Onyx4]]

==== x86-based SGIs ====
• [[Visual Workstation 320]]

• [[Visual Workstation 540]]

• [[Visual Workstation Rebrands]]

===== Itanium (IA-64) based SGIs =====
• [[SGI 750]]

• [[Altix 330]]

• [[Altix 350]]

• [[Prism]]<br />
</div>
</div>
</div>

<div id="mp-PrintWorks" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-header incell_top"> '''Software''' </div>
<div class="mp-image mw-no-invert"></div>
<div class="mp-content">

===== IRIX Major Versions =====
• [[IRIX 6.5]]

• [[IRIX 6.2]]

• [[IRIX 5.3]]

• [[IRIX 4.0]]

===== 4D1 Versions =====
• [[4D1-3.x]]

• [[4D1-2.x]]

===== GL2 Versions =====
• [[GL2-3.x]]

• [[GL2-2.x]]

• [[GL2-1.x]]

===== RISC/OS =====
• [[RISC/OS]]

===== Development Information =====
• [[IRIS Development Option|IRIS Development Option (IRIX 6.2 and prior)]]

• [[MIPSPro|MIPSPro (IRIX 6.5)]]

• [[GCC]]

• [[Dbx|dbx (debugger)]]

• [[optxeno]]

• [[Nekoware SDK]]

===== Open Source Distributions =====
• [[SGI Freeware]]

• [[Nekoware]]

• [[SGUG RSE]]

'''IRIX Minor Versions'''

• [[IRIX 5.0 and 5.1]]

• [[IRIX 6.0 and 6.1]]
</div>

===== Subsystems =====
• [[:Category:Filesystems|Filesystems]]
</div>
</div>
</div>
</div>
<div id="mp-RightColumn">
<div id="mp-News" class="mp-box mp-wide">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''News''' </div>'''01/21/2026'''

Some performance issues are being monitored. We're still adding new content, often weekly!

'''11/14/2025'''

100 articles! We're working hard to provide the highest quality SGI resource on the web!</div>
</div>
<div id="mp-Info" class="mp-box"><div class="mp-innerBox">
<div id="mp-Encyclopedia" class="mp-subBox">
<div class="mp-header incell_top"> '''Policies and Information''' </div>[[Style Guide]]
[[TechPubs Wiki:About|About The TechPubs Wiki]]

[[TechPubs Wiki:Copyrights|Copyright Information]]
</div>
<div id="mp-OtherArticles" class="mp-subBox">
<div class="mp-header incell"> '''Tutorials''' </div>• [[IRIX 101]]

• [[Setting Up NFS]]

• [[How To Find Commercial Software]]

• [[Porting Software to IRIX]]

• [[SSH Setup for 6.5]]

• [[IRIX Gigabit Card Hack]]
</div>
<div id="mp-AttentionArticles" class="mp-subBox">
<div class="mp-header incell"> '''Articles Needing Attention''' </div>
<div class="mp-content">
[[:Category:Stubs|Stub Articles]]

[[:Category:No Images|Articles Needing Images]]

<div class="mp-header incell"> '''SGI in Popular Culture''' </div>

[[Jurassic Park]]

[[Nintendo 64]]
</div>
</div>
</div>
</div>
</div>
</div>
</div>

__NOTOC__

Main Page

2026-01-21T05:11:58Z

Raion:

<div id="mf-home">
<div id="MainPage">
<div id="mp-LeftColumn">
<div id="mp-Welcome" class="mp-box mp-wide">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''Welcome to The TechPubs Wiki''' </div>
<div class="mp-content">
<center>[[Special:Statistics|{{NUMBEROFARTICLES}}]] [[Special:AllPages|articles]]<p>

Tech-Pubs.net, or TechPubs, is a public wiki cataloging the hardware of the former Silicon Graphics Corporation.</center><div class="sharethis-inline-follow-buttons"></div>
</div>
</div>
</div>

<div id="mp-WorksColumns" class="mp-box mp-wide">
<div id="mp-Games" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''Getting Started''' </div>
<div class="mp-content">

===== Setting up IRIX/Familiarization =====
• [[IRIX 101]]

• [[Installing IRIX]]

• [[IRIX Setup 101]]

===== Setting up Software =====
• [[How To Find Commercial Software]]

• [[Open Source Software|Open Source Software (See Software Section)]]

===== Communities for Help =====
• [[IRIXNet]]

• [[Reddit]]

• [[SGUG]]

===== Peripherals =====
• [[Nvme|NVME]]

• [[Firewire]]

• [[USB]]

• [[Serial Tablets]]

• [[Tape Drives]]

===== Events =====
• [[Vintage Computer Festival]]

• [[IRIXNet Proposed Swap Meet]]

'''Resellers'''

• [[SGIDepot]]

• [[Mashek]]
</div>
</div>
</div>

<div id="mp-Music" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-header incell_top"> '''Hardware''' </div>
<div class="mp-image mw-no-invert"></div>
<div class="mp-content">

==== 68k-based SGIs (GL2 era) ====
• [[68k-based SGIs (IRIS Series)]]

==== MIPS-based SGIs (IRIX era) ====
• [[Professional IRIS]]

• [[Personal IRIS]]

• [[IRIS Indigo]]

• [[Power Series]]

• [[Crimson]]

• [[Indy]]

• [[Challenge S]]

• [[Indigo 2]]

• [[Challenge L]]

• [[Onyx]]

• [[Origin 200]]

• [[Onyx2]]

• [[Origin 2000]]

• [[Octane]]

• [[O2]]

• [[Origin 3000]]

• [[Fuel]]

• [[Origin 300]]

• [[Origin 350]]

• [[Tezro]]

• [[Onyx4]]

==== x86-based SGIs ====
• [[Visual Workstation 320]]

• [[Visual Workstation 540]]

• [[Visual Workstation Rebrands]]

===== Itanium (IA-64) based SGIs =====
• [[SGI 750]]

• [[Altix 330]]

• [[Altix 350]]

• [[Prism]]<br />
</div>
</div>
</div>

<div id="mp-PrintWorks" class="mp-box mp-tall">
<div class="mp-innerBox">
<div class="mp-header incell_top"> '''Software''' </div>
<div class="mp-image mw-no-invert"></div>
<div class="mp-content">

===== IRIX Major Versions =====
• [[IRIX 6.5]]

• [[IRIX 6.2]]

• [[IRIX 5.3]]

• [[IRIX 4.0]]

===== 4D1 Versions =====
• [[4D1-3.x]]

• [[4D1-2.x]]

===== GL2 Versions =====
• [[GL2-3.x]]

• [[GL2-2.x]]

• [[GL2-1.x]]

===== RISC/OS =====
• [[RISC/OS]]

===== Development Information =====
• [[IRIS Development Option|IRIS Development Option (IRIX 6.2 and prior)]]

• [[MIPSPro|MIPSPro (IRIX 6.5)]]

• [[GCC]]

• [[Dbx|dbx (debugger)]]

• [[optxeno]]

• [[Nekoware SDK]]

===== Open Source Distributions =====
• [[SGI Freeware]]

• [[Nekoware]]

• [[SGUG RSE]]

'''IRIX Minor Versions'''

• [[IRIX 5.0 and 5.1]]

• [[IRIX 6.0 and 6.1]]
</div>

===== Subsystems =====
• [[:Category:Filesystems|Filesystems]]
</div>
</div>
</div>
</div>
<div id="mp-RightColumn">
<div id="mp-News" class="mp-box mp-wide">
<div class="mp-innerBox">
<div class="mp-image mw-no-invert"></div>
<div class="mp-header incell_top"> '''News''' </div>'''01/21/2026'''

Some performance issues are being monitored. We're still adding new content, often weekly!
'''11/14/2025'''

100 articles! We're working hard to provide the highest quality SGI resource on the web!</div>
</div>
<div id="mp-Info" class="mp-box"><div class="mp-innerBox">
<div id="mp-Encyclopedia" class="mp-subBox">
<div class="mp-header incell_top"> '''Policies and Information''' </div>[[Style Guide]]
[[TechPubs Wiki:About|About The TechPubs Wiki]]

[[TechPubs Wiki:Copyrights|Copyright Information]]
</div>
<div id="mp-OtherArticles" class="mp-subBox">
<div class="mp-header incell"> '''Tutorials''' </div>• [[IRIX 101]]

• [[Setting Up NFS]]

• [[How To Find Commercial Software]]

• [[Porting Software to IRIX]]

• [[SSH Setup for 6.5]]

• [[IRIX Gigabit Card Hack]]
</div>
<div id="mp-AttentionArticles" class="mp-subBox">
<div class="mp-header incell"> '''Articles Needing Attention''' </div>
<div class="mp-content">
[[:Category:Stubs|Stub Articles]]

[[:Category:No Images|Articles Needing Images]]

<div class="mp-header incell"> '''SGI in Popular Culture''' </div>

[[Jurassic Park]]

[[Nintendo 64]]
</div>
</div>
</div>
</div>
</div>
</div>
</div>

__NOTOC__

Category:Kernel Documentation

2026-01-10T17:58:42Z

Raion: Created page with "This page catalogs documentation of the IRIX kernel"

This page catalogs documentation of the IRIX kernel

Kernel: Process/Time Management Syscalls

2026-01-09T23:59:42Z

Raion:

== Overview ==
IRIX has many syscalls grouped by core process identity, time management, scheduling control, profiling, and signal-related system calls in the IRIX kernel. These calls operate on vproc_t (virtual process) structures, which encapsulate state shared across threads (uthreads) in multi-threaded processes.
Key areas:

Time retrieval/setting
UID/GID manipulation (System V and BSD semantics)
Process group/session control
Nice value and real-time priority adjustments
Profiling (clock-based, shared-library, R10000 event counters)
Signal blocking/masking, pending checks, suspend, handler installation, alternate stacks
Miscellaneous (pause, umask, ulimit, vhangup, sysconf)

The implementation blends System V, BSD, and POSIX behaviors, with extensions for IRIX-specific features (e.g., Frame Scheduler via schedctl).
== Key Functions ==
Time Management

gtime: Returns current time-of-day in seconds.
stime: Sets system clock.
alarm: Sets interval timer on real-time clock.
times: Returns process and child CPU times.

Identity Management

setuid / setreuid: Set real/effective UID.
setgid / setregid: Set real/effective GID (with XPG4 variant for saved-GID semantics).
getuid / getgid: Return real and effective IDs.
setgroups / getgroups: Manage supplementary group list.
umask: Set/get file creation mask (per-uthread, shared).

Process Group and Session

setpgrp: System V style (flag=0 returns pgid).
BSDsetpgrp / BSDgetpgrp: BSD compatibility.
setpgid: POSIX version.
setsid: Create new session.

Scheduling and Priority

nice: Adjust nice value.
schedctl: Unified interface for:
Real-time fixed priority
Time slice setting
Nice adjustments (process, pgrp, user-wide via plistscan)
CPU affinity
Scheduling mode (free/gang)
Frame Scheduler (FRS) operations
Legacy hooks

Profiling

profil: Traditional clock-based profiling.
sprofil: Shared-library profiling.
evc_profil: R10000 hardware event counter profiling (per-thread counters).

Signal Handling

sigpending: Return pending signal set.
sigsuspend: Atomically swap signal mask and sleep.
sigprocmask: Block/unblock signals.
sigaction: Install signal handler with mask/flags.
sigstack / sigaltstack: Set/query alternate signal stack (with XPG4 corrected behavior).

Miscellaneous

pause: Sleep until signal.
ulimit: Query/set resource limits (file size, data segment, descriptors).
vhangup: Invalidate controlling terminal.
sysconf: Runtime configuration values (e.g., _SC_ARG_MAX, _SC_NGROUPS_MAX).

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
vproc_t-Centric Design
All process-wide operations dispatch through VPROC_ macros on curvprocp, supporting shared state across uthreads.
Dual Semantics

System V (setpgrp) and BSD/POSIX (setpgid, setsid) co-exist.
XPG4 variants for sigaltstack (correct stack direction) and setregid (saved-GID handling).

schedctl Extensions

Real-time fixed priorities (non-degrading).
Gang scheduling modes.
Full Frame Scheduler (FRS) user interface for hard real-time gangs.
User-wide nice operations via process table scan.

Profiling Variants

Clock-based, shared-library, and hardware counter (R10000) profiling.
Fast profiling mode.

Signal Stack Handling

Historical IRIX sigaltstack required user to account for stack growth direction; XPG4 variant fixes this.

== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Strong overlap:

UID/GID, nice, alarm, times, pause, umask, ulimit nearly identical.
priocntl(2) analogous to schedctl for real-time classes.
Signal syscalls match POSIX.
Alternate stack via sigaltstack.

Differences: No direct FRS; different real-time model.
BSD (FreeBSD, etc.)
Close matches:

setreuid, setregid, setpgid, setsid, nice, getpriority/setpriority.
Signal interfaces standard.
sysconf for configuration.

Differences: Separate syscalls instead of unified schedctl; weaker real-time support.
Overall, IRIX provides a rich unified scheduling interface (schedctl) with strong real-time extensions (FRS, fixed-priority) while maintaining compatibility with both SVR4 and BSD/POSIX. For reimplementation, focus on vproc dispatch and dual semantics; FRS is IRIX-specific.

[[Category: Kernel Documentation]]

Kernel: vnode Operations

2026-01-09T23:58:53Z

Raion:

Summary of known vfs operations and [[Kernel: vnode and vfs|vnode]] operations.

=== 1. VFS Operations (<code>vfsops_t</code>) ===
These are operations on the '''filesystem as a whole''':
{| class="wikitable"
!Operation
!Purpose / Semantics
!Typical FS Relevance
|-
|<code>mount</code>
|Mount the filesystem; initialize structures, link root vnode.
|All FS
|-
|<code>umount</code>
|Unmount; flush buffers, release resources.
|All FS
|-
|<code>sync</code>
|Flush all dirty buffers and VM pages to disk.
|Persistent FS (EFS, XFS)
|-
|<code>statvfs</code>
|Retrieve filesystem statistics (free space, block size).
|All FS
|-
|<code>vget</code>
|Retrieve vnode by inode number or identifier.
|Persistent FS
|-
|<code>quotactl</code>
|Manage quotas on filesystem (user/group limits).
|Optional, persistent FS
|-
|<code>import</code>
|Integrate remote filesystem structures (NFS, exported FS).
|Network FS
|-
|<code>root</code>
|Return root vnode of filesystem.
|All FS
|-
|<code>reclaim</code>
|Cleanup filesystem-specific vnode data before freeing vnode memory.
|All FS
|-
|<code>fsid</code>
|Return filesystem ID.
|Persistent FS
|-
|<code>check</code>
|Perform consistency or integrity checks (optional).
|Persistent FS
|-
|<code>remount</code>
|Update mount options without unmounting.
|Optional
|-
|<code>statfs</code>
|Return summarized filesystem status.
|Persistent FS
|}
'''Notes:'''

* Pseudo-filesystems (pipefs, fifofs) stub most of these functions; only <code>root</code> or <code>vget</code> may return in-memory structures.
* Real filesystems (EFS, XFS) implement almost all operations for proper filesystem management.

----

=== 2. Vnode Operations (<code>vnodeops_t</code>) ===
These are operations on '''individual vnodes''', dispatched via the BHV layer.
{| class="wikitable"
!Operation
!Purpose / Semantics
!FS Relevance / Typical Implementation
|-
|<code>read</code>
|Read data from vnode into user or kernel buffer.
|All FS supporting files or streams
|-
|<code>write</code>
|Write data to vnode from buffer.
|All FS supporting files or streams
|-
|<code>ioctl</code>
|Perform device-specific or FS-specific commands.
|Devices, pseudo-FS, streams
|-
|<code>getattr</code>
|Retrieve vnode attributes (mode, owner, size, timestamps).
|All FS
|-
|<code>setattr</code>
|Update vnode attributes.
|All FS
|-
|<code>access</code>
|Check access permissions.
|All FS
|-
|<code>lookup</code>
|Resolve pathname component to vnode.
|Directory FS (EFS, XFS, pipefs limited)
|-
|<code>create</code>
|Create a new file.
|Persistent FS; pseudo-FS may stub
|-
|<code>remove</code>
|Remove a file.
|Persistent FS; pipefs/FIFO may implement
|-
|<code>mkdir</code>
|Create directory.
|Persistent FS
|-
|<code>rmdir</code>
|Remove directory.
|Persistent FS
|-
|<code>readdir</code>
|Read directory entries.
|Persistent FS
|-
|<code>symlink</code>
|Create symbolic link.
|Optional, persistent FS
|-
|<code>readlink</code>
|Read symbolic link target.
|Optional, persistent FS
|-
|<code>rename</code>
|Rename a file.
|Persistent FS
|-
|<code>link</code>
|Create hard link.
|Persistent FS
|-
|<code>unlink</code>
|Remove a link.
|Persistent FS
|-
|<code>fsync</code>
|Flush vnode’s buffers to disk.
|Persistent FS
|-
|<code>map</code>
|Map file pages into VM.
|Persistent FS, memory-mapped files
|-
|<code>addmap</code>
|Notify FS of memory mapping.
|Persistent FS
|-
|<code>delmap</code>
|Notify FS of unmapped region.
|Persistent FS
|-
|<code>frlock</code>
|File region locking.
|All FS supporting advisory locks
|-
|<code>poll</code>
|Determine readiness for I/O.
|Streams, pipes, devices
|-
|<code>seek</code>
|Validate seek operation.
|Regular files, optionally pseudo-FS
|-
|<code>inactive</code>
|Called when last reference released; free resources.
|All FS
|-
|<code>reclaim</code>
|Called to cleanup filesystem-specific vnode state.
|All FS
|-
|<code>realvp</code>
|Return underlying “real” vnode in layered FS.
|Stacked or layered FS
|-
|<code>cover</code>
|Return vnode that this vnode overlays.
|Stacked FS
|-
|<code>link_removed</code>
|Notify FS that a link was removed.
|Persistent FS
|}
'''Notes:'''

* '''Pseudo-filesystems''' (pipefs, fifofs):
** Implement <code>read</code>, <code>write</code>, <code>poll</code>, <code>inactive</code>
** Many other operations are stubs (<code>fs_nosys</code>) because they have no persistent storage.
* '''Persistent filesystems''' (EFS, XFS):
** Implement almost all operations fully.
** VM integration (<code>map</code>, <code>addmap</code>, <code>delmap</code>) links vnode buffers with page cache.
** Locking (<code>frlock</code>) and attribute operations are critical for filesystem consistency.
* '''Streams / devices:'''
** Integrate with <code>poll</code> / <code>select</code> via pollhead structures.
** <code>ioctl</code> is heavily used to expose device-specific functionality.

----

=== 3. Behavior Semantics ===

* Vnode operations are '''dispatched via the behavior chain''', allowing:
** '''Layered filesystems''': stacking additional behaviors (e.g., shadow vnodes, network FS).
** '''Pseudo-filesystems''': handle vnodes without disk backing.
* Operations are '''always invoked on BHV descriptors''', not directly on vnodes. This ensures correct dispatch in multi-layer environments.

----

=== 4. Filesystem Type Considerations ===
{| class="wikitable"
!FS Type
!Implemented Operations
|-
|Persistent (EFS/XFS)
|All VFS and vnode ops; full VM/page cache integration, locking, attributes
|-
|Pseudo-FS (pipefs/fifofs)
|<code>read</code>, <code>write</code>, <code>poll</code>, <code>inactive</code>; stubs for most others
|-
|Device FS (devfs)
|<code>read</code>, <code>write</code>, <code>ioctl</code>, <code>poll</code>, <code>getattr</code>/<code>setattr</code>
|-
|Network FS (NFS-like)
|<code>import</code>, <code>vget</code>, <code>root</code>, <code>lookup</code>, <code>read</code>, <code>write</code>
|}
----

=== 5. Reference / Lifecycle Management ===

* '''VFS ops:''' <code>reclaim</code> and <code>sync</code> ensure global cleanup.
* '''Vnode ops:''' <code>inactive</code> and <code>reclaim</code> ensure per-vnode cleanup.
* '''BHVs:''' behavior chain allows multiple layers to participate in cleanup or dispatch.

[[Category: Kernel Documentation]]

Kernel: malloc

2026-01-09T23:58:28Z

Raion: Raion moved page Kernel:malloc to Kernel: malloc without leaving a redirect: Misspelled title

This page documents the memory allocation subsystem of the IRIX kernel (`malloc`, `rmalloc`, and related functions) as implemented in the IRIX kernel. It is intended as a functional reference for reimplementation in other kernels (e.g., Illumos).

== Overview ==

The IRIX memory allocation system provides:

* Map-based memory management (`struct map`) for contiguous resource allocation.
* Page-aligned and color-aware allocations for cache efficiency (R4000-specific).
* Bitmap-based system page table (SPT) management.
* Waiting and non-waiting allocation paths (`VM_NOSLEEP` flag).
* Synchronization primitives using spinlocks and semaphores.

Memory management in IRIX is based on two concepts:

# **Maps** – contiguous resources tracked as a list of free/allocated blocks.
# **Bitmaps** – finer-grained allocation (e.g., pages, cache-colored pages) with alignment support.

== Map Allocation API ==

=== rmallocmap() ===
'''Purpose:''' Allocate and initialize a `struct map` for tracking resources.
'''Inputs:''' `mapsiz` – number of entries in the map.
'''Outputs:''' Pointer to newly allocated map, or NULL on failure.

'''Behavior:'''

* Allocates memory for `mapsiz + 2` map entries.
* Allocates and initializes a synchronization structure (`lock + semaphore`).
* Stores pointers to synchronization primitives in the second map entry.
* Returns a fully initialized map ready for allocations.

=== rmfreemap() ===
'''Purpose:''' Free a previously allocated map.
'''Inputs:''' Pointer to map.
'''Behavior:'''

* Waits for any threads currently blocked on the map.
* Destroys associated semaphore and spinlock.
* Frees both the map memory and the synchronization structure.

=== malloc / malloc_wait / rmalloc / rmalloc_wait ===
'''Purpose:''' Allocate contiguous units from a map.
'''Inputs:'''

* `mp` – pointer to map
* `size` – number of units
* Optional `flags` (`VM_NOSLEEP` for non-blocking)

'''Behavior:'''

* Uses **first-fit allocation**.
* Non-blocking (`VM_NOSLEEP`) returns `0` if allocation fails.
* Blocking waits on the map’s semaphore until space becomes available.
* Returns the starting address of allocated space.

=== mfree / rmfree ===
'''Purpose:''' Free previously allocated space in a map.
'''Inputs:'''

* `mp` – pointer to map
* `size` – units to free
* `a` – base address

'''Behavior:'''

* Sorts the freed block into the map.
* Merges with adjacent free blocks if possible.
* Updates map’s size and count.
* Broadcasts to any waiting threads if space becomes available.
* Logs warnings if map overflow or invalid free occurs.

== Bitmap-Based Page Table Management ==

The IRIX kernel uses **bitmap structures** to manage system page tables (`spt`). This allows fine-grained allocation with support for color and alignment.

=== sptalloc() ===
'''Purpose:''' Allocate pages from the system page table bitmap.
'''Inputs:'''

* `bm` – pointer to system bitmap structure
* `want` – number of pages
* `flags` – allocation flags (`VM_NOSLEEP`, `VM_VACOLOR`, `VM_BREAKABLE`)
* `color` – desired cache color (for R4000)
* `alignment` – page boundary alignment (power of 2)

'''Behavior:'''

* Selects a bitmap (clean, stale, aged) for allocation.
* If color-specific allocation is requested, attempts color map first.
* Uses rotors to track possible starting positions for efficiency.
* Supports alignment constraints.
* Will optionally wait (blocking) if pages are unavailable.
* Updates bitmap counters and rotors on allocation.

=== sptfree() ===
'''Purpose:''' Free pages back to the system page table bitmap.
'''Inputs:'''

* `bm` – pointer to system bitmap
* `size` – number of pages
* `mapaddr` – base address of pages to free

'''Behavior:'''

* Updates `m_lowbit`, `m_highbit`, and `m_count` in the bitmap.
* Sets freed bits in the bitmap.
* Broadcasts to waiting threads.

=== mergebitmaps() ===
'''Purpose:''' Merge one bitmap into another (e.g., stale pages back into main SPT map).
'''Inputs:'''

* `bm` – system bitmap
* `to` – destination bitmap
* `from` – source bitmap

'''Behavior:'''

* Copies set bits from source to destination.
* Updates rotor information for SPT allocation.
* Clears source bitmap.

=== bmapswtch() ===
'''Purpose:''' Swap contents of two bitmaps.
'''Use case:''' Replace an old bitmap with a new one without modifying allocation state.

=== sptgetsizes() ===
'''Purpose:''' Get counts of pages in different states (clean, stale, aged, in-transit).

== Synchronization and Multi-Processor Considerations ==

* Spinlocks (`mutex_spinlock`) protect map structures during allocation.
* Bitmaps have a hierarchy of locks:
** Normal allocation lock (`MAP_ALLOCLOCK`)**
** Urgent lock (`MAP_URGENTLOCK`)** – signals to other threads to back off during replenishment.
* Wait queues (semaphores) are used for threads blocked on resources.

== R4000-Specific Enhancements ==

* **Cache-colored allocation:** ensures pages allocated from a bitmap minimize cache conflicts.
* **sptvctst()** – tests for a free bit in a specific cache color.
* **color_alloc()** – allocates a page of a specific color.
* **sptaligntst()** – ensures alignment in allocations.

== Fault Checking ==

* `kvfaultcheck()` inspects which CPUs have references to aged or temporary pages.
* Returns a CPU mask indicating CPUs that need TLB flushes.
* Integration with isolate debugging on multi-CPU systems (EVEREST/SN0).

== Notes for Reimplementation ==

* Map-based allocations are generic and can be adapted to other OS kernels.
* Bitmap-based page allocations depend on low-level page tables; rotors and color optimizations can be implemented optionally.
* Careful handling of spinlocks, semaphores, and wait queues is required in multi-processor environments.
* Ensure that alignment and cache color are power-of-two values for correctness.
* Debug assertions (`ASSERT`) in IRIX should be converted to runtime checks or kernel asserts in the new environment.

[[Category: Kernel Documentation]]

Kernel: Poll and Select

2026-01-09T23:57:52Z

Raion:

This section describes the behavior of IRIX’s [[Kernel:6.5 Kernel|6.5 Kernel]] <code>poll(2)</code> and <code>select(2)</code> system calls as observed from kernel behavior and historical design goals.

It intentionally avoids implementation details and code structure, focusing instead on externally visible semantics, internal contracts, and compatibility considerations.

== 1. Design philosophy ==
IRIX treats <code>poll(2)</code> as the fundamental readiness-notification mechanism.

<code>select(2)</code> is a compatibility interface layered atop <code>poll</code>.

The IRIX design emphasizes:

* Precise wakeups over broadcast signaling
* Predictable latency under high fd counts
* Scalability on large SMP systems
* Tolerance of imperfect or legacy drivers
* Compatibility with historical SVR4 semantics

This leads to observable differences from Solaris and BSD-derived systems.

== 2. Core readiness model ==

=== 2.1 Explicit interest registration ===
When a thread calls <code>poll(2)</code> or <code>select(2)</code>, IRIX:

* Actively registers the thread’s interest in each polled object
* Associates that interest with the object itself
* Records the specific events the thread is waiting for

This differs from systems that merely re-scan descriptors after wakeup.

Consequence:

Only threads that expressed interest in a specific event are eligible to be woken.

=== 2.2 Object-centric wakeups ===
Pollable kernel objects (files, sockets, devices) are responsible for:

* Advertising readiness
* Waking interested threads when state changes

Wakeups originate from the object, not from a global selector.

Consequence:

Wakeups are targeted and efficient, especially when many threads are polling unrelated objects.

== 3. Wakeup precision and filtering ==
IRIX wakeups are event-filtered:

* A thread is woken only if:
** The event matches its registered interest, or
** The event represents a terminal condition (e.g., hangup or error)
* Objects may request:
** Waking all interested threads
** Waking only a single waiting thread

This behavior reduces unnecessary context switches.

=== Comparison to Solaris ===
Solaris follows a similar object-centric model, but tends to wake broader sets of threads and rely more on post-wakeup filtering.

== 4. Poll ordering and locality (“rotor behavior”) ==
IRIX introduces a locality optimization that influences how readiness scans resume after sleep:

* When a thread wakes, IRIX records ''which descriptor triggered the wakeup''
* Subsequent readiness scans preferentially resume near that descriptor
* If ambiguity exists (e.g., multiple wakeups or mixed object capabilities), the optimization is disabled

This improves performance for workloads that repeatedly poll the same small subset of descriptors.

=== Observable effects ===

* Reduced latency for hot descriptors
* Slightly different readiness ordering than Solaris in some cases
* No effect on correctness or POSIX compliance

== 5. Handling of partially pollable objects ==
IRIX supports environments where:

* Some objects fully support readiness notification
* Others cannot actively signal readiness

In such cases:

* The thread may still block
* Optimizations that rely on precise wakeup hints are conservatively disabled
* Correctness is preserved at the cost of additional scanning

=== Comparison to Solaris ===
Solaris generally expects pollable objects to fully participate in readiness signaling and is less tolerant of partial support.

== 6. Race avoidance and readiness consistency ==
IRIX takes explicit measures to avoid lost wakeups:

* Readiness is checked before sleeping
* Registration and wakeup are ordered to detect concurrent state changes
* If readiness changes during registration, the scan is immediately retried

Consequence:

A readiness event that occurs during a <code>poll(2)</code> call is not silently lost.

Solaris employs similar concepts, but IRIX favors immediate in-kernel recovery rather than deferring detection to later scans.

== 7. Timeout behavior ==
IRIX timeouts:

* Are internally rounded to system clock resolution
* Are conservatively extended to avoid early expiration
* May therefore exceed the requested timeout by a small margin

This behavior prioritizes correctness over precision.

Solaris typically offers finer-grained timeout resolution.

== 8. Interaction with signals ==
If a polling thread receives a signal:

* The poll is interrupted
* All readiness registrations made during the call are cleaned up
* The system call returns with <code>EINTR</code>

IRIX guarantees that interrupted polls do not leave stale readiness state behind.

== 9. select(2) compatibility semantics ==
Although implemented atop <code>poll(2)</code>, IRIX preserves traditional <code>select(2)</code> behavior:

* Invalid descriptors cause <code>select(2)</code> to fail with <code>EBADF</code>
* The same condition in <code>poll(2)</code> results in per-descriptor error reporting
* Exceptional conditions are reported using historical bitmask semantics

This ensures compatibility with legacy applications.

== 10. Driver expectations ==
Kernel drivers participating in readiness notification are expected to:

* Advertise readiness consistently
* Signal state changes when readiness transitions occur
* Maintain internal state sufficient to avoid missed notifications

IRIX is tolerant of drivers that partially implement these expectations, though reduced performance or warnings may result.

Solaris assumes stricter adherence to the readiness framework.

== 11. Summary of key differences from Solaris ==
{| class="wikitable"
!Area
!IRIX
!Solaris
|-
|Readiness model
|Object-centric, targeted
|Object-centric, broader
|-
|Wakeup precision
|Highly filtered
|Moderately filtered
|-
|Poll ordering
|Locality-optimized
|Fairness-oriented
|-
|Partial poll support
|Tolerated
|Less common
|-
|Race recovery
|Immediate retry
|Deferred detection
|-
|Timeout precision
|Tick-based, conservative
|Higher resolution
|-
|select compatibility
|Strong legacy fidelity
|Version-dependent
|}

== 12. Guidance for emulation or re-implementation ==
To mimic IRIX poll/select behavior:

* Use object-centric readiness tracking
* Avoid broadcast wakeups
* Preserve per-event filtering
* Support conservative timeout rounding
* Clean up readiness state on interruption
* Preserve historical select(2) error behavior

Attempting to directly transplant Solaris semantics without accounting for these differences will result in observable behavioral drift.

== 13. Final note ==
IRIX poll/select behavior is best understood not as a variant of Solaris, but as a parallel evolution from the same SVR4 roots, shaped by IRIX’s scalability goals and long hardware lifespan.

This behavior is intentional, consistent, and relied upon by real software.

[[Category: Kernel Documentation]]

Kernel: STREAMS

2026-01-09T23:57:41Z

Raion:

The IRIX [[STREAMS]] framework provides a modular, message-passing I/O subsystem for character devices, terminals, network protocols, and pseudo-devices. It uses queues (read/write pairs per module/driver), message blocks (mblk_t/dblk_t), and buffers for data transfer. The implementation is highly optimized for performance with:

Per-CPU free lists (NUMA-aware) for message blocks, data blocks, and buffers of various sizes.
Cache coloring and alignment support.
Zone-based allocation for small structures.
Page-based buffering with coalescing and reclaim.
Global limits and dynamic reclamation via strgiveback.
MP-safe design using spinlocks per CPU.

The core data structures are managed through list vectors (lf_listvec) per CPU, with separate pools for different buffer sizes (64B to full page).
== Key Functions ==
Initialization

str_init_master: Initializes global structures for master CPU.
str_init_slave: Sets up per-CPU structures for slave CPUs.
str_init_memsize: Configures page limits based on physical memory.
str_init_alloc_bufs: Preallocates initial buffers per CPU.
strinit_giveback: Starts periodic page reclamation timer.

Message Block Allocation

allocb: Allocates mblk_t + dblk_t + buffer (various sizes).
allocb_nobuffer: Allocates only mblk_t/dblk_t (no data buffer).
esballoc: Attaches external buffer (zero-copy).
bufcall / esbbcall: Schedule callback when memory available.

Queue Operations

putq / putbq / insq: Insert message into queue (priority-ordered).
getq: Remove next message from queue.
rmvq: Remove specific message.
flushq / flushband: Discard messages (all or by band).
qenable: Schedule queue service routine.
canput / bcanput: Flow control checks.

Buffer Management

lf_get / lf_free: Node allocation/deallocation from per-CPU lists.
lf_addpage / lf_getpage_tiled: Page tiling and addition to free lists.
lf_freepage: Return full page to kernel VM.
str_preallocate: Initial buffer preallocation.

Special Cases

msgpullup: Coalesce message into single contiguous buffer.
copyb / copymsg / dupb / dupmsg: Copy or reference-count messages.
linkb / unlinkb: Chain management.
adjmsg: Trim bytes from head/tail.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Structures

mblk_t: Message descriptor (pointers, type, flags, band).
dblk_t: Data block (buffer pointers, refcount, type, size, free routine).
queue_t: Read/write queue pair with flow control parameters.
qband_t: Per-priority-band flow control (for non-zero bands).
lf_listvec / listvec: Per-CPU free list vectors with multiple size classes.
strstat: Per-CPU statistics.

Buffer Pools

Fixed sizes: 64, 256, 512, 2048 bytes + full page.
Combined mblk_t/dblk_t pool.
Separate message header pool.
Page reclamation: strgiveback returns excess pages to kernel.

NUMA Awareness

Per-node, per-CPU list vectors.
Allocation prefers local node.

Flow Control

High/low water marks per queue and band.
QFULL / QB_FULL flags.
Back-enable nearest upstream service routine.

Extended Free Routine

esballoc supports external buffers with custom free function.

== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Strong similarity:

Message block (mblk_t/dblk_t) and queue model nearly identical.
allocb, esballoc, putq, getq, canput, qenable.
Per-CPU caches and buffer pools.
Flow control with high/low water.

Differences: illumos uses kmem_cache extensively; more modular.
BSD (FreeBSD, etc.)
Less similar:

No native STREAMS (removed long ago).
Character I/O via cdevsw or tty.
Some ports emulate via compatibility layers.

Overall, IRIX STREAMS is classic SVR4 with NUMA/per-CPU optimizations. illumos provides closest modern equivalent; BSD lacks native support. For replication: preserve per-CPU lists, buffer size classes, and queue scheduling semantics. Page reclamation and tiling logic are IRIX-specific.
[[Category: Kernel Documentation]]

Kernel: vnode and vfs

2026-01-09T23:57:38Z

Raion:

IRIX’s VFS (Virtual File System) and vnode architecture is conceptually similar to many UNIX-derived systems (BSD, System V, Solaris), but with some IRIX-specific behavior layering and STREAMS integration. The vnode system provides a uniform abstraction for all filesystem objects, enabling the kernel to operate generically on files, directories, FIFOs, and devices without knowing the underlying filesystem implementation.

=== 1. Vnode: Abstract File Object ===

* Purpose: Represents an in-memory file or pseudo-file object. Every file, device, pipe, or FIFO that a process can access has a corresponding vnode.
* Key Responsibilities:
** Maintain reference counts (<code>v_count</code>) for lifecycle management.
** Track the type of file (<code>v_type</code>), device association (<code>v_rdev</code>), and filesystem association (<code>v_vfsp</code>).
** Serve as a link to behavior-specific operations (via <code>v_bh</code>).
** Integrate with streams (<code>v_stream</code>) if the object is a pipe, TTY, or socket.
** Enable VM caching, delayed writes, and buffer trees for efficient I/O.
* Comparison to Solaris: IRIX vnodes are conceptually similar to Solaris <code>vnode_t</code>. Both provide:
** Reference counting
** Filesystem abstraction
** A behavior or operations layer
** VM caching integration Differences: IRIX exposes <code>v_buf</code>/<code>v_dpages</code> directly for buffer/page management; Solaris tends to isolate VM caching in the <code>vnode</code>/<code>vfs</code> interface via <code>v_cache</code> and VM layers.

=== 2. Behavior Layer (BHV) ===

* Purpose: Allows vnodes to stack filesystem-specific operations on top of a generic vnode.
* Mechanism:
** Each vnode has a behavior descriptor list (<code>v_bh</code>).
** Filesystems (pipefs, efs, xfs, fifofs) insert their operations at initialization.
** Kernel vnode calls (<code>VOP_READ</code>, <code>VOP_WRITE</code>, <code>VOP_CLOSE</code>) traverse the behavior chain to find the appropriate function.
* Comparison to Solaris: IRIX’s BHV is functionally similar to Solaris’ VOP vector and shadow vnode mechanism in layered filesystems, but IRIX’s BHV model explicitly allows multiple behaviors per vnode (stacked operations).

=== 3. VFS: Virtual Filesystem Layer ===

* Purpose: Represents a mounted filesystem in-memory, providing a global interface for:
** File lookup
** Attribute management
** Mount/unmount operations
** Import/export for NFS or network filesystems
* VFS Operations (<code>vfsops_t</code>):
** <code>mount</code> / <code>umount</code>: Mount/unmount filesystem
** <code>sync</code>: Flush dirty data
** <code>statvfs</code>: Retrieve filesystem statistics
** <code>vget</code>: Lookup vnode by inode within the filesystem
** <code>quotactl</code>: Manage quotas (if supported)
** <code>import</code>: Handle import of remote filesystem data
** <code>root</code>: Provide vnode for root of FS
** <code>reclaim</code>: Clean up filesystem-specific vnode state

<blockquote>Note: In IRIX pipefs, most of these are <code>fs_nosys</code> or dummy functions because pipefs is a pseudo-filesystem without persistent storage.</blockquote>

* Comparison to Solaris:
** Very similar to Solaris <code>vfsops_t</code>.
** Both systems separate filesystem-specific behavior (<code>vnodeops_t</code>) from filesystem-wide operations (<code>vfsops_t</code>).
** IRIX adds <code>vfs_insertbhv</code> to bind a VFS to its BHV layer, enabling layered filesystems.

=== 4. Vnode Operations (<code>vnodeops_t</code>) ===

* Purpose: Defines the operations you can perform on a vnode, such as read, write, ioctl, getattr, setattr, seek, poll, and more.
* IRIX Implementation Pattern:
** Functions take a behavior descriptor (<code>bhv_desc_t</code>) instead of the vnode directly.
** For pseudo-filesystems like pipefs, the operations implement custom logic (e.g., <code>pipe_read</code>, <code>pipe_write</code>, <code>pipe_poll</code>).
** Many operations are stubbed to <code>fs_nosys</code> or <code>fs_noerr</code> if not meaningful (e.g., <code>vop_create</code> in pipefs).
* Categories of operations:
*# File I/O: <code>read</code>, <code>write</code>, <code>ioctl</code>, <code>fsync</code>, <code>fcntl</code>
*# Attributes: <code>getattr</code>, <code>setattr</code>, <code>access</code>, <code>pathconf</code>, <code>attr_get/set</code>
*# Directory/Namespace: <code>lookup</code>, <code>create</code>, <code>remove</code>, <code>mkdir</code>, <code>rmdir</code>, <code>readdir</code>, <code>symlink</code>, <code>readlink</code>
*# Locking/Mapping: <code>rwlock</code>, <code>rwunlock</code>, <code>map</code>, <code>addmap</code>, <code>delmap</code>, <code>frlock</code>
*# Streams support: <code>strgetmsg</code>, <code>strputmsg</code>
*# Polling/Selection: <code>poll</code>, <code>select</code> integration via <code>pollhead</code>
*# Cleanup: <code>inactive</code>, <code>reclaim</code>, <code>realvp</code>, <code>cover</code>, <code>link_removed</code>
* Comparison to Solaris:
** IRIX <code>vnodeops_t</code> maps almost one-to-one to Solaris VOP functions.
** IRIX uses <code>bhv_desc_t</code> for behavior dispatch; Solaris uses direct <code>vnode_t*</code> and VOP macros.
** <code>pipefs</code> shows how pseudo-filesystems are inserted into the BHV chain.

=== 5. Lifecycle Management ===

* Reference counting (<code>v_count</code>) is used by:
** VFS, FS operations, streams, and user-level file descriptors.
* Inactive/Teardown:
** <code>vnode_inactive</code> is called when the last reference is released.
** Pseudo-filesystems clean up buffers, semaphores, SVs, and polling structures.
* Reclaim:
** <code>vop_reclaim</code> (or <code>fs_noerr</code>) allows the FS to free internal structures before the vnode memory itself is freed.
* Comparison to Solaris:
** IRIX inactive/reclaim closely mirrors Solaris, where <code>VN_RELE</code> triggers <code>VOP_INACTIVE</code> and may later call <code>VOP_RECLAIM</code>.

=== 6. Integration with Poll/Select ===

* Each vnode supporting streams or pseudo-filesystems exposes a <code>poll</code> operation (<code>pipe_poll</code> example).
* Vnode maintains pollheads (<code>pi_rpq</code>, <code>pi_wpq</code>) to manage sleeping readers/writers.
* Poll/select logic interacts directly with vnodes’ wait queues, using semaphores and SVs to wake sleeping processes.
* IRIX integrates select/poll tightly with its behavior layer: the <code>vnodeops</code> dispatch ensures the correct filesystem or pseudo-device handles events.

=== 7. Streams and Pseudo-Filesystems ===

* Vnodes can represent STREAMS objects (<code>v_stream</code>), which include pipes, ttys, sockets.
* Pseudo-filesystems like pipefs, fifofs, or STREAMS-based devices rely on vnodes for identity but do not implement persistent storage.
* Pipefs shows:
** Behavior insertion (<code>pipe_bhv</code>)
** Read/write/poll implemented at the vnode level
** Attribute, locking, and inactive handling integrated with BHV and semaphores

=== 8. Key Semantic Takeaways vs. Solaris/OpenSolaris ===
{| class="wikitable"
!Feature
!IRIX
!Solaris / OpenSolaris
!Notes
|-
|Vnode abstraction
|Generic file object
|Generic file object
|Conceptually identical
|-
|Behavior Layer
|<code>v_bh</code>, multiple behaviors
|VOP vector, shadow vnode
|IRIX allows stacking; Solaris uses layered vnode/shadow vnodes
|-
|VFS interface
|<code>vfsops_t</code>
|<code>vfsops_t</code>
|Almost identical; mount/unmount, sync, statvfs, vget
|-
|Vnode ops
|<code>vnodeops_t</code>
|<code>vnodeops_t</code>
|Nearly identical; both separate FS operations from global FS ops
|-
|Streams integration
|<code>v_stream</code>
|<code>v_stream</code> (STREAMS)
|Very similar; IRIX integrates tightly with select/poll via SVs/semaphores
|-
|Page/Buffer caching
|<code>v_dpages</code>, <code>v_buf</code>, <code>v_pc</code>
|Solaris uses <code>v_cache</code>, <code>v_pages</code>
|IRIX exposes more VM/buffer fields directly
|-
|Poll/select
|<code>pollhead</code>, <code>sv_wait_sig</code>
|<code>pollhead</code> + <code>selwait</code>
|Both implement readiness/wakeup mechanisms; IRIX uses semaphores/SV directly
|}

=== 9. Summary ===
IRIX vnode/VFS system is:

* Highly modular: behavior layers allow multiple filesystems and pseudo-filesystems to stack operations.
* Stream-aware: supports pipes, ttys, FIFOs, and sockets in a unified way.
* Poll/select integrated: readiness queues and SVs are part of each vnode.
* VM-aware: page cache, dirty pages, buffers, and delwri structures are exposed.
* Reference-counted: ensures proper lifecycle management via <code>inactive</code>/<code>reclaim</code>.
* OpenSolaris-like: almost all concepts map directly to Solaris VFS/vnode system.

== See also ==

* [[Kernel: vnode Operations]]

[[Category: Kernel Documentation]]

Kernel: pfile

2026-01-09T23:57:08Z

Raion:

== Overview ==
The pfile (physical file) object in the IRIX kernel represents per-open-file state beyond the vnode (file system-independent) and vfile (open file description) layers. It primarily manages the current file offset (pf_offset) and associated synchronization (pf_offlock). In single-cell (non-distributed) configurations, the pfile layer directly handles offset and flag operations. In distributed (multi-cell) environments using Cellular IRIX features, higher layers (DC - Distributed Coordinator, DS - Distributed Server) take over offset and flag management for coherence across cells.
The pfile is integrated via the behavior descriptor (bhv_desc_t) mechanism, part of IRIX's chained vnode/behavior system. This allows stacking behaviors (e.g., pfile on top of filesystem-specific behaviors) on a common vfile_t structure. The pfile behavior is registered through pfile_ops (a vfileops_t table) at position VFILE_POSITION_PFILE.
== Key Functions ==
The implementation provides operations for creation, offset management, flag handling, teardown, close, and migration.
Initialization (pfile_init)
Allocates a kernel zone (pfile_zone) for efficient pfile_t structures using kmem_zone_init.
Creation (pfile_create)
Called on file open: allocates a pfile_t from the zone, initializes offset mutex and sets offset to 0, creates and inserts a bhv_desc_t (pf_bd) into the vfile_t behavior chain at the initial position.
Migration (pfile_target_migrate)
Used during distributed target migration (e.g., cell handover): creates a new pfile behavior, inserts it into the chain, and sets a specific offset (preserving position across migration).
Flag Management (pfile_setflags)
Locks the vfile_t, modifies open flags (vf_flag) using atomic mask/or operations, unlocks.
Offset Access (pfile_getoffset / pfile_setoffset)
Simple unprotected read/write of pf_offset. VFILE_NO_OFFSET is ignored on set.
Locked Offset Access (pfile_getoffset_locked / pfile_setoffset_locked)
Optional locking of pf_offlock (cell mutex) around offset operations for distributed safety.
Teardown (pfile_teardown)
Destroys offset mutex, removes behavior from chain (if vnode exists), frees pfile_t to zone. Asserts mutex not held.
Close Handling (pfile_close)
Called twice per close (first/last): decrements vf_count in vfile_t, returns flags indicating last close.
== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Critical Structures

pfile_t (from pfile_private.h):
off_t pf_offset — current file position.
mutex_t pf_offlock — mutex protecting offset in distributed mode.
bhv_desc_t pf_bd — behavior descriptor linking to vfile.

vfileops_t pfile_ops — operations table registered in behavior chain:
Position: VFILE_POSITION_PFILE
Functions: setflags, getoffset, setoffset, locked variants, teardown, close.

Integration with vfile_t:
Contains vf_flag (open flags), vf_count (reference count), vf_bh (behavior chain head).

Distributed vs Single-Cell Behavior

Single-cell: pfile directly manages offset/flags.
Multi-cell (Cellular IRIX): DC/DS layers override; pfile provides fallback or local cache.

Behavior Chain Mechanics
Uses bhv_desc_t chaining (bhv_insert_initial, bhv_insert, bhv_remove). Allows dynamic stacking of behaviors (e.g., pfile over XFS/EFS vnode).
Migration Support
pfile_target_migrate enables seamless offset preservation during distributed file target changes (rare in standard IRIX, specific to Cellular configurations).
== Similarities to illumos and BSD libc/kernel Implementations ==
IRIX file handling differs significantly from modern open-file-description models due to its vnode/behavior layering.
illumos (Solaris-derived)
Moderate similarity in layered vnode design (vnode ops, but no direct behavior chaining). File offsets live in struct file (user fd) or uio; no separate pfile-like object. Distributed features (Cluster) use different mechanisms. illumos uses struct cred, zones; no exact pfile equivalent.
BSD (FreeBSD, etc.)
Less similar: file offsets in struct file (per-fd), with filedesc table. Vnode ops direct, no behavior descriptors/chaining. No distributed cell concept; clustering separate. Close handling simpler (single decrement).
Overall, IRIX's pfile is unique to its bhv_desc_t behavior system, designed for extensibility and distributed coherence. For replication or porting, focus on exact behavior insertion order and mutex usage. No direct illumos/BSD analog for easy porting; closest is Solaris vnode layering but without pfile separation.
[[Category: Kernel Documentation]]

Kernel: malloc

2026-01-09T23:56:26Z

Raion:

Kernel: Signal Infrastructure

2026-01-09T23:56:07Z

Raion:

== Overview ==
The IRIX kernel signal infrastructure provides a comprehensive, POSIX-compliant signal delivery system with extensions for real-time, debugging, and multi-threaded processes. Signals are managed at both process (sigvec_t in proc_t) and thread (ut_sig, ut_sighold in uthread_t) levels, allowing per-thread signal masks and delivery while maintaining process-wide consistency.
Key features:

Queued signals (sigqueue_t) for POSIX sigqueue and siginfo delivery.
Priority-based delivery with job control stops handled specially.
Alternate signal stacks (sigaltstack, legacy sigstack).
Signal contexts (ucontext_t, sigcontext) for setcontext/getcontext and signal handlers.
Debugging integration (/proc, ptrace).
Multi-threaded awareness — signals can target specific uthreads or the process.
Async signal delivery via async_vec_t for non-sleepable contexts.

The system carefully handles races between signal posting, masking, and delivery using spinlocks and atomic operations.
== Key Functions ==
Signal Posting

sigtopid: Send signal to process by PID (handles async via async_call if SIG_NOSLEEP).
sigtouthread / sigtouthread_common: Deliver to specific uthread.
sigaddq / sigdeq / sigdelq: Manage queued siginfo structures.
sigqueue_alloc / sigqueue_free: Zone-based allocation.

Signal Delivery

issig: Check for pending unmasked signals (returns signal number).
fsig: Find first unheld signal.
psig: Process current signal — installs handler or takes default action.
sendsig: Set up user context and registers for handler entry.
stop / unstop: Job control and debugger stops.

Context Management

save/restore context functions for ucontext_t and legacy sigcontext.
irix5_*_savecontext / restorecontext: ABI-specific versions.

Signal Waiting

sigpending: Return pending signal set.
sigsuspend: Swap mask and sleep.
sigprocmask: Modify signal mask.
sigpoll / sigtimedwait: Wait for specific signals (POSIX sigwait family).

Special Interfaces

ptrace: Classic debugging interface.
sigaltstack / sigstack: Alternate signal stack control.
core: Generate core dump on fatal signals.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Structures

sigvec_t (process-wide):
sv_sig, sv_sigign, sv_sigcatch: Pending, ignored, caught signals.
sv_hndlr[NSIG_HNDLRS]: Handler array.
sv_sigmasks, sv_signodefer, sv_sigrestart, sv_sigresethand: Per-signal flags.
sv_sigqueue: Head of queued siginfo list.
sv_pending: Count of queued signals.

uthread_t signal fields:
ut_sig: Thread-private pending signals.
ut_sighold: Thread-private blocked mask.
ut_sigwait: Signals being waited on.
ut_cursig, ut_curinfo: Current signal and siginfo.
ut_suspmask: Saved mask during sigsuspend.

sigqueue_t: Queued siginfo with chaining.

Dual Delivery Model

Signals can be process-directed (posted to sigvec_t) or thread-directed (sigtouthread).
VPROC_SENDSIG virtualizes delivery across threads.
Async delivery queue for non-sleepable contexts.

Job Control Special Cases

SIGCONT cancels pending stop signals.
Stop signals ignored if no handler and process orphaned (except SIGSTOP).

Queued Signals

sigqueue() delivers siginfo_t with value.
Multiple same-signal infos preserved only if SI_QUEUE, SI_ASYNCIO, etc.

Alternate Stack

prxy_sigsp, prxy_spsize, prxy_siglb: Track alternate stack base/size/low bound.
SS_ONSTACK flag managed carefully.

== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Strong similarity:

sigqueue(), queued signals, siginfo_t.
sigprocmask, sigsuspend, sigaction semantics.
Alternate stack via sigaltstack.
Process + thread signal masks.

Differences: illumos uses turnstiles; IRIX uses explicit queues and sv_t.
BSD (FreeBSD, etc.)
Moderate similarity:

sigaction, sigprocmask, kill, sigaltstack.
Signal contexts for longjmp-style handlers.

Differences: BSD simpler — no queued signals, weaker real-time, different threading model.
Overall, IRIX signal system is SVR4/POSIX compliant with strong multi-threading and queued signal support. illumos closest modern analog; BSD covers basics but lacks queued delivery and per-thread complexity. For replication: preserve dual process/thread model, queued siginfo handling, and careful ut_lock/sigvec coordination.

[[Category: Kernel Documentation]]

Kernel: Virtual Paging

2026-01-09T23:55:59Z

Raion:

== Overview ==
The IRIX kernel virtual memory subsystem manages physical page allocation, deallocation, and mapping for kernel use. It features a sophisticated free page list organized by cache color buckets with separate queues for clean/stale and associated/unassociated pages, support for large pages (contiguous allocation and coalescing), NUMA-aware node-specific freelists, cache coloring and VCE avoidance, and optimizations for direct-mapped (K0/K1) vs K2 addresses.
Key characteristics:

pfdat_t structures track per-page metadata (flags, use count, hash chains, etc.).
phead_t bucket arrays per node and page size manage free lists.
Aggressive cache line reuse and coloring to minimize conflicts.
Reservation system via memory pools to prevent deadlock.
Special handling for R10000 speculation bug (lowmem separation).
Poisoned page support for ECC/uncorrectable errors.
Kernel stack pool for fast allocation.

The implementation prioritizes low-latency kernel allocation with careful TLB and cache management.
== Key Functions ==
Core Allocation

kvpalloc / kvpalloc_node: Allocate virtual + physical pages (K2 + physical).
kvalloc: Allocate only K2 virtual space.
kpalloc / kpalloc_node: Map physical pages into existing K2 space.
pagealloc / pagealloc_node / pagealloc_size: Core physical page allocator (single or large pages).
contig_memalloc / kmem_contig_alloc: Physically contiguous allocation.

Deallocation

kvpfree / kvpffree: Free virtual + physical (handles K0/K1/K2).
kvfree: Free only K2 virtual space.
pagefree / pagefree_size: Return physical page to freelist (with coalescing).
kmem_contig_free: Free contiguous block.

Large Page Support

lpage_alloc_contig_physmem: Allocate large contiguous block.
lpage_free_contig_physmem: Free large block.
lpage_coalesce: Background merging of adjacent free base pages.
lpage_split: Break large page into smaller ones.

Special Cases

page_mapin / page_mapout: Temporary mapping for copy/zero.
page_copy / page_zero: COW and fault-time zeroing (with BTE on SN0).
page_discard / page_error_clean: Handle ECC/poisoned pages.
kstack_alloc / kstack_free: Kernel stack page pool.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Critical Structures (from pfdat.h, page.h, etc.)

pfd_t (page frame data):
pf_flags: P_QUEUE, P_HASH, P_ANON, P_DONE, P_WAIT, P_DIRTY, P_DUMP, P_BULKDATA, P_ERROR, P_HWBAD, etc.
pf_use: Reference count.
pf_next/prev: Free list links.
pf_hchain: Hash chain.
pf_tag: Vnode or anon handle.
pf_pageno: File offset.

phead_t (per-color bucket):
ph_count: Number of pages.
ph_list[PH_NLISTS]: CLEAN/STALE, ASSOC/NOASSOC (and POISONOUS on NUMA).

Node-specific:
pg_free_t per node: freelists, phead arrays, rotors, counters.

Free List Organization

Per-node, per-page-size phead arrays.
Cache color bucketed (pheadmask).
Separate lists: CLEAN/STALE × ASSOC/NOASSOC (plus POISONOUS).
Rotor for round-robin uncached allocation.

NUMA and Migration

Node-local freelists.
Round-robin or radial search fallback.
Poisoned page handling (directory clearing, discard queues).

R10000 Speculation Workaround

Low memory (<256MB) separated.
Special sxbrk variants (low/high memory).
Kernel reference tracking (krpf) for DMA safety.

Cache and TLB Optimizations

Direct K0/K1 preferred when possible.
VCE avoidance via color validation.
Stale → clean promotion with selective cache flush.

== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Strong similarity:

Page freelist with hash buckets and color awareness.
kmem allocator for kernel objects (zones similar to IRIX zones).
Contiguous allocation via vmem.
Page daemon (vhand equivalent).
NUMA support evolved differently (resource pools).

Porting: illumos kmem/page subsystem closest; lacks exact phead coloring and large-page coalescing.
BSD (FreeBSD)
More divergent:

Simple page queues (free, cache, etc.).
UMA/kmem for slabs, vm_page for physical.
Contiguous via contigmalloc.
No per-color buckets or large-page splitting.

Porting: BSD simpler; lacks IRIX's sophisticated coloring, NUMA freelists, and coalescing.
Overall, IRIX VM is classic SVR4 with heavy MIPS/NUMA/R10000 optimizations. illumos provides nearest modern analog; BSD too simplified for direct mapping. For replication: preserve pfdat flags, phead structure, node freelists, and coalescing logic.

[[Category: Kernel Documentation]]

Kernel: ELF Loader

2026-01-09T23:55:52Z

Raion:

== Overview ==

The IRIX kernel's ELF loader manages the execution of ELF-format binaries on MIPS-based systems, accommodating 32-bit and 64-bit architectures along with multiple ABIs. It performs tasks such as validating file headers, preparing the user stack and arguments, mapping memory segments, handling dynamic linking, and applying hardware-specific adjustments. Integration with kernel components like address space handling, virtual memory allocation, process control, and resource management ensures efficient and reliable execution.

The loader supports ABI transitions during execution, resource pre-allocation for constrained environments, and extensions for MIPS hardware errata. It processes both static and dynamic executables, coordinating with the runtime linker for shared libraries.

== Key Functions ==

The loader comprises several core operations that orchestrate the execution process. Below is a detailed functional overview of these operations, describing their roles, inputs, logic, and outputs.

=== Header Retrieval and Validation ===

This function reads the ELF header and program headers from the executable file. It validates essential fields such as the magic number, class (32-bit or 64-bit), data encoding, file type (executable or dynamic), and MIPS-specific architecture flags. It determines the ABI version based on machine type and flags, ensuring compatibility with the system's capabilities. On success, it provides the parsed headers for further processing; failures result in errors like invalid executable format or bad request due to unsupported architecture.

=== ELF Execution Dispatch ===

The primary entry point for ELF binary execution dispatches based on the file's class to handle 32-bit or 64-bit specifics. It retrieves headers, scans program headers for dynamic linking indicators, auxiliary setup needs, and hardware options. It calculates auxiliary vector size, allocates kernel space for argument building, constructs the user stack, and reserves memory resources if required for batch processing. The process splits to manage stack usage, proceeding to image removal and new address space creation. Errors lead to cleanup and restoration of original state.

=== Execution Completion ===

Continuing from the dispatch, this phase removes the existing process image, creates a new address space with affinity considerations, and maps segments. For dynamic binaries, it loads the runtime linker, builds extended auxiliary vectors, and sets up the stack with execution parameters. It configures registers, including floating-point unit settings based on architecture, and transfers control to the entry point. Failures trigger process termination with detailed logging.

=== Segment Mapping ===

This operation maps ELF segments into the address space, focusing on loadable sections. It computes protections (read, write, execute) and flags (local mapping, heap consideration), handles zero-fill regions, and applies workarounds for hardware issues in executable pages. It identifies special program headers for dynamic linking, shared libraries, and options. Mapping occurs with file-backed regions, supporting checkpointing. Errors include memory shortages or invalid segment orders.

=== Dynamic Shared Object Mapping ===

Accessible from user space, this function maps segments for shared objects, typically invoked by the runtime linker. It validates file descriptors and permissions, copies program headers from user space, and performs mappings with potential workarounds. On memory errors, it attempts relocation to an alternate address range. Success returns the base address; failures unmap partial allocations.

=== Memory Requirement Calculation ===

These utilities estimate the physical memory needed for execution, summing requirements for writable segments, the user stack, and the runtime linker. Computations account for page alignments and cache results for repeated use, updating on file changes. This supports early reservation in resource-managed environments, preventing failures during critical phases.

=== Hardware Workaround Check ===

For specific CPU errata, this checks program headers for cleanliness indicators regarding problematic instructions. If needed, it flags the use of proxy mechanisms during mapping to mitigate issues in read-only executable regions.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==

=== MIPS Hardware Workarounds in PT_MIPS_OPTIONS ===

IRIX scans PT_MIPS_OPTIONS sections for hardware patch flags:

* '''OHW_R5KCVTL''' (0x8): Indicates the binary is clean of the R5000 cvt.[ds].l bug. If absent on affected CPUs (with ''R5000_cvt_war'' enabled, typically n32/n64 ABIs), the kernel uses the ''mtext'' subsystem (proxy vnodes) to rewrite problematic instructions in read-only executable pages during mapping.
* '''OHW_R8KPFETCH''' (TFP_PREFETCH_WAR): On TFP (R8000) CPUs, non-dynamic MIPS4 binaries with prefetch instructions are rejected (EBADRQC) unless ''chk_ohw_r8kpfetch'' is non-zero. For dynamic binaries, the kernel sets a flag to add '''AT_PFETCHFD''' to auxv (see below).

These flags trigger kernel-level instruction patching or rejection, not documented in public ELF ABI supplements.

=== Extended Auxiliary Vector Entries ===

* '''AT_PFETCHFD''': Provides an open file descriptor to the executable for the runtime linker (rld) to apply prefetch instruction patches (no-ops) on TFP systems. Added when a dynamic binary requires the prefetch workaround.

Standard auxv entries (AT_PHDR, AT_BASE, etc.) are used, but AT_PFETCHFD is an IRIX-specific extension.

=== Memory Reservation (availsmem) for Exec ===

* Functions ''elf_compute_availsmem'' and ''elf_get_availsmem'' precompute physical memory needs for writable segments (PF_W in PT_LOAD), user stack, and the runtime linker.
* Cached globally in ''runtime_loader_availsmem'' (recomputed if the runtime linker's vnode changes).
* For Miser batch jobs, reserves memory early via ''vm_pool_exec_reservemem''; failure returns EMEMRETRY for retry.

This mechanism prevents mid-exec failures in memory-constrained environments.

=== Mapping Interfaces ===

* ''execmap'' / ''mtext_execmap_vnode'': Low-level mapping of file-backed regions with ZFOD, protections, and flags (e.g., MAP_LOCAL, MAP_BRK, MAP_PRIMARY).
* ''elfmap'': User-called (from rld) to map DSO PT_LOAD segments. Supports alternate address relocation on ENOMEM by finding a free range and adjusting vaddrs.
* Integration with checkpointing (ckpt handles passed to mapping calls).

=== Other Internal Behaviors ===

* ABI transition handling: Temporarily sets process ABI proxy during exec; resets on failure.
* NUMA/affinity: New address space creation via ''aspm_exec_create'' and affinity link setup.
* FPU flags from PT_MIPS_OPTIONS (ODK_EXCEPTIONS): Sets precise exceptions or speculative mode in process FP flags.
* Runtime linker loading: Caches availsmem needs; sticky bit (VSVTX) on rld allows saving pregions.
* Error reporting: Detailed kill messages with reason codes for failed execs.

These features extend standard ELF handling with IRIX-specific resource management, hardware errata mitigation, and kernel-runtime linker coordination.

[[Category: Kernel Documentation]]

Kernel:Virtual Memory

2026-01-09T23:55:35Z

Raion:

== Overview ==
The IRIX virtual memory system manages physical and virtual memory resources on MIPS-based Silicon Graphics systems, supporting both 32-bit and 64-bit addressing modes with dynamic switching. It is designed for high-performance computing, graphics, and real-time applications, incorporating SVR4 features like demand paging, memory-mapped I/O (mmap, mprotect), and ELF executables. The system handles anonymous memory (e.g., heap, stack) via tree-based structures for copy-on-write efficiency during forks, and file-backed memory through vnode-integrated page caching. It supports large physical memory (up to 16 GB in later versions), virtual address spaces up to 1 TB per 64-bit process, and NUMA-aware allocation for multiprocessor scalability.

Key aspects include page frame management, swapping to disk, variable page sizes for optimization, memory migration for load balancing, and reverse mapping for efficient invalidation. The VM subsystem integrates with IRIX's filesystem layers (e.g., XFS, EFS) for unified caching and I/O, and includes real-time enhancements like page locking to minimize latencies. It emphasizes multiprocessor efficiency with fine-grained locking, preemption, and hardware-specific optimizations for MIPS processors (e.g., R8000, R10000).

== Key Components and Flow ==

* **Address Space Management**: Processes operate in user or kernel mode, with virtual addresses mapped to physical memory or swap. User space is segmented (e.g., kuseg for 32-bit: 0-2GB), while kernel accesses extended regions.
* **Page Frame Data (pfdat)**: Tracks physical pages, including flags for states like hashed, queued, recycled, or bad. Supports replication in NUMA environments.
* **Anonymous Memory Handling**: Uses binary trees of anon structures for copy-on-write sharing post-fork, with caches for pages (pcache) and swap handles (scache).
* **File-Backed Caching**: Vnode page cache integrates with filesystems for demand-loaded pages, handling flush, invalidate, and toss operations.
* **Swapping and Paging**: Manages swap devices (up to 255), demand paging, and precomputation of memory needs (availsmem) for resource-constrained environments.
* **NUMA and Large Pages**: Node-specific data structures (pgdata, nodepda) for free lists and stats; supports multiple page sizes with coalescing and splitting.
* **Migration and Mapping**: Page migration for balancing; reverse maps (rmap) for quick invalidation during unmap or protection changes.
* **Real-Time Features**: Page locking, bounded interrupt latencies, and Miser integration for batch scheduling.

Typical flow: On page fault (vfault/pfault), lookup in caches; if missing, allocate or swap in. Forks duplicate anon trees; exits prune and free resources. Memory pressure triggers swapping, coalescing, or migration.

== Key Functions ==

The VM system comprises operations for memory allocation, mapping, fault handling, and resource management. Below is a detailed functional overview, describing roles, logic, and interactions.

=== Anonymous Memory Initialization and Allocation ===
Initializes global structures like allocation zones and shared anon lists. Creates new anon handles for regions, setting up locks and caches. Allocates and initializes anon nodes with reference counts and depth hints for tree management.

=== Fork Handling (Duplication) ===
Duplicates anon structures for child processes, forming or extending binary trees to enable copy-on-write sharing. Allocates new leaf nodes for parent and child, linking them to the original root. Checks for tree depth and prunes if necessary. Reserves resources for potential cache growth.

=== Exit or Region Free (Deallocation) ===
Disassociates regions from anon memory, removing leaf nodes and freeing pages/swap space. Collapses branches with single children recursively toward the root. Releases locks and nodes when reference counts reach zero.

=== Tree Optimization (Collapse and Prune) ===
Reduces tree depth by merging parent-child pairs when one child is absent, transferring pages and swap handles. Selects survivor based on page count; discards covered pages. Prunes empty intermediate nodes with no pages/swap to prevent unbounded growth in long-lived forking processes.

=== Page Insertion into Anon ===
Adds pages to leaf node caches, covering lower tree levels if needed. Ensures no duplicates; handles potential cache resizing.

=== Page Modification Handling ===
Determines copy or steal for writes: Copies for shared or non-top-level pages; steals otherwise, clearing swap info and rehashing to top level. Heuristics for caching swapped pages when memory is abundant.

=== Swap Handle Management ===
Merges or clears swap handles during collapses; transfers non-covered handles to survivors.

=== Vnode Page Cache Initialization ===
Sets up per-vnode caches during allocation or recycling, initializing hash structures and reference counts.

=== Vnode Page Lookup and Attachment ===
Searches caches for pages by logical number; attaches by incrementing use counts, resolving races with allocation/recycling.

=== Vnode Page Insertion ===
Adds pages to caches, resizing if needed; supports conditional insertion to handle races, freeing duplicates.

=== Vnode Page Removal and Invalidation ===
Removes pages from caches, marking bad or requeuing free; flushes/invalidates ranges, tossing to buffers if needed.

=== Page Recycling and Migration ===
Recycles pages for reuse, removing from caches; migrates by copying state to new frames, updating caches atomically.

=== Memory Requirement Estimation ===
Precomputes swap/memory needs for operations, caching for runtime linker and batch jobs.

=== Hardware Workaround Checks ===
Scans for CPU errata indicators, flagging proxy use for instruction rewriting in executable pages.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==

=== Anonymous Memory Tree Structures ===
Binary trees of anon nodes for efficient copy-on-write: Leaves represent process-private pages; internal nodes share via parents. Depth hints and pruning thresholds (e.g., PRUNE_THRESHOLD) prevent degradation in forking servers. Covered pages discarded during merges; swap caches (scache) track out-of-memory handles.

=== Shared Anonymous Pages (sanon) ===
Special lists for unreferenced, dirty, shared anon pages (psanonmem counter). Node-specific free lists with locks; removal macros handle MP races.

=== Page and Swap Caches (pcache/scache) ===
Dual caches per anon/vnode: pcache hashes in-memory pages; scache manages swap handles for faulted-out pages. Dynamic resizing, preemption during long operations. Undocumented tokens for space reservation.

=== Memory Reservation (availsmem) ===
Precomputes and reserves physical/swap memory for execs/forks, integrated with Miser for batch retries (EMEMRETRY). Global caching for runtime components.

=== NUMA-Aware Data Structures ===
Per-node pgdata for free lists, stats, and rotors; nodepda integration for allocation. Large page (lpage) support with coalescing daemons, splitting, and stats (e.g., vfault/pfault retries by size).

=== Page Migration and Reverse Mapping ===
Migr subsystem for NUMA balancing; rmap for efficient TLB shootdowns and unmaps. Pagemigr transfers states, handling object mutations.

=== Hardware and Real-Time Extensions ===
Flags for MIPS errata (e.g., R5000 CVT, TFP prefetch); mtext proxies for instruction patching. Page locking for real-time, bounded latencies, and VCE avoidance for cache coloring.

=== Vnode Cache Synchronization ===
Reference counting (v_pcacheref) with wait bits for reclaim coordination; broadcast on zero refs. Integration with DMAPI, ShareII for extended file ops.

These extend standard UNIX VM with SGI-specific optimizations for MIPS, NUMA, graphics, and HPC, emphasizing scalability and reliability.

[[Category: Kernel Documentation]]

Kernel: Process Scheduler

2026-01-09T23:55:24Z

Raion:

== Overview ==
The IRIX process scheduler is accessed primarily through the schedctl(2) system call, which provides a rich set of scheduling controls reflecting IRIX's historical focus on real-time, multiprocessor, and high-performance computing workloads. It supports:

Real-time fixed-priority scheduling (non-degrading)
Traditional UNIX nice-value adjustments (timeshare)
Process group and user-wide nice operations (BSD compatibility)
CPU affinity control
Scheduling mode selection (free/gang)
Full Frame Scheduler (FRS) interface for user-level hard real-time gangs
Legacy hooks for older scheduling extensions

The implementation centers on vproc_t (virtual process) objects, which abstract scheduling attributes across processes/threads. Changes are applied via VPROC_ operations that update runqueue information safely.
== Key Functions ==
Main Interface (schedctl)
Single entry point dispatching commands:

MPTS_RTPRI / MPTS_GETRTPRI: Set/get real-time priority (range NDPHIMAX..NDPLOMIN). Superuser required except for self-demotion or within normal range.
MPTS_SLICE: Set per-process time slice (ticks).
MPTS_RENICE / variants: Adjust nice values for process, process group, or all processes of a user (emulating BSD setpriority/getpriority semantics).
MPTS_SETHINTS: Initialize PRDA hints (obsolete pthread-related).
MPTS_SETMASTER: Set scheduling master PID (legacy).
MPTS_SCHEDMODE: Set scheduling mode (SGS_FREE, SGS_GANG, etc.).
MPTS_AFFINITY_*: Enable/disable/query CPU affinity.
MPTS_FRS_*: Full Frame Scheduler user interface (create, enqueue, yield, etc.).

Most operations require CAP_SCHED_MGT capability.
Process List Scanner (plistscanner / plistscan)
Utility for user-wide or group-wide operations:

Scans entire process table via procscan().
Handles renice/getnice across all matching processes.
Safe credential access via pcred_access().

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Scheduling Parameters

Real-time priorities: Fixed, non-degrading. Higher numerical value = higher priority.
NDPHIMAX (highest), NDPNORMMIN (boundary to timeshare), NDPLOMIN (lowest RT).

Nice values: Traditional UNIX (-20..+19 translated via NZERO=20).
Time slice: Configurable in ticks (default system-wide).

Scheduling Modes (via MPTS_SCHEDMODE)

SGS_FREE: Default independent scheduling.
SGS_GANG: Gang scheduling (co-scheduling of related threads).

CPU Affinity
Controlled via VPROC_SCHED_AFF; requires CAP_SCHED_MGT.
Frame Scheduler (FRS)
Hard real-time extension:

User-level creation of scheduling "frames" (gangs).
Precise control over dispatch, yield, interrupt handling.
All FRS operations require CAP_SCHED_MGT.
Old FRS interface (MPTS_OLDFRS_*) returns ENOTSUP.

Batch Job Restrictions
Processes in batch process groups (Miser) cannot be made real-time.
Permission Model
Heavy reliance on CAP_SCHED_MGT capability rather than simple uid==0 checks.
== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Very close heritage (both SVR4 descendants):

schedctl-like interface existed historically in Solaris.
Real-time fixed priorities (RT class).
PRIORITY/NICE control via priocntl(2).
Gang scheduling concepts (though Solaris used processor sets).
Frame Scheduler unique to IRIX; Solaris had alternative real-time extensions.

Porting: illumos priocntl(2) system provides similar class/parameter control. FRS has no direct analog.
BSD (FreeBSD, NetBSD, OpenBSD)
More divergent:

Nice via setpriority/getpriority (exact semantics matched by IRIX MPTS_RENICE_* variants).
Real-time via sched_setparam/sched_getparam (POSIX).
CPU affinity via cpuset(2).
No direct gang or frame scheduler equivalents.
No unified schedctl; separate syscalls.

Porting: BSD nicer for nice/priority; lacks IRIX's unified interface and FRS. Real-time weaker than IRIX fixed-priority model.
Overall, IRIX scheduler reflects strong SVR4 real-time heritage with unique extensions (FRS, gang modes). illumos provides closest conceptual match; BSD covers nice semantics well but lacks advanced features. For replication, focus on vproc abstraction and capability checks. FRS is largely IRIX-specific and hard to port directly.

[[Category: Kernel Documentation]]

Kernel: Mutex

2026-01-09T23:54:26Z

Raion:

== Overview ==
The IRIX kernel mutex implementation provides basic mutual exclusion primitives with priority inheritance to mitigate priority inversion, atomic owner tracking via compare-and-swap, optional metering/statistics, and integration with the broader [[Kernel:ksync]] (kernel synchronization) framework that includes sv_t (synchronization variables) for semaphores, condition variables, and other waitable objects.
The design uses a single-word owner field (m_bits) combining owner thread pointer with flags (lock bit, queue bit). Contention spins briefly then sleeps on a circular doubly-linked waiter queue. Priority inheritance propagates up blocked chains. The implementation supports debugging/metering via optional info structures and integrates with spinlocks, bitlocks, mrlocks, and semaphores through sv_t wrappers.
== Key Functions ==
Initialization (kmutei_init)
Creates zones for mutex_t and sv_t structures. Initializes hash buckets for optional wchan info (debug/metering).
Allocation (mutex_alloc / init_mutex)
Zone-allocates mutex_t, clears bits, optionally allocates metering/info structure.
Deallocation (mutex_destroy / mutex_dealloc)
Frees info structure, zone-frees mutex.
Core Operations

mutex_trylock: Atomic compare-and-swap to set owner; updates metering.
mutex_lock: Trylock → on miss, queue and sleep with priority inheritance probing.
mutex_unlock: Clears owner; if waiters, wakes highest-priority waiter (single thread).
mutex_wait: Queues thread, handles inheritance, blocks (non-breakable).
mutex_wake: Dequeues highest-priority waiter, transfers ownership, updates metering.

Priority Inheritance

resource_raise_owner_pri: Boosts owner priority to waiter’s.
resource_test_owner_pri: Detects inversion, raises or spins/yields.
drop_inheritance: Restores base priority on unlock.
Supports chained inheritance via k_inherit pointer.

Waiter Queue Management

Circular doubly-linked list in m_queue.
Queued in approximate priority order (mutex_queue).
Single waiter woken on unlock (mutex_wake).

Synchronization Variables (sv_t)
General-purpose wait queue supporting:

FIFO, LIFO, priority, keyed ordering.
Signal (wake one), broadcast (wake all), bounded broadcast.
Timed waits, signal-breakable waits.
Integration with mutex/spin/bit/mrlock/sema release.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Critical Structures

mutex_t:
__psunsigned_t m_bits — owner thread pointer + flags (low bit lock, next bit queue).
kthread_t *m_queue — circular waiter list head.
Optional m_info pointer for metering/wchan info.

sv_t:
__psunsigned_t sv_queue — waiter pointer + lock bit + type (FIFO/LIFO/PRIO/KEYED).
Optional sv_info for metering.

Flags/macros:
MUTEX_LOCKBIT, MUTEX_QUEUEBIT
SV_LOCK, SV_TYPE masks
KT_WMUTEX, KT_WSV thread sleep flags

Priority Inheritance Details

Aggressive: propagates through chains, handles indirect waits.
Temporary priority boost with KT_PS flag.
Supports real-time and timeshare scheduling.

Metering and Debug (SEMAMETER/SEMAINFO)

Optional per-object statistics (lock attempts, hold/wait times, contention).
Hash bucket lists for idbg scanning.

sv_t Flexibility

Unified queue for multiple lock types via wrapper functions.
Supports bounded broadcast (wakes only original waiter set).
Threshold wake (sv_threshold).

== Similarities to illumos Implementation ==
illumos (Solaris-derived)

Strong similarity due to shared SVR4 heritage:

Adaptive mutexes with priority inheritance (similar owner word, waiter lists).

mutex_enter, mutex_tryenter, mutex_exit.

Turnstiles for sleeping/waiting (similar to sv_t but more integrated).

CVs and semaphores separate but similar.

Metering via kstat or dtrace.

Porting: illumos adaptive mutex closest match. Differences in turnstile priority blocking vs IRIX explicit inheritance chains.

[[Category: Kernel Documentation]]

Kernel: vfile

2026-01-09T23:54:02Z

Raion:

== Overview ==
The vfile (virtual file) object in the IRIX kernel represents an open file description — the kernel-side structure that corresponds to an open file shared across processes (via fork, dup, etc.). It holds per-open state such as reference count, open flags, credentials, associated vnode or vsocket, and a behavior chain head for stacked behaviors (notably the pfile behavior for offset management).
The vfile layer sits between the per-process file descriptor table (fdt) and lower-level objects (vnode for files, vsocket for sockets). It manages reference counting, close semantics (including double-close protocol for races), credential handling, and integration with distributed (Cellular IRIX) features. The implementation emphasizes thread/sproc safety via spinlocks and careful race avoidance during close.
== Key Functions ==
Initialization (vfile_init)
Initializes the file_zone for efficient allocation of vfile_t structures, sets up debugging lists/locks, calls vfile_cell_init() (distributed support) and pfile_init().
Creation (vfile_create)
Allocates a vfile_t from the zone, initializes:

Spinlock (vf_lock)
Reference count = 1
Flags and credential hold
Behavior chain head (vf_bh)
Links into debug active list
Increments global SYSINFO.filecnt

Allocation for Open (vfile_alloc)
Creates a vfile (with FINPROGRESS flag), allocates an fd via fdt_alloc, creates associated pfile behavior. Returns file pointer and fd; caller must call vfile_ready after successful VOP_OPEN.
Activation (vfile_ready)
Clears FINPROGRESS, sets associated vnode/vsocket pointer.
Undo on Failed Open (vfile_alloc_undo)
Reverses vfile_alloc when VOP_OPEN fails: removes fd, drops refcount, tears down pfile, destroys vfile.
Close Protocol (vfile_close, vfile_close_common, vfile_ref_release)
Implements a two-phase close to handle races between multiple threads/sprocs closing the same fd:

vfile_close: Calls VFILE_CLOSE with VFILE_FIRSTCLOSE to probe if last reference.
vfile_close_common: Performs actual cleanup:
Cleans locks if present
Calls VOP_CLOSE (or VSOP_CLOSE) with appropriate lastclose flag
Handles double-call race by potentially issuing extra VOP_CLOSE
On true last close: flushes/invalidates if requested, releases vnode, removes GRIO reservations, tears down behaviors, destroys vfile

vfile_ref_release: Used for non-close reference drops (e.g., rfork cleanup); only performs full close if last reference.

Assignment Helper (vfile_assign)
Convenience wrapper: allocates vfile/fd, performs VOP_OPEN (updating vnode pointer if changed), readies vfile on success, undoes on failure.
== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Critical Structures (from ksys/vfile.h)

vfile_t:
int vf_count — reference count (shared opens)
int vf_flag — open flags (FREAD, FWRITE, etc.) + internal (FINPROGRESS, FLCINVAL, FLCFLUSH, FPRIORITY)
cred_t *vf_cred — held credentials of opener
spinlock_t vf_lock — protects structure
bhv_head_t vf_bh — head of behavior chain (pfile inserted here)
void *vf_data — pointer to vnode_t or vsock_t (via VF_TO_VNODE/VF_TO_VSOCK)
Debug links (vf_next, vf_prev) for active list

Macros:
VFLOCK / VFUNLOCK — spinlock wrappers
VFILE_CLOSE(fp, phase, info) — behavior chain dispatch for close
VFILE_TEARDOWN(fp) — behavior chain teardown dispatch
VF_IS_VNODE, VF_SET_DATA

Double-Close Protocol
IRIX uses a two-call close pattern (VFILE_FIRSTCLOSE, VFILE_SECONDCLOSE) via behavior chain to safely determine last close in multiprocessor/shared-process environments. Prevents race where one thread tears down structure while another assumes it still exists.
Flags and Special Handling

FINPROGRESS: Set during open until vfile_ready
FLCINVAL / FLCFLUSH: Trigger VOP_FSYNC with invalidate or flush on last close
FPRIORITY: Indicates GRIO (Guaranteed Rate I/O) reservation
VFRLOCKS: Vnode has record locks → clean on close

Distributed Support
References to DC/DS (Distributed Coordinator/Server) and VFILE_SKIPCLOSE indicate special handling in Cellular IRIX: last close may be deferred or coordinated remotely.
== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Moderate similarity:

Per-open state in struct file (referenced by filedesc table)
Reference counting and close races handled via closef()
Vnode ops with VOP_CLOSE(last)
Credential holding
No behavior chaining; vnode ops direct
No explicit pfile separation — offset in uio or per-read/write

Porting: illumos file closer to vfile than BSD, but lacks behavior chain and double-close protocol.
BSD (FreeBSD, NetBSD, OpenBSD)
Closer in some aspects:

struct file with reference count, flags, credential, pointer to fileops and data (vnode/socket)
Double-close avoidance via careful refcounting
closef() performs fdrop() → ops → free
No behavior chaining; direct fops dispatch
Offset not stored in file — managed per-I/O via uio

Porting: BSD struct file semantically similar to vfile. Main differences: no bhv chain, no explicit pfile layer, different lock strategy.
Overall, IRIX vfile is unique due to bhv_desc_t behavior chaining and [[Kernel: pfile]] offset separation, designed for extensibility and Cellular IRIX distributed coherence. No direct equivalent in illumos/BSD for easy porting; closest analogs are struct file in both, but require adding behavior dispatch and double-close logic for fidelity.

[[Category: Kernel Documentation]]

Kernel: Introduction

2026-01-09T23:51:36Z

Raion:

The ''Kernel:'' namespace serves as a comprehensive, community-driven repository for detailed technical documentation of the IRIX kernel, derived from reverse engineering efforts on [[IRIX 6.5]] binaries. This initiative focuses on analyzing, decompiling, and annotating kernel object files to produce high-level, functional descriptions of subsystems, data structures, and behaviors. The documentation is intended to preserve and disseminate deep technical knowledge about IRIX's unique kernel architecture, which remains largely undocumented outside of original Silicon Graphics sources.

=== Objectives ===

The primary goal is to create accurate, readable documentation of IRIX kernel components based on decompiled and extensively commented binary code. This effort emerged in response to the challenges encountered during the IRIX-32 project, where direct access to original source code proved impractical. By leveraging modern reverse engineering tools and AI-assisted analysis, the project aims to produce standalone technical articles that describe kernel functionality without relying on or distributing proprietary source code.

A key operational objective is to maintain clear separation between active IRIX development communities and the volunteer reverse engineering team. This isolation ensures compliance with legal and ethical boundaries while allowing independent progress on documentation.

Ultimately, these articles provide a reliable reference for understanding IRIX kernel internals, supporting historical preservation, academic study, and potential future reimplementations.

=== Rationale ===

IRIX represents a sophisticated UNIX variant optimized for high-performance graphics, scientific computing, and real-time applications on MIPS architecture. Many of its kernel innovations—particularly in virtual memory management, NUMA support, ELF loading, and hardware-specific optimizations—remain poorly documented in public sources. This namespace seeks to fill that gap by systematically documenting subsystems as they existed in IRIX 6.5, the final major release.

The documentation serves as groundwork for skilled developers interested in faithfully reimplementing portions of the IRIX kernel. By providing detailed functional overviews, data structure descriptions, and behavioral analyses derived from binary analysis, it enables clean-room reimplementation efforts without exposure to original source code.

=== Methods ===

Documentation is produced through careful reverse engineering of IRIX 6.5 kernel binaries. Primary tools include:

* Ghidra for disassembly, decompilation, and structural analysis
* mips2c and related projects for improving decompiler output readability
* decomp.me for collaborative decompilation matching

All articles are written from decompiled output that has been extensively commented and analyzed by engineers. A strict policy is maintained: no original source code is reproduced or distributed within these pages. Descriptions focus on functional behavior, data flows, and algorithmic logic. Where necessary, function prototypes (names, return types, and parameters) may be included for clarity, but only as derived from binary analysis.

Articles emphasize high-level overviews, key data structures, and IRIX-specific behaviors while highlighting deviations from standard UNIX or SVR4 conventions.

=== Personnel ===

* '''Młynar''' – Documenting Engineer from Politechnika Wrocławska: primary decompiler and commenter responsible for detailed analysis and annotation of kernel objects
* '''Yura''' – Engineer from Shenzhen: supporting documentation and verification. MIPS ASM analysis.
* '''Raion''' – Primary documenter and formatter: article structuring, MediaWiki formatting, and coordination

This volunteer effort combines expertise in MIPS architecture, kernel internals, and reverse engineering to produce accurate technical documentation for the broader IRIX preservation community.

[[Category: Kernel Documentation]]

Kernel: Introduction

2026-01-09T23:46:22Z

Raion: Raion moved page Kernel:Introduction to Kernel: Introduction without leaving a redirect: Misspelled title

== Introduction ==

The ''Kernel:'' namespace serves as a comprehensive, community-driven repository for detailed technical documentation of the IRIX kernel, derived from reverse engineering efforts on [[IRIX 6.5]] binaries. This initiative focuses on analyzing, decompiling, and annotating kernel object files to produce high-level, functional descriptions of subsystems, data structures, and behaviors. The documentation is intended to preserve and disseminate deep technical knowledge about IRIX's unique kernel architecture, which remains largely undocumented outside of original Silicon Graphics sources.

=== Objectives ===

The primary goal is to create accurate, readable documentation of IRIX kernel components based on decompiled and extensively commented binary code. This effort emerged in response to the challenges encountered during the IRIX-32 project, where direct access to original source code proved impractical. By leveraging modern reverse engineering tools and AI-assisted analysis, the project aims to produce standalone technical articles that describe kernel functionality without relying on or distributing proprietary source code.

A key operational objective is to maintain clear separation between active IRIX development communities and the volunteer reverse engineering team. This isolation ensures compliance with legal and ethical boundaries while allowing independent progress on documentation.

Ultimately, these articles provide a reliable reference for understanding IRIX kernel internals, supporting historical preservation, academic study, and potential future reimplementations.

=== Rationale ===

IRIX represents a sophisticated UNIX variant optimized for high-performance graphics, scientific computing, and real-time applications on MIPS architecture. Many of its kernel innovations—particularly in virtual memory management, NUMA support, ELF loading, and hardware-specific optimizations—remain poorly documented in public sources. This namespace seeks to fill that gap by systematically documenting subsystems as they existed in IRIX 6.5, the final major release.

The documentation serves as groundwork for skilled developers interested in faithfully reimplementing portions of the IRIX kernel. By providing detailed functional overviews, data structure descriptions, and behavioral analyses derived from binary analysis, it enables clean-room reimplementation efforts without exposure to original source code.

=== Methods ===

Documentation is produced through careful reverse engineering of IRIX 6.5 kernel binaries. Primary tools include:

* Ghidra for disassembly, decompilation, and structural analysis
* mips2c and related projects for improving decompiler output readability
* decomp.me for collaborative decompilation matching

All articles are written from decompiled output that has been extensively commented and analyzed by engineers. A strict policy is maintained: no original source code is reproduced or distributed within these pages. Descriptions focus on functional behavior, data flows, and algorithmic logic. Where necessary, function prototypes (names, return types, and parameters) may be included for clarity, but only as derived from binary analysis.

Articles emphasize high-level overviews, key data structures, and IRIX-specific behaviors while highlighting deviations from standard UNIX or SVR4 conventions.

=== Personnel ===

* '''Młynar''' – Documenting Engineer from Politechnika Wrocławska: primary decompiler and commenter responsible for detailed analysis and annotation of kernel objects
* '''Yura''' – Engineer from Shenzhen: supporting documentation and verification. MIPS ASM analysis.
* '''Raion''' – Primary documenter and formatter: article structuring, MediaWiki formatting, and coordination

This volunteer effort combines expertise in MIPS architecture, kernel internals, and reverse engineering to produce accurate technical documentation for the broader IRIX preservation community.

Kernel: STREAMS

2026-01-09T05:16:17Z

Raion: Created page with "The IRIX STREAMS framework provides a modular, message-passing I/O subsystem for character devices, terminals, network protocols, and pseudo-devices. It uses queues (read/write pairs per module/driver), message blocks (mblk_t/dblk_t), and buffers for data transfer. The implementation is highly optimized for performance with: Per-CPU free lists (NUMA-aware) for message blocks, data blocks, and buffers of various sizes. Cache coloring and alignment support. Zone-based..."

Kernel: Signal Infrastructure

2026-01-04T03:52:14Z

Raion: Created page with "== Overview == The IRIX kernel signal infrastructure provides a comprehensive, POSIX-compliant signal delivery system with extensions for real-time, debugging, and multi-threaded processes. Signals are managed at both process (sigvec_t in proc_t) and thread (ut_sig, ut_sighold in uthread_t) levels, allowing per-thread signal masks and delivery while maintaining process-wide consistency. Key features: Queued signals (sigqueue_t) for POSIX sigqueue and siginfo delivery. P..."

Kernel: Process/Time Management Syscalls

2026-01-04T03:48:49Z

Raion: Created page with "== Overview == IRIX has many syscalls grouped by core process identity, time management, scheduling control, profiling, and signal-related system calls in the IRIX kernel. These calls operate on vproc_t (virtual process) structures, which encapsulate state shared across threads (uthreads) in multi-threaded processes. Key areas: Time retrieval/setting UID/GID manipulation (System V and BSD semantics) Process group/session control Nice value and real-time priority adjustm..."

Kernel: Virtual Paging

2026-01-04T03:42:30Z

Raion: Created page with "== Overview == The IRIX kernel virtual memory subsystem manages physical page allocation, deallocation, and mapping for kernel use. It features a sophisticated free page list organized by cache color buckets with separate queues for clean/stale and associated/unassociated pages, support for large pages (contiguous allocation and coalescing), NUMA-aware node-specific freelists, cache coloring and VCE avoidance, and optimizations for direct-mapped (K0/K1) vs K2 addresses...."

Kernel: Process Scheduler

2026-01-04T03:39:46Z

Raion: Created page with "== Overview == The IRIX process scheduler is accessed primarily through the schedctl(2) system call, which provides a rich set of scheduling controls reflecting IRIX's historical focus on real-time, multiprocessor, and high-performance computing workloads. It supports: Real-time fixed-priority scheduling (non-degrading) Traditional UNIX nice-value adjustments (timeshare) Process group and user-wide nice operations (BSD compatibility) CPU affinity control Scheduling mode..."

Kernel: pfile

2026-01-04T03:28:02Z

Raion: Created page with "== Overview == The pfile (physical file) object in the IRIX kernel represents per-open-file state beyond the vnode (file system-independent) and vfile (open file description) layers. It primarily manages the current file offset (pf_offset) and associated synchronization (pf_offlock). In single-cell (non-distributed) configurations, the pfile layer directly handles offset and flag operations. In distributed (multi-cell) environments using Cellular IRIX features, higher la..."

Kernel: vfile

2026-01-04T03:27:21Z

Raion: Created page with "== Overview == The vfile (virtual file) object in the IRIX kernel represents an open file description — the kernel-side structure that corresponds to an open file shared across processes (via fork, dup, etc.). It holds per-open state such as reference count, open flags, credentials, associated vnode or vsocket, and a behavior chain head for stacked behaviors (notably the pfile behavior for offset management). The vfile layer sits between the per-process file descriptor..."

== Overview ==
The vfile (virtual file) object in the IRIX kernel represents an open file description — the kernel-side structure that corresponds to an open file shared across processes (via fork, dup, etc.). It holds per-open state such as reference count, open flags, credentials, associated vnode or vsocket, and a behavior chain head for stacked behaviors (notably the pfile behavior for offset management).
The vfile layer sits between the per-process file descriptor table (fdt) and lower-level objects (vnode for files, vsocket for sockets). It manages reference counting, close semantics (including double-close protocol for races), credential handling, and integration with distributed (Cellular IRIX) features. The implementation emphasizes thread/sproc safety via spinlocks and careful race avoidance during close.
== Key Functions ==
Initialization (vfile_init)
Initializes the file_zone for efficient allocation of vfile_t structures, sets up debugging lists/locks, calls vfile_cell_init() (distributed support) and pfile_init().
Creation (vfile_create)
Allocates a vfile_t from the zone, initializes:

Spinlock (vf_lock)
Reference count = 1
Flags and credential hold
Behavior chain head (vf_bh)
Links into debug active list
Increments global SYSINFO.filecnt

Allocation for Open (vfile_alloc)
Creates a vfile (with FINPROGRESS flag), allocates an fd via fdt_alloc, creates associated pfile behavior. Returns file pointer and fd; caller must call vfile_ready after successful VOP_OPEN.
Activation (vfile_ready)
Clears FINPROGRESS, sets associated vnode/vsocket pointer.
Undo on Failed Open (vfile_alloc_undo)
Reverses vfile_alloc when VOP_OPEN fails: removes fd, drops refcount, tears down pfile, destroys vfile.
Close Protocol (vfile_close, vfile_close_common, vfile_ref_release)
Implements a two-phase close to handle races between multiple threads/sprocs closing the same fd:

vfile_close: Calls VFILE_CLOSE with VFILE_FIRSTCLOSE to probe if last reference.
vfile_close_common: Performs actual cleanup:
Cleans locks if present
Calls VOP_CLOSE (or VSOP_CLOSE) with appropriate lastclose flag
Handles double-call race by potentially issuing extra VOP_CLOSE
On true last close: flushes/invalidates if requested, releases vnode, removes GRIO reservations, tears down behaviors, destroys vfile

vfile_ref_release: Used for non-close reference drops (e.g., rfork cleanup); only performs full close if last reference.

Assignment Helper (vfile_assign)
Convenience wrapper: allocates vfile/fd, performs VOP_OPEN (updating vnode pointer if changed), readies vfile on success, undoes on failure.
== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Critical Structures (from ksys/vfile.h)

vfile_t:
int vf_count — reference count (shared opens)
int vf_flag — open flags (FREAD, FWRITE, etc.) + internal (FINPROGRESS, FLCINVAL, FLCFLUSH, FPRIORITY)
cred_t *vf_cred — held credentials of opener
spinlock_t vf_lock — protects structure
bhv_head_t vf_bh — head of behavior chain (pfile inserted here)
void *vf_data — pointer to vnode_t or vsock_t (via VF_TO_VNODE/VF_TO_VSOCK)
Debug links (vf_next, vf_prev) for active list

Macros:
VFLOCK / VFUNLOCK — spinlock wrappers
VFILE_CLOSE(fp, phase, info) — behavior chain dispatch for close
VFILE_TEARDOWN(fp) — behavior chain teardown dispatch
VF_IS_VNODE, VF_SET_DATA

Double-Close Protocol
IRIX uses a two-call close pattern (VFILE_FIRSTCLOSE, VFILE_SECONDCLOSE) via behavior chain to safely determine last close in multiprocessor/shared-process environments. Prevents race where one thread tears down structure while another assumes it still exists.
Flags and Special Handling

FINPROGRESS: Set during open until vfile_ready
FLCINVAL / FLCFLUSH: Trigger VOP_FSYNC with invalidate or flush on last close
FPRIORITY: Indicates GRIO (Guaranteed Rate I/O) reservation
VFRLOCKS: Vnode has record locks → clean on close

Distributed Support
References to DC/DS (Distributed Coordinator/Server) and VFILE_SKIPCLOSE indicate special handling in Cellular IRIX: last close may be deferred or coordinated remotely.
== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Moderate similarity:

Per-open state in struct file (referenced by filedesc table)
Reference counting and close races handled via closef()
Vnode ops with VOP_CLOSE(last)
Credential holding
No behavior chaining; vnode ops direct
No explicit pfile separation — offset in uio or per-read/write

Porting: illumos file closer to vfile than BSD, but lacks behavior chain and double-close protocol.
BSD (FreeBSD, NetBSD, OpenBSD)
Closer in some aspects:

struct file with reference count, flags, credential, pointer to fileops and data (vnode/socket)
Double-close avoidance via careful refcounting
closef() performs fdrop() → ops → free
No behavior chaining; direct fops dispatch
Offset not stored in file — managed per-I/O via uio

Porting: BSD struct file semantically similar to vfile. Main differences: no bhv chain, no explicit pfile layer, different lock strategy.
Overall, IRIX vfile is unique due to bhv_desc_t behavior chaining and pfile offset separation, designed for extensibility and Cellular IRIX distributed coherence. No direct equivalent in illumos/BSD for easy porting; closest analogs are struct file in both, but require adding behavior dispatch and double-close logic for fidelity.

Kernel: Mutex

2026-01-04T03:24:39Z

Raion: /* Similarities to illumos */

Kernel: Mutex

2026-01-04T03:23:40Z

Raion:

== Overview ==
The IRIX kernel mutex implementation provides basic mutual exclusion primitives with priority inheritance to mitigate priority inversion, atomic owner tracking via compare-and-swap, optional metering/statistics, and integration with the broader [[Kernel:ksync]] (kernel synchronization) framework that includes sv_t (synchronization variables) for semaphores, condition variables, and other waitable objects.
The design uses a single-word owner field (m_bits) combining owner thread pointer with flags (lock bit, queue bit). Contention spins briefly then sleeps on a circular doubly-linked waiter queue. Priority inheritance propagates up blocked chains. The implementation supports debugging/metering via optional info structures and integrates with spinlocks, bitlocks, mrlocks, and semaphores through sv_t wrappers.
== Key Functions ==
Initialization (kmutei_init)
Creates zones for mutex_t and sv_t structures. Initializes hash buckets for optional wchan info (debug/metering).
Allocation (mutex_alloc / init_mutex)
Zone-allocates mutex_t, clears bits, optionally allocates metering/info structure.
Deallocation (mutex_destroy / mutex_dealloc)
Frees info structure, zone-frees mutex.
Core Operations

mutex_trylock: Atomic compare-and-swap to set owner; updates metering.
mutex_lock: Trylock → on miss, queue and sleep with priority inheritance probing.
mutex_unlock: Clears owner; if waiters, wakes highest-priority waiter (single thread).
mutex_wait: Queues thread, handles inheritance, blocks (non-breakable).
mutex_wake: Dequeues highest-priority waiter, transfers ownership, updates metering.

Priority Inheritance

resource_raise_owner_pri: Boosts owner priority to waiter’s.
resource_test_owner_pri: Detects inversion, raises or spins/yields.
drop_inheritance: Restores base priority on unlock.
Supports chained inheritance via k_inherit pointer.

Waiter Queue Management

Circular doubly-linked list in m_queue.
Queued in approximate priority order (mutex_queue).
Single waiter woken on unlock (mutex_wake).

Synchronization Variables (sv_t)
General-purpose wait queue supporting:

FIFO, LIFO, priority, keyed ordering.
Signal (wake one), broadcast (wake all), bounded broadcast.
Timed waits, signal-breakable waits.
Integration with mutex/spin/bit/mrlock/sema release.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Critical Structures

mutex_t:
__psunsigned_t m_bits — owner thread pointer + flags (low bit lock, next bit queue).
kthread_t *m_queue — circular waiter list head.
Optional m_info pointer for metering/wchan info.

sv_t:
__psunsigned_t sv_queue — waiter pointer + lock bit + type (FIFO/LIFO/PRIO/KEYED).
Optional sv_info for metering.

Flags/macros:
MUTEX_LOCKBIT, MUTEX_QUEUEBIT
SV_LOCK, SV_TYPE masks
KT_WMUTEX, KT_WSV thread sleep flags

Priority Inheritance Details

Aggressive: propagates through chains, handles indirect waits.
Temporary priority boost with KT_PS flag.
Supports real-time and timeshare scheduling.

Metering and Debug (SEMAMETER/SEMAINFO)

Optional per-object statistics (lock attempts, hold/wait times, contention).
Hash bucket lists for idbg scanning.

sv_t Flexibility

Unified queue for multiple lock types via wrapper functions.
Supports bounded broadcast (wakes only original waiter set).
Threshold wake (sv_threshold).

== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Strong similarity due to shared SVR4 heritage:

Adaptive mutexes with priority inheritance (similar owner word, waiter lists).
mutex_enter, mutex_tryenter, mutex_exit.
Turnstiles for sleeping/waiting (similar to sv_t but more integrated).
CVs and semaphores separate but similar.
Metering via kstat or dtrace.

Porting: illumos adaptive mutex closest match. Differences in turnstile priority blocking vs IRIX explicit inheritance chains.

Kernel: Mutex

2026-01-04T03:23:07Z

Raion: Created page with "== Overview == The IRIX kernel mutex implementation provides basic mutual exclusion primitives with priority inheritance to mitigate priority inversion, atomic owner tracking via compare-and-swap, optional metering/statistics, and integration with the broader ksync (kernel synchronization) framework that includes sv_t (synchronization variables) for semaphores, condition variables, and other waitable objects. The design uses a single-word owner field (m_bits) combining o..."

== Overview ==
The IRIX kernel mutex implementation provides basic mutual exclusion primitives with priority inheritance to mitigate priority inversion, atomic owner tracking via compare-and-swap, optional metering/statistics, and integration with the broader ksync (kernel synchronization) framework that includes sv_t (synchronization variables) for semaphores, condition variables, and other waitable objects.
The design uses a single-word owner field (m_bits) combining owner thread pointer with flags (lock bit, queue bit). Contention spins briefly then sleeps on a circular doubly-linked waiter queue. Priority inheritance propagates up blocked chains. The implementation supports debugging/metering via optional info structures and integrates with spinlocks, bitlocks, mrlocks, and semaphores through sv_t wrappers.
== Key Functions ==
Initialization (kmutei_init)
Creates zones for mutex_t and sv_t structures. Initializes hash buckets for optional wchan info (debug/metering).
Allocation (mutex_alloc / init_mutex)
Zone-allocates mutex_t, clears bits, optionally allocates metering/info structure.
Deallocation (mutex_destroy / mutex_dealloc)
Frees info structure, zone-frees mutex.
Core Operations

mutex_trylock: Atomic compare-and-swap to set owner; updates metering.
mutex_lock: Trylock → on miss, queue and sleep with priority inheritance probing.
mutex_unlock: Clears owner; if waiters, wakes highest-priority waiter (single thread).
mutex_wait: Queues thread, handles inheritance, blocks (non-breakable).
mutex_wake: Dequeues highest-priority waiter, transfers ownership, updates metering.

Priority Inheritance

resource_raise_owner_pri: Boosts owner priority to waiter’s.
resource_test_owner_pri: Detects inversion, raises or spins/yields.
drop_inheritance: Restores base priority on unlock.
Supports chained inheritance via k_inherit pointer.

Waiter Queue Management

Circular doubly-linked list in m_queue.
Queued in approximate priority order (mutex_queue).
Single waiter woken on unlock (mutex_wake).

Synchronization Variables (sv_t)
General-purpose wait queue supporting:

FIFO, LIFO, priority, keyed ordering.
Signal (wake one), broadcast (wake all), bounded broadcast.
Timed waits, signal-breakable waits.
Integration with mutex/spin/bit/mrlock/sema release.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
Critical Structures

mutex_t:
__psunsigned_t m_bits — owner thread pointer + flags (low bit lock, next bit queue).
kthread_t *m_queue — circular waiter list head.
Optional m_info pointer for metering/wchan info.

sv_t:
__psunsigned_t sv_queue — waiter pointer + lock bit + type (FIFO/LIFO/PRIO/KEYED).
Optional sv_info for metering.

Flags/macros:
MUTEX_LOCKBIT, MUTEX_QUEUEBIT
SV_LOCK, SV_TYPE masks
KT_WMUTEX, KT_WSV thread sleep flags

Priority Inheritance Details

Aggressive: propagates through chains, handles indirect waits.
Temporary priority boost with KT_PS flag.
Supports real-time and timeshare scheduling.

Metering and Debug (SEMAMETER/SEMAINFO)

Optional per-object statistics (lock attempts, hold/wait times, contention).
Hash bucket lists for idbg scanning.

sv_t Flexibility

Unified queue for multiple lock types via wrapper functions.
Supports bounded broadcast (wakes only original waiter set).
Threshold wake (sv_threshold).

== Similarities to illumos and BSD Kernel Implementations ==
illumos (Solaris-derived)
Strong similarity due to shared SVR4 heritage:

Adaptive mutexes with priority inheritance (similar owner word, waiter lists).
mutex_enter, mutex_tryenter, mutex_exit.
Turnstiles for sleeping/waiting (similar to sv_t but more integrated).
CVs and semaphores separate but similar.
Metering via kstat or dtrace.

Porting: illumos adaptive mutex closest match. Differences in turnstile priority blocking vs IRIX explicit inheritance chains.

Libc: malloc

2025-12-30T19:10:34Z

Raion:

The IRIX libc malloc family (malloc, free, realloc, etc.) implements a classic System V-style dynamic memory allocator using a splay tree for managing free blocks of varying sizes, separate linked lists for small blocks, aggressive coalescing, and delayed freeing to preserve freed block contents across calls. It obtains more memory via sbrk (or equivalent GETCORE), aligns allocations to word boundaries, and handles non-contiguous arenas when necessary.

This decompiled implementation reveals MIPS-specific details (e.g., word size alignment, conditional segmented memory handling), a unique delayed free mechanism using flist and Lfree to avoid disturbing freed data until the next allocation, and optimizations like small-block lists and history-based batch allocation.

Also see: [[Kernel:malloc]]
== Key Functions ==
The allocator centers on a splay tree of free blocks with supporting structures and routines for coalescing, tree maintenance, and arena growth.

Core Allocation (_malloc / __malloc)

Rounds size to word alignment (WORDSIZE, typically 8 on 64-bit MIPS). Checks last freed block (Lfree) for reuse. Performs pending frees via cleanfree(). Handles small requests (< MINSIZE) via _smalloc. Searches splay tree for best-fit (approximated via splaying). Falls back to Bottom chunk or _morecore() for new memory. Coalesces leftovers if large enough.

Deallocation (free / __free / realfree)
free delays actual deallocation by placing pointer in circular flist buffer (size FREESIZE=32) and sets Lfree. Actual freeing occurs in next malloc/realloc via cleanfree() or when buffer fills. realfree coalesces with adjacent blocks, inserts into small lists or splay tree (leaf insertion without immediate splay), updates neighbor busy/free bits.

Reallocation (realloc / _realloc)

Attempts in-place expansion by forward merging. Extends via _morecore if at arena end. Falls back to new allocation + copy + free. Handles special recovery cases when allocation fails (shrink, small-block fallback, backward merge with copy).

Small Block Allocation (_smalloc)
Maintains per-size linked lists (List[]) for sizes < MINSIZE. Batch-allocates multiples (powers of 2 based on history bits) from large blocks to reduce calls to main allocator.

Arena Extension (_morecore)

Requests memory via GETCORE (sbrk wrapper), aligns to page boundaries, doubles request size after threshold calls, handles contiguous/non-contiguous cases, creates new Bottom block.

Tree Maintenance (t_splay, t_delete)

Bottom-up splaying on access (in search/delete). Macro-based rotations for zig/zig-zig cases. Supports lists of equal-sized blocks within tree nodes (via LINKFOR/LINKBAK).
== Undocumented or IRIX-Specific Interfaces and Behaviors ==

=== Critical Structures for ABI Compatibility (from mallint.h) ===
Exact layout must match for binary compatibility; block headers overlap user data minimally.

TREE (block header, placed before user data):

size_t SIZE field in low bits: actual size + flags (BIT0 busy, BIT1 previous free).

Tree fields: TREE *LEFT, RIGHT, PARENT.
List fields: TREE *LINKFOR, LINKBAK (for equal-size doubly-linked lists).

Self-pointer at end of block for validation.
Macros: DATA(tp) (user pointer), BLOCK(p) (header from user), NEXT(tp), LAST(tp), BOTTOM(tp), etc.

=== Global state: ===
TREE *Root — splay tree root.

TREE *Bottom — last chunk at arena end.

char *Baddr — current break address.

char *Lfree — last freed pointer (data intact).

VOID *flist[FREESIZE] + int freeidx — delayed free ring buffer.

TREE *List[MINSIZE/WORDSIZE-1] — small block free lists.

History vars: coresizemask, corecalls.

Constants/macros:
WORDSIZE — typically 8 (64-bit) or 4.

ALIGN — same as WORDSIZE.
MINSIZE — threshold for small lists (often 40-48 bytes).

BIT0 (busy), BIT1 (prev free), BITS01.

=== Delayed Free Mechanism ===
Unique to this implementation: free rarely calls realfree immediately. Instead buffers pointers in flist (preserves data in freed blocks). Next allocation frees buffered blocks (except possibly current realloc target). Enables optimizations assuming freed data undisturbed briefly.

Splay Tree with Equal-Size Lists

Free blocks ordered by size in splay tree. Equal-size blocks form doubly-linked lists within tree nodes (using extra fields). Insertion leaf-only; splaying on search/delete for amortization.

=== Other Behaviors ===
malloc(0) returns unique pointer (size WORDSIZE).

Aggressive coalescing forward/backward on free.

No mmap for large blocks (pure sbrk).

Thread-safe via optional locks (__LOCK_MALLOC).

Special sgi page-end allocation adjustment.

== Similarities to illumos and BSD libc Implementations ==
To enable reimplementation via modified illumos/BSD sources:

illumos libc (malloc.c in libc or watchmalloc)

Extremely close — IRIX derived from same SVR4 lineage as Solaris/illumos:

Nearly identical structure: splay tree + small lists + coalescing + delayed free via flist/Lfree.

Same functions: realfree, t_splay, t_delete, _morecore.

Identical delayed free ring buffer and cleanfree.

Same small-block batching with history bits.

Minor differences: illumos evolved (better thread support, umem alternative); may use mmap for large allocs.

For reimplementation: illumos malloc.c is virtually the same base. Adjust MIPS alignment/constants, ensure exact header layout/macros, preserve delayed free and splay details.

BSD libc (jemalloc or legacy)

More divergent:

Modern FreeBSD/NetBSD use jemalloc (arena-per-thread, red-black trees, extensive caching).

Older BSD had simpler first-fit or dlmalloc-derived.

No splay trees, no delayed free ring, different coalescing.

jemalloc highly tuned for multi-thread, low fragmentation.

For reimplementation: BSD sources less suitable as base; useful for ideas on thread arenas or modern features, but require major rewrite to match IRIX splay/delayed behavior.

Overall, illumos/Solaris-derived malloc is the closest match for direct porting due to shared System V heritage and near-identical internals. Combine with IRIX specifics for exact ABI/behavior replication. Verify against mallint.h equivalents and test with IRIX binaries.

Libc: malloc

2025-12-30T19:09:58Z

Raion: Created page with "The IRIX libc malloc family (malloc, free, realloc, etc.) implements a classic System V-style dynamic memory allocator using a splay tree for managing free blocks of varying sizes, separate linked lists for small blocks, aggressive coalescing, and delayed freeing to preserve freed block contents across calls. It obtains more memory via sbrk (or equivalent GETCORE), aligns allocations to word boundaries, and handles non-contiguous arenas when necessary. This decompiled im..."

The IRIX libc malloc family (malloc, free, realloc, etc.) implements a classic System V-style dynamic memory allocator using a splay tree for managing free blocks of varying sizes, separate linked lists for small blocks, aggressive coalescing, and delayed freeing to preserve freed block contents across calls. It obtains more memory via sbrk (or equivalent GETCORE), aligns allocations to word boundaries, and handles non-contiguous arenas when necessary.
This decompiled implementation reveals MIPS-specific details (e.g., word size alignment, conditional segmented memory handling), a unique delayed free mechanism using flist and Lfree to avoid disturbing freed data until the next allocation, and optimizations like small-block lists and history-based batch allocation.
== Key Functions ==
The allocator centers on a splay tree of free blocks with supporting structures and routines for coalescing, tree maintenance, and arena growth.

Core Allocation (_malloc / __malloc)

Rounds size to word alignment (WORDSIZE, typically 8 on 64-bit MIPS). Checks last freed block (Lfree) for reuse. Performs pending frees via cleanfree(). Handles small requests (< MINSIZE) via _smalloc. Searches splay tree for best-fit (approximated via splaying). Falls back to Bottom chunk or _morecore() for new memory. Coalesces leftovers if large enough.

Deallocation (free / __free / realfree)
free delays actual deallocation by placing pointer in circular flist buffer (size FREESIZE=32) and sets Lfree. Actual freeing occurs in next malloc/realloc via cleanfree() or when buffer fills. realfree coalesces with adjacent blocks, inserts into small lists or splay tree (leaf insertion without immediate splay), updates neighbor busy/free bits.

Reallocation (realloc / _realloc)

Attempts in-place expansion by forward merging. Extends via _morecore if at arena end. Falls back to new allocation + copy + free. Handles special recovery cases when allocation fails (shrink, small-block fallback, backward merge with copy).

Small Block Allocation (_smalloc)
Maintains per-size linked lists (List[]) for sizes < MINSIZE. Batch-allocates multiples (powers of 2 based on history bits) from large blocks to reduce calls to main allocator.

Arena Extension (_morecore)

Requests memory via GETCORE (sbrk wrapper), aligns to page boundaries, doubles request size after threshold calls, handles contiguous/non-contiguous cases, creates new Bottom block.

Tree Maintenance (t_splay, t_delete)

Bottom-up splaying on access (in search/delete). Macro-based rotations for zig/zig-zig cases. Supports lists of equal-sized blocks within tree nodes (via LINKFOR/LINKBAK).
== Undocumented or IRIX-Specific Interfaces and Behaviors ==

=== Critical Structures for ABI Compatibility (from mallint.h) ===
Exact layout must match for binary compatibility; block headers overlap user data minimally.

TREE (block header, placed before user data):

size_t SIZE field in low bits: actual size + flags (BIT0 busy, BIT1 previous free).

Tree fields: TREE *LEFT, RIGHT, PARENT.
List fields: TREE *LINKFOR, LINKBAK (for equal-size doubly-linked lists).

Self-pointer at end of block for validation.
Macros: DATA(tp) (user pointer), BLOCK(p) (header from user), NEXT(tp), LAST(tp), BOTTOM(tp), etc.

=== Global state: ===
TREE *Root — splay tree root.

TREE *Bottom — last chunk at arena end.

char *Baddr — current break address.

char *Lfree — last freed pointer (data intact).

VOID *flist[FREESIZE] + int freeidx — delayed free ring buffer.

TREE *List[MINSIZE/WORDSIZE-1] — small block free lists.

History vars: coresizemask, corecalls.

Constants/macros:
WORDSIZE — typically 8 (64-bit) or 4.

ALIGN — same as WORDSIZE.
MINSIZE — threshold for small lists (often 40-48 bytes).

BIT0 (busy), BIT1 (prev free), BITS01.

=== Delayed Free Mechanism ===
Unique to this implementation: free rarely calls realfree immediately. Instead buffers pointers in flist (preserves data in freed blocks). Next allocation frees buffered blocks (except possibly current realloc target). Enables optimizations assuming freed data undisturbed briefly.

Splay Tree with Equal-Size Lists

Free blocks ordered by size in splay tree. Equal-size blocks form doubly-linked lists within tree nodes (using extra fields). Insertion leaf-only; splaying on search/delete for amortization.

=== Other Behaviors ===
malloc(0) returns unique pointer (size WORDSIZE).

Aggressive coalescing forward/backward on free.

No mmap for large blocks (pure sbrk).

Thread-safe via optional locks (__LOCK_MALLOC).

Special sgi page-end allocation adjustment.

== Similarities to illumos and BSD libc Implementations ==
To enable reimplementation via modified illumos/BSD sources:

illumos libc (malloc.c in libc or watchmalloc)

Extremely close — IRIX derived from same SVR4 lineage as Solaris/illumos:

Nearly identical structure: splay tree + small lists + coalescing + delayed free via flist/Lfree.

Same functions: realfree, t_splay, t_delete, _morecore.

Identical delayed free ring buffer and cleanfree.

Same small-block batching with history bits.

Minor differences: illumos evolved (better thread support, umem alternative); may use mmap for large allocs.

For reimplementation: illumos malloc.c is virtually the same base. Adjust MIPS alignment/constants, ensure exact header layout/macros, preserve delayed free and splay details.

BSD libc (jemalloc or legacy)

More divergent:

Modern FreeBSD/NetBSD use jemalloc (arena-per-thread, red-black trees, extensive caching).

Older BSD had simpler first-fit or dlmalloc-derived.

No splay trees, no delayed free ring, different coalescing.

jemalloc highly tuned for multi-thread, low fragmentation.

For reimplementation: BSD sources less suitable as base; useful for ideas on thread arenas or modern features, but require major rewrite to match IRIX splay/delayed behavior.

Overall, illumos/Solaris-derived malloc is the closest match for direct porting due to shared System V heritage and near-identical internals. Combine with IRIX specifics for exact ABI/behavior replication. Verify against mallint.h equivalents and test with IRIX binaries.

Libc: doscan

2025-12-30T18:41:45Z

Raion: Created page with "The _doscan function is the core implementation of formatted input in IRIX libc, serving as the internal routine for the entire scanf family (scanf, fscanf, sscanf, vscanf, etc.). It parses the format string, reads from a FILE * stream (or string via dummy stream for sscanf), matches input against specifiers, skips whitespace as required, and stores converted values via va_list. This decompiled version shows MIPS-specific handling (e.g., conditional long double support i..."

The _doscan function is the core implementation of formatted input in IRIX libc, serving as the internal routine for the entire scanf family (scanf, fscanf, sscanf, vscanf, etc.). It parses the format string, reads from a FILE * stream (or string via dummy stream for sscanf), matches input against specifiers, skips whitespace as required, and stores converted values via va_list.
This decompiled version shows MIPS-specific handling (e.g., conditional long double support in 32-bit ABI), full POSIX positional parameter support, wide-character conversions (%C/%S), and careful stream handling with macros like locgetc/locungetc. It uses a dynamic scratch buffer for numeric parsing, character class tables for %[], and multibyte-to-wide conversion for wide specifiers.
== Key Functions ==
The implementation features a main parsing loop with helper routines for different conversion types.
=== Main Entry Point (_doscan) ===
_doscan validates the stream for readability, initializes positional argument handling if needed, and loops through the format:

Skips whitespace in format and input.
Handles literal '%' (%%) matching.
Parses suppression (*), field width, positional ($), length modifiers (h,l,ll,L).
Dispatches to conversion-specific handlers.
Returns the number of successful assignments or EOF on error/end-of-input with no matches.

=== Format Parsing and Positional Parameters ===
Uses charswitch for incremental parsing. Full support for POSIX %n$ positional parameters with fast path via _mkarglst (pre-scans for first 30 args) and fallback va_arg skipping. Same stva_list wrapper as in _doprnt.
=== String and Character Handling (c, s, [, C, S) ===

string(): Reads characters until whitespace (for %s) or mismatch (for %c/%[). Respects field width; no null-termination for %c.
wstring(): Wide version using nextwc() for multibyte-to-wide conversion.
setup(): Builds character class table for %[] (handles ^ negation, ranges like a-z).

=== Integer and Pointer Conversion (d, i, o, u, x, p) ===
Handled in number(): Collects digits into dynamic scratch buffer, detects base (including 0x auto for %i/%x), handles sign. Uses strtol-like accumulation with careful overflow avoidance. %p treated as hex long.
=== Floating-Point Conversion (e, E, f, F, g, G) ===
Collects full numeric string (sign, digits, decimal, exponent) into scratch buffer, then calls atof/atold for conversion. Handles locale decimal point (_numeric[0]). Long double conditional on ABI.
=== Assignment Count (%n) ===
Stores characters consumed so far (with h/l/ll modifiers).
=== Auxiliary and Internal Utilities ===

locgetc/locungetc: Stream-aware get/unget (handles sscanf dummy streams).
readchar(): Direct read() fallback when buffer empty (non-sscanf).
nextwc(): Multibyte-to-wide conversion with mbtowc.
Dynamic scratch buffer (initial 128 bytes, grows by 128) for numeric strings.
_mkarglst: Pre-scans format to build positional va_list array (assumes uniform pointer size).

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
=== Critical Structures for Compatibility ===

stva_list: Same wrapper as in _doprnt for positional args.
No special FP union needed (unlike output).

=== Extended Format Specifiers ===

%C / %S: Wide character/string (uppercase, similar to glibc %lc/%ls).
Full POSIX positional parameters (%n$).

=== Length Modifier Handling ===

In 32-bit ABI, 'L' for floating-point defaults to 'l' (no quad FP support).
Uppercase specifiers (E,G,X) converted to lowercase (except C/S); non-floating uppercase treated as 'l'.

=== Stream and Locale Integration ===

Uses _numeric[0] for decimal point in floats.
Multibyte-aware wide conversions.
Robust EOF handling and character count tracking.

These extend standard scanf with wide support, positional args, and careful sscanf integration while maintaining System V-style internals.
== Similarities to illumos and BSD libc Implementations ==
To aid reimplementation using modified illumos or BSD sources, note the strong System V heritage shared with illumos.
=== illumos libc (__doscan_u / doscan.c) ===
Very close match (IRIX likely derived from earlier SVR4):

Core function often named _doscan or __doscan_u.
Identical macros locgetc/locungetc for sscanf handling.
Dynamic scratch buffer for numbers.
Character class table (NCHARS) for %[].
Positional parameter support with similar fast/slow paths.
Wide handling separate.
Floating uses atof/strtod family.
Minor differences: illumos may use strtoll/strtoull directly; locale handling evolved.

For reimplementation: Start with illumos doscan.c (or Solaris-derived forks), add IRIX-specific wide handling (%C/%S via nextwc), match exact positional logic and scratch buffer growth. ABI conditionals for long double easy to adapt.
=== BSD libc (vfscanf.c / __svfscanf) ===
More divergent (BSD heritage):

Core is vfscanf or __svfscanf; no _doscan.
State-machine parsing with explicit conversion types (CT_INT, CT_FLOAT, etc.).
Fixed-size buffer for floats (often 513); no dynamic scratch.
No native positional parameters (%n$).
Advanced locale/xlocale support.
Floating via custom parsefloat (not atof).
Wide via %lc/%ls (not %C/%S).

For reimplementation: BSD code is portable and modern but requires adding positional support (port from illumos/IRIX), changing to dynamic buffer, adapting wide specifiers. Less direct match than illumos.
Overall, illumos/Solaris-derived _doscan is the closest base for porting; combine with IRIX specifics for wide/positional/ABI handling. Verify against sources (e.g., illumos-gate doscan.c equivalents, FreeBSD vfscanf.c).

Libc: doprnt

2025-12-30T18:40:45Z

Raion: Initial Commit

== Overview ==
The _doprnt function forms the core of the formatted output routines in IRIX libc, serving as the internal implementation for the entire printf family (printf, fprintf, sprintf, vprintf, etc.). It parses the format string, retrieves variable arguments via va_list, converts values according to specifiers, and writes formatted output to a FILE * stream or buffer (with dummy streams used for string variants).
This decompiled implementation reveals MIPS-specific adaptations for 32-bit and 64-bit ABIs (controlled by _MIPS_SIM macros), support for ANSI C specifiers, POSIX extensions (positional parameters, thousands grouping), and IRIX-specific behaviors (human-readable size formats, detailed NaN printing). It coordinates buffer management, locale-aware grouping, floating-point bit manipulation, and wide-character handling while ensuring efficient output through macros like PUT and PAD.
== Key Functions ==
The implementation consists of a main loop with supporting utilities that handle parsing, conversion, and output. Below is a detailed overview of the primary operations and structures.
=== Main Entry Point (_doprnt) ===
_doprnt processes the format string in a loop, copying literal text directly and handling '%' specifiers through flag parsing, width/precision extraction, modifier application, and conversion-specific logic. It maintains output count, manages stream buffering via _dowrite, and constructs output components (prefix, padding, value, suffix) before emission. Special handling exists for dummy streams (sprintf family) and flushing on newline or unbuffered/line-buffered modes.
=== Format Parsing and Flag Management ===
Flags, width, precision, and modifiers are parsed incrementally using a charswitch loop. Supports standard flags (+, -, space, #, 0), precision (.), width, length modifiers (h, l, ll, L), positional parameters (n$), and dynamic width/precision (*). The apostrophe (') flag enables thousands grouping via __do_group. Bitmask flagword tracks state for padding, justification, and suffixes.
=== Integer Conversion (d, i, u, o, x, X, p) ===
Signed conversions handle negative values with careful overflow avoidance using _lowdigit for minimum integer cases. Digit generation uses table-based division (powers of 10) or bit shifting for non-decimal bases. Optional thousands grouping applies for decimal with ' flag. # flag adds prefixes (0 for octal, 0x/0X for hex). Pointers (%p) are treated as hex with length modifier in 64-bit.
=== Floating-Point Conversion (e, E, f, F, g, G, a/A absent) ===
Uses ecvt_r/fcvt_r (or quad variants for long double) to obtain mantissa and exponent. Special detection and formatting for Inf ("inf"/"INF") and NaN ("nan0x<hex>"/"NAN0X<hex>") via _dval bit fields. Supports # flag for trailing decimal, precision defaults, and exponent formatting. Grouping applies to integral part in fixed formats.
=== Human-Readable Size Formats (b, B – IRIX-specific) ===
Divides floating value repeatedly by 1024 (%b) or 1000 (%B), appending suffix (k,m,g,t,p,e,z,y or uppercase). Falls through to %f logic for the numeric part.
=== String and Character Handling (s, S, c, C) ===
Narrow strings copy with precision limit; NULL renders as "(null)". Wide characters/strings use wctomb conversion. Uppercase specifiers handle wide types.
=== Auxiliary and Internal Utilities ===

_dowrite: Flushes buffer when full, handling read-mode quirks.
_lowdigit / _lowdigit_l: Safe digit extraction for negative extremes.

decimal_digits_ll / decimal_digits_l: Fast digit count via binary search on power-of-10 tables.

_mkarglst / _getarg: Enable positional parameters with fast path for up to 30 arguments.

__do_group: External locale-aware thousands separator insertion.

==== Macros ====

IsZero(x): Checks if a _dval double is zero, ABI-aware.

PUT(p, n): Writes n bytes from p to the buffer/stream, handling overflow via _dowrite.

PAD(s, n): Pads with string s repeated n times, using _dowrite for large n.

SNLEN = 5: Length for NaN strings ("nan0x").

NDIG = 82: Buffer size from ecvt.c.

MAXARGS = 30: Max fast positional arguments.

==== Constants and Tables ====

table10_ll[18], table10_l[9]: Powers of 10 for decimal digit counting.

_blanks, _zeroes: Padding strings.

uc_digs, lc_digs: Hex digit tables.

lc_nan = "nan0x", uc_nan = "NAN0X": NaN prefixes (IRIX-specific with "0x" for hex payload).

lc_inf = "inf", uc_inf = "INF": Infinity strings.

wnull_buf: Wide null string for %S NULL handling.

==== Flags (bit positions) ====
Defined as bitmasks for format parsing:

LENGTH = 1: 'l' modifier.

FPLUS = 2: '+' flag.

FMINUS = 4: '-' flag.

FBLANK = 8: ' ' flag.

FSHARP = 16: '#' flag.

PADZERO = 32: '0' flag.

DOTSEEN = 64: '.' seen (precision).

SUFFIX = 128: Exponent/suffix needed.

RZERO = 256: Trailing zeros.

LZERO = 512: Leading zeros.

SHORT = 1024: 'h' modifier.

LLONG = 2048: 'll' modifier.

LDOUBLE = 4096: 'L' modifier.

FQUOTE = 0x10000: ''' (apostrophe) flag for thousands grouping (IRIX/POSIX extension).'''

These are stored in flagword and control output formatting.
==== Structs and Unions ====
To ensure ABI compatibility, these must match exactly in any replacement:

'''_dval''': Union for bit-level access to double. Critical for NaN/Inf detection and floating-point manipulation.
typedef union {

struct {
unsigned sign :1;
unsigned exp :11;
unsigned hi :20;
unsigned lo :32;
} fparts;
if (_MIPS_SIM != _MIPS_SIM_ABI32)
struct {
unsigned sign :1;
unsigned long long rest :63;
} dparts;
else
struct {
unsigned sign :1;
unsigned hi :31;
unsigned lo :32;
} dparts;
endif
struct {
unsigned hi;
unsigned lo;
} fwords;
double d;

} _dval;

ABI-specific: In 32-bit ABI (_MIPS_SIM_ABI32), double is split into two 32-bit words. In 64-bit, uses 63-bit rest after sign.

Used with IsNANorINF, IsINF, IsNegNAN, GETNaNPC (from nan.h).

'''stva_list''': Wrapper for va_list to allow assignment (bypasses C array restrictions).
typedef struct stva_list {

va_list ap;

} stva_list;

Used for positional argument handling in _mkarglst and _getarg.

==== Internal Functions ====

_lowdigit(long long *valptr), _lowdigit_l(long *valptr): Compute low-order decimal digit for negative numbers near overflow, divide by 10.
_dowrite(const char *p, ssize_t n, FILE *iop, unsigned char **ptrptr): Handles buffer flushing/writing when buffer is full.
decimal_digits_ll(long long), decimal_digits_l(long): Count decimal digits using binary search on power-of-10 tables.
__do_group(char *str, double val, int prec, int ndigs, int strsize, int maxfsig): Inserts thousands separators (locale-aware) for ''' flag. (External, not defined here.)
_mkarglst(char *fmt, stva_list args, stva_list arglst[]): Initializes array of va_list for first MAXARGS positional args.
_getarg(char *fmt, stva_list *pargs, int argno): Advances va_list for args beyond MAXARGS.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==
=== Critical Structures for ABI Compatibility ===

_dval: Union providing bit-field access to double representation. Layout differs by ABI (32-bit splits into two words; 64-bit uses 63-bit mantissa). Essential for NaN/Inf detection and payload extraction.

stva_list: Wrapper around va_list to permit assignment, enabling positional argument array.

=== Extended Format Specifiers ===

%b / %B: Human-readable byte sizes with binary (1024) or decimal (1000) scaling and suffixes.

%C / %S: Wide character/string (equivalent to glibc %lc/%ls).

Apostrophe (') flag: Thousands grouping in decimal integer and fixed float output (POSIX, locale-aware).

=== NaN and Infinity Representation ===

Infinity: "inf" or "INF".
NaN: "nan0x<hex-payload>" or "NAN0X<hex-payload>" – includes significand bits as hex (unique to IRIX/MIPS; most systems omit payload).

=== Positional Parameters (%n$) ===
Full POSIX support with fast path (pre-scanned array for first 30 arguments) and fallback scanning for higher positions.
=== Long Double Handling ===
Conditional on 64-bit ABI; uses separate quad conversion routines and extended precision in grouping.
=== Buffer and Locale Integration ===

Uses _numeric[0] for decimal point.
Thousands grouping via external __do_group, supporting locale-specific separators.
Robust NULL string handling and wide-character conversion.

These behaviors extend standard printf semantics with IRIX-specific formatting, hardware-aware floating-point representation, and efficient positional argument handling while maintaining ABI-critical structure layouts. For replacement implementations, exact matching of _dval layout and NaN printing behavior is required for binary compatibility.
== Similarities to illumos and BSD libc Implementations ==
To facilitate reimplementation using modified sources from illumos (OpenSolaris descendant) or BSD libc, note the following shared and divergent aspects based on their printf cores (_doprnt in illumos, vfprintf in BSD).
=== illumos libc (_doprnt) ===
As a System V derivative like IRIX, illumos shares significant structural similarities:

Core function name and signature (_doprnt(const char *fmt, va_list ap, FILE *iop)).
Parsing loop with flagword bitmasks for flags (similar positions for FPLUS, FMINUS, etc.).
Macros like PUT/PAD for buffered output, _lowdigit for overflow-safe digit extraction.
Integer handling with power-of-10 tables for fast digit count and generation.
Floating-point uses ecvt/fcvt (with quad for long double), but NaN/Inf as plain "NaN"/"Inf" without hex payload.
Positional parameters (%n$) with similar _mkarglst/_getarg logic and MAXARGS limit.
Apostrophe (') flag for grouping via external function.
Wide support (%lc/%ls instead of %C/%S).
No %b/%B; lacks IRIX-specific human-readable sizes.
FP union (_ieee_double) similar but not MIPS-ABI-specific; no _dval equivalent.

For reimplementation: Start with illumos _doprnt, port _dval for MIPS ABI, add hex NaN printing using GETNaNPC, implement %b/%B by modifying %f case, match IRIX flags/extensions. Buffer utils (_dowrite) are comparable.
=== BSD libc (vfprintf) ===
BSD (FreeBSD/OpenBSD/NetBSD) uses vfprintf as the core, with differences in organization but shared ANSI logic:

Main loop parses format, handles specifiers in switch; flag bits similar but differently named (PF_ prefixes).
Buffered output via __sprint or similar, with padding functions.
Integer conversion uses custom loops or strtol; some have bitfield %b (different from IRIX %b).
Floating-point via gdtoa or dragon4, NaN as "nan"/"inf" (case-sensitive); no hex payload.
No native positional args (BSD extension in some, but not standard).
No ' flag for grouping; locale support via LC_NUMERIC but not auto-grouping.
Wide support (%lc/%ls); some BSDs have %C as synonym.
Extensions like %m (strerror), %D (long), %ll (long long).
Long double via %Lf; FP handling portable, no ABI-specific unions like _dval.

For reimplementation: BSD vfprintf is less similar due to different architecture (no _doprnt), but floating-point (Inf/NaN) and integer logic can be adapted. Add positional support from illumos/IRIX, modify NaN to include hex, implement IRIX extensions. Buffer management differs but portable.
Overall, illumos is closer for direct porting due to System V heritage; combine with BSD for modern FP precision if needed. Verify against sources (e.g., illumos-gate doprnt.c, FreeBSD vfprintf.c).

Kernel: Introduction

2025-12-30T02:24:36Z

Raion: Created page with "== Introduction == The ''Kernel:'' namespace serves as a comprehensive, community-driven repository for detailed technical documentation of the IRIX kernel, derived from reverse engineering efforts on IRIX 6.5 binaries. This initiative focuses on analyzing, decompiling, and annotating kernel object files to produce high-level, functional descriptions of subsystems, data structures, and behaviors. The documentation is intended to preserve and disseminate deep technic..."

Kernel:Virtual Memory

2025-12-30T02:14:48Z

Raion:

Kernel:Virtual Memory

2025-12-30T02:14:30Z

Raion: Initial Commit

{{KernelNav}}

== Overview ==

The IRIX virtual memory system manages physical and virtual memory resources on MIPS-based Silicon Graphics systems, supporting both 32-bit and 64-bit addressing modes with dynamic switching. It is designed for high-performance computing, graphics, and real-time applications, incorporating SVR4 features like demand paging, memory-mapped I/O (mmap, mprotect), and ELF executables. The system handles anonymous memory (e.g., heap, stack) via tree-based structures for copy-on-write efficiency during forks, and file-backed memory through vnode-integrated page caching. It supports large physical memory (up to 16 GB in later versions), virtual address spaces up to 1 TB per 64-bit process, and NUMA-aware allocation for multiprocessor scalability.

Key aspects include page frame management, swapping to disk, variable page sizes for optimization, memory migration for load balancing, and reverse mapping for efficient invalidation. The VM subsystem integrates with IRIX's filesystem layers (e.g., XFS, EFS) for unified caching and I/O, and includes real-time enhancements like page locking to minimize latencies. It emphasizes multiprocessor efficiency with fine-grained locking, preemption, and hardware-specific optimizations for MIPS processors (e.g., R8000, R10000).

== Key Components and Flow ==

* **Address Space Management**: Processes operate in user or kernel mode, with virtual addresses mapped to physical memory or swap. User space is segmented (e.g., kuseg for 32-bit: 0-2GB), while kernel accesses extended regions.
* **Page Frame Data (pfdat)**: Tracks physical pages, including flags for states like hashed, queued, recycled, or bad. Supports replication in NUMA environments.
* **Anonymous Memory Handling**: Uses binary trees of anon structures for copy-on-write sharing post-fork, with caches for pages (pcache) and swap handles (scache).
* **File-Backed Caching**: Vnode page cache integrates with filesystems for demand-loaded pages, handling flush, invalidate, and toss operations.
* **Swapping and Paging**: Manages swap devices (up to 255), demand paging, and precomputation of memory needs (availsmem) for resource-constrained environments.
* **NUMA and Large Pages**: Node-specific data structures (pgdata, nodepda) for free lists and stats; supports multiple page sizes with coalescing and splitting.
* **Migration and Mapping**: Page migration for balancing; reverse maps (rmap) for quick invalidation during unmap or protection changes.
* **Real-Time Features**: Page locking, bounded interrupt latencies, and Miser integration for batch scheduling.

Typical flow: On page fault (vfault/pfault), lookup in caches; if missing, allocate or swap in. Forks duplicate anon trees; exits prune and free resources. Memory pressure triggers swapping, coalescing, or migration.

== Key Functions ==

The VM system comprises operations for memory allocation, mapping, fault handling, and resource management. Below is a detailed functional overview, describing roles, logic, and interactions.

=== Anonymous Memory Initialization and Allocation ===
Initializes global structures like allocation zones and shared anon lists. Creates new anon handles for regions, setting up locks and caches. Allocates and initializes anon nodes with reference counts and depth hints for tree management.

=== Fork Handling (Duplication) ===
Duplicates anon structures for child processes, forming or extending binary trees to enable copy-on-write sharing. Allocates new leaf nodes for parent and child, linking them to the original root. Checks for tree depth and prunes if necessary. Reserves resources for potential cache growth.

=== Exit or Region Free (Deallocation) ===
Disassociates regions from anon memory, removing leaf nodes and freeing pages/swap space. Collapses branches with single children recursively toward the root. Releases locks and nodes when reference counts reach zero.

=== Tree Optimization (Collapse and Prune) ===
Reduces tree depth by merging parent-child pairs when one child is absent, transferring pages and swap handles. Selects survivor based on page count; discards covered pages. Prunes empty intermediate nodes with no pages/swap to prevent unbounded growth in long-lived forking processes.

=== Page Insertion into Anon ===
Adds pages to leaf node caches, covering lower tree levels if needed. Ensures no duplicates; handles potential cache resizing.

=== Page Modification Handling ===
Determines copy or steal for writes: Copies for shared or non-top-level pages; steals otherwise, clearing swap info and rehashing to top level. Heuristics for caching swapped pages when memory is abundant.

=== Swap Handle Management ===
Merges or clears swap handles during collapses; transfers non-covered handles to survivors.

=== Vnode Page Cache Initialization ===
Sets up per-vnode caches during allocation or recycling, initializing hash structures and reference counts.

=== Vnode Page Lookup and Attachment ===
Searches caches for pages by logical number; attaches by incrementing use counts, resolving races with allocation/recycling.

=== Vnode Page Insertion ===
Adds pages to caches, resizing if needed; supports conditional insertion to handle races, freeing duplicates.

=== Vnode Page Removal and Invalidation ===
Removes pages from caches, marking bad or requeuing free; flushes/invalidates ranges, tossing to buffers if needed.

=== Page Recycling and Migration ===
Recycles pages for reuse, removing from caches; migrates by copying state to new frames, updating caches atomically.

=== Memory Requirement Estimation ===
Precomputes swap/memory needs for operations, caching for runtime linker and batch jobs.

=== Hardware Workaround Checks ===
Scans for CPU errata indicators, flagging proxy use for instruction rewriting in executable pages.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==

=== Anonymous Memory Tree Structures ===
Binary trees of anon nodes for efficient copy-on-write: Leaves represent process-private pages; internal nodes share via parents. Depth hints and pruning thresholds (e.g., PRUNE_THRESHOLD) prevent degradation in forking servers. Covered pages discarded during merges; swap caches (scache) track out-of-memory handles.

=== Shared Anonymous Pages (sanon) ===
Special lists for unreferenced, dirty, shared anon pages (psanonmem counter). Node-specific free lists with locks; removal macros handle MP races.

=== Page and Swap Caches (pcache/scache) ===
Dual caches per anon/vnode: pcache hashes in-memory pages; scache manages swap handles for faulted-out pages. Dynamic resizing, preemption during long operations. Undocumented tokens for space reservation.

=== Memory Reservation (availsmem) ===
Precomputes and reserves physical/swap memory for execs/forks, integrated with Miser for batch retries (EMEMRETRY). Global caching for runtime components.

=== NUMA-Aware Data Structures ===
Per-node pgdata for free lists, stats, and rotors; nodepda integration for allocation. Large page (lpage) support with coalescing daemons, splitting, and stats (e.g., vfault/pfault retries by size).

=== Page Migration and Reverse Mapping ===
Migr subsystem for NUMA balancing; rmap for efficient TLB shootdowns and unmaps. Pagemigr transfers states, handling object mutations.

=== Hardware and Real-Time Extensions ===
Flags for MIPS errata (e.g., R5000 CVT, TFP prefetch); mtext proxies for instruction patching. Page locking for real-time, bounded latencies, and VCE avoidance for cache coloring.

=== Vnode Cache Synchronization ===
Reference counting (v_pcacheref) with wait bits for reclaim coordination; broadcast on zero refs. Integration with DMAPI, ShareII for extended file ops.

These extend standard UNIX VM with SGI-specific optimizations for MIPS, NUMA, graphics, and HPC, emphasizing scalability and reliability.

Kernel: ELF Loader

2025-12-30T01:59:54Z

Raion:

Kernel: ELF Loader

2025-12-30T01:59:35Z

Raion: Created page with "{{KernelNav}} == Overview == The IRIX kernel's ELF loader manages the execution of ELF-format binaries on MIPS-based systems, accommodating 32-bit and 64-bit architectures along with multiple ABIs. It performs tasks such as validating file headers, preparing the user stack and arguments, mapping memory segments, handling dynamic linking, and applying hardware-specific adjustments. Integration with kernel components like address space handling, virtual memory allocation..."

{{KernelNav}}

== Overview ==

The IRIX kernel's ELF loader manages the execution of ELF-format binaries on MIPS-based systems, accommodating 32-bit and 64-bit architectures along with multiple ABIs. It performs tasks such as validating file headers, preparing the user stack and arguments, mapping memory segments, handling dynamic linking, and applying hardware-specific adjustments. Integration with kernel components like address space handling, virtual memory allocation, process control, and resource management ensures efficient and reliable execution.

The loader supports ABI transitions during execution, resource pre-allocation for constrained environments, and extensions for MIPS hardware errata. It processes both static and dynamic executables, coordinating with the runtime linker for shared libraries.

== Key Functions ==

The loader comprises several core operations that orchestrate the execution process. Below is a detailed functional overview of these operations, describing their roles, inputs, logic, and outputs.

=== Header Retrieval and Validation ===

This function reads the ELF header and program headers from the executable file. It validates essential fields such as the magic number, class (32-bit or 64-bit), data encoding, file type (executable or dynamic), and MIPS-specific architecture flags. It determines the ABI version based on machine type and flags, ensuring compatibility with the system's capabilities. On success, it provides the parsed headers for further processing; failures result in errors like invalid executable format or bad request due to unsupported architecture.

=== ELF Execution Dispatch ===

The primary entry point for ELF binary execution dispatches based on the file's class to handle 32-bit or 64-bit specifics. It retrieves headers, scans program headers for dynamic linking indicators, auxiliary setup needs, and hardware options. It calculates auxiliary vector size, allocates kernel space for argument building, constructs the user stack, and reserves memory resources if required for batch processing. The process splits to manage stack usage, proceeding to image removal and new address space creation. Errors lead to cleanup and restoration of original state.

=== Execution Completion ===

Continuing from the dispatch, this phase removes the existing process image, creates a new address space with affinity considerations, and maps segments. For dynamic binaries, it loads the runtime linker, builds extended auxiliary vectors, and sets up the stack with execution parameters. It configures registers, including floating-point unit settings based on architecture, and transfers control to the entry point. Failures trigger process termination with detailed logging.

=== Segment Mapping ===

This operation maps ELF segments into the address space, focusing on loadable sections. It computes protections (read, write, execute) and flags (local mapping, heap consideration), handles zero-fill regions, and applies workarounds for hardware issues in executable pages. It identifies special program headers for dynamic linking, shared libraries, and options. Mapping occurs with file-backed regions, supporting checkpointing. Errors include memory shortages or invalid segment orders.

=== Dynamic Shared Object Mapping ===

Accessible from user space, this function maps segments for shared objects, typically invoked by the runtime linker. It validates file descriptors and permissions, copies program headers from user space, and performs mappings with potential workarounds. On memory errors, it attempts relocation to an alternate address range. Success returns the base address; failures unmap partial allocations.

=== Memory Requirement Calculation ===

These utilities estimate the physical memory needed for execution, summing requirements for writable segments, the user stack, and the runtime linker. Computations account for page alignments and cache results for repeated use, updating on file changes. This supports early reservation in resource-managed environments, preventing failures during critical phases.

=== Hardware Workaround Check ===

For specific CPU errata, this checks program headers for cleanliness indicators regarding problematic instructions. If needed, it flags the use of proxy mechanisms during mapping to mitigate issues in read-only executable regions.

== Undocumented or IRIX-Specific Interfaces and Behaviors ==

=== MIPS Hardware Workarounds in PT_MIPS_OPTIONS ===

IRIX scans PT_MIPS_OPTIONS sections for hardware patch flags:

* '''OHW_R5KCVTL''' (0x8): Indicates the binary is clean of the R5000 cvt.[ds].l bug. If absent on affected CPUs (with ''R5000_cvt_war'' enabled, typically n32/n64 ABIs), the kernel uses the ''mtext'' subsystem (proxy vnodes) to rewrite problematic instructions in read-only executable pages during mapping.
* '''OHW_R8KPFETCH''' (TFP_PREFETCH_WAR): On TFP (R8000) CPUs, non-dynamic MIPS4 binaries with prefetch instructions are rejected (EBADRQC) unless ''chk_ohw_r8kpfetch'' is non-zero. For dynamic binaries, the kernel sets a flag to add '''AT_PFETCHFD''' to auxv (see below).

These flags trigger kernel-level instruction patching or rejection, not documented in public ELF ABI supplements.

=== Extended Auxiliary Vector Entries ===

* '''AT_PFETCHFD''': Provides an open file descriptor to the executable for the runtime linker (rld) to apply prefetch instruction patches (no-ops) on TFP systems. Added when a dynamic binary requires the prefetch workaround.

Standard auxv entries (AT_PHDR, AT_BASE, etc.) are used, but AT_PFETCHFD is an IRIX-specific extension.

=== Memory Reservation (availsmem) for Exec ===

* Functions ''elf_compute_availsmem'' and ''elf_get_availsmem'' precompute physical memory needs for writable segments (PF_W in PT_LOAD), user stack, and the runtime linker.
* Cached globally in ''runtime_loader_availsmem'' (recomputed if the runtime linker's vnode changes).
* For Miser batch jobs, reserves memory early via ''vm_pool_exec_reservemem''; failure returns EMEMRETRY for retry.

This mechanism prevents mid-exec failures in memory-constrained environments.

=== Mapping Interfaces ===

* ''execmap'' / ''mtext_execmap_vnode'': Low-level mapping of file-backed regions with ZFOD, protections, and flags (e.g., MAP_LOCAL, MAP_BRK, MAP_PRIMARY).
* ''elfmap'': User-called (from rld) to map DSO PT_LOAD segments. Supports alternate address relocation on ENOMEM by finding a free range and adjusting vaddrs.
* Integration with checkpointing (ckpt handles passed to mapping calls).

=== Other Internal Behaviors ===

* ABI transition handling: Temporarily sets process ABI proxy during exec; resets on failure.
* NUMA/affinity: New address space creation via ''aspm_exec_create'' and affinity link setup.
* FPU flags from PT_MIPS_OPTIONS (ODK_EXCEPTIONS): Sets precise exceptions or speculative mode in process FP flags.
* Runtime linker loading: Caches availsmem needs; sticky bit (VSVTX) on rld allows saving pregions.
* Error reporting: Detailed kill messages with reason codes for failed execs.

These features extend standard ELF handling with IRIX-specific resource management, hardware errata mitigation, and kernel-runtime linker coordination.

Kernel: malloc

2025-12-29T20:54:11Z

Raion:

Kernel: malloc

2025-12-29T20:53:44Z

Raion: Initial

= IRIX Kernel Memory Allocation: Functional Documentation =

This page documents the memory allocation subsystem of the IRIX kernel (`malloc`, `rmalloc`, and related functions) as implemented in the IRIX kernel. It is intended as a functional reference for reimplementation in other kernels (e.g., Illumos).

== Overview ==

The IRIX memory allocation system provides:

* Map-based memory management (`struct map`) for contiguous resource allocation.
* Page-aligned and color-aware allocations for cache efficiency (R4000-specific).
* Bitmap-based system page table (SPT) management.
* Waiting and non-waiting allocation paths (`VM_NOSLEEP` flag).
* Synchronization primitives using spinlocks and semaphores.

Memory management in IRIX is based on two concepts:

# **Maps** – contiguous resources tracked as a list of free/allocated blocks.
# **Bitmaps** – finer-grained allocation (e.g., pages, cache-colored pages) with alignment support.

== Map Allocation API ==

=== rmallocmap() ===
'''Purpose:''' Allocate and initialize a `struct map` for tracking resources.
'''Inputs:''' `mapsiz` – number of entries in the map.
'''Outputs:''' Pointer to newly allocated map, or NULL on failure.

'''Behavior:'''

* Allocates memory for `mapsiz + 2` map entries.
* Allocates and initializes a synchronization structure (`lock + semaphore`).
* Stores pointers to synchronization primitives in the second map entry.
* Returns a fully initialized map ready for allocations.

=== rmfreemap() ===
'''Purpose:''' Free a previously allocated map.
'''Inputs:''' Pointer to map.
'''Behavior:'''

* Waits for any threads currently blocked on the map.
* Destroys associated semaphore and spinlock.
* Frees both the map memory and the synchronization structure.

=== malloc / malloc_wait / rmalloc / rmalloc_wait ===
'''Purpose:''' Allocate contiguous units from a map.
'''Inputs:'''

* `mp` – pointer to map
* `size` – number of units
* Optional `flags` (`VM_NOSLEEP` for non-blocking)

'''Behavior:'''

* Uses **first-fit allocation**.
* Non-blocking (`VM_NOSLEEP`) returns `0` if allocation fails.
* Blocking waits on the map’s semaphore until space becomes available.
* Returns the starting address of allocated space.

=== mfree / rmfree ===
'''Purpose:''' Free previously allocated space in a map.
'''Inputs:'''

* `mp` – pointer to map
* `size` – units to free
* `a` – base address

'''Behavior:'''

* Sorts the freed block into the map.
* Merges with adjacent free blocks if possible.
* Updates map’s size and count.
* Broadcasts to any waiting threads if space becomes available.
* Logs warnings if map overflow or invalid free occurs.

== Bitmap-Based Page Table Management ==

The IRIX kernel uses **bitmap structures** to manage system page tables (`spt`). This allows fine-grained allocation with support for color and alignment.

=== sptalloc() ===
'''Purpose:''' Allocate pages from the system page table bitmap.
'''Inputs:'''

* `bm` – pointer to system bitmap structure
* `want` – number of pages
* `flags` – allocation flags (`VM_NOSLEEP`, `VM_VACOLOR`, `VM_BREAKABLE`)
* `color` – desired cache color (for R4000)
* `alignment` – page boundary alignment (power of 2)

'''Behavior:'''

* Selects a bitmap (clean, stale, aged) for allocation.
* If color-specific allocation is requested, attempts color map first.
* Uses rotors to track possible starting positions for efficiency.
* Supports alignment constraints.
* Will optionally wait (blocking) if pages are unavailable.
* Updates bitmap counters and rotors on allocation.

=== sptfree() ===
'''Purpose:''' Free pages back to the system page table bitmap.
'''Inputs:'''

* `bm` – pointer to system bitmap
* `size` – number of pages
* `mapaddr` – base address of pages to free

'''Behavior:'''

* Updates `m_lowbit`, `m_highbit`, and `m_count` in the bitmap.
* Sets freed bits in the bitmap.
* Broadcasts to waiting threads.

=== mergebitmaps() ===
'''Purpose:''' Merge one bitmap into another (e.g., stale pages back into main SPT map).
'''Inputs:'''

* `bm` – system bitmap
* `to` – destination bitmap
* `from` – source bitmap

'''Behavior:'''

* Copies set bits from source to destination.
* Updates rotor information for SPT allocation.
* Clears source bitmap.

=== bmapswtch() ===
'''Purpose:''' Swap contents of two bitmaps.
'''Use case:''' Replace an old bitmap with a new one without modifying allocation state.

=== sptgetsizes() ===
'''Purpose:''' Get counts of pages in different states (clean, stale, aged, in-transit).

== Synchronization and Multi-Processor Considerations ==

* Spinlocks (`mutex_spinlock`) protect map structures during allocation.
* Bitmaps have a hierarchy of locks:
** Normal allocation lock (`MAP_ALLOCLOCK`)**
** Urgent lock (`MAP_URGENTLOCK`)** – signals to other threads to back off during replenishment.
* Wait queues (semaphores) are used for threads blocked on resources.

== R4000-Specific Enhancements ==

* **Cache-colored allocation:** ensures pages allocated from a bitmap minimize cache conflicts.
* **sptvctst()** – tests for a free bit in a specific cache color.
* **color_alloc()** – allocates a page of a specific color.
* **sptaligntst()** – ensures alignment in allocations.

== Fault Checking ==

* `kvfaultcheck()` inspects which CPUs have references to aged or temporary pages.
* Returns a CPU mask indicating CPUs that need TLB flushes.
* Integration with isolate debugging on multi-CPU systems (EVEREST/SN0).

== Notes for Reimplementation ==

* Map-based allocations are generic and can be adapted to other OS kernels.
* Bitmap-based page allocations depend on low-level page tables; rotors and color optimizations can be implemented optionally.
* Careful handling of spinlocks, semaphores, and wait queues is required in multi-processor environments.
* Ensure that alignment and cache color are power-of-two values for correctness.
* Debug assertions (`ASSERT`) in IRIX should be converted to runtime checks or kernel asserts in the new environment.

Kernel:Kernel Timers

2025-12-29T20:49:16Z

Raion: Initial

# IRIX Kernel Timers

The IRIX kernel implements a **high-resolution, per-thread timer subsystem** designed to track the time threads spend in various modes (user, system, interrupt, etc.) with hardware-specific accuracy. This subsystem differs from Illumos/OpenSolaris in several notable ways due to differences in hardware assumptions and kernel design.

---

## Overview

IRIX kernel timers are responsible for:

* Maintaining **accumulated time** for individual threads across multiple timer modes.
* Providing **high-resolution snapshots** of thread execution time.
* Handling **timer switching** and accumulation safely in SMP or multi-threaded contexts.
* Measuring proportional **thread sleep/wait times**.
* Converting low-level hardware ticks into standard time units (seconds and nanoseconds).

---

## Key Concepts

### Snapshots

* Each thread maintains a **timer snapshot**, representing its current time state.
* Snapshots may consist of:

* A single high-resolution counter (if the platform supports absolute, monotonic timers), or
* A combination of seconds and hardware-specific ticks to handle short-wrap timers.
* Snapshots are used to compute deltas between timer updates and to detect timer wrap-around.

### Timer Accumulation

* Each thread has a **per-thread timer package** that tracks:

* The currently active timer mode.
* Accumulated time for all supported timers.
* The last snapshot for delta calculations.
* When switching timers, IRIX computes the delta between the last snapshot and the current time, adding it to the accumulator for the previous timer mode.

### Timer Switching

* Threads can switch between different timer modes explicitly.
* Timer switching involves:

* Snapshotting the current timer.
* Updating the accumulator of the previously active timer.
* Setting the new timer as active.
* Race conditions are carefully handled by verifying that snapshots are consistent during the update.

### Reading Timers

* Timer reads return the accumulated time for a specific thread and timer mode.
* If the requested timer is currently active, IRIX computes the time since the last snapshot and adds it to the accumulator.
* Reading is designed to be **race-resilient**, looping until a consistent snapshot is obtained.

### Sleep Time Measurement

* IRIX provides a measure of **thread sleep/wait time**, representing how long a thread has been idle.
* This measure is proportional to real time but does not guarantee absolute accuracy.
* Threads in active timer modes (user, system, or interrupt) report zero sleep time.

### Conversion to Standard Time

* Low-level hardware ticks are converted into **seconds and nanoseconds** for user-facing APIs.
* Conversion uses hardware-specific frequency and unit scaling, reflecting differences in RTC or high-resolution counters.

### SMP and Atomic Operations

* On multi-processor systems, atomic operations ensure correct accumulation of timers.
* IRIX distinguishes **CELL IRIX** systems, which use specific atomic add instructions for timer updates.
* Non-CELL SMP systems rely on standard atomic or interrupt-safe mechanisms.

---

## Differences from Illumos/OpenSolaris

| Feature | IRIX | Illumos/OpenSolaris | Notes |
| -------------------- | ------------------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------- |
| Timer representation | Hardware-specific ticks, may wrap | 64-bit monotonic nanoseconds (`hrtime`) | IRIX handles wrap-around; Solaris simpler |
| Snapshots | Stored as ticks or [seconds + ticks] | Stored as cumulative `hrtime` | IRIX explicitly tracks dual-field snapshots for wrap detection |
| Timer switching | Explicit per-thread function | Handled by scheduler/context switch | IRIX exposes manual switching, Solaris hides it internally |
| Sleep time | Computed dynamically from snapshots | Maintained in thread scheduler counters | IRIX calculates on-demand; Solaris updates in scheduler |
| SMP safety | Explicit atomic operations (CELL-specific) | Generic atomic operations | IRIX has platform-specific atomic paths; Solaris uses uniform atomic ops |
| Time conversion | Scaled using hardware frequency | Division of nanoseconds | IRIX converts hardware ticks; Solaris works directly with `hrtime` |
| Race handling | Looping snapshot checks | Scheduler guarantees consistency | IRIX implements explicit consistency checks; Solaris relies on locks/atomic ops |

---

## Key Takeaways

* IRIX kernel timers are **hardware-conscious**, designed for platforms with wrapping high-resolution counters.
* The subsystem provides **manual control** over timer modes and accumulators.
* It carefully manages **race conditions and SMP safety**, including platform-specific atomic operations.
* Unlike Illumos/OpenSolaris, IRIX must scale raw hardware ticks into standard time units and detect timer wrap-around.
* Sleep time and deltas are **computed dynamically** rather than tracked in scheduler-maintained counters.

SGIfetch

2025-12-28T03:25:57Z

Raion: Created page with "'''sgifetch''' is a neofetch-like tool that displays system information for SGI MIPS hardware running IRIX."

'''sgifetch''' is a neofetch-like tool that displays system information for SGI MIPS hardware running IRIX.