Linux LITE QMUX  MBPL_SDK_R25_ENG3
Data Structures | Files | Macros | Typedefs | Enumerations | Functions
QMUX layer (lite-qmux)

Data Structures

struct  QmiService
 
struct  CtlService
 
struct  QmiTransaction
 
struct  QMUX_TRANSPORT_ERR_INFO
 
struct  QmuxTransport
 
struct  QmiSyncObject
 

Files

file  QmiService.h
 
file  CtlService.h
 
file  QmiTransaction.h
 
file  QmuxTransport.h
 
file  QmiSyncObject.h
 

Macros

#define MAX_QMI_PACKET_SIZE   (2048 - 6)
 

Typedefs

typedef void(* QMI_INDICATION_CALLBACK) (uint8_t *qmiPacket, uint16_t qmiPacketSize, void *pIndicationCallbackContext)
 
typedef struct QmiService QmiService
 
typedef struct CtlService CtlService
 
typedef void(* QMI_RESPONSE_CALLBACK) (uint8_t *qmiPacket, uint16_t qmiPacketSize, void *pResponseCallbackContext)
 
typedef struct QmiTransaction QmiTransaction
 
typedef void(* QMUX_TRANSPORT_ERR_CALLBACK) (void *pErrCallbackContext, QMUX_TRANSPORT_ERR_INFO err_info)
 
typedef struct QmuxTransport QmuxTransport
 
typedef struct QmiSyncObject QmiSyncObject
 

Enumerations

enum  QMUX_TRANSPORT_ERR_TYPE { QMUX_TRANSPORT_ERR_UNKNOWN, QMUX_TRANSPORT_ERR_READ, QMUX_TRANSPORT_ERR_WRITE }
 

Functions

void QmiService_Initialize (QmiService *pThis, uint8_t serviceType, uint8_t clientId, struct QmuxTransport *pTransport, QMI_INDICATION_CALLBACK pIndicationCallback, void *pIndicationCallbackContext)
 
void QmiService_ShutDown (QmiService *pThis)
 
uint16_t QmiService_GetNextTransactionId (QmiService *pThis)
 
int QmiService_SendRequest (QmiService *pThis, uint16_t transactionId, uint8_t *qmiRequest, uint16_t qmiRequestSize, QMI_RESPONSE_CALLBACK pResponseCallback, void *pResponseCallbackContext)
 
void QmiService_CancelTransaction (QmiService *pThis, uint16_t transactionId)
 
bool QmiService_HandleQmiPacket (QmiService *pThis, uint8_t serviceType, uint8_t clientId, uint8_t *qmiPacket, uint16_t qmiPacketSize)
 
int CtlService_Initialize_Ex (CtlService *pThis, struct QmuxTransport *pTransport, uint8_t nWaitDelay)
 
int CtlService_Initialize (CtlService *pThis, struct QmuxTransport *pTransport)
 
void CtlService_ShutDown (CtlService *pThis)
 
int CtlService_GetClientId (CtlService *pThis, uint8_t serviceType, uint8_t *clientId)
 
int CtlService_ReleaseClientId (CtlService *pThis, uint8_t serviceType, uint8_t clientId)
 
int CtlService_InitializeRegularService (CtlService *pThis, QmiService *pRegularService, uint8_t serviceType, QMI_INDICATION_CALLBACK pIndicationCallback, void *pIndicationCallbackContext)
 
int CtlService_ShutDownRegularService (CtlService *pThis, QmiService *pRegularService)
 
void QmiTransaction_Initialize (QmiTransaction *pThis, uint16_t transactionId, uint16_t messageId, QMI_RESPONSE_CALLBACK pResponseCallback, void *pResponseCallbackContext)
 
int QmuxTransport_Initialize (QmuxTransport *pThis, char *devicePath, bool useMbim, void *pInterfaceSpecific)
 
int QmuxTransport_InitializeEx (QmuxTransport *pThis, char *destination, int interfaceType, void *pInterfaceSpecific)
 
