> ## 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 Use Cases

> GLink channel setup, data transfer, transport negotiation, and restart flows.

## Open a channel

A client supplies an open configuration containing the optional transport name, the remote edge, the channel name, and callback functions. The core copies the configuration and uses the callbacks to report channel state, received data, transmit completion, receive-intent requests, signal changes, and aborts.

To open a channel:

1. Prepare a configuration with the transport name, remote edge, channel name, and callback functions.
2. Call the open function with the configuration.
3. Wait for the connected notification before sending data.

Treat the returned handle as pending until a connected notification is received. Invalid configuration returns an error, no available transport returns an error, and the channel cannot be reopened yet returns an error.

## Transmit and receive data

The receiver should queue intents before the sender transmits. A sender can call a transmit function for a contiguous buffer or a vector-backed buffer such as an SKB or DSM chain.

To send and receive data:

1. **Receiver**: Queue receive intents with the maximum packet size it can accept.
2. **Sender**: Call transmit with the data and size.
3. **Receiver**: Receive the data and process it.
4. **Receiver**: Signal completion when done with the buffer.
5. **Sender**: Receive notification that the buffer was processed.

If no suitable intent exists, the sender can request an intent from the peer. The request can be denied, in which case the transmit operation returns an error.

## Control signals

A client can exchange a 32-bit control signal field with the peer:

* Set the local signal value.
* Read the cached local value.
* Read the cached remote value.
* Receive notification when the remote signal changes.

The upper bits can carry standard modem-control meanings when a client wants them, but the field remains transport-visible pass-through data.

## Close a channel

Call close when no more data should be exchanged. A local close reports local disconnection; a peer-initiated close reports remote disconnection. The close path must drain or abort pending work before callback-owned resources are destroyed.

## Transport registration

A transport registers an interface and configuration with the core. The configuration supplies its name, edge, supported versions, maximum channel IDs, and maximum intent IDs. The transport moves through these states:

* Down (initial state)
* Negotiating (version negotiation in progress)
* Opened (ready for channels)
* Failed (negotiation failed)

Unregistering a transport returns it to the down state, resets negotiation state and channel identifiers, and removes its channel list.

## User-space channel access

A user-space driver can expose a configured GLink channel as a character device. The file operations map to the client API:

* Open → Open a channel
* Write → Send data
* Read → Receive data and complete it
* Release → Close the channel
* ioctl → Queue a receive intent
* poll → Wait for channel availability
* mmap → Avoid an extra kernel/user buffer copy

A typical user-space flow opens the device, queues an intent, writes a packet, reads the received data, and closes the file descriptor.

## Packet scheduling and migration

GLink schedules packets round-robin across active channels. A transport can fragment large packets to preserve fairness and reduce latency for other channels. When multiple transports are available on an edge, the core can migrate or select a channel transport according to configured priority and client selection information.

## Subsystem restart

Subsystem restart handling must clean up channel state and recover buffer ownership before restart completes. A restart notification system can use the application processor as a coordinator: it identifies affected edges, sends notifications over GLink, waits for each subsystem to clean up, and then allows the restart sequence to continue.