QMI Vendor Specific Services User Guide 80 VM274 1
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 21
| Download | |
| Open PDF In Browser | View PDF |
ACKNOWLEDGEMENT
By utilizing this website and/or documentation, I hereby acknowledge as follows:
Effective October 1, 2012, QUALCOMM Incorporated completed a corporate reorganization in
which the assets of certain of its businesses and groups, as well as the stock of certain of its
direct and indirect subsidiaries, were contributed to Qualcomm Technologies, Inc. (QTI), a whollyowned subsidiary of QUALCOMM Incorporated that was created for purposes of the
reorganization.
Qualcomm Technology Licensing (QTL), the Company’s patent licensing business, continues
to be operated by QUALCOMM Incorporated, which continues to own the vast majority of the
Company’s patent portfolio. Substantially all of the Company’s products and services businesses,
including QCT, as well as substantially all of the Company’s engineering, research and
1
development functions, are now operated by QTI and its direct and indirect subsidiaries . Neither
QTI nor any of its subsidiaries has any right, power or authority to grant any licenses or other
rights under or to any patents owned by QUALCOMM Incorporated.
No use of this website and/or documentation, including but not limited to the downloading of
any software, programs, manuals or other materials of any kind or nature whatsoever, and no
purchase or use of any products or services, grants any licenses or other rights, of any kind or
nature whatsoever, under or to any patents owned by QUALCOMM Incorporated or any of its
subsidiaries. A separate patent license or other similar patent-related agreement from
QUALCOMM Incorporated is needed to make, have made, use, sell, import and dispose of any
products or services that would infringe any patent owned by QUALCOMM Incorporated in the
absence of the grant by QUALCOMM Incorporated of a patent license or other applicable rights
under such patent.
Any copyright notice referencing QUALCOMM Incorporated, Qualcomm Incorporated,
QUALCOMM Inc., Qualcomm Inc., Qualcomm or similar designation, and which is associated
with any of the products or services businesses or the engineering, research or development
groups which are now operated by QTI and its direct and indirect subsidiaries, should properly
reference, and shall be read to reference, QTI.
1
The products and services businesses, and the engineering, research and development groups, which are now operated by QTI and its
subsidiaries include, but are not limited to, QCT, Qualcomm Mobile & Computing (QMC), Qualcomm Atheros (QCA), Qualcomm Internet
Services (QIS), Qualcomm Government Technologies (QGOV), Corporate Research & Development, Qualcomm Corporate Engineering
Services (QCES), Office of the Chief Technology Officer (OCTO), Office of the Chief Scientist (OCS), Corporate Technical Advisory Group,
Global Market Development (GMD), Global Business Operations (GBO), Qualcomm Ventures, Qualcomm Life (QLife), Quest, Qualcomm
Labs (QLabs), Snaptracs/QCS, Firethorn, Qualcomm MEMS Technologies (QMT), Pixtronix, Qualcomm Innovation Center (QuIC),
Qualcomm iSkoot, Qualcomm Poole and Xiam.
QMI Vendor-Specific Services
User Guide
80-VM274-1 D
October 4, 2010
Submit technical questions at:
https://support.cdmatech.com/
Qualcomm Confidential and Proprietary
Restricted Distribution. Not to be distributed to anyone who is not an employee of either Qualcomm or a
subsidiary of Qualcomm without the express approval of Qualcomm’s Configuration Management.
Not to be used, copied, reproduced in whole or in part, nor its contents revealed in any manner to others without the
express written permission of Qualcomm.
Qualcomm reserves the right to make changes to the product(s) or information contained herein without notice. No
liability is assumed for any damages arising directly or indirectly by their use or application. The information
provided in this document is provided on an “as is” basis.
This document contains Qualcomm confidential and proprietary information and must be shredded when discarded.
QUALCOMM is a registered trademark of QUALCOMM Incorporated in the United States and may be registered
in other countries. Other product and brand names may be trademarks or registered trademarks of their respective
owners. CDMA2000 is a registered certification mark of the Telecommunications Industry Association, used under
license. ARM is a registered trademark of ARM Limited. QDSP is a registered trademark of QUALCOMM
Incorporated in the United States and other countries.
This technical data may be subject to U.S. and international export, re-export, or transfer (“export”) laws. Diversion
contrary to U.S. and international law is strictly prohibited.
QUALCOMM Incorporated
5775 Morehouse Drive
San Diego, CA 92121-1714
U.S.A.
Copyright © 2008-2010 QUALCOMM Incorporated.
All rights reserved.
Contents
1 Introduction...................................................................................................... 5
1.1 Purpose.......................................................................................................................... 5
1.2 Scope............................................................................................................................. 5
1.3 Conventions .................................................................................................................. 5
1.4 References ..................................................................................................................... 5
1.5 Technical assistance ...................................................................................................... 6
1.6 Acronyms ...................................................................................................................... 6
2 Theory of Operation ........................................................................................ 7
3 Implementing Vendor-Specific Services ....................................................... 8
3.1 Service ID assignment .................................................................................................. 8
3.2 Service list..................................................................................................................... 9
3.2.1 Service list registration with QMUX ................................................................. 9
3.3 Service initialization ................................................................................................... 10
3.3.1 Service registration with QMUX ..................................................................... 11
3.3.2 Service configuration parameters (qmi_vs_cfg) .............................................. 11
3.3.3 QMI common service and client state initializations ....................................... 14
3.4 QMI command handling ............................................................................................. 15
3.4.1 Blocking request .............................................................................................. 15
3.4.2 Nonblocking request ........................................................................................ 16
3.4.3 Asynchronous indications ................................................................................ 17
3.4.4 Building a response/indication packet ............................................................. 18
4 Limitations/Assumptions .............................................................................. 20
80-VM274-1 D
2
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Contents
Figures
Figure 2-1 Vendor-specific service support ................................................................................................. 7
Tables
Table 1-1 Reference documents and standards ............................................................................................ 5
Table 3-1 Example of QMI instances that support vendor-specific services ............................................... 9
80-VM274-1 D
3
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1
Revision history
Revision
Date
Description
A
Aug 2008
Initial release
B
May 2009
Made editing changes to conform to Qualcomm standards
C
Dec 2009
Added Section 3.4.4 as a reference for vendors
D
Oct 2010
Modified vendor-specific service ID range
2
80-VM274-1 D
4
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1
2
3
4
5
6
7
1 Introduction
1.1 Purpose
The QMI framework supports QMI vendor-specific services that can be added by vendors. With
the QMI APIs, vendors can use the QMI service library to access the underlying QMI framework.
These APIs are subject to change in future target releases.
1.2 Scope
This document provides the following details about QMI vendor-specific service support:
8
Theory of operation
9
User guide for vendors
10
Semantics of exposed QMI APIs
11
12
13
1.3 Conventions
Function declarations, function names, type declarations, and code samples appear in a different
font, e.g., #include.
15
If you are viewing this document using a color monitor, or if you print this document to a color
printer, red boldface indicates sample code snippets for reference.
16
Shading indicates content that has been added or changed in this revision of the document.
14
17
1.4 References
20
Reference documents, which may include QUALCOMM®, standards, and resource documents,
are listed in Table 1-1. Reference documents that are no longer applicable are deleted from this
table; therefore, reference numbers may not be sequential.
21
Table 1-1 Reference documents and standards
18
19
Ref.
Document
Qualcomm
Q1
Application Note: Software Glossary for Customers
CL93-V3077-1
Q2
Qualcomm MSM™ Interface (QMI) Architecture
80-VB816-1
Q3
QMI Global Constant Definitions
80-VB816-2
22
80-VM274-1 D
5
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Introduction
1
2
3
4
5
6
7
1.5 Technical assistance
For assistance or clarification on information in this guide, submit a case to Qualcomm CDMA
Technologies at https://support.cdmatech.com/.
If you do not have access the CDMA Tech Support Service web site, register for access or send
email to support.cdmatech@qualcomm.com.
1.6 Acronyms
For definitions of terms and abbreviations, see [Q1].
8
80-VM274-1 D
6
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1
2
3
4
2 Theory of Operation
QMI vendor-specific service support enables vendors to add their own QMI services to run over
Qualcomm’s QMI framework. Utility functions are provided in QMI to enable vendors to register
and use their vendor-specific services with the QMI framework.
7
Vendors can add their own QMI services and messages to their services. They can receive
requests for their services and send responses/indications to the client using the QMI framework
and the QMI common service library APIs.
8
Figure 2-1 is an example of vendor-specific service support.
5
6
Client 1
Vendor
Service 1
Client 2
Client 3
Vendor
Service 2
Client 1
Client 2
Vendor
Service 3
Client 1
9
10
Figure 2-1 Vendor-specific service support
80-VM274-1 D
7
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1
2
3
4
5
6
7
8
9
10
11
12
13
3 Implementing Vendor-Specific Services
A maximum of 27 vendor-specific services can be added by vendors. This chapter describes how
to implement QMI vendor-specific services.
3.1 Service ID assignment
Every vendor-specific service must have a service ID. The valid vendor-specific service ID range
is 227 to 253. Service ID assignment should be done inside the enum qmux_service_e_type in
ds_qmi_svc_ext.h. Vendor-specific service IDs must be placed between
QMUX_SERVICE_VENDOR_MIN and QMUX_SERVICE_VENDOR_MAX in the enum.
Vendor-specific services must be assigned service IDs consecutively and must begin with
QMUX_SERVICE_VENDOR_MIN. QMUX_SERVICE_VENDOR_MAX should always be
QMUX_SERVICE_VENDOR_MIN + the number of vendor-specific services. For example, if
there are no vendor-specific services, then QMUX_SERVICE_VENDOR_MAX has a value of
QMUX_SERVICE_VENDOR_MIN.
15
If you are viewing this document using a color monitor, or if you print this document to a color
printer, red boldface indicates sample code snippets for reference.
16
Sample code in ds_qmi_svc_ext.h
14
17
18
typedef enum
19
{
20
QMUX_SERVICE_MIN
21
/* Qualcomm Internal Service IDs */
= 0,
22
23
QMUX_SERVICE_VENDOR_MIN
24
VENDOR_SPECIFIC_SERVICE1
= QMUX_SERVICE_VENDOR_MIN,
25
VENDOR_SPECIFIC_SERVICE2
= QMUX_SERVICE_VENDOR_MIN +1,
26
27
QMUX_SERVICE_VENDOR_MAX
= 227,
//(= QMUX_SERVICE_VENDOR_MIN +2)
} qmux_service_e_type;
28
80-VM274-1 D
8
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
3.2 Service list
5
Multiple vendor-specific services are maintained using a service list data structure that is a
two-dimensional array of qmux_svc_info_type. This service list can be used to map a specific set
of services to each QMI instance. Table 3-1 is an example of QMI instances that are mapped to
different sets of vendor-specific services as desired by the vendor.
6
Table 3-1 Example of QMI instances that support vendor-specific services
2
3
4
QMI instance
Vendor-specific services
QMI INSTANCE 1
VS1
VS2
VS3
VS4
VS5
VS6
QMI INSTANCE 2
VS1
VS2
VS3
VS6
…
…
QMI INSTANCE 3
VS1
VS2
VS3
VS4
VS6
…
7
8
9
10
11
12
Memory must be allocated for the service list in ds_qmi_svc_ext.c. There should be enough
memory allocated to facilitate all the services supported by the particular instance to which it is
assigned. The maximum number of QMI instances is defined by the constant
QMI_INSTANCE_MAX in ds_qmi_svc_ext.h. However, if the vendor-specific services are
needed only on one QMI instance, then memory can be allocated only for one instance.
13
14
qmux_svc_info_type
15
qmi_vs_svc_list [number of qmi instances][number of VS services];
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
After the memory is allocated, the service list must be registered with QMUX, as described in
Section 3.2.1.
3.2.1 Service list registration with QMUX
The qmux_reg_vs_service_list () function (declaration can be found in ds_qmux_ext.h) must be
called to register the service list with QMUX. This function must be called separately for each
QMI instance. Hence, the best place to call this function would be from within the
qmi_svc_ext_init() function in ds_qmi_svc_ext.c, which is typically called separately for each
QMI instance.
Vendors can selectively choose which QMI instance includes or excludes a particular service by
selectively calling the service initialization function only on the desired QMI instance. This
model gives the vendor the flexibility to choose not to register a service for a specific instance.
The following example shows how to register vendor-specific services for the first QMI instance.
The check for the first instance (i==0) can be removed when support for multiple instances is
added to the QMI framework.
80-VM274-1 D
9
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
Template for service-list registration
2
void qmi_svc_ext_init ( qmi_instance_e_type i )
3
{
/* Built-in QMI Service Initializations */
4
5
…
6
/* Vendor Specific Service List Registration with QMUX */
7
8
boolean reg_list_success;
9
if (i == 0) //check for 1st QMI instance
10
{
reg_list_success = qmux_reg_vs_service_list(
11
12
i,
13
&(qmi_vs_svc_list[i][0]),
number_of_vendor_specific_services);
14
15
16
/* NOTE: Only after this step the vendor service initialization functions
can be called for individual services to register with QMUX. */
17
18
/* Vendor Specific Services Initializations */
19
vendor_service1_init(i);
20
vendor_service2_init(i);
…
21
22
}
23
}
24
3.3 Service initialization
29
Every service must have an initialization function (typically defined in the vendor-specific service
source file), which should be called after the service list registration with QMUX is done. The
following template shows the steps that must be performed in this function, followed by
vendor-specific steps. A more detailed explanation of the APIs and structures used within it are
described in Sections 3.3.1 through 3.3.3.
30
Initialization function template
31
void vendor_service_init( qmi_instance_e_type
32
{
25
26
27
28
33
qmux_svc_info_type * qmux_svc_handle;
34
qmi_vendor_service_state_type * vs1_sp;
35
qmi_vendor_client_state_type * cl_sp;
qmi_inst )
36
37
38
/* 1. Obtain Service Handle */
qmux_svc_handle = qmux_reg_vs_service(qmi_inst,
39
VENDOR_SERVICE_ID,
40
&qmi_vs_cfg[qmi_inst]);
41
80-VM274-1 D
10
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
/* 2. QMI Common Service State Initialization */
1
vs1_sp = &qmi_vendor_service_state[qmi_inst];
2
qmi_svc_common_svc_init(&vs1_sp->common, qmux_svc_handle);
3
4
/* 3. Vendor specific service state initialization */
5
…
6
7
8
cl_sp = vs1_sp->client;
9
for (client=0; client < VS1I_MAX_CLIDS; client++, cl_sp++)
{
10
11
/* 4. QMI Common Client State Initialization */
12
qmi_svc_common_cl_init(&vs1_sp->common, &cl_sp->common);
13
/* 5. Vendor specific client state initialization */
14
…
15
}
16
17
}
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
3.3.1 Service registration with QMUX
All individual services must be registered with QMUX using the qmux_reg_vs_service() function
(the declaration can be found in ds_qmux_ext.h), which can be called from the initialization
functions of the individual services, as shown in Section 3.3. This function must be called
separately for each QMI instance and it will return a unique service handle (qmux_svc_handle in
the initialization template), which can be used for the common service initialization.
The QMI vendor-service configuration, qmi_vs_cfg (see Section 3.3.2), must also be passed as
one parameter in this function. Hence, the callback and the state pointers must be populated using
the qmux_svc_config_type structure before this step.
3.3.2 Service configuration parameters (qmi_vs_cfg)
Vendors must allocate memory and set the members of the service configuration structure
(qmux_svc_config_type) as needed in the vendor-specific service source file. Vendors can choose
not to register their own implementation of the configuration members by defining them as
NULL or zero appropriately. This will result in usage of the QMI built-in capability. The service
configuration consists of the fields described in this section.
34
Base/addendum versions – These can be optionally used by vendors to keep track of versions.
35
Registerable callback function array (qmux_svc_cbs_type) – Vendors can register their own
callback functions in this structure (qmux_svc_cbs_type). Choose to use the QMI built-in
functionality by setting any of these pointers to NULL. Some of the callbacks shown below
(in red) must be provided by the vendor, as they depend on vendor-specific implementation.
36
37
38
80-VM274-1 D
11
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
2
If you are viewing this document using a color monitor, or if you print this document to a color
printer, red boldface indicates sample code snippets for reference.
3
4
5
typedef struct _qmux_svc_callbacks
{
/* To allocate client IDs */
6
7
byte (* alloc_clid) ( void * sp );
8
9
/* To check if clid is valid */
boolean (* is_valid_clid) ( void * sp, byte clid );
10
11
/* To deallocate client IDs. */
12
13
boolean (* dealloc_clid) ( void * sp, byte clid );
14
15
/* To free all clients when QMI link is closed */
16
void (* qmux_closed) ( void * sp );
17
/* To get the QMUX SDU and trigger the appropriate command handler */
18
19
void(* recv) (void * sp, byte clid, dsm_item_type * sdu_in);
20
21
22
23
24
/* To get the next client state pointer based on the client state pointer
passed as the input to this function. Vendor needs to implement this as
the client state varies based on vendor specific definition. */
void * (* get_next_client_sp) ( void * sp, void * cl_sp);
25
26
27
28
29
/* To clean up the vendor specific client state. Vendor needs to implement
this function. This function can call qmi_svc_common_reset_client() api to
clean the common client state. */
void (* reset_client) ( void *);
30
31
} qmux_svc_cbs_type;
32
33
34
35
36
37
38
39
40
41
42
43
QMI has built-in client ID management for clients. Vendors can choose to use it by setting the
alloc_clid, is_valid_clid, dealloc_clid, qmux_closed, recv function pointers to NULL in the
service configuration. However, vendors must register their own get_next_client_sp and
reset_client callback functions in the service configuration. QMI needs the client state pointers to
perform client ID management for each client. The client state pointers must be returned via
get_next_client_sp callback, as the vendor client state can vary in size based on the vendorspecific parameters in it. The reset_client callback must clean up the client state and will trigger
when the client ID is deallocated. The reset_client callback function can, additionally, call
qmi_svc_common_reset_client(void * cl_sp_in) API to clean up the common client based on the
common client-state pointer, which is passed in as a parameter.
44
45
46
47
48
80-VM274-1 D
Command handler array – Any vendor-specific service must offer its services via commands
that the client can use to request information that it needs. Every command must have a
unique command value (e.g., CMD1 in the following example). The QMI framework gives
vendors the ability to declare an array of command handlers (of type qmi_svc_cmd_hdlr_type
defined in ds_qmi_svc_ext.h), which can be included in the vendor-specific service
configuration.
12
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
Template
2
3
static qmi_svc_cmd_hdlr_type vs_cmd_handler_array[# of cmds] =
4
{
{CMD1, “cmd description”,
5
(qmi_svc_hdlr_ftype) cmd_funtion_ptr)},
6
…
7
8
};
9
Number of commands – Number of commands supported in the service
10
Service-provided state pointer – The following example declares the service configuration
structure for one instance:
11
12
13
qmux_svc_config_type qmi_vs_cfg[1] =
14
{
15
{ { base major version, base minor version },
{ addendum major version, addendum minor version },
16
{ NULL, // alloc: use QMI built-in capability
17
18
NULL, // is_valid_clid: use QMI built-in capability
19
NULL, // dealloc: use QMI built-in capability
20
NULL, // qmux_closed: use QMI built-in capability
21
NULL, // recv: use QMI built-in capability
22
qmi_vendor_service_get_next_client_sp,
23
qmi_vendor_service_reset_client
24
},
25
vs_cmd_handler_array,
26
# of vendor service commands (in the array),
27
&qmi_vendor_service_state[0]
28
};
29
80-VM274-1 D
13
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
2
3
4
5
6
7
3.3.3 QMI common service and client state initializations
Every vendor-specific service must maintain a state (qmi_vendor_service_state[], in the
vendor-specific service source file) to store service-related information. A vendor-specific service
can have multiple clients to which it can offer services, and for which it must maintain a client
state to store information that applies to specific clients. The client and service state structures
must follow the format described in this section to work with the QMI model.
Vendor-specific service client state definition (cl_sp)
8
9
10
typedef struct qmi_vendor_service_client_state_s
{
byte common[QMI_COMMON_CLIENT_STATE_SIZE]; //must be first
11
13
/* Add vendor-defined client specific fields here. Eg: Number of times a
request was serviced for the client */
14
} qmi_vendor_service_client_state_type;
12
15
16
Vendor-specific service state definition (vs1_sp)
17
18
typedef struct qmi_vendor_service_state_s
19
{
20
byte common[QMI_COMMON_SVC_STATE_SIZE]; // must be first
21
qmi_vendor_service_client_state_type client[num of clients];
23
/* Add vendor specific fields here. Eg: Total number of request messages
serviced so far */
24
} qmi_vendor_service_state_type;
22
25
26
27
Vendors are required to declare and allocate memory for the service state for any number of QMI
instances as desired; for example, of memory allocation for one instance:
28
29
static qmi_vendor_service_state_type
qmi_vendor_service_state[1] = {0,};
30
31
32
33
34
35
36
37
The common service and client states in the above structures must be initialized using
qmi_svc_common_svc_init() and qmi_svc_common_cl_init() APIs, as shown in the initialization
function template in Section 3.3. The QMI framework supports a maximum of 255 clients per
service and the number of elements in the client[] array in the vendor-specific service state cannot
exceed 255. The qmi_svc_common_cl_init() must be called separately for each client. Vendorspecific service-state and vendor-specific client-state initializations can be performed after the
common-state initializations.
80-VM274-1 D
14
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
2
3
4
5
6
3.4 QMI command handling
Vendor-specific services must offer their services via commands that the client can use to request
the information it needs. Each command can be associated with the corresponding vendor-defined
command handler function. An array of command handlers (vs_cmd_handler_array) of type
qmi_svc_hdlr_ftype (defined in ds_qmi_svc_ext.h) must be defined as part of the service
configuration parameters, described in Section 3.3.2, in the vendor-specific service source file.
7
8
typedef dsm_item_type* (* qmi_svc_hdlr_ftype)
(
9
10
void * sp,
11
void * cmd_buf_p, // Command buffer
12
void * cl_sp,
// Client state pointer
dsm_item_type ** sdu //Packet containing request to be
13
14
//Service provided state pointer
processed
);
15
16
17
18
19
20
21
22
23
24
The sp and cl_sp parameters should be appropriately cast to the vendor-specific service-state and
client-state structures, respectively, in the command handlers. The cmd_buf_p parameter holds
the command information used by the QMUX layer. The sdu parameter is the dsm_item_type
packet that can hold any input parameters specific to a command. The data from this packet must
be extracted using the DSM APIs.
Vendor-specific services have the option to make the command handlers blocking or
nonblocking.
3.4.1 Blocking request
27
This option should be used when the service can immediately process the request. The response
must be pushed into a dsm_item_type packet in the command handler function, and this packet
should be returned by the command handler.
28
See Section 3.4.4 for an example of how to build a response packet.
25
26
80-VM274-1 D
15
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
2
3
4
5
6
3.4.2 Nonblocking request
The vendor-specific service must store the command buffer pointer (cmd_buf_p) and return 1 as
the return value for the command handler. This is a way to inform the QMI framework that the
response for the request is pending and will be sent at a later time. Once the response is ready, the
vendor-specific service can retrieve the previously stored command buffer and use the
qmi_svc_send_response() API to send the response to the client.
7
8
boolean qmi_svc_send_response
9
(
10
void * sp, // Service-provided state pointer
11
void * cmd_buf_p_in, // Retrieved command buffer pointer
12
dsm_item_type *
13
msg_ptr
// Response packet
);
14
15
16
17
18
See Section 3.4.4 for an example of how to build a response packet.
The qmi_svc_get_client_sp_by_cmd_buf() API returns the client-state pointer from the command
buffer, which is de-queued. This can be used to send the response to specific clients, if required,
by checking if this client state matches the desired client.
19
20
void * qmi_svc_get_client_sp_by_cmd_buf
21
(
void * cmd_buf_p_in //Retrieved command buffer pointer
22
23
);
24
80-VM274-1 D
16
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
2
3
3.4.3 Asynchronous indications
In addition to synchronous queries and responses, indications can be sent asynchronously by the
vendor-specific service using the qmi_svc_send_ind() API.
4
5
void qmi_svc_send_ind
6
(
7
void * sp,
8
uint8 clid,// Client ID of the client to send the ind
9
uint16 cmd_type, //Command value/ID associated with this
ind
dsm_item_type * ind //Packet containing indication info to be sent
10
11
// Service-provided state pointer
);
12
13
14
15
16
17
18
This API requires client ID and cmd_type input parameters in addition to the service-state pointer
and data packet to be sent in the indication. The cmd_type parameter is the unique command
value described in Section 3.3.2. For broadcast indications sent out to all clients, the client ID
must be set to 255. For unicast indications, the client ID of the client must be used. If vendors
choose QMI to do the client ID management, they can use the
qmi_svc_get_clid_from_client_sp() API to get the client ID that is associated with the client.
19
20
uint8 qmi_svc_get_clid_from_client_sp
21
(
22
23
void * cl_sp
this api
24
);
// Client state pointer whose client ID is returned via
25
26
See Section 3.4.4 for an example of how to build a packet to be sent in the indication.
80-VM274-1 D
17
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
3.4.4 Building a response/indication packet
6
This section provides an example of how to build a packet to be sent in the response or indication
messages that are described in Sections 3.4.1, 3.4.2, and 3.4.3. In this example, the packet being
built contains a result TLV (only relevant for response and not indication) and another VS TLV
that holds a 4-byte integer (int32). The response is built by pushing both TLVs from back to
front. See [Q3] for example values of constants for QMI_ERR_* and QMI_RESULT_*.
7
The following psuedocode provides an example of how to build a response/indication packet:
2
3
4
5
8
9
10
static dsm_item_type * qmi_vs_build_packet()
{
11
...
12
dsm_item_type * response = NULL; //assume memory allocation done
13
uint16 errval = QMI_ERR_NONE;
14
uint16 result = QMI_RESULT_SUCCESS;
15
16
/* STEP 1: PUSH VS TLV INTO THE RESPONSE DSM ITEM */
17
uint8 type = 1; //type of VS TLV
18
uint16 len = sizeof(int32); //length of VS TLV
19
int32 out = 3;
//value of VS TLV
20
21
/* STEP 1a: PUSH VALUE OF VS TLV INTO THE RESPONSE */
22
if (len != dsm_pushdown_packed(&response, &out,
len, DSM_DS_SMALL_ITEM_POOL))
23
{
24
25
/* Cannot populate VALUE into response pointer */
26
errval = QMI_ERR_*;
dsm_free_packet(&response);
27
28
}
29
else
30
{
31
/* STEP 1b: PUSH LENGTH OF VS TLV INTO THE RESPONSE */
32
if (sizeof(len) != dsm_pushdown_packed(&response, &len,
sizeof(len), DSM_DS_SMALL_ITEM_POOL))
33
{
34
35
/* Cannot populate LENGTH into response pointer */
36
errval = QMI_ERR_*;
dsm_free_packet(&response);
37
}
38
80-VM274-1 D
18
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Implementing Vendor-Specific Services
1
else
2
{
/* STEP 1c: PUSH TYPE OF VS TLV INTO THE RESPONSE */
3
if (sizeof(type) != dsm_pushdown_packed(&response, &type,
4
sizeof(type), DSM_DS_SMALL_ITEM_POOL))
5
{
6
7
/* Cannot populate TYPE into response pointer */
8
errval = QMI_ERR_*;
9
dsm_free_packet(&response);
}
10
}
11
}
12
13
14
/* STEP 2: PUSH RESULT TLV INTO THE RESPONSE DSM ITEM */
15
/* NOTE: Step 2 is not applicable for indication messages */
16
type = 2; // type of Result TLV
17
//length of Result TLV (sizes of errval + result)
18
len = sizeof(uint16) + sizeof(uint16);
19
if (errval == QMI_ERR_NONE)
20
{
result = QMI_RESULT_SUCCESS; /* value = Success */
21
22
}
23
else
24
{
result = QMI_RESULT_FAILURE; /* value = Failure */
25
}
26
27
28
/* STEP 2a: PUSH VALUE OF RESULT TLV INTO THE RESPONSE */
29
dsm_pushdown_packed(&response, &errval,
sizeof(uint16), DSM_DS_SMALL_ITEM_POOL);
30
dsm_pushdown_packed(&response, &result,
31
sizeof(uint16), DSM_DS_SMALL_ITEM_POOL);
32
33
/* STEP 2b: PUSH LENGTH OF RESULT TLV INTO THE RESPONSE */
34
dsm_pushdown_packed(&response, &len,
sizeof(len), DSM_DS_SMALL_ITEM_POOL);
35
36
/* STEP 2c: PUSH TYPE OF RESULT TLV INTO THE RESPONSE */
37
dsm_pushdown_packed(&response, &type,
sizeof(type), DSM_DS_SMALL_ITEM_POOL);
38
39
return response;
40
41
}
80-VM274-1 D
19
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1
2
4 Limitations/Assumptions
The following limitations and assumptions apply:
There is no deregister function supported in the current implementation that allows
deregistration with QMUX.
5
Vendor-specific services must be compiled with AMSS.
6
Vendor services run either in the DS or DCC task context.
3
4
80-VM274-1 D
20
Qualcomm Confidential and Proprietary
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No Encryption : Standard V2.3 (128-bit) User Access : Print, Modify, Copy, Annotate, Fill forms, Print high-res Keywords : October, 2010 Modify Date : 2017:07:18 20:00:18-07:00 Create Date : 2010:10:04 10:11:58-07:00 Company : QUALCOMM Incorporated.5775 Morehouse Drive.San Diego, CA 92121-1714.U.S.A. QUALCOMM India Private Limited.Building 10, Mindspace.HiTech City, Madhapur.Hyderabad, Andhra Pradesh 500081.India QUALCOMM Israel.Omega Center.MATAM Post Office.Haifa 31905.Israel QUALCOMM (UK) Ltd .Spectrum Point.279 Farnborough Road.Farnborough , Hants.GU14 7LS.UNITED KINGDOM SnapTrack, Inc..5775 Morehouse Drive.San Diego, CA 92121-1714.U.S.A. QUALCOMM Flarion Technologies, Inc..500 Somerset Corporate Boulevard.Bridgewater, NJ 08807.U.S.A. Source Modified : D:20101004171129 Author : Page Mode : UseOutlines Page Layout : SinglePage Format : application/pdf Description : 80-VM274-1_D_QMI_Vendor-Specific_Services_UG.pdf Subject : 80-VM274-1_D_QMI_Vendor-Specific_Services_UG.pdf Title : QMI Vendor-Specific Services User Guide Creator : Producer : Gnostice PDFOne Java; modified using iText® 5.4.0 ©2000-2012 1T3XT BVBA (AGPL-version) Creator Tool : Acrobat PDFMaker 8.1 for Word Tagged PDF : Yes Page Count : 21EXIF Metadata provided by EXIF.tools