Home /Modules/telephony-skya/DRIVER.LOAD.METHOD.md

DRIVER.LOAD.METHOD.md

telephony-skya/drivers/DRIVER.LOAD.METHOD.md · 296 line(s) · markdown

Skya™ Driver Load Method

Purpose

This document defines how Skya™ Telephony Drivers are loaded on Linux, Windows 10+, and macOS.

The load method is distinct from DRIVER.SCHEDULE.md: the schedule defines implementation/testing stages; this document defines how a completed driver becomes available to the Skya runtime.

Architecture:

Skya GUI / SLeeLa / Guia™
        -> Driver Registry
        -> Discovery / Identity / Capability Check
        -> Platform Driver Layer
        -> Runtime Device

A catalog entry alone MUST NOT cause a driver to be considered loaded. Loading requires a compatible implementation, successful registration, and positive device/endpoint matching.

1. Common Load Contract

Every platform follows:

  1. Locate the built-in or explicitly installed driver.
  2. Validate platform, architecture, ABI/version, and dependencies.
  3. Register the driver with the Skya registry.
  4. Probe connected hardware or network endpoints.
  5. Match vendor, model, transport, firmware family, and capabilities.
  6. Activate the runtime device instance.
  7. Verify audio, HID/call-control, or SIP/network capability.
  8. Publish the device to Skya/SLeeLa.
  9. Monitor removal, reconnect, and failure.

Recommended states:

DISCOVERED -> VALIDATING -> REGISTERING -> PROBING -> MATCHED -> ACTIVATING -> READY

Failure/removal states: FAILED, REMOVED, RECONNECTING.

2. Linux Load Method

Preferred platform path

Use existing Linux interfaces before custom kernel code:

  1. USB/Bluetooth discovery.
  2. ALSA device discovery/capability inspection.
  3. PipeWire/PulseAudio application routing where present.
  4. HID discovery for call-control peripherals.
  5. SIP/network discovery for VoIP desk phones.
  6. Vendor-specific controls only where standard interfaces are insufficient.
  7. Hotplug and reconnect monitoring.

Skya should normally remain a user-space application. A custom kernel module is not required merely because a device appears in the catalog.

Built-in load

libskya-drivers.a
  -> skya_driver_registry
  -> vendor probe
  -> ALSA / HID / network discovery
  -> skya_driver_device

Startup sequence:

  1. Initialize registry.
  2. Register built-in vendor adapters.
  3. Enumerate devices/endpoints.
  4. Probe candidates.
  5. Select only a matching driver.
  6. Create runtime device.
  7. Publish capabilities.

External modules

Future separately installed Linux modules MUST validate architecture, ABI, dependencies, permissions, package/integrity policy, and controlled search path. A filename or catalog name is never sufficient for loading.

Removal/reload

On removal, stop I/O, release ALSA/HID/network handles, mark the device REMOVED, retain the logical driver registration, wait for re-enumeration, and probe again.

3. Windows 10+ Load Method

Preferred platform path

Use Windows user-mode APIs and Microsoft class drivers whenever they provide the required capability:

  1. Plug-and-Play enumeration.
  2. Audio endpoint discovery.
  3. WASAPI endpoint activation.
  4. USB Audio class support.
  5. HID discovery/control.
  6. Vendor SDK/control interface only when necessary.
  7. Device notification and re-enumeration.

Custom kernel-mode drivers should be reserved for capabilities that cannot be provided through supported user-mode/class-driver interfaces.

Load sequence

PnP enumeration
  -> USB / Audio / HID identity
  -> Skya vendor/model probe
  -> WASAPI + HID capability check
  -> registry activation
  -> Skya runtime device

Validate Windows version, architecture, device instance identity, USB VID/PID where applicable, audio endpoint identity, HID collections, driver ABI/version, and dependencies.

A vendor's Windows driver package is not itself the Skya logical driver. The boundary remains:

Windows class/vendor driver
  -> Skya vendor adapter
  -> Skya Driver API
  -> SLeeLa / Guia™

Removal/reload

On device invalidation, stop I/O, release WASAPI/HID resources, mark REMOVED, wait for re-enumeration, re-probe, and recreate the runtime device.

4. macOS Load Method

Preferred platform path

Use Apple-supported user-space facilities first:

  1. Core Audio discovery.
  2. Audio endpoint/stream inspection.
  3. USB/HID discovery where required.
  4. Vendor control interfaces where required.
  5. DriverKit/AudioDriverKit only where genuinely necessary.
  6. Device arrival/removal monitoring.

Load sequence

Core Audio / device discovery
  -> USB / HID identity
  -> Skya vendor/model probe
  -> capability validation
  -> registry activation
  -> Skya runtime device

Validate macOS version, Intel/Apple Silicon architecture, device identity, Core Audio endpoint identity, USB/HID identity where applicable, ABI/version, permissions, and any required DriverKit component.

DriverKit/AudioDriverKit is a separate system-driver boundary. It must not be introduced simply because a device has a vendor-specific feature. Where required, the component must be separately packaged, signed, installed, approved, and removable under macOS security rules.

Removal/reload

Stop I/O, release Core Audio/HID resources, mark REMOVED, retain logical registration, wait for arrival, re-probe, recreate the runtime device, and report restored/unavailable capabilities.

5. Vendor Loading Rule

The brand/version catalog is a discovery target, not blanket authorization to load code.

Catalog Entry
  -> Physical / Network Identity
  -> Transport Match
  -> Capability Match
  -> OS Compatibility
  -> Driver Load

Record vendor, model, family, hardware revision, firmware, transport, OS, architecture, driver version, capabilities, limitations, load result, and failure diagnostics.

6. Built-in vs External Drivers

Built-in

Built-in drivers are compiled into the Skya driver library and registered at application startup. This provides deterministic ABI/versioning and reproducible deployment.

Current foundation:

External

External drivers may be added for hardware requiring separate packaging. They MUST use explicit installation and controlled loading with ABI, platform, architecture, dependency, and integrity/signature validation as applicable.

Never load an arbitrary driver from the current working directory by default.

7. Security

Skya MUST:

Firmware updates are separate operations requiring explicit authorization.

8. Diagnostics

Each load attempt should record:

timestamp
os
architecture
vendor
model
hardware_revision
firmware
transport
device_id
driver_name
driver_version
registry_state
probe_result
capabilities
error_code
error_message

Example:

SKYA DRIVER LOAD
vendor=Yealink
model=MP45
transport=USB_AUDIO
os=linux
state=PROBING
audio_input=yes
audio_output=yes
hid=no
result=READY

9. Relationship to DRIVER.SCHEDULE.md

DRIVER.SCHEDULE.md
  -> implementation + test
  -> build / install / register
  -> DRIVER.LOAD.METHOD.md
  -> probe / activate / monitor

A scheduled driver is not automatically loaded. A loaded driver is not automatically certified. Certification follows the applicable test matrix and platform requirements.

10. Platform Completion Criteria

Linux

Windows 10+

macOS

11. Normative Principle

Skya loads a logical telephony driver only after the operating system exposes a compatible device or endpoint and the driver registry positively matches its identity and capabilities.

The catalog identifies intended support. The operating system supplies the device interface. The adapter connects those layers. SLeeLa and Guia™ remain authoritative for application behavior, commands, events, sessions, and GUI semantics.