void QmuxTransport_ShutDown (QmuxTransport *pThis)
 
void QmuxTransport_AttachQmiService (QmuxTransport *pThis, struct QmiService *pQmiService)
 
void QmuxTransport_DetachQmiService (QmuxTransport *pThis, struct QmiService *pQmiService)
 
int QmuxTransport_SendQmiPacket (QmuxTransport *pThis, uint8_t qmiServiceType, uint8_t qmiClientId, uint16_t qmiTransactionId, uint8_t *qmiPacket, uint16_t qmiPacketSize)
 
void QmuxTransport_RegisterErrCallback (QmuxTransport *pThis, QMUX_TRANSPORT_ERR_CALLBACK pErrCallback, void *pErrCallbackContext)
 
int QmiSyncObject_Initialize (QmiSyncObject *pThis)
 
int QmiSyncObject_Destroy (QmiSyncObject *pThis)
 
int QmiSyncObject_Lock (QmiSyncObject *pThis)
 
int QmiSyncObject_Unlock (QmiSyncObject *pThis)
 
int QmiSyncObject_Wait (QmiSyncObject *pThis)
 
int QmiSyncObject_TimedWait (QmiSyncObject *pThis, time_t timeoutSeconds)
 
int QmiSyncObject_Signal (QmiSyncObject *pThis)
 
void QmiSyncObject_ResponseCallback (uint8_t *qmiPacket, uint16_t qmiPacketSize, void *pResponseCallbackContext)
 

Detailed Description

Macro Definition Documentation

◆ MAX_QMI_PACKET_SIZE

#define MAX_QMI_PACKET_SIZE   (2048 - 6)

Maximum size in bytes of a QMI packet. This does not include QMUX header. It becomes the maximum SDU of a QMUX packet, MAX_QMUX_PACKET_SIZE - sizeof(QMUX_HDR)

Typedef Documentation

◆ QMI_INDICATION_CALLBACK

typedef void(* QMI_INDICATION_CALLBACK) (uint8_t *qmiPacket, uint16_t qmiPacketSize, void *pIndicationCallbackContext)

This funcion prototype represents the callback which is called by the QMI service when a QMI indication is received.

Parameters
[in]qmiPacketindication's QMI packet (note: this does not include QMUX header).
[in]qmiPacketSizeNumber of bytes in indication's QMI packet.
[in]pIndicationCallbackContextUser context supplied when QMI service was initialized.

◆ QmiService

typedef struct QmiService QmiService

This structure abstracts a QMI service. It is responsible issuing transaction IDs. It tracks QMI requests and responses using transaction objects from a pool. It invokes a user callback when QMI indications which match its client ID (or a broadcast ID) are received from the transport layer.

Parameters
pNext
  • A link so we can store this object in a linked list by the transport layer.
serviceType
  • QMI service type, CTL, NAS, etc.
clientId
  • QMI client ID
pTransport
  • Pointer to underlying QMUX transport object.
transactionId
  • QMI transaction ID. Upper limit 0xffff for regular QMI services, 0xff for CTL service.
transactionIdLock
  • Mutex to make transactionId access thread-safe.
transactionPool
  • Pool of transaction objects which may be assigned to QMI requests made by clients of this service.
transactionPoolLock
  • Mutex to make transactionPool access thread-safe
pIndicationCallback
  • User callback for QMI indications of this service.
pIndicationCallbackContext
  • User context for user callback.

◆ CtlService

typedef struct CtlService CtlService

This structure abstracts a CTL QMI service. It wraps a QMI service which is initialized to type CTL. Synchronous methods are provided for getting and releasing client IDs on behalf of other (regular) QMI services.

Parameters
service
  • QMI service object, initialized to be of type CTL.

◆ QMI_RESPONSE_CALLBACK

typedef void(* QMI_RESPONSE_CALLBACK) (uint8_t *qmiPacket, uint16_t qmiPacketSize, void *pResponseCallbackContext)

This funcion prototype represents the callback which is called by the QMI service when a QMI response is received.

