> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GLink Debugging

> Diagnose GLink transport state, channel state, intents, logs, and subsystem restart failures.

GLink failures usually fall into one of four areas: the transport never becomes available, version negotiation fails, the channel never reaches connected state, or data ownership is not returned after a transfer or restart.

## Check the transport state first

The transport must progress from down through negotiation to opened before channels can communicate. A failed or permanently down transport points to the transport plug-in, its physical link, or its dependency initialization rather than to the client channel.

The transport plug-in is responsible for:

* Reading from and writing to the physical transport
* Reporting available read data and write space
* Translating core commands and payloads
* Closing the transport cleanly

The shared-memory native transport additionally depends on shared memory and interrupts in both directions. Other plug-ins have their own transport-specific dependencies.

## Check channel state and callbacks

A channel is not ready merely because the open call returned a handle. Confirm that:

1. The requested edge, transport, and channel name match the remote endpoint.
2. A connected notification is received.
3. The receiver queues an intent large enough for the expected packet.
4. A receive notification is invoked.
5. The receiver calls the completion function.
6. The sender receives a transmit-done notification.

A missing transmit-done notification often means that the remote side has not consumed the receive buffer, while a missing receive notification usually means that no matching intent was available or the packet was rejected before delivery.

## Enable logging

The GLink core and loopback server expose logging control. The supported logging modes are:

* **Informational** – Default informational messages
* **Debug** – Verbose protocol and state debugging
* **Performance** – Performance-only logging

The modes can be combined. Performance mode suppresses other logging and keeps only messages emitted through performance logging macros.

## Diagnose negotiation failures

Both endpoints independently start version negotiation. This is not a race: the transport is not opened until both sequences complete, and both sides converge on a compatible version and feature set.

Check for:

* No version acknowledgement
* A selected version of zero (no compatible version found)
* Features that are not accepted by the peer
* Negotiation beginning before the transport can reliably exchange commands
* A transport configuration that advertises incorrect supported versions

A version mismatch should select the lower mutually supported version. An optional feature should be enabled only when both sides advertise it.

## Diagnose buffer ownership

Track the private token passed at each stage:

1. Queue a receive intent.
2. Receive notification with the data.
3. Call the completion function.
4. Receive transmit-done notification.

If a channel closes while packets or intents are pending, the client must handle abort callbacks for both receive-intent and transmit-packet private data. Releasing callback-owned memory before the abort notification can cause use-after-free or permanently leaked buffer ownership.

## Subsystem restart symptoms

A restart can affect every channel connected to an edge. Confirm that the restart path:

* Identifies the affected subsystem and its GLink edge
* Notifies dependent endpoints
* Closes or aborts affected channels
* Returns receive-intent and transmit private data
* Waits for cleanup before restart completion
* Reopens channels after the remote endpoint is available again

Do not treat a transport reconnect as proof that all channels recovered; channel state and buffer ownership must be checked separately.