ISR Safety Validator

Scans MacTCP ASR, Open Transport notifier, and AppleTalk callback functions for interrupt-time safety violations.

Usage

code

/check-isr src/mactcp/
/check-isr src/mactcp/tcp_mactcp.c
/check-isr

Without arguments, scans all Mac-specific source directories.

Process

•

Verify prerequisites:

bash

# Check validator exists
if [[ ! -f tools/validators/isr_safety.py ]]; then
    echo "❌ ISR validator not found at tools/validators/isr_safety.py"
    exit 1
fi

# Run validator with Python (available in Docker or host)
# The validator is a standalone Python script with no dependencies
echo "✓ Prerequisites OK"

•

Run the validator:

bash

python tools/validators/isr_safety.py ${ARGUMENTS:-src/mactcp src/opentransport src/appletalk}

•
For each violation found:
- •Show the file, line number, and callback function name
- •Show the forbidden function call
- •Explain why it's forbidden (with documentation reference)
- •Suggest the correct pattern
•
If no violations: Confirm the code is ISR-safe

What It Checks

The validator detects callback functions by matching:

•Function names ending in _asr, _notifier, _completion, _callback
•Functions with pascal keyword and MacTCP/OT callback signatures
•Functions matching known ASR/notifier parameter patterns

Within those functions, it checks for calls to:

Category	Examples	Why Forbidden
Memory allocation	malloc, NewPtr, NewHandle	Heap operations at interrupt time
Memory operations	memcpy, BlockMove	May use unsafe implementations
Timing	TickCount	Not in Table B-3 interrupt-safe list
I/O	printf, FSRead, FSWrite	File/device operations forbidden
Sync network	TCPSend, OTConnect	Synchronous calls in async context
Toolbox	GetResource, DrawString	Most Toolbox not interrupt-safe

Common Fixes

Violation	Correct Pattern
memcpy in callback	Use `pt_memcpy_isr()`
TickCount in callback	Set `timestamp = 0`, let main loop timestamp
malloc in callback	Use pre-allocated buffers from context struct
Sync network call	Use async version with completion callback
printf/logging	Set a flag, print from main loop

Example Output

code

src/mactcp/tcp_mactcp.c
Line  | Callback        | Forbidden Call | Reason
------|-----------------|----------------|----------------------------------
142   | tcp_asr         | memcpy         | May use BlockMove internally
156   | tcp_asr         | TickCount      | Not in Table B-3 interrupt-safe
189   | udp_asr         | malloc         | Dynamic allocation forbidden

Integration

The ISR Safety Validator is also integrated as a pre-edit hook. When editing files in src/mactcp/, src/opentransport/, or src/appletalk/, the hook will block edits that introduce violations.

Example Workflows

After Implementing Mac Code

bash

# Implemented MacTCP TCP driver
/check-isr src/mactcp/tcp_mactcp.c
# → Shows violations if any

# Fix violations, then verify all Mac code
/check-isr
# → Checks all src/mactcp/, src/opentransport/, src/appletalk/

During Development

bash

# Write code with callbacks...
# Edit tool auto-runs isr-safety-check.sh hook
# → Hook BLOCKS edit if violation detected

# Fix the violation
# Re-attempt edit
# → Hook allows edit through ✓

Pre-Commit Check

bash

/check-isr
# → Verify all Mac code is ISR-safe before committing

Debugging a Violation

When a hook blocks an edit with an ISR violation:

•Understand why: Check .claude/rules/isr-safety.md for the forbidden function
•Find all instances: /check-isr src/mactcp/ shows violations with line numbers
•Fix using safe pattern: Replace with ISR-safe alternative (see Common Fixes table)
•Verify fix: /check-isr should report no violations

Example: TickCount() → Set flag in callback, timestamp in main loop

Reference

See CLAUDE.md sections:

•"MacTCP ASR Rules"
•"Open Transport Notifier Rules"
•"AppleTalk ADSP Callback Rules"

Source: Inside Macintosh Volume VI, Table B-3 - "Routines That May Be Called at Interrupt Time"