Parameters
[in]qmiPacketResponse's QMI packet (note: this does not include QMUX header).
[in]qmiPacketSizeNumber of bytes in response's QMI packet.
[in]pResponseCallbackContextUser context supplied when QMI transaction was initialized.

◆ QmiTransaction

This structure abstracts a QMI transaction. It is responsible for tracking a QMI request to its response.

Parameters
inUse
  • true indicates that this object has been allocated by the QMI service and is un use.
transactionId
  • QMI transaction ID. Upper limit 0xffff for regular QMI services, 0xff for CTL service.
messageId
  • QMI message ID.
pResponseCallback
  • User callback for QMI response.
pResponseCallbackContext
  • User context for user callback.

◆ QMUX_TRANSPORT_ERR_CALLBACK

typedef void(* QMUX_TRANSPORT_ERR_CALLBACK) (void *pErrCallbackContext, QMUX_TRANSPORT_ERR_INFO err_info)

QMUX transport error callback function.

Parameters
[in]pErrCallbackContextUser context of the callback function
[in]err_infoA QMUX_TRANSPORT_ERR_INFO structure which contains the detailed error info.
Returns
None

◆ QmuxTransport

typedef struct QmuxTransport QmuxTransport

This structure abstracts a QMUX transport layer. It is responsible for applying QMUX headers to QMI packets from QMI services and forwarding them to the device. It is responsible for receiving QMUX packets from the device. On the basis of QMUX headers, it distributes the SDUs (QMI packets) to the appropriate QMI service. It maintains a list of connected QMI service objects.

Parameters
interfaceType
  • Using direct, MBIM, or router for data layer.
pDataLayer
  • Pointer to instantiated data layer.
deviceFd
  • File descriptor of device.
shutdownFd
  • Event descriptor. Used to signal read thread to terminate.
devRemoved
  • Flag indicating device has been removed or not.
qmiServiceList
  • List of connected QMI service objects.
writeLock
  • Provides mutual exclusion for write operations.
qmiServiceListLock
  • Provides thread safety for the service list.
readThread
  • Thread responsible for reading from device.
pErrCallback
  • Callback function for transport error events.
pErrCallbackContext
  • User context for MbimTransport error callback

◆ QmiSyncObject

typedef struct QmiSyncObject QmiSyncObject

This structure is a wrapper around a mutex and condition object and a buffer. It is a convenience object which may be used to create synchronous QMI APIs.

Parameters
mutex
  • For thread safety.
condition
  • Triggered on completion.
buffer
  • QMI request packet is written to this buffer. On request completion, contains the QMI response packet.
bufferSize
  • Set to size in bytes of QMI request packet. On request completion, set to size of QMI response packet.
Note
The buffer is intended for QMI packet only i.e. QMI header and QMI payload. This buffer becomes the SDU of a QMUX packet.

Enumeration Type Documentation

◆ QMUX_TRANSPORT_ERR_TYPE

QMUX transport error type definitions

Function Documentation

◆ QmiService_Initialize()

void QmiService_Initialize ( QmiService pThis,
uint8_t  serviceType,
uint8_t  clientId,
struct QmuxTransport pTransport,
QMI_INDICATION_CALLBACK  pIndicationCallback,
void *  pIndicationCallbackContext 
)

Initialize QMI service.

Parameters
[in]pThisThe primary object of this call.
[in]serviceTypeQMI service e.g. NAS, etc.
[in]clientIdValue previously obtained by invoking CtlService_GetClientId
[in]pTransportPointer to underlying transport layer which is responsible for sending and receiving QMUX packets
[in]pIndicationCallbackUser function to be be called when QMI indications are received.
[in]pIndicationCallbackContextA user context for callback.

◆ QmiService_ShutDown()

void QmiService_ShutDown ( QmiService pThis)

Shut down QMI service. Brings service to an uninitiaized state.

Parameters
[in]pThisThe primary object of this call.

◆ QmiService_GetNextTransactionId()

