1. OVERVIEW

This document defines runtime rules, execution guarantees, lifecycle behavior, and system-level constraints for SDI drivers.

It standardizes how drivers execute once loaded, including calling conventions, stack usage, concurrency assumptions, memory ownership, and failure behavior.

This document does not define new interfaces. It defines rules governing existing SDI components.

BCP 14 (RFC 2119 and RFC 8174) applies.

2. EXECUTION MODEL

2.1 Calling Convention

All SDI driver functions and kernel-provided function pointers in sdi_ops MUST use the spec mandated platform ABI.

• Arguments MUST be passed according to the ABI.
• Return values MUST follow ABI rules for scalar and pointer types.
• No custom calling conventions are permitted.

2.2 Permitted architecture specific ABIs

Not all architectures are listed. The below table defines what ABI MUST be used on each architecture listed (if the architecture is not listed, MUST be considered undefined for a future SDI specification to define.)

2.2.1 On Architectures without a defined standard
For architectures that do not have a defined ABI, anyone can send the BDIO group a draft of an ABI. The proposed ABI MUST be implemented in at least one reference toolchain that can compile C compatible with a C99 freestanding environment. The proposal MUST come with a valid compiled (ELF) version of the example driver from the reference drivers.

Said drafts MUST also provide a new arch/{architecture} for rKern which supports the architecture and is in compliance with the ABI draft.

2.3 Stack Ownership

• The kernel owns and manages the execution stack at all times.
• The kernel MUST provide a valid, aligned stack before invoking any driver function.
• Drivers MUST NOT modify, replace, or assume control of the stack pointer outside normal function execution.
• Stack switching by drivers is prohibited.

2.4 Execution Context

• Drivers execute in kernel context.
• No user-mode transitions are defined by SDI.
• No TLS (thread-local storage) is provided.
• Drivers MUST NOT assume the existence of per-thread or per-CPU storage unless explicitly provided via sdi_ops.

3. CONCURRENCY MODEL

3.1 Driver State Safety

• Drivers that maintain internal state MUST implement their own synchronization if concurrency is possible.
• SDI does not provide built-in locking primitives.
• Any required synchronization MUST be implemented using kernel-provided facilities (if available via sdi_ops) or internal mechanisms.

4. DRIVER LIFECYCLE

4.1 Lifecycle States

A driver exists in the following conceptual states:

• LOADED
• MAPPED
• RELOCATED
• INITIALIZED
• ACTIVE
• ERROR (optional terminal state)
• UNLOADED (optional terminal state)

4.2 Initialization Behavior

• The driver entry point MUST return an sdi_status.
• SDI_OK indicates successful initialization.
• Any non-SDI_OK value indicates failure.

If initialization fails:

• The driver MUST NOT be used for any further calls.
• The kernel MUST treat the driver as inactive.
• The kernel MAY unload the driver or retain it in a disabled state.

4.3 Reinitialization

• Drivers MUST NOT be initialized more than once without a full unload and reload cycle.
• Behavior of reinitialization without unload is undefined.

5. MEMORY MODEL

5.1 Ownership Rules

• Memory allocated via sdi_ops.alloc is owned by the driver.
• Memory MUST be released using sdi_ops.free.
• Drivers MUST NOT free memory not allocated via alloc.

5.2 Mapping Rules

• Memory returned by sdi_ops.memmap MUST remain valid until unmap is called.
• Drivers MUST NOT access unmapped memory regions.
• Behavior of accessing unmapped memory is undefined.

5.3 Kernel Memory Safety

• Drivers MUST NOT assume kernel memory layout or direct kernel structure access beyond sdi_ops.

5.4 Memory allocated via kernel functions

Any function that returns a pointer within sdi_ops the pointer MAY be freed by the driver at any time.

5.4.1 Memory from kernel_ver

The pointer from kernel_ver MAY NOT be freed.

6. ERROR HANDLING

6.1 Function Failure

• All SDI functions that return status MUST use sdi_status.
• Drivers MUST check and handle failure cases.
• Ignoring failure results in undefined behavior.

6.2 Fault Handling

• The kernel MAY terminate a driver on illegal behavior.
• SDI does not define recovery from driver faults.
• Drivers MUST NOT assume recovery or retry semantics after faults unless explicitly defined by subsystem specs.

7. INTERRUPT CONTEXT

• Driver functions MAY be called from interrupt context if exposed by the kernel.
• In interrupt context:
  • blocking is prohibited
  • memory allocation MAY be restricted depending on kernel implementation
• Drivers SHOULD avoid long-running operations in interrupt context unless explicitly designed for it.

8. PORTABILITY RULES

• Drivers MUST NOT depend on architecture-specific behavior unless explicitly stated in SDI extensions.
• Any architecture-specific behavior MUST be isolated behind sdi_ops or class-defined interfaces.
• Drivers SHOULD NOT call assembly or other architecture-specific code unless absolutely needed for driver functionality.