uint16_t QmiService_GetNextTransactionId ( QmiService pThis)

Returns next transaction ID for a QMI service.

Parameters
[in]pThisThe primary object of this call.
Returns
transaction ID

◆ QmiService_SendRequest()

int QmiService_SendRequest ( QmiService pThis,
uint16_t  transactionId,
uint8_t *  qmiRequest,
uint16_t  qmiRequestSize,
QMI_RESPONSE_CALLBACK  pResponseCallback,
void *  pResponseCallbackContext 
)

Send a QMI request to the device and return immediately.

Parameters
[in]pThisThe primary object of this call.
[in]transactionIdtransaction ID obtained by previous call to QmiService_GetNextTransactionId.
[in]qmiRequestQMI request (this becomes the QMUX SDU).
[in]qmiRequestSizeSize in bytes of QMI request.
[in]pResponseCallbackCallback called when QMI request completes.
[in]pResponseCallbackContextContext for callback.
Returns
0 on success, < 0 on failure.

◆ QmiService_CancelTransaction()

void QmiService_CancelTransaction ( QmiService pThis,
uint16_t  transactionId 
)

Cancel an outstanding QMI request.

Parameters
[in]pThisThe primary object of this call.
[in]transactionIdTransaction ID of outstanding request.

◆ QmiService_HandleQmiPacket()

bool QmiService_HandleQmiPacket ( QmiService pThis,
uint8_t  serviceType,
uint8_t  clientId,
uint8_t *  qmiPacket,
uint16_t  qmiPacketSize 
)

Process a received QMI packet. This function is called by the QMUX transport layer.

Parameters
[in]pThisThe primary object of this call.
[in]serviceTypeQMI service type of received packet.
[in]clientIdQMI Client ID of received packet.
[in]qmiPacketPointer to QMI packet.
[in]qmiPacketSizePointer to size in bytes of QMI packet.
Returns
true if packet is consumed by function, false if it should be offered to another QMI service

◆ CtlService_Initialize_Ex()

int CtlService_Initialize_Ex ( CtlService pThis,
struct QmuxTransport pTransport,
uint8_t  nWaitDelay 
)

Initialize CTL service.

Parameters
[in]pThisThe primary object of this call.
[in]pTransportPointer to underlying transport layer which is responsible for sending and receiving QMUX packets
[in]nWaitDelayNumber of seconds to delay after a CTL_SYNC_REQ/RESP exchange. Zero means no delay.
Returns
0 on success, ETIMEDOUT, or < 0 on failure.

◆ CtlService_Initialize()

int CtlService_Initialize ( CtlService pThis,
struct QmuxTransport pTransport 
)

Initialize CTL service.

Parameters
[in]pThisThe primary object of this call.
[in]pTransportPointer to underlying transport layer which is responsible for sending and receiving QMUX packets
Returns
0 on success, ETIMEDOUT, or < 0 on failure.

◆ CtlService_ShutDown()

void CtlService_ShutDown ( CtlService pThis)

Shut down CTL service.

Parameters
[in]pThisThe primary object of this call.

◆ CtlService_GetClientId()

int CtlService_GetClientId ( CtlService pThis,
uint8_t  serviceType,
uint8_t *  clientId 
)

Get a client ID for a given QMI service type.

Parameters
[in]pThisThe primary object of this call.
[in]serviceTypeQMI service type.
[out]clientIdReturned client ID.
Returns
0 on success, ETIMEDOUT, or < 0 on failure.

◆ CtlService_ReleaseClientId()

int CtlService_ReleaseClientId ( CtlService pThis,
uint8_t  serviceType,
uint8_t  clientId 
)

Release a client ID for a given QMI service type. Client ID will have beeb previously obtained by invoking CtlService_GetClientId.

Parameters
[in]pThisThe primary object of this call.
[in]serviceTypeQMI service type.
[in]clientIdClient ID to be released.
Returns
0 on success, ETIMEDOUT, or < 0 on failure.

◆ CtlService_InitializeRegularService()

int CtlService_InitializeRegularService ( CtlService pThis,
QmiService pRegularService,
uint8_t  serviceType,
QMI_INDICATION_CALLBACK  pIndicationCallback,
void *  pIndicationCallbackContext 
)

Convenience function to initialize a QMI service object. Under the hood, it gets a client ID for a given QMI service type.

Parameters
[in]pThisThe primary object of this call.
[in]pRegularServiceUninitialized QMI service object.
[in]serviceTypeQMI service type.
[in]pIndicationCallbackUser function to be be called when QMI indications are received by the service.
[in]pIndicationCallbackContextA user context for callback.
Returns
0 on success, ETIMEDOUT, or < 0 on failure.

◆ CtlService_ShutDownRegularService()

int CtlService_ShutDownRegularService ( CtlService pThis,
QmiService pRegularService 
)

Convenience function to shut down a QMI service object. Under the hood, it releases a client ID for a given QMI service type.

Parameters
[in]pThisThe primary object of this call.
[in]pRegularServicePreviously initialized QMI service object.
Returns
0 on success, < 0 on failure.

◆ QmiTransaction_Initialize()

void QmiTransaction_Initialize ( QmiTransaction pThis,
uint16_t  transactionId,
uint16_t  messageId,
QMI_RESPONSE_CALLBACK  pResponseCallback,
void *  pResponseCallbackContext 
)

Initialize QMI transaction.

Parameters
[in]pThisThe primary object of this call.
[in]transactionIdTransaction ID obtained from a call to QmiService_GetNextTransactionId.
[in]messageIdQMI message ID.
[in]pResponseCallbackUser function to be be called when QMI response is received.
[in]pResponseCallbackContextA user context for callback.

◆ QmuxTransport_Initialize()

int QmuxTransport_Initialize ( QmuxTransport pThis,
char *  devicePath,
bool  useMbim,
void *  pInterfaceSpecific 
)

Initialize the transport layer.

Parameters
[in]pThisThe primary object of this call.
[in]devicePathAbsolute path to device.
[in]useMbimUse MBIM interface as opposed to direct interface for data layer.
[in]pInterfaceSpecificA pointer to an object (may be NULL) related to the specific interface used. Currently ignored for useMbim = false. If useMbim = true, it may point to an already initialized MbimTransport object, in which case, this object will use that object rather than try to create its own MbimTransport object.
Returns
0 on success, < 0 on failure.

◆ QmuxTransport_InitializeEx()

int QmuxTransport_InitializeEx ( QmuxTransport pThis,
char *  destination,
int  interfaceType,
void *  pInterfaceSpecific 
)

Initialize the transport layer.

Parameters
[in]pThisThe primary object of this call.
[in]destinationFor direct or MBIM, it is absolute path to device. For router, it is the IP address of router or NULL for localhost
[in]interfaceTypeUse direct, MBIM, or router interface for data layer. for direct, use QMUX_INTERFACE_DIRECT for MBIM, use QMUX_INTERFACE_MBIM for router, use QMUX_INTERFACE_ROUTER
[in]pInterfaceSpecificA pointer to an object (may be NULL) related to the specific interface used. Currently ignored for useMbim = false. If useMbim = true, it may point to an already initialized MbimTransport object, in which case, this object will use that object rather than try to create its own MbimTransport object.
Returns
0 on success, < 0 on failure.

◆ QmuxTransport_ShutDown()

void QmuxTransport_ShutDown ( QmuxTransport pThis)

Shut down the transport layer.

Parameters
[in]pThisThe primary object of this call.

◆ QmuxTransport_AttachQmiService()

void QmuxTransport_AttachQmiService ( QmuxTransport pThis,
struct QmiService pQmiService 
)

Attaches a QMI service to the transport layer.

Parameters
[in]pThisThe primary object of this call.
[in]pQmiServiceThe QMI service to be attached.

◆ QmuxTransport_DetachQmiService()

void QmuxTransport_DetachQmiService ( QmuxTransport pThis,
struct QmiService pQmiService 
)

Detaches a QMI service from the transport layer.

Parameters
[in]pThisThe primary object of this call.
[in]pQmiServiceThe QMI service to be detached.

◆ QmuxTransport_SendQmiPacket()

int QmuxTransport_SendQmiPacket ( QmuxTransport pThis,
uint8_t  qmiServiceType,
uint8_t  qmiClientId,
uint16_t  qmiTransactionId,
uint8_t *  qmiPacket,
uint16_t  qmiPacketSize 
)

Send a QMI request to the device and return immediately.

Parameters
[in]pThisThe primary object of this call.
[in]qmiServiceTypeQMI service type.
[in]qmiClientIdQMI client ID.
[in]qmiTransactionIdQMI transaction ID. Can be used for tracking purposes.
[in]qmiPacketPointer to QMI request.
[in]qmiPacketSizeSize in bytes of QMI packet.
Returns
0 on success, < 0 on failure.

◆ QmuxTransport_RegisterErrCallback()

void QmuxTransport_RegisterErrCallback ( QmuxTransport pThis,
QMUX_TRANSPORT_ERR_CALLBACK  pErrCallback,
void *  pErrCallbackContext 
)

This function is for client applications to register for transport error info callbacks. The most recent callback registration is the only function that is invoked when device is removed.

Parameters
[in]pThisThe primary object of this call.
[in]pErrCallbackA valid function pointer to be notified when device is removed. NULL to disable callback notifications.
[in]pErrCallbackContextUser context when transport error callback is called
Returns
None

◆ QmiSyncObject_Initialize()

int QmiSyncObject_Initialize ( QmiSyncObject pThis)

Initialize sync object.

Parameters
[in]pThisThe primary object of this call.
Returns
0 on success, < 0 on failure.

◆ QmiSyncObject_Destroy()

int QmiSyncObject_Destroy ( QmiSyncObject pThis)

Destroy sync object.

Parameters
[in]pThisThe primary object of this call.
Returns
0 on success, < 0 on failure.

◆ QmiSyncObject_Lock()

int QmiSyncObject_Lock ( QmiSyncObject pThis)

Lock sync object.

Parameters
[in]pThisThe primary object of this call.
Returns
0 on success, < 0 on failure.

◆ QmiSyncObject_Unlock()

int QmiSyncObject_Unlock ( QmiSyncObject pThis)

Unlock sync object.

Parameters
[in]pThisThe primary object of this call.
Returns
0 on success, < 0 on failure.

◆ QmiSyncObject_Wait()

int QmiSyncObject_Wait ( QmiSyncObject pThis)

Block, waiting on sync object.

Parameters
[in]pThisThe primary object of this call.
Returns
0 on success, < 0 on failure.

◆ QmiSyncObject_TimedWait()

int QmiSyncObject_TimedWait ( QmiSyncObject pThis,
time_t  timeoutSeconds 
)

Block, waiting on sync object for a number of seconds.

Parameters
[in]pThisThe primary object of this call.
[in]timeoutSecondsTimeout in seconds before abondoning wait.
Returns
0 on success, ETIMEDOUT, or < 0 on failure.

◆ QmiSyncObject_Signal()

int QmiSyncObject_Signal ( QmiSyncObject pThis)

Signal sync object. Waiting thread should wake up.

Parameters
[in]pThisThe primary object of this call.
Returns
0 on success, or < 0 on failure.

◆ QmiSyncObject_ResponseCallback()

void QmiSyncObject_ResponseCallback ( uint8_t *  qmiPacket,
uint16_t  qmiPacketSize,
void *  pResponseCallbackContext 
)

This funcion copies QMI response packet to buffer and signals the waiting thread.

Parameters
[in]qmiPacketReceived QMI packet.
[in]qmiPacketSizeReceived QMI packet size in bytes.
[in]pResponseCallbackContextPointer to this sync object.

Copyright (c) 2011-2020 Sierra Wireless, Inc. All rights reserved