Diag System Architecture

80-NA157-61 E
April 25, 2014

Submit technical questions at:

https://support.cdmatech.com/

Confidential and Proprietary – Qualcomm Technologies, Inc.

NO PUBLIC DISCLOSURE PERMITTED: Please report postings of this document on public servers or websites
to: DocCtrlAgent@qualcomm.com.

Restricted Distribution: Not to be distributed to anyone who is not an employee of either Qualcomm or its
subsidiaries without the express approval of Qualcomm’s Configuration Management.

Not to be used, copied, reproduced, or modified in whole or in part, nor its contents revealed in any manner to others
without the express written permission of Qualcomm Technologies, Inc.

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 confidential and proprietary information and must be shredded when discarded.

Qualcomm is a trademark of QUALCOMM Incorporated, registered in the United States and other countries. All
QUALCOMM Incorporated trademarks are used with permission. Other product and brand names may be
trademarks or registered trademarks of their respective owners.

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 Technologies, Inc.

5775 Morehouse Drive
San Diego, CA 92121
U.S.A.

© 2012-2014 Qualcomm Technologies, Inc.

All rights reserved.
Contents

1 Introduction...................................................................................................... 7
1.1 Purpose.......................................................................................................................... 7
1.2 Scope............................................................................................................................. 7
1.3 Conventions .................................................................................................................. 7
1.4 References..................................................................................................................... 8
1.5 Technical assistance ...................................................................................................... 8
1.6 Acronyms ...................................................................................................................... 8

2 Diagnostic Services Overview ........................................................................ 9

2.1 Central routing .............................................................................................................. 9
2.1.1 Handling common requests ............................................................................. 10
2.2 Working with diag services ........................................................................................ 11
2.3 Diag services APIs ...................................................................................................... 11
2.3.1 Command service ............................................................................................ 12
2.3.2 Debug Message service ................................................................................... 13
2.3.3 Event Reporting service ................................................................................... 15
2.3.4 Logging service ............................................................................................... 16

3 Common Customization Examples.............................................................. 18

3.1 Defining a new subsystem command ......................................................................... 18
3.1.1 Single response command ............................................................................... 18
3.1.2 Multiple response command ............................................................................ 21
3.2 Defining a new log packet .......................................................................................... 24
3.3 Defining a new event report........................................................................................ 25
3.4 Defining new SSIDs and using them in F3s ............................................................... 26

4 On-Device Logging ........................................................................................ 28

4.1 Running on-device logging (diag_mdlog) .................................................................. 28
4.1.1 Running diag_mdlog using ADB .................................................................... 28
4.1.2 Running diag_mdlog on the device ................................................................. 29
4.2 Troubleshooting SD card issues.................................................................................. 29
4.3 Converting .qmdl files to .isf for use in QXDM ......................................................... 30
4.4 Diag masks .................................................................................................................. 30
4.4.1 Creating a mask config (.cfg) file .................................................................... 30
4.4.2 Loading a mask config (.cfg) file in QXDM Pro ............................................. 32
4.4.3 Saving diag stress test command requests ....................................................... 34
4.4.4 Saving diag task profile requests ..................................................................... 37
4.5 Low power modes ....................................................................................................... 39
4.5.1 NRT/Buffering................................................................................................. 40

80-NA157-61 E 2 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Contents

4.5.2 Real-Time mode .............................................................................................. 40

4.6 Initializing diag_mdlog at boot time ........................................................................... 41
4.6.1 Required code changes for initializing diag_mdlog at boot time .................... 41

5 Socket Logging.............................................................................................. 43
5.1 Initial setup ................................................................................................................. 44
5.1.1 Ping device from PC ........................................................................................ 44
5.1.2 Ping PC from device ........................................................................................ 44
5.2 Application usage ....................................................................................................... 45
5.2.1 Running the diag_socket_log application ........................................................ 45
5.2.2 Stopping the diag_socket_log application ....................................................... 45
5.3 QPST configuration .................................................................................................... 46

6 UART Logging ............................................................................................... 47

6.1 Application usage ....................................................................................................... 47
6.1.1 Running the diag_uart_log application ............................................................ 47
6.1.2 Fused target enhancements .............................................................................. 48
6.1.3 Examples ......................................................................................................... 48
6.2 Required code changes for enabling UART logging .................................................. 49
6.2.1 TN builds – MDM9x15, MDM9x25, MDM9x35 ........................................... 49
6.2.2 LE/LA builds ................................................................................................... 50
6.3 Tools tested ................................................................................................................. 51
6.4 Limitations .................................................................................................................. 51

7 Diag Consumer Interface .............................................................................. 54

7.1 Overview..................................................................................................................... 54
7.2 Initialization ................................................................................................................ 55
7.3 Command/response packets ........................................................................................ 56
7.4 Logs and events .......................................................................................................... 57
7.5 Limitations .................................................................................................................. 57
7.6 Sample application...................................................................................................... 58
7.6.1 Usage ............................................................................................................... 58
7.6.2 Parsing ............................................................................................................. 58
7.6.3 Sample code ..................................................................................................... 59
7.7 Security ....................................................................................................................... 60
7.7.1 Apps processor protections .............................................................................. 60
7.7.2 Modem processor protections .......................................................................... 60
7.8 NRT mode................................................................................................................... 61
7.8.1 NRT/Buffering mode ....................................................................................... 61
7.8.2 Power management on the apps processor ...................................................... 62

8 Listeners......................................................................................................... 63
8.1 Single listener ............................................................................................................. 63
8.2 Extended listener......................................................................................................... 64

9 Debugging ...................................................................................................... 65
9.1 QPST disconnect/“No Phone” status .......................................................................... 65

80-NA157-61 E 3 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Contents

9.1.1 QPST port trace ............................................................................................... 66

9.1.2 Packet interpretation ........................................................................................ 68
9.1.3 Ports ................................................................................................................. 69
9.1.4 Modem ............................................................................................................. 69
9.1.5 QPST and QXDM Pro ..................................................................................... 70
9.1.6 ADB shell ........................................................................................................ 70
9.1.7 Debugfs ............................................................................................................ 70
9.2 Linux APSS ................................................................................................................ 73
9.2.1 Command/Response routing ............................................................................ 73
9.2.2 F3 masks .......................................................................................................... 75
9.2.3 Log masks ........................................................................................................ 76
9.2.4 Kernel logs ....................................................................................................... 77
9.3 Modem processor ........................................................................................................ 77
9.3.1 Command/response handling........................................................................... 77
9.3.2 Diag Tx routing (logs, events, F3s) ................................................................. 78
9.3.3 Log packet generation...................................................................................... 79
9.3.4 Event report generation.................................................................................... 81
9.3.5 F3 messages generation ................................................................................... 82
9.3.6 Diag signals ..................................................................................................... 83
9.3.7 DSM debugging ............................................................................................... 85
9.3.8 Sleep voting ..................................................................................................... 87
9.3.9 F3 trace ............................................................................................................ 89
9.3.10 Timestamps .................................................................................................... 89
9.3.11 Common issues .............................................................................................. 90

10 Code Structure............................................................................................. 91
10.1 L4/Rex ...................................................................................................................... 91
10.2 Linux ......................................................................................................................... 92
10.2.1 LA .................................................................................................................. 92
10.2.2 LE .................................................................................................................. 93

11 Case Study ................................................................................................... 94

11.1 Packet drop ............................................................................................................... 94
11.1.1 Creating IPC buffer on APSS ........................................................................ 94
11.1.2 Using MPM timecount .................................................................................. 94

A Problem Areas for Opening a Diag Case .................................................... 99

B Defining Custom Android Permissions for Diag ...................................... 101

B.1 Enabling use of custom permissions by a system APK ........................................... 101
B.1.1 Declaring custom Android permission.......................................................... 101
B.1.2 Mapping custom Android permission to Linux permission .......................... 102
B.1.3 Additional modifications to APK’s Android.mk file .................................... 102
B.1.4 Proper placement of APK’s mapping .xml file ............................................. 102
B.1.5 Making the APK part of the system image ................................................... 103
B.2 Enabling use of custom permissions by a nonsystem APK ..................................... 103
B.2.1 Using custom Android permissions .............................................................. 103
B.2.2 Signing an unsigned APK ............................................................................. 104

80-NA157-61 E 4 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Contents

Figures
Figure 5-1 Architecture for socket logging ................................................................................................ 43
Figure 7-1 Diag consumer services overview ............................................................................................ 54
Figure 7-2 Call flow for initialization ........................................................................................................ 55
Figure 7-3 Call flow for command request/response service..................................................................... 56
Figure 7-4 Call flow for logs/events services ............................................................................................ 57
Figure 9-1 Log packet generation call flow ............................................................................................... 79
Figure 9-2 Event report generation call flow ............................................................................................. 81
Figure 9-3 F3 message generation call flow .............................................................................................. 82
Figure 9-4 Diag DSM pools and watermark queues .................................................................................. 85
Figure 9-5 Diag sleep voting call flow....................................................................................................... 87

Tables
Table 1-1 Reference documents and standards ............................................................................................ 8
Table 2-1 ESN request ............................................................................................................................... 12
Table 2-2 ESN response............................................................................................................................. 13
Table 2-3 MSG 2.0 macros ........................................................................................................................ 14
Table 2-4 Bit values for DIAG_F3_TRACE_DETAIL_MASK_DEFAULT_VAL ................................. 15
Table 3-1 Single response APSS command table ...................................................................................... 20
Table 3-2 Single response modem command table.................................................................................... 20
Table 3-3 Delayed response APSS command table ................................................................................... 23
Table 3-4 Delayed response modem command table ................................................................................ 23
Table 4-1 Options available with diag_mdlog application ........................................................................ 29
Table 5-1 diag_socket_log command arguments....................................................................................... 45
Table 6-1 diag_uart_log command arguments........................................................................................... 47
Table 7-1 Log packet structure .................................................................................................................. 58
Table 9-1 Modem loopback command structure in APSS Linux dispatch table ....................................... 74

80-NA157-61 E 5 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Revision history

Revision Date Description

A Aug 2012 Initial release
B Oct 2013 Numerous changes were made to this document; it should be
read in its entirety.
C Nov 2013 Updated Chapter 7
D Feb 2014 Numerous changes were made to this document; it should be
read in its entirety
E Apr 2014 Added Sections 4.5, 4.6, 6.2, and 6.3, Chapters 9 and 10, and
Appendixes A and B; updated Sections 2.3.2, 2.3.3, 2.3.4 and
Chapter 7

80-NA157-61 E 6 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 1 Introduction

2 1.1 Purpose
3 This document describes the diagnostic module system-level architecture, its functionalities, and
4 the newer features.

5 1.2 Scope
6 This document is meant for engineers using and working with diagnostic module services.

7 1.3 Conventions
8 Function declarations, function names, type declarations, and code samples appear in a different
9 font, e.g., #include.
10 Code variables appear in angle brackets, e.g., <number>.
11 Button and key names appear in bold font, e.g., click Save or press Enter.
12 If you are viewing this document using a color monitor, or if you print this document to a color
13 printer, red boldface indicates code that is to be added, and blue strikethrough indicates code
14 that is to be replaced or removed (if present).
15 Shading indicates content that has been added or changed in this revision of the document.

80-NA157-61 E 7 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Introduction

1 1.4 References
2 Reference documents are listed in Table 1-1. Reference documents that are no longer applicable
3 are deleted from this table; therefore, reference numbers may not be sequential.

4 Table 1-1 Reference documents and standards

Ref. Document

Qualcomm Technologies
Q1 Application Note: Software Glossary for Customers CL93-V3077-1
Q2 Diagnostic Services Interface Specification and Operational Description 80-V6135-1
Q3 CDMA Dual-Mode Subscriber Station Serial Data Interface Control Document 80-V1294-1
(ICD)
Q6 Diagnostic Consumer Interface API on Linux 80-N8469-2
Q7 QXDM Professional™ User Guide 80-V1241-21
Q11 Diagnostic Services Subsystem Interface Control Document (ICD) 80-V1294-10
Q14 Long Term Evolution (LTE) Interface Control Document (ICD) 80-VP457-1
Q15 Presentation: Secure Services Module (SSM) Overview for Windows Phone 8 80-NA027-1
Q16 Presentation: Secure Services Module (SSM) Overview for Linux Android™ 80-NH283-1
Resources
R1 Declaring and Enforcing Permissions http://developer.android.com/guide/topics/
security/permissions.html#declaring
5

6 1.5 Technical assistance

7 For assistance or clarification on information in this document, submit a case to Qualcomm
8 Technologies, Inc. (QTI) at https://support.cdmatech.com/.
9 If you do not have access to the CDMATech Support website, register for access or send email to
10 support.cdmatech@qti.qualcomm.com.

11 1.6 Acronyms
12 For definitions of terms and abbreviations, see [Q1].
13

80-NA157-61 E 8 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 2 Diagnostic Services Overview

2 2.1 Central routing

3 Central routing provides a robust, scalable solution and reduces the round-trip delay found in
4 legacy diag systems. In the central routing environment, remote processors communicate local
5 registrations to the master diag. This communication is performed through an SIO-SMD channel.
6 When the master diag receives a request, it immediately knows whether to generate an error
7 response or a forward request to the appropriate remote processor. The master diag uses the
8 following routing:
9 1. At initialization, the remote or slave processors create local registration tables of commands
10 that are sent to the apps processor. The apps processor creates a master registration table of
11 all commands. This table includes the specific processor to be used for each command.

Remote Modem
processor
Local registration Local registration
table table

APSS ADSP

Master Local registration

registration table table
12
13

14 2. When a command request is sent from a connected PC via QXDM Professional™ (QXDM
15 Pro), the apps processor compares the request to its table, and the command is forwarded to
16 the relevant processor.

80-NA157-61 E 9 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diagnostic Services Overview

1 3. The processor handling the command, e.g., modem or ADSP, sends a response routed
2 through the apps processor, which forwards it to the PC.

3
4

5 2.1.1 Handling common requests

6 A set of common requests is sent by QXDM Pro to the phone when QXDM Pro is connected.
7 This set of commands configures diag by setting the F3s, events, and log masks. The commands
8 must be received and processed by diag on all processors, hence the term common requests.
9 When master diag is notified that a slave is up, it sends a copy of the most current F3s/events/log
10 masks via CTRL messages.
11 When the master diag receives a set mask request from a tool, it updates its mask. After the mask
12 is updated, the master diag sends a copy of the updated mask to all available slaves via CTRL
13 messages. It then responds to the runtime set mask request. The master diag continues to forward
14 all other common requests to the slaves.
15 When a slave opens the CTRL connection to the master diag, it receives mask updates via CTRL
16 messages from the master. The modem slave diag continues to send the response to all common
17 requests. The modem should not respond to set mask requests because they are no longer
18 forwarded from the master diag.

80-NA157-61 E 10 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diagnostic Services Overview

1 2.2 Working with diag services

2 The following methods are available for use with diag services for processes such as sending diag
3 commands, accessing logs, saving logs on the device, and logging via QXDM Pro and QPST:
4 n Diag services API functions – Performs tasks such as defining new commands, event reports,
5 and packets. See [Q2] for additional details.
6 n On-device logging – diag_mdlog app enables and performs logging on the device and saving
7 directly on the SD card. On-device logging offers the advantage of being able to capture log
8 information without being connected to a PC.
9 n Logging a connected device on a PC via QPST and QXDM Pro:
10 ¨ Socket logging
11 ¨ UART logging
12 n Diag Consumer Interface (DCI) – Set of APIs used by a diag client on the apps processor to
13 inject command requests to supported peripherals and receive responses.
14 n Listeners – Tasks that register for and receive notification when the specified logs/events/F3s
15 are generated.
16 n QPST polling – Allows users to run a trace to collect information on connection issues.
17 n Low Power mode – Gives non-HLOS processors the ability to buffer data for longer
18 durations without waking the apps processor, reducing the current drain on the device.

19 2.3 Diag services APIs

20 This section describes the basic diag services. Request/Response service allows the clients to send
21 commands or solicit data from DMSS/AMSS. Debug Message, Event Reporting, and Logging
22 services are configured by the external device to deliver unsolicited data from DMSS/AMSS
23 when triggered by system operation. Useful functions of the services are:
24 n Request/Response service – Enables clients to process inbound request packets from and
25 return a response packet to the external device. The client takes appropriate action for the
26 command, generates a response packet using the Packet Service API, and returns (or
27 commits) the response packet. All packets must return a response packet to the external
28 device. See [Q2] for details.
29 n Debug Message service – Debugs messaging that is conditionally compiled into the code
30 based on the default build mask or on a custom build mask specified in msgtgt.h. With MSG
31 2.0, each message is categorized first by a Subsystem ID (SSID), then by up to 32 disjoint
32 categories associated with that subsystem. See [Q2] for details.
33 n Event Reporting service – Reports events from the DMSS/AMSS to indicate actions, such as
34 state changes and configuration, related to the operating standards of the system. See [Q2] for
35 details.
36 n Logging service – Enables clients to send information to the external device when it is
37 available, rather than when requested from the external device. The external device can
38 individually configure (enable/disable) any log packet in DMSS/AMSS. See [Q2] for details.

80-NA157-61 E 11 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diagnostic Services Overview

1 2.3.1 Command service

2 This service enables clients to receive diag commands from an external device. A command
3 packet’s first byte is the command code. For subsystem commands, there are additional fields:
4 n Command code – 1 byte
5 n SSID –1 byte
6 n Subsystem command code – 2 bytes
7 n Payload – Up to 4 K - 4 bytes
8 There are single response commands and delayed response commands for which multiple
9 response packets are sent at certain intervals, e.g., modem loopback command (75 18 41 0 1 2 3)
10 can be broken down as:
11

12 Command code(1 byte): 75

13 Subsystem ID(1 byte): 18
14 Subsystem command code(2 bytes): 0 41
15 Payload: 1 2 3
16

17 Subsystem commands are discussed in subsystem ICDs, and the nonsubsystem commands are
18 explained in [Q3].

19 The packet service operates by using a dispatch table for inbound packets. The master table is a
20 list of client tables, each identified by an SSID, and a table of command code/packet handler
21 function pointer sets.
22 When it is dispatched, the client must allocate a response packet. Allocation is implemented using
23 the dedicated diag heap. If allocation is not successful, a block and retry mechanism is employed
24 until enough memory is available for the response packet. Clients should still handle the case of a
25 NULL response allocation by not sending one.
26 When it is committed, the response is placed in a queue to be serviced by the diag task at the next
27 Tx packet boundary. diagpkt_rsp_send() is called by diagbuf_drain() to dequeue and send a
28 response packet. This is done at every packet boundary to ensure that packet service response
29 packets are sent to the external device as quickly as possible. If packet service latency is greater
30 than ~2 sec, external devices may time out and assume that the connection with diag services is
31 lost. Therefore, the client should respond in less than 1 sec.
32 APIs and implementation can be found in diagpkt.h and diagpkt.c.
33 A simple example using the ESN request and response is shown in Table 2-1 and Table 2-2.

34 Table 2-1 ESN request

Field Length (bytes) Description
CMD_CODE (1/0x01) 1 According to [Q3]
35

80-NA157-61 E 12 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diagnostic Services Overview

1 Table 2-2 ESN response

Field Length (bytes) Description
CMD_CODE (1/0x01) 1 According to [Q3]
ESN 4 Electronic serial number

2 2.3.2 Debug Message service

3 The Debug Message service MSG 2.0 improves efficiency, bandwidth requirements, and filter
4 granularity. With MSG 2.0, each message is categorized first by an SSID and then by up to 32
5 disjointed categories associated with that subsystem.
6

NOTE: The following table was added to this document revision.

7 A message packet has the format shown here.

8

Field Length (bytes) Description

Command code 1 0x79
Timestamp type 1 § 0 – CDMA time
§ 1 – WIN32 (used in off-target environments)
Number of 1 Specifies the number of 32-bit arguments listed in
arguments the Arguments field below
Drop count 1 Total number of messages dropped between this
message and the previous one
Timestamp 8 Time the message was originally generated
(not transmitted)
Line number 2 Line number identifying location of the message in
the file denoted by File name
Subsystem ID 1 Subsystem identifier
Subsystem mask 4 32-bit mask with each bit denoting a category
assigned by the internal client denoted by SSID
Arguments 4*Number of arguments(s) Array of 32-bit signed arguments, corresponding to
the printf-style Formatted String
Formatted String Variable NULL-terminated ASCII string containing a
printf()-style format string, with formatting specifiers
that are replaced with the formatted contents of
Arguments in the order they are encountered;
allowed formatting specifiers are:
§ %x – Hexadecimal word display
§ %u – Unsigned Decimal word display
§ %d – Decimal word display
§ %c – Character display
§ %lx – Long (dword) hexadecimal display
§ %ld – Long (dword) decimal display
Note: Float(%f) or string(%s) types are not
supported.
File name Variable NULL-terminated ASCII filename string identifying
the location of message, such as mccdma.c
9

80-NA157-61 E 13 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diagnostic Services Overview

1 Table 2-3 shows the macros for Debug Message service MSG 2.0.

2 Table 2-3 MSG 2.0 macros

Macro Description
MSG Message with literal string; no printf(f) style arguments
MSG_N N refers to the number (1..9) of printf() style arguments in the macro
MSG_SPRINTF_N Message that calls sprintf() in the caller’s context, passing N arguments;
this is costly but allows the expansion of types such as string and float
3

4 For example, in MSG_2 (ss_id, ss_mask, fmt, arg1, arg2), ss_mask can take the values FATAL,
5 ERROR, HIGH, MED, and LOW (msg_mask.h).

6 2.3.2.1 Filtering
7 MSG 2.0 filtering uses a 32-bit mask for each SSID. Each message is filtered using a bitwise
8 AND against a MSG system mask. If the AND operation is nonzero, the message passes the
9 filter. There are two types of filtering:
10 n Build-time filtering – Each SSID has a build mask with the naming convention,
11 MSG_BUILD_MASK_<SSID name> (msgtgt.h). A MSG macro is conditionally compiled
12 into the code based on this build-time mask.
13 n Runtime filtering – Filtering is performed based on the mask set by the user in an external
14 tool, e.g., QXDM Pro.

15 Filter table
16 The external device may query the message service for a list of SSID ranges and build/runtime
17 masks for all SSIDs. When msg.c is compiled, it enables MSG_TGL_GEN prior to including
18 msgcfg.h. This declares a table to be used by the Debug Message service. This table is a list of
19 structures containing SSID ranges and pointers to build mask arrays and runtime mask arrays.
20 The external device may query all of this information. As SSIDs are added to msgcfg.h, this table
21 must also be updated.
22 Legacy macros are assigned to MSG_SSID_LEGACY (SSID 0), unless
23 MSG_BT_SSID_LEGACY is set to a valid SSID symbol.

24 2.3.2.2 F3 trace
25 F3 trace is a runtime buffer in the device’s RAM memory where F3/Debug messages can be
26 saved and retrieved later from a RAM dump. F3 trace does not support MSG_SPRINTF macros.
27 Definitions needed for this feature are:
28 n DIAG_F3_TRACE_BUFFER_SIZE – Defines the buffer size; currently set to 128 KB
29 n FEATURE_SAVE_DEBUG_TRACE – Main feature to enable F3 trace saving; must be
30 defined
31 n FEATURE_SAVE_TRACE_ON_BY_DEFAULT – Enables F3 trace saving by default when
32 NV items are not set. For example:
33 ¨ If feature is defined and NV items are set, NV item values are used.
34 ¨ If feature is not defined and NV items are not set, F3 trace is disabled.

80-NA157-61 E 14 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diagnostic Services Overview

1 ¨ If feature is enabled, the following defines can be used to further control the settings:
2 – DIAG_F3_TRACE_CONTROL_MASK_DEFAULT_VAL
3 • 0x0 – Disables F3 message saving
4 • 0x1 – Enables F3 message saving
5 – DIAG_F3_TRACE_DETAIL_MASK_DEFAULT_VAL – 8-bit bitmask (where bit 0
6 is Least Significant Bit) that controls the levels of detail of the saved F3 trace; if a bit
7 is set to 1, the information associated with that bit is saved to the buffer; bitmask
8 details are given in Table 2-4.

9 Table 2-4 Bit values for DIAG_F3_TRACE_DETAIL_MASK_DEFAULT_VAL

Bit position Information saved in buffer
7 MSG_FATAL (MSG_MASK_4)
6 MSG_ERROR (MSG_MASK_3)
5 MSG_HIGH (MSG_MASK_2)
4 MSG_MED (MSG_MASK_1)
3 MSG_LOW (MSG_MASK_0)
2 Custom MSG levels (MSG_MASK_5 to MSG_MASK_31)
1 Timestamp
0 F3 arguments

10 2.3.2.3 Qshrink
11 Qshrink reduces the memory footprint of F3 messages in target builds. Prior to Qshrink 2.0, the
12 optimization was done by maintaining a hash table for format strings and filenames. This hash
13 table was shared with QXDM Pro and used by the T32 recovery script to reconstruct the hashed
14 messages from F3 trace; e.g., a 4-byte hash is assigned to the following debug message with an
15 associated source file:
16

17 712406761:diagdiag.c:Diagpkt_alloc returned NULL in diagdiag_peekw.

18

19 Qshrink 3.0 additionally hashes the SSID, subsystem mask, and runtime mask associated with the
20 F3 message. The hash table is added to modem ELF for runtime filtering and reconstruction of
21 hashed messages. The reconstruction is currently being done by diag for QXDM Pro messages
22 (not needed for F3 trace), so no change is needed on the QXDM Pro side.

23 2.3.3 Event Reporting service

24 Static events are reported by the DMSS/AMSS to indicate actions such as state changes and
25 configuration that are directly related to the operating standards of the system. These actions are
26 common to all CDMA subscriber units, regardless of the hardware or firmware manufacturer.
27 The intent is to provide a reporting mechanism that minimizes resource usage, in particular,
28 bandwidth, and maximizes storage and transmission priority for operating information that is
29 considered most important in software test and verification.

80-NA157-61 E 15 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diagnostic Services Overview

1 This service queues reported events and packages several events to be sent in a single packet. To
2 save bandwidth, several events are reported in one packet. Time deltas are used to compress the
3 timestamp information.
4 The event service is designed to be reliable. Event packets are sent before any other unsolicited
5 diagnostic data type. Event packets are sent when the stale timer expires or the event queue
6 exceeds a configurable threshold size, which is settable in diagtune.h.
7

NOTE: The following table was added to this document revision.

8 An event packet has the format shown here.

9

Field Length (bytes) Description

Command code 1 0x60
Length 2 Length of all the subsequent fields
Event info 2 This field is further broken down as:
§ Event ID – 12 bits
§ Reserved – 1 bit
§ Payload length flag – 2 bits
§ Time length – 1 bit
ú 0 – Full system timestamp is 8 bytes
ú 1 – Truncated timestamp is 2 bytes
Time Variable Depending on Time Length
Payload Length 0 or 1 Depending if this event has any payload
Payload data Payload length bytes If this particular EVENT_ID is specified to contain
extra data, it is included in this field

10 2.3.4 Logging service

11 This service enables clients to send information to the external device when it is available, rather
12 than when the information is requested from the external device.
13 The external device can individually configure (enable/disable) any log packet in the DMSS. A
14 log packet’s size is limited only by DIAGBUF_SIZE (diagtune.h) by this service. However, due
15 to legacy reasons, some external devices cannot handle log packets larger than 1 K.
16 If resources are insufficient, the logging service is unreliable and logs may be dropped. Larger
17 packets are more likely to be dropped.
18 Log codes are disabled during initialization. The external device uses a bitmask to configure log
19 codes as on/off.
20 In log on-demand (16/0x10), the DMSS removes the oldest log item and places it in a Log
21 Response message.

80-NA157-61 E 16 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diagnostic Services Overview

NOTE: The following table was added to this document revision.

2 A log packet has the format shown here.

3

Field Length (bytes) Description

Command code 1 0x10
More 1 More log data available indicator; indicates how many
log entries (not including the one returned with this
message) are queued in diag buffer
Length 2
Length 2 Length of subsequent fields
Log code 2 Composed of:
§ Equipment identifier – Most significant 4 bits of the log
code specify the equipment ID
§ Item identifier – Least significant 12 bits of the log
code specify the log item ID within the equipment ID
Timestamp 8 System time
Payload (Length-12) Data specific to this log packet

80-NA157-61 E 17 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 3 Common Customization Examples

2 3.1 Defining a new subsystem command

3 For a full list of command service APIs, see [Q2].
4 New commands can be defined on an apps processor (Linux, TN, MN) or non-HLOS processors
5 (modem, ADSP, WCNSS) using the following process:
6 1. Write a command handler function.
7 2. Create a subsystem command table.
8 3. Register the table with diag.

9 3.1.1 Single response command

10 Single response commands have a single immediate response.

11 Modem loopback 75 18 41 0 1 2 3 example

12 1. Write a command handler function.
13 ¨ API
14

15 PACK(void *) (*func_ptr) (PACK(void *) req_pkt_ptr, uint16 pkt_len);

16

17 ¨ Sample code on the modem

18

19 #define DIAG_SUBSYS_DIAG_SERV 18
20 PACK(void *) diagdiag_subsys_loopback (
21 PACK(void *) req_pkt,
22 uint16 pkt_len
23 )
24 {
25 /* Retrieve sub-system command code from request pkt*/
26 diagpkt_subsys_cmd_code_type cmd_code =
27 diagpkt_subsys_get_cmd_code (req);
28 /* Allocate memory for response pkt */
29 diag_subsys_loopback_rsp_type *rsp =
30 (diag_subsys_loopback_rsp_type *)diagpkt_subsys_alloc
31 (DIAG_SUBSYS_DIAG_SERV, cmd_code, pkt_len);
32

80-NA157-61 E 18 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 /* Fill rsp structure */

2

3 /* Commit response pkt if it needs to be sent immediately,

4 else return 'rsp' pointer and Diag dispatcher will commit it*/
5 If(1){
6 diagpkt_commit((void *)rsp, pkt_len);
7 return NULL;
8 }
9

10 return (void *) rsp;

11 }
12

13 2. Create a subsystem command table. APSS commands are shown in Table 3-1 and modem
14 commands are shown in Table 3-2.
15 ¨ API
16

17 typedef struct
18 {
19 word cmd_code_lo; /* Minimum Command code value */
20 word cmd_code_hi; /* Maximum Command code value */
21 PACK(void *) (*func_ptr) (PACK(void *) req_pkt_ptr, uint16
22 pkt_len); /* Pointer to Function to handle the packet when command
23 code is in the range of cmd_code_lo, cmd_code_hi */
24 }
25 diagpkt_user_table_entry_type;
26

27 ¨ Sample code on the modem

28

29 #define DIAGDIAG_STRESS_TEST_SUBSYS_LOOPBACK_MODEM 0x0029 /* 41 */

30 static const diagpkt_user_table_entry_type diagdiag_subsys_tbl[] =
31 {
32 {DIAGDIAG_STRESS_TEST_SUBSYS_LOOPBACK_MODEM,
33 DIAGDIAG_STRESS_TEST_SUBSYS_LOOPBACK_MODEM, diagdiag_subsys_loopback}
34 /* can add more entries*/
35 };
36

80-NA157-61 E 19 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 3. Register the table with diag.

2 ¨ API
3

4 #define DIAGPKT_DISPATCH_TABLE_REGISTER(xx_subsysid, xx_entry) \

5 do { \
6 static diagpkt_master_table_type xx_entry##_table = { \
7 0, 0xFF, xx_subsysid, sizeof (xx_entry) / sizeof (xx_entry[0]),
8 DIAG_NO_PROC, 0, DIAGCOMM_CTRL_NO_PORT, xx_entry \
9 }; \
10 /*lint -save -e717 */ \
11 diagpkt_tbl_reg_append_proc (&xx_entry##_table); \
12 } while (0)
13 /*lint -restore */
14

15 ¨ Sample code on the modem

16

17 #define DIAG_SUBSYS_DIAG_SERV 18
18 DIAGPKT_DISPATCH_TABLE_REGISTER (DIAG_SUBSYS_DIAG_SERV,
19 diagdiag_subsys_tbl);
20

21 Table 3-1 Single response APSS command table

cmd_code SS_ID client_id cmd_lo cmd_hi process_id
255 18 0 41 41 -1
*client_id:
§ 0 – Modem
§ 1 – ADSP/LPASS
§ 2 – WCNSS
§ 3 – Apps processor

22 Table 3-2 Single response modem command table

cmd_code SS_ID cmd_lo cmd_hi Command handler
255 18 41 41 diagdiag_subsys_loopback()
23

24 After defining a new log packet, it is necessary to rebuild the code and verify that the new log
25 packet performs properly. Information on debugging the new subsystem command will be
26 provided in the next revision of this document.

80-NA157-61 E 20 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 3.1.2 Multiple response command

2 Multiple response commands have an immediate response along with one or more delayed
3 responses.

4 Modem delayed loopback 128 18 99 0 example

5 1. Write a command handler function.
6 ¨ API – Same as shown in Section 3.1.1
7 ¨ Sample code on the modem
8

9 #define DIAG_SUBSYS_DIAG_SERV 18
10 #define DIAGDIAG_STRESS_TEST_DELAYED_RSP 0x0063 /* 99 */
11 PACK(void *) diagdiag_delayed_rsp_test (
12 PACK(void *) req_pkt,
13 uint16 pkt_len
14 )
15 {
16 uint32 delayed_rsp_id = 0;
17 /* Allocates immediate response pkt for sub-system version 2 pkt
18 (cmd code 128)*/
19 diagdiag_delayed_rsp_test_rsp_type *rsp =
20 (diagdiag_delayed_rsp_test_rsp_type *)diagpkt_subsys_alloc_v2
21 (DIAG_SUBSYS_DIAG_SERV, DIAGDIAG_STRESS_TEST_DELAYED_RSP,
22 sizeof(diagdiag_delayed_rsp_test_rsp_type));
23 if(rsp) {
24 delayed_rsp_id = rsp->delayed_rsp_id; /*Set by Diag dispatcher to
25 help Tool unify all responses for this command*/
26 /* Commit immediate response pkt, or return 'rsp' pointer for
27 Diag dispatcher to commit*/
28 diagpkt_commit(rsp);
29 }
30

80-NA157-61 E 21 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 rsp = NULL;
2 /* Allocates delayed response pkt for sub-system version 2 pkt (cmd
3 code 128)*/
4 rsp = (diagdiag_delayed_rsp_test_rsp_type
5 *)diagpkt_subsys_alloc_v2_delay(DIAG_SUBSYS_DIAG_SERV,
6 DIAGDIAG_STRESS_TEST_DELAYED_RSP, delayed_rsp_id,
7 sizeof(diagdiag_delayed_rsp_test_rsp_type));
8 if(rsp) {
9 rsp->response_cnt = 1; /* should increment for each response pkt
10 sent*/
11 /* Must be called for the delayed response to be committed */
12 diagpkt_delay_commit(rsp);
13 }
14

15 return NULL;
16 }
17

18 2. Create a subsystem command table. APSS commands are shown in Table 3-3 and modem
19 commands are shown in Table 3-4.
20 ¨ API – Same as shown in Section 3.1.1
21 ¨ Sample code on the modem
22

23 #define DIAGDIAG_STRESS_TEST_DELAYED_RSP 0x0063 /* 99 */

24 static const diagpkt_user_table_entry_type diagdiag_delayed_rsp_tbl[]
25 =
26 {
27 {DIAGDIAG_STRESS_TEST_DELAYED_RSP,
28 DIAGDIAG_STRESS_TEST_DELAYED_RSP, diagdiag_delayed_rsp_test}
29 /* can add more entries*/
30 };
31

80-NA157-61 E 22 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 3. Register the table with diag.

2 ¨ API
3

4 #define DIAGPKT_DISPATCH_TABLE_REGISTER_V2_DELAY(xx_cmdcode,
5 xx_subsysid, xx_entry) \
6 do { \
7 static diagpkt_master_table_type xx_entry##_table = { \
8 1, xx_cmdcode, xx_subsysid, sizeof (xx_entry) / sizeof
9 (xx_entry[0]), DIAG_NO_PROC, 0, DIAGCOMM_CTRL_NO_PORT, xx_entry \
10 }; \
11 /*lint -save -e717 */ \
12 diagpkt_tbl_reg_append_proc (&xx_entry##_table); \
13 } while (0)
14 /*lint -restore */
15

16 ¨ Sample code on the modem

17

18 #define DIAG_SUBSYS_CMD_VER_2_F 128

19 #define DIAG_SUBSYS_DIAG_SERV 18
20 DIAGPKT_DISPATCH_TABLE_REGISTER_V2_DELAY( DIAG_SUBSYS_CMD_VER_2_F,
21 DIAG_SUBSYS_DIAG_SERV, diagdiag_delayed_rsp_tbl);
22

23 Table 3-3 Delayed response APSS command table

cmd_code SS_ID client_id cmd_lo cmd_hi process_id
128 18 0 99 99 -1
*client_id:
§ 0 – Modem
§ 1 – ADSP/LPASS
§ 2 – WCNSS
§ 3 – Apps processor

24 Table 3-4 Delayed response modem command table

cmd_code SS_ID cmd_lo cmd_hi Command handler
128 18 99 99 diagdiag_delayed_rsp_test ()
25

26 After defining a new log packet, it is necessary to rebuild the code and verify that the new log
27 packet performs properly. Information on debugging the new subsystem command will be
28 provided in the next revision of this document.

80-NA157-61 E 23 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 3.2 Defining a new log packet

2 Log packet commands are handled by the Logging Service defined in [Q2]. New log packet IDs
3 must be defined in log_codes.h. In the following example, 0x82F is the last log packet ID defined
4 in log_codes.h.
5

6 …
7 #define LOG_DATA_PROTOCOL_LOGGING_EX_C ((0x82C) + LOG_1X_BASE_C)
8 #define LOG_RF_WCDMA_LOG_V3_C ((0x82D) + LOG_1X_BASE_C)
9 #define LOG_ROHC_DECOMPRESSOR_INPUT_C ((0x82E) + LOG_1X_BASE_C)
10 #define LOG_ROHC_COMPRESSOR_OUTPUT_C ((0x82F) + LOG_1X_BASE_C)
11

12 /* The last defined DMSS log code */

13 #define LOG_1X_LAST_C ((0x82F) + LOG_1X_BASE_C)
14

15 To add a new log packet, add it to the list of defines and update LOG_1X_LAST_C to specify the
16 last log packet ID. The following example shows the addition of 0x830.
17

18 …
19 #define LOG_DATA_PROTOCOL_LOGGING_EX_C ((0x82C) + LOG_1X_BASE_C)
20 #define LOG_RF_WCDMA_LOG_V3_C ((0x82D) + LOG_1X_BASE_C)
21 #define LOG_ROHC_DECOMPRESSOR_INPUT_C ((0x82E) + LOG_1X_BASE_C)
22 #define LOG_ROHC_COMPRESSOR_OUTPUT_C ((0x82F) + LOG_1X_BASE_C)
23 #define LOG_FOO_TEST_C ((0x830) + LOG_1X_BASE_C)
24

25 /* The last defined DMSS log code */

26 #define LOG_1X_LAST_C ((0x830) + LOG_1X_BASE_C)
27

28 The following code sample illustrates the use of the new log packet:
29

30 #include "log.h"
31 #include "log_codes.h"
32

33 typedef struct
34 {
35 log_hdr_type xx_header; /* place holder */
36 int param; /* parameter */
37 int task_pri; /* task priority */
38 } foo_log_type;
39

80-NA157-61 E 24 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 void foo_test (uint32 param)

2 {
3 foo_log_type *log = NULL;
4 log = (foo_log_type *) log_alloc (LOG_FOO_TEST_C, sizeof
5 (foo_log_type));
6

7 if (log != NULL)
8 {
9 log.foo1 = param;
10 log.foo2 = rex_get_pri ();
11 log_commit (log);
12 }
13 }
14

15 After defining a new log packet, it is necessary to rebuild the code and verify that the new log
16 packet performs properly.

17 3.3 Defining a new event report

18 Commands are handled by Event Service defined in [Q2]. Event IDs must be defined in
19 event_defs.h. In the following example, 0x9D8 is the last event defined in event_defs.h.
20

21 …
22 EVENT_PM_UE_MODE = 0x9D6,
23 EVENT_TDSCDMA_SELF_HOSTING = 0x9D7,
24 EVENT_LTE_ML1_SEARCH_IDLE = 0x9D8,
25

26 EVENT_LAST_ID = 0x9D8,
27 EVENT_NEXT_UNUSED_EVENT,
28

29 To add a new event, add it to the list of defines and update EVENT_LAST_ID to specify the last
30 event ID. The following example shows the addition of 0x9D9:
31

32 …
33 EVENT_PM_UE_MODE = 0x9D6,
34 EVENT_TDSCDMA_SELF_HOSTING = 0x9D7,
35 EVENT_LTE_ML1_SEARCH_IDLE = 0x9D8,
36 EVENT_FOO = 0x9D9,
37

38 EVENT_LAST_ID = 0x9D9,
39 EVENT_NEXT_UNUSED_EVENT,
40

80-NA157-61 E 25 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 The following code sample illustrates the use of the new event:
2

3 #include "event.h"
4 #include "event_defs.h"
5

6 void foo (void)

7 {
8 /* ... */
9

10 event_report (EVENT_FOO);
11

12 /* ... */
13 }
14

15 After defining an event report, it is necessary to rebuild the code and verify that the new event
16 report performs properly.

17 3.4 Defining new SSIDs and using them in F3s

18 Commands are handled by Debug Message Service defined in [Q2]. This section describes the
19 API functions needed to define new SSIDs and use them in F3s.
20 The available range of SSIDs are defined in msgcfg.h. The SSIDs within this range will never be
21 used by QTI.
22

23 #define MSG_FIRST_TARGET_OEM_SSID (0xC000)

24 #define MSG_LAST_TARGET_OEM_SSID (0xCFFF)
25

26 In msgtgt.h, define the mask for the new SSID. In the following example,
27 MSG_BUILD_MASK_MSG_SSID_FOO is defined as a new mask:
28

29 …
30 #if 1
31 #define MSG_BUILD_MASK_MSG_SSID_FOO (MSG_LVL_MED | 0x00ff00)
32 #endif
33

80-NA157-61 E 26 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Common Customization Examples

1 The following code sample illustrates the use of the new SSID:
2

3 #include "msg.h"
4 #include "msgcfg.h"
5

6 void foo_test (int parm)

7 {
8 int param1, param2, param3 = 0;
9 MSG_3 (MSG_SSID_FOO, MSG_LEGACY_HIGH,
10 "MSG_3 param1 %d param2 %d param3 %d \n",
11 param1, param2, param3);
12 }
13

14 After adding a new SSID, it is necessary to rebuild the code to verify that the new SSID is
15 registered.
16

80-NA157-61 E 27 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 4 On-Device Logging

2 On-device logging allows diagnostic traffic to be saved to a memory device, i.e., SD card or
3 eMMC. It can be used in field testing when connecting the device to a workstation or laptop is
4 undesirable. Later on, host PC tools can be used to process the logged items files.
5 On-device logging uses circular logging, which allows logging to continue even if the device runs
6 out of memory. When the device runs out of memory, the application deletes the oldest log file to
7 create free space and continues logging. With each deletion of a file, the application prints the log
8 filename and size of the log file (in KB) that was deleted to create space. The deleted logs are not
9 recoverable.

10 4.1 Running on-device logging (diag_mdlog)

11 Two methods can be used to run the on-device logging (diag_mdlog) application:
12 n From an ADB shell with the device connected via USB
13 n On the device using the Qualcomm Settings menu; no USB connection is required

14 4.1.1 Running diag_mdlog using ADB

15 1. Plug in the device via USB.
16 2. Open an ADB command shell.
17 3. Navigate to the SD card directory and run the following command to ensure that the SD card
18 is mounted on the device:
19

20 ls
21

22 When the SD card is mounted on the device, a list of files present on the SD card appears. If a
23 list of files does not appear, reboot the phone and repeat this step. It takes approximately
24 10 sec for the card to get mounted after power-up.
25 4. Once the SD card is mounted, push the mask configuration file to the device.
26

27 adb push <path to Diag.cfg> /sdcard/diag_logs/

28

29 5. Run the logging application.

30

31 /system/bin/diag_mdlog
32

33 Log files are created under the directory /sdcard/diag_logs/.

80-NA157-61 E 28 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 Table 4-1 gives the available options with the diag_mdlog application.

2 Table 4-1 Options available with diag_mdlog application

Argument Function
-f Path and mask filename for MSM™ and APQ targets
-m Path and mask filename for MDM targets
-l Name of file containing the list of mask files
-o Name of the output directory
-s Maximum log file size in MB
-w Waiting for directory
-n Maximum log file number
-k Kill existing instance of diag_mdlog
-c Send mask cleanup to modem at exit
-d Disable console messages
-e Run using wakeup source to keep apps processor on
-b Have peripherals buffer data and send data in nonreal-time
-h Usage help; prints a list of these arguments

3 Syntax example
4

5 diag_mdlog -f <mask_file name> -o <output dir> -s <size in MB> -c

6

7 4.1.2 Running diag_mdlog on the device

8 1. In the phone UI, navigate to Settings→Qualcomm Settings.
9 2. Select the option to enable on-device logging to route traffic to the SD card on the phone.
10 Clearing this option switches the traffic back to USB logging.

11 4.2 Troubleshooting SD card issues

12 If the SD card is not present when the app is launched, the app displays “file open error.” In
13 addition, the following issues can occur when the SD card is removed:
14 n If the SD card is removed during logging, the Android™ OS kills the logging app because it
15 has an open file handle to the SD card that no longer exists. In such cases, the current open
16 file may or may not get corrupted.
17 n If the SD card is removed and reinserted, the device does not always detect the SD card
18 because polling for the SD card is disabled in the default configuration to save power.
19 Always ensure that the card is properly mounted before launching the app.

80-NA157-61 E 29 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 4.3 Converting .qmdl files to .isf for use in QXDM

2 All diag traffic is written to diag_log_<num>.qmdl files in the folder /scard/diag_logs/ on the SD
3 card. The .qmdl files can be read back using QCAT and converted for use in QXDM Pro.
4 To convert a .qmdl file to an .isf file for viewing in QXDM Pro:
5 1. Load the .qmdl file in QCAT and save it as a .dlf file.
6 2. Use Tools→DLF File Converter (bundled with QXDM Pro) to convert from .dlf to .isf.

7 4.4 Diag masks

8 With on-device logging, to enable Diag packet masks on each processor:
9 1. Generate a file containing all mask information from QXDM Pro.
10 2. Place this file in the diag_logs folder on the SD card.
11 When working with diag masks in QXDM Pro, Filtered View must be used. However, multiple
12 instances of Filtered View, or other views, may remain open at the same time. Saving diag masks
13 in QXDM Pro does not require a device connection.

14 4.4.1 Creating a mask config (.cfg) file

15 1. Launch QXDM Pro.
16 2. Masks are loaded only from Filtered View. Use one of the following options to select Filtered
17 View:
18 ¨ Press F12.
19 or
20 ¨ Select View→New→Common→Filtered View.
21 3. Right-click the Filtered View pane and select Config.

22
23

24 4. Select the desired Log/Event/Message (F3) masks.

80-NA157-61 E 30 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 5. In the SD Logging drop-down list, select Save Diag masks for Stream 1 and click OK.

2
3

4 A dialog appears for saving the .cfg file.

5 NOTE: Stream 2 is intended for an obsolete feature and should not be used.

6 6. Enter a filename or keep the system-generated one and click Save. A diag.cfg file, e.g.,
7 DIAG_test1.cfg, is generated in the C:\Users\Public\Documents\Qualcomm\QXDM\
8 ISF\DIAG directory.

9 NOTE: It is not necessary to close QXDM Pro before generating another config file, although there is no
10 harm in doing so. Closing QXDM Pro after generating a config file does not result in deletion of
11 a saved file.

80-NA157-61 E 31 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 4.4.2 Loading a mask config (.cfg) file in QXDM Pro

2 1. Launch QXDM Pro.
3 2. It is necessary to disconnect the device before proceeding. Check the device and disconnect it
4 from the PC, if necessary.
5 3. Masks are loaded only from Filtered View. Use one of the following options to select Filtered
6 View:
7 ¨ Press F12.
8 or
9 ¨ Select View→New→Common→Filtered View.

10
11

12 4. Right-click the Filtered View pane and select Config.

13
14

80-NA157-61 E 32 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 5. In the SD Logging drop-down list, select Load Diag masks for Stream 1.

2
3

4 A dialog appears for saving the .cfg file.

5 NOTE: Stream 2 is intended for an obsolete feature and should not be used.

6 6. From the file dialog that appears, select an existing diag.cfg file and click Open.

7
8

80-NA157-61 E 33 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 The diag masks from the chosen stream are loaded and displayed.

3 4.4.3 Saving diag stress test command requests

4 Diag stress testing allows checking the health of each service, such as F3s, logs, and events on
5 each processor. QXDM Pro can be used to append such a command request to a .cfg file.
6 For example, to check the health of F3 service on the modem processor, the command is:
7

8 75 18 0 0 1 0 0 0 1 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0
9

80-NA157-61 E 34 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 To save a diag stress test command into a .cfg file:

2 1. Launch Item Tester bundled with QXDM Pro.
3 2. Expand Subsystem Dispatch Request in the Item pane and scroll down to subsystem [18]
4 Diagnostic Services.

5
6

7 The name of the diag stress test request displays in the QXDM Pro Command Example status
8 bar.

9
10

11 3. On the Field Packing tab, tune the command parameters.

12
13

80-NA157-61 E 35 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 4. To append the command to an existing diag.cfg file:

2 a. Click Save to “Diag.cfg”.
3

4
5

6 b. Select the applicable .cfg file and click Open. The subsystem command automatically
7 appends to the end of the selected file.
8 Note that this dialog is displayed only if a diag stress test subsystem was selected.

10 NOTE: If there are no .cfg files in the folder, see Section 4.4.1 for instructions on creating a .cfg file.

80-NA157-61 E 36 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 4.4.4 Saving diag task profile requests

2 Diag task profiling requests allow system-level tasks and per-task profiling logs to be viewed. See
3 [Q7] for information on configuring this feature. To save task profile requests into the diag.cfg
4 file:
5 1. Launch QXDM Pro.
6 2. Open either the MPU or APU task profiling display. From the View drop-down, go to
7 Common→Task Profiling→Task Profiling MPU or Task Profiling APU and click Config.

80-NA157-61 E 37 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 3. Select Intervals and click Save Req to “DIAG.cfg”.

2
3

80-NA157-61 E 38 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 4. When the Save the request to... dialog appears, select a diag.cfg file and click Open:

2
3

4 5. Click OK in the Config dialog. The Task Profile subsystem requests are automatically saved
5 in the selected diag config file.

6
7

8 NOTE: If there is no diag.cfg file in the folder, see Section 4.4.1 for instructions on creating a .cfg file.

9 4.5 Low power modes

10

NOTE: This section was added to this document revision.

11 In the default design, non-HLOS processors frequently drain packets to the communication layer
12 and hence to the apps processor. This results in too many wake-ups for the apps processor,
13 causing high current drain for the device. Non-HLOS processors have the ability to buffer data
14 for longer durations, reducing the current drain on the device.
15 When there is more than one client in the system, a client opting for real-time data is not
16 suppressed by a client opting for Non-Real-Time (NRT) data. The clients vote for their desired
17 mode and the apps processor diag makes a decision on the final mode, considering all the active
18 diag clients (DCI and different logging modes) and the state of USB connection.
19 The APIs for voting for Real-Time and NRT/Buffering modes are provided for the diag and DCI
20 clients.

80-NA157-61 E 39 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 4.5.1 NRT/Buffering
2 In NRT mode, there are very few apps processor wake-ups. If there are no other active processes
3 running, it might go to power collapse, and hence the diag driver would drop packets to be sent to
4 user space.
5 To prevent the system from power collapse, the diag driver notifies the Power Management core
6 that a wake-up event is being processed by acquiring a wake-up source object. The diag driver
7 acquires the wake-up source in the SMD-notify context and holds the wake-up source until the
8 data is copied to the user space library. Once the data reaches the user space, the diag library
9 signals the client to release the acquired wake-up object. It is then the client’s responsibility to
10 acquire and release a new wake-up source(s) within their app to process the data.
11 When NRT or Buffering mode is selected on a processor, the diag drain timer is set to a larger
12 value along with the buffer threshold adjusted to hold more data before forwarding it to the apps
13 processor. When a USB is connected, power consumption is already high and there is no
14 significant savings in power. APIs are provided for diag and DCI clients to achieve these power
15 savings, giving similar results to running on-device logging with a –b (buffering) argument:
16

17 int diag_vote_md_real_time(int real_time);

18

19 This function is used for the diag client. It accepts parameters MODE_REALTIME or
20 MODE_NONREALTIME and returns 0 for success.

21 4.5.2 Real-Time mode

22 This function is used for the diag client. It accepts a pointer to store the real-time value and
23 returns 0 for success.
24

25 void diag_get_real_time_status(int *real_time);

26

80-NA157-61 E 40 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 4.6 Initializing diag_mdlog at boot time

2

NOTE: This section was added to this document revision.

3 The diag_mdlog on-device logging application can also be started at boot time, without ADB
4 shell command intervention. To start diag_mdlog at boot time, the following code changes must
5 be made and the code recompiled.

6 4.6.1 Required code changes for initializing diag_mdlog at boot time

7 If you are viewing this document using a color monitor, or if you print this document to a color
8 printer, red boldface indicates code that is to be added.

9 MSM8960
10 File: /system/core/rootdir/init.rc
11 At the end of the file, add the code shown below.

service diag_mdlog /system/bin/diag_mdlog –f /data/Diag.cfg –o

/data/diag_logs/test1 &
class main
user root
group log system sdcard_rw
oneshot #for running only once
12 At least three levels of directories are needed for the -o argument. The first two directories should
13 already be present and the third is created by the app.

14 APQ8064+MDM9x15
15 Make the same changes as on MSM8960 above.
16 If logs from MDM are missing, try the following change in diag_mdlog.c:

/* Main Function. This initializes Diag_LSM, sets up On Devic ec Logging,

then exits. */
int (main(int argc, char *argv[])
{
boolean bInit_Success = FALSE;
. . .

/* Read mask file to tell On Device Logging what you are interested in */
sleep(10);
diag_read_mask_file();
. . .
}
17

80-NA157-61 E 41 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 On-Device Logging

1 MDM9x15
2 Add a diag_mdlog bash script such as the following.

#! /bin/sh

set -e

case "$1" in
start)
echo -n "Starting diag_mdlog: "
start-stop-daemon -S -b -a /usr/bin/diag_mdlog -- -f /data/all_logs.cfg
-o /data/diag_logs
echo "done"
;;
stop)
echo -n "Stopping diag_mdlog: "
start-stop-daemon -K -n diag_mdlog
echo "done"
;;
restart)
$0 stop
$0 start
;;
*)
echo "Usage diag_mdlog { start | stop | restart }" >&2
exit 1
;;
esac

exit 0
3

4 Linux services can be started, stopped, and reloaded with the use of scripts stocked in /etc/init.d/.
5 However, during startup or when changing run level, those scripts are searched as follows in
6 /etc/rcX.d/, where X is the run level number.
7 1. Push the above script in /etc/init.d/.
8 2. Add symlinks to this script in /etc/rc?.d/.

#update-rc.d diag_mdlog defaults 100

9

80-NA157-61 E 42 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1 5 Socket Logging

2 The socket logging feature provides diagnostic traffic over Ethernet and Wi-Fi. If the device has
3 Ethernet/Wi-Fi enabled, it can be connected to QPST and QXDM Pro to fetch diag packets
4 similar to other logging methods. The architecture for socket logging is shown in Figure 5-1.

6 Figure 5-1 Architecture for socket logging

80-NA157-61 E 43 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Socket Logging

1 5.1 Initial setup

2 The Android phone must be set up to Rx and Tx data to the network. This behavior can be
3 verified by using the ping command with the PC and Android phone IP addresses as described in
4 Section 5.1.1 and Section 5.1.2.

5 5.1.1 Ping device from PC

6 Use the netcfg command to get the Android phone’s Wi-Fi/Ethernet device status and IP address.
7

8 C:\Users\johndoe>ping 10.73.82.37
9 Pinging 10.73.82.37 with 32 bytes of data:
10 Reply from 10.73.82.37: bytes=32 time=76ms TTL=55
11 Reply from 10.73.82.37: bytes=32 time=100ms TTL=55
12 Reply from 10.73.82.37: bytes=32 time=122ms TTL=55
13 …

14 5.1.2 Ping PC from device

15 Use the ipconfig command to get the Window’s machine Wi-Fi/Ethernet device IP address.
16

17 root@android:/ # ping 10.73.46.115

18 ping 10.73.46.115
19 PING 10.73.46.115 (10.73.46.115) 56(84) bytes of data.
20 64 bytes from 10.73.46.115: icmp_seq=1 ttl=63 time=84.9 ms
21 64 bytes from 10.73.46.115: icmp_seq=2 ttl=63 time=97.8 ms
22 64 bytes from 10.73.46.115: icmp_seq=3 ttl=63 time=108 ms
23 …

80-NA157-61 E 44 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Socket Logging

1 5.2 Application usage

2 5.2.1 Running the diag_socket_log application

3 1. Plug in the device via USB.
4 2. Open an ADB command shell as root.
5 3. Run the following command:
6

7 diag_socket_log –a <IP address of PC> -p <port number> -r <number of

8 retries to connect> &
9

10 Table 5-1 lists the diag_socket_log command arguments.

11 Table 5-1 diag_socket_log command arguments

Argument Function
–a IP address
–p Port number; defaults to 2500
–r Number of retries for connect; defaults to 10000, with a 2 sec wait between tries
–k Kill existing instance of diag_socket_log
–h Usage help; prints a list of these arguments

12 NOTE: -a is required; -p and -r are optional.

13 Note that appending an & to the command causes the application to run in the background, which
14 allows the application to keep running when the USB cable is disconnected.

15 5.2.2 Stopping the diag_socket_log application

16 1. Determine the process ID of diag_socket_log.
17

18 # ps
19

20 2. Kill the process with the following command:

21

22 # kill -9 <diag_socket_log process id>

23

24 When the diag_socket_log app exits, diag functionality returns to the default USB configuration.

80-NA157-61 E 45 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Socket Logging

1 5.3 QPST configuration

2 If QPST/QXDM Pro/Qualcomm Tools are being used, QPST must be set up to accept client
3 connections. In QPST Configuration:
4 1. Click the IP Server tab.
5 2. On the IP Server screen, select the Accept client connections checkbox. This screen also
6 displays the IP address of the machine in use.
7 When running diag over sockets, the QPST Configuration Ports screen should display the
8 following:
9 n The USB port currently connected to should change to “No Phone.”
10 n A port with a number in the 30000 range is created. This is the port that QPST uses for the
11 network connection. The display should change from “No Phone” to the string associated
12 with the device. If QXDM Pro is being used, connect to this port.
13 n After stopping diag over sockets, the 30000 port should change back to “No Phone” and the
14 USB port that was used should change from “No Phone” back to the string associated with
15 the device.
16

80-NA157-61 E 46 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 6 UART Logging

2 UART logging refers to getting diag packets over a UART device. The device can be connected
3 to QPST/QXDM Pro via UART, and traffic can be fetched similar to other logging methods.

4 6.1 Application usage

5 The diag_uart_log application routes diag traffic to and from a UART port. The application reads
6 diag packets from a diag driver and writes the packets to the UART port. It reads packets from
7 QPST/QXDM Pro over UART and sends the packets to the diag driver.
8 To use diag over UART, neither the kernel nor any application should use or perform an
9 operation on the UART port of the phone.

10 6.1.1 Running the diag_uart_log application

11 1. Ensure that the code changes described in Section 6.2 have been done and that the code is
12 recompiled.
13 2. Plug in the device via USB.
14 3. Open an ADB command shell.
15 4. Run the following command:
16

17 diag_uartlog –d <device node> -o <Out baud rate> -i <In baud rate>

18

19 Table 6-1 lists the diag_uart_log command arguments.

20 Table 6-1 diag_uart_log command arguments

Argument Function
-d UART device node; default is /dev/ttyHSL0
-o Output baud rate; default is 115200
-i Input baud rate; default is 115200
-p Logging processor type; kills previous instance of application running on previous
processor type and starts routing diag traffic from given processor type to QXDM Pro;
acceptable values are:
§ MSM (default) – Both MSM and APQ targets take this value
§ MDM
§ QSC
-h Usage help; prints a list of these arguments
21

80-NA157-61 E 47 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 UART Logging

1 6.1.2 Fused target enhancements

2 The following enhancements were made for QTI fused architecture targets:
3 n Separation of traffic from local (MSM) and remote (MDM) processors
4 n Runtime selection of processor for diag traffic, i.e., a user can select a processor for
5 diag→diag traffic and the processor can be switched at runtime as indicated in Table 6-1.

6 6.1.3 Examples
7 n The user can start the application with MSM, MDM, or QSC traffic as follows:
8

9 /system/bin/diag_uart_log -p MSM <Starting UART log for MSM traffic>

10

11 This instance of the UART application kills the previous instance of the UART application
12 running with a processor type as MDM/QSC and starts routing diag traffic from
13 MSM→QXDM Pro.
14 n To switch to the remote (MDM, MDM2, etc.) processor, start the UART application in
15 another shell with the processor option as MDM:
16

17 /system/bin/diag_uart_log -p MDM <Starting UART log for MDM traffic>

18

19 This instance of the UART application kills the previous instance of the application running
20 with an MSM/QSC processor type and starts routing diag traffic from MDM→QXDM Pro.
21 n To switch to the remote QSC processor, start the UART application in another shell with
22 QSC as a processor option:
23

24 /system/bin/diag_uart_log -p QSC <Starting UART log for QSC traffic>

25

26 This instance of the UART application kills the previous instance of the application running with
27 an MSM/MDM processor type and starts routing diag traffic from QSC→QXDM Pro.

80-NA157-61 E 48 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 UART Logging

1 6.2 Required code changes for enabling UART logging

2

NOTE: This section was added to this document revision.

3 The apps processor serves as master in the diag central routing architecture. All slave processors
4 (modem, ADSP, and WCNSS) forward their diag traffic to the apps processor, which then pushes
5 the traffic over the USB or UART channels.
6 The modem processor can have a standalone diag configuration as well, i.e., only modem diag
7 traffic is pushed out of the device. This can be done by configuring a UART device on the
8 modem to support diag services. Hence, a UART device can be configured either on the apps
9 processor or modem processor for diag services.
10 Make sure that the GSBI or BLSP device pins being used on the configured processor are not
11 being used on any other processor or by some client other than diag services.

12 6.2.1 TN builds – MDM9x15, MDM9x25, MDM9x35

13 All of the following configurations set the UART1 device for diag services. Check the UART
14 configuration files for the physical GSBI (custsio_9x15.h) or BLSP (uart/build/SConscript)
15 device mapped to UART 1. Diag uses low speed UART with a baud rate of 115200 bps.

16 6.2.1.1 Configuring UART on the apps processor

17 If you are viewing this document using a color monitor, or if you print this document to a color
18 printer, red boldface indicates code that is to be added, and blue strikethrough indicates code
19 that is to be replaced or removed (if present).

20 Changes required in apps build

21 In cust<build_flavor>.h (\apps_proc\build\ms):

define FEATURE_FIRST_UART

define FEATURE_DMOV_HS_UART_ON_APPS

define FEATURE_RDEVMAP_DIAG_DEFAULT_TO_USB
define RDM_USB_SER1_INIT_SRVC RDM_DIAG_SRVC
define RDM_UART1_INIT_SRVC RDM_DIAG_SRVC

define FEATURE_DIAG_MP_MASTER_APPS
define FEATURE_DIAG_MP_MASTER_MODEM
define FEATURE_DIAG_MP_MODEM_ONLY

define DIAG_RUNTIME_DEVMAP

22 Changes required in modem build

23 None

80-NA157-61 E 49 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 UART Logging

1 6.2.1.2 Configuring UART on modem processor

2 Changes required in apps build

3 In cust<build_flavor>.h (\apps_proc\build\ms):

define FEATURE_RDEVMAP_DIAG_DEFAULT_TO_USB
define RDM_USB_SER1_INIT_SRVC RDM_DIAG_SRVC

define FEATURE_DIAG_MP_MASTER_APPS
define FEATURE_DIAG_MP_MASTER_MODEM

define FEATURE_DIAG_MP_MODEM_ONLY
define DIAG_RUNTIME_DEVMAP

4 Changes required in modem build

5 In cust<build_flavor>.h (\modem_proc\build\ms):

define FEATURE_FIRST_UART

define FEATURE_DIAG_MODEM_ONLY

define RDM_UART1_INIT_SRVC RDM_DIAG_SRVC

define DIAG_RUNTIME_DEVMAP

6 6.2.2 LE/LA builds

7 In the reference design, UART might be getting used by the apps boot loader (little kernel) or the
8 kernel for debugging over a serial console. Disable this use of UART before using it for diag
9 logging.

10 6.2.2.1 Configuring UART on the apps processor

11 Changes required in apps build

12 None, however, this script uses UART1, so be sure to disable the console before running the
13 application as described in Chapter 6 of [Q2].

14 Changes required in modem build

15 None

80-NA157-61 E 50 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 UART Logging

1 6.2.2.2 Configuring UART on the modem processor

2 Changes required in apps build

3 None

4 Changes required in modem build

5 In cust<build_flavor>.h (\modem_proc\build\ms):

define FEATURE_FIRST_UART

define FEATURE_DIAG_MODEM_ONLY

define RDM_UART1_INIT_SRVC RDM_DIAG_SRVC

define DIAG_RUNTIME_DEVMAP
6

7 6.3 Tools tested

8

NOTE: This section was added to this document revision.

9 The UART configurations have been tested to work with the following tools:
10 n QXDM Pro
11 n QPST NV Backup/Restore
12 n EFS Explorer
13 n QSPR

14 6.4 Limitations
15 Due to UART throughput, QPST may lose the port connection in heavy traffic. QPST only waits
16 400 ms for any command/response, including polling. Because of a throughput bottleneck, the
17 response is delayed and reaches QPST after 2 to 3 sec.
18 If a port disconnection issue is observed during diag over UART logging:
19 n Update QPST register settings
20 n Configure QPST and QXDM Pro for the new settings
21 The default QPST port parameter settings are:
22 n Polling timeout duration – 400 ms
23 n Polling timer interval – 600 ms
24 n Polling maximum retries – 3

80-NA157-61 E 51 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 UART Logging

1 When experiencing a port disconnect, these values can be increased:

2 n Polling timeout duration – 3000 ms
3 n Polling timer interval – 3000 ms
4 n Polling maximum retries – 5
5 If a port disconnection issue is observed during diag over UART logging:
6 1. Ensure that both QPST and QXDM Pro are closed.
7 2. Two options are available for making the required registry changes to resolve the port
8 disconnection issue.
9 ¨ Create and run a Windows Registry file (.reg) with the following contents:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\Software\Qualcomm\QPST\PARAMS\PORT_SERVER]
"polling_timeout_ms"=dword:00000bb8
"polling_timer_interval_ms"=dword:00000bb8
"polling_max_tries"=dword:00000005

[HKEY_CURRENT_USER\Software\Qualcomm\QPST\PARAMS\PORT_SERVER]
"polling_timeout_ms"=dword:00000bb8
"polling_timer_interval_ms"=dword:00000bb8
"polling_max_tries"=dword:00000005

10 or
11 ¨ Manually change the registry setting for QPST, i.e., the timeout, polling interval, and
12 number of retries.
13 – Go to regedit, to the path [HKEY_LOCAL_MACHINE\Software\Qualcomm\
14 QPST\PARAMS\PORT_SERVER], and update the configuration values.
15 • polling_timeout_ms – 3000 ms
16 • polling_timer_interval_ms – 3000 ms
17 • polling_max_tries – 5
18 – Go to regedit, to the path [HKEY_CURRENT_USER\Software\Qualcomm\
19 QPST\PARAMS\PORT_SERVER], and update the configuration values.
20 • polling_timeout_ms – 3000 ms
21 • polling_timer_interval_ms – 3000 ms
22 • polling_max_tries – 5

80-NA157-61 E 52 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 UART Logging

1 To configure QPST and QXDM Pro:

2 1. Start QPST.
3 2. Right-click the COM port in QPST, select the baud rate option, and update the baud rate to
4 230400.
5 3. If a target was previously connected over USB and connected to QXDM Pro, disable the logs.
6 This ensures that if many masks were enabled with USB, after the UART app restarts, data is
7 pumped to the UART, disabling the unwanted masks.
8 4. Start diag over the UART app with the following command:
9

10 ./diag_uart_log –p <proc name> -i 230400 –o 230400

11

12 5. Start QXDM Pro and set the mask per the requirement. However, this should be kept minimal
13 and use only required logs. Wait for the target to be enumerated in QPST over the UART
14 port. This may take additional time because the QPST parameters were changed.
15 6. Connect QXDM Pro to the device over the COM port.
16 7. In this configuration, runtime switching does not work because QPST needs time for the port
17 to be reenumerated due to the change in parameters. To change the logging processor:
18 a. Disconnect QXDM Pro.
19 b. Kill the diag_over_uart app. Wait for the target to be enumerated on USB (all ports) and
20 to disappear from the UART port. This takes time due to the change in the QPST port
21 parameter.
22 c. Start the UART app with the desired processor by repeating steps 4 through 6.
23

80-NA157-61 E 53 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 7 Diag Consumer Interface

NOTE: Numerous changes were made in this chapter.

3 NOTE: This chapter is not applicable for APQ or MDM targets.

4 7.1 Overview
5 The DCI allows a client application to inject command requests; to set logs and events masks on
6 the peripheral processor; and receive back command responses, log packets, and event reports on
7 the apps processor. The existing diag communication with PC Tools has not changed. Therefore,
8 this interface can be used simultaneously with the existing use of QXDM Pro/On-Device
9 Logging.
10 A new SMD data channel is opened to handle DCI traffic. The apps processor Diag Router
11 manages the traffic between the peripheral processors and individual clients. Figure 7-1 is an
12 architectural diagram of DCI.

13

14 Figure 7-1 Diag consumer services overview

80-NA157-61 E 54 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diag Consumer Interface

1 7.2 Initialization
2 A client application must call Diag_LSM_Init() to access the diag user space library/LSM API.
3 This call creates a read thread for the client application. While this read thread performs all read
4 operations with the kernel driver and is internal to the diag library, the main client application
5 thread is responsible for write operations such as sending command packets, masks, etc.
6 The client must register with DCI, via the LSM layer, to receive a handle for using any of the
7 DCI services.
8 As part of the initialization process, a client may also register a signal callback and indicate the
9 peripherals for which it must receive state change notification. This notification can be triggered
10 by the opening or closing of a peripheral’s DCI channel (as shown in Figure 7-2), which can be
11 caused by events such as a Subsystem Restart (SSR). The kernel driver keeps track of all DCI
12 clients with the corresponding peripheral mask, signal information, and log/event masks for each
13 client.
14 Figure 7-2 shows the call flow.

Client Peripheral
Apps Kernel
Application Processor

Register DCI Client

[handle]

(If DCI channel is closed)

Trigger Callback

Deregister DCI Client

[ACK]

15

16 Figure 7-2 Call flow for initialization

80-NA157-61 E 55 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diag Consumer Interface

1 7.3 Command/response packets

2 This service allows a client application to originate a diag command request and receive a
3 response. The request packets are handled by the diag kernel driver and routed to the non-HLOS
4 processor that has registered with diag to receive that command. If that processor does not have a
5 DCI channel open or does not support DCI, then an error code is returned. Likewise, if the
6 command is not registered with diag, another error code is returned.
7 The client application must send a command request in raw byte format using the async
8 command send function described in [Q6].
9 The format of the command packets and their corresponding responses are described in [Q3].
10 Command/response packets supported by specific technology areas are documented in various
11 Interface Control Documents (ICDs), e.g., [Q14].

12 NOTE: Unlike command/response packets sent over the primary diag data stream, those sent over the
13 DCI channel are not High-Level Data Link Control (HDLC)-encoded.

14 Figure 7-3 shows the call flow.

Client Client
Peripheral
Application Application Apps Kernel
Processor
(main thread) (LSM read thread)

Send Command Packet

Forward Command Packet
Register command
response callback with
LSM Layer

In sleep state

Process incoming packet Send Command Response

and wake up client

Trigger command
callback

15

16 Figure 7-3 Call flow for command request/response service

80-NA157-61 E 56 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diag Consumer Interface

1 7.4 Logs and events

2 A DCI client can configure masks for logs and events and register corresponding callbacks to be
3 called on their receipt. The client must not include complex processing in these callback
4 functions, since that can lead to packets eventually being dropped on non-HLOS processors. It
5 could buffer the received packets for later processing.
6 The diag kernel router maintains mask information for every DCI client so it can route a packet
7 coming from the peripheral to the matching DCI clients. In Figure 7-4, LSM refers to the read
8 thread for a client application that is created on the Diag_LSM_Init() call. While the main client
9 thread is used for writing data, this LSM read thread is used for reading data from the kernel
10 driver.
11 The individual log records and event reports are formatted as outlined in [Q3]. Information on
12 how logs are encapsulated as a Log Response message and events are encapsulated in event
13 reports is provided.

14 NOTE: Unlike log and event packets sent over the primary diag data stream, packets sent using the DCI
15 are not HDLC-encoded.

16 Figure 7-4 shows the call flow.

Client Client
Peripheral
Application Application Apps Kernel
Processor
(main thread) (LSM read thread)

Register log/event
callbacks with LSM layer
Set log/event masks
Send log/event masks

In sleep state

Process log/events Log packets/event reports

and wake up client

Trigger log/event
callbacks

17

18 Figure 7-4 Call flow for logs/events services

19 7.5 Limitations
20 Currently, DCI support is available on both the modem and apps processors.
21 DCI does not currently support diag debug/F3 messages.

80-NA157-61 E 57 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diag Consumer Interface

1 7.6 Sample application

2 The sample application /diag/dci_client/diag_dci_sample.c demonstrates using the DCI API
3 functions. The operations performed by the application include:
4 n Registering for the DCI
5 n Registering for DCI connection update
6 n Enabling logs
7 n Sending commands
8 n Receiving responses
9 n Receiving logs
10 n Parsing and printing logs and responses to the console and/or sending to a text file
11 n Disabling some logs
12 n Continuing to receive and parse the enabled logs
13 n Deregistering with DCI
14 n Closing

15 7.6.1 Usage
16 Run the sample app using /system/bin/diag_dci_sample.

17 7.6.2 Parsing
18 The sample application has logic to partially parse the log packets to demonstrate processing raw
19 bytes received by a DCI Client.
20 Table 7-1 lists the complete log packet format described in [Q3].

21 Table 7-1 Log packet structure

Field Length (bytes) Description
CMD_CODE (16 / 0x10) 1 This byte is set to 16 for all log packets.
MORE 1 More log data available indicator; indicates how
many log entries (not including the one returned with
this message) are queued in the DMSS.
LENGTH 2 Length of the log record; this is the entire record
including LENGTH, LOG_CODE, and TIMESTAMP.
LOG_CODE 2 LOG_CODE is the 16-bit logging code and consists
of the following fields:
§ Equipment identifier – Most significant 4 bits of
the log code specify the equipment ID
§ Item identifier – Least significant 12 bits of the log
code specify the log item ID within the equipment
ID
TIMESTAMP 8 DMSS timestamp; this is the same format as in the
Time Stamp (29/0x1D).
DATA LENGTH-12 This is data specific to that log type.

80-NA157-61 E 58 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diag Consumer Interface

1 7.6.3 Sample code

2 The DCI client application receives log packets excluding the first 2 bytes, i.e., from the
3 LENGTH field onward (the diag kernel driver drops the first 2 bytes and forwards the remaining
4 packet to the DCI client application).
5 Reference the log packet format in Table 7-1 to parse the raw bytes. The sample application
6 demonstrates parsing LOG_CODE by maintaining a data structure of some log codes as follows:
7

8 /* Structure for Log packet parsing*/

9 struct log_code_name_type{
10 int log_code;
11 char *name;
12 };
13 struct log_code_name_type log_codes[TOTAL_LOG_CODES] = {
14 {0x5072, "GSM L1 Serving Cell Info"},
15 {0x12E8, "Transceiver Resource Manager"},
16 {0x119B, "Srch TNG 1x Searcher"},
17 {0x11AF, "Srch Finger Driver Dump"},
18 {0x115F, "DIAG TEST LOG"},
19 {0x14C8,"CPU MPNITOR MODEM"},
20 {0x1375,"CGPS IPC DATA"},
21 {0x158C,"XOADC READING LOG"},
22 {0x14D8,"TEMP_MONITOR_LOG"},
23 };
24

25 Log codes are maintained in several ICDs by each technology team, e.g., the ICD for LTE log
26 packets is [Q14].

27 Raw output
28 c 2 5f 11 0 0 6c b1 52 9e c2 0 2 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0
29 0 0 0 0 0 ..
30 20 0 c8 14 0 0 82 b1 52 9e c2 0 1 0 0 fa 63 63 1e 5 64 14 64 14 64 14 64 14
31 64 14 14 0

32 Parsed output
33 Received a Log of type DIAG TEST LOG, length = <log_size>
34 c 2 5f 11 0 0 6c b1 52 9e c2 0 2 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0
35 0 0 0 0 0 ..
36 Received a Log of type CPU MONITOR MODEM, length = <log_size>
37 20 0 c8 14 0 0 82 b1 52 9e c2 0 1 0 0 fa 63 63 1e 5 64 14 64 14 64 14 64 14
38 64 14 14 0

80-NA157-61 E 59 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diag Consumer Interface

1 7.7 Security
2 Several security methods exist to help protect unauthorized applications from using or abusing
3 DCI. The following sections provide a brief overview of these methods, referring to other detailed
4 documentation where appropriate.

5 7.7.1 Apps processor protections

6 7.7.1.1 Access permissions

7 The DCI client application needs access to the /dev/diag port to function properly. /dev/diag has
8 access permissions set to 660, only the owner and group have read and write permissions.
9 Therefore, the DCI client application must run as one of the following:
10 n User root
11 n User system
12 n Within the qcom_diag group

13 7.7.2 Modem processor protections

14 7.7.2.1 DCI Override feature

15 The DCI authentication feature allows the customers to lock down access to DCI, while the
16 device is in the factory, by provisioning an authentication cookie to the modem. When DCI
17 access is locked out, the modem does not open its DCI SMD channel to the apps processor,
18 preventing any DCI access. To unlock DCI access, an override cookie must be provided over the
19 standard diag interface. This is referred to as the DCI Override feature.

20 7.7.2.2 Secure Services Module

21 NOTE: A full descriptions of the Secure Services Module (SSM) can be found in [Q15] or [Q16]
22 depending on the HLOS.

23 The SSM service on the modem processor provides fine-grain controls with which diag
24 commands can be allowed to execute on the modem. Each incoming diag command received on
25 the modem (either through the DCI channel or the standard diag channel) is checked against the
26 modem’s SSM permissions files that have been provisioned to the device by the OEM:
27 n Allowed by SSM – Command executes
28 n Disallowed by SSM – Error response returns to the originator of the command

80-NA157-61 E 60 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diag Consumer Interface

1 7.8 NRT mode

2 By default, diag packets generated on peripheral processors are forwarded to the apps processor
3 with minimal buffering to help ensure the packets are received in a timely manner. However, this
4 behavior can lead to high power consumption in the device due to frequent wake-ups of the apps
5 processor.
6 DCI now supports the ability to configure the peripheral processors to aggregate diag packets for
7 a longer period of time before sending them to the apps processor, which can help reduce the
8 frequency of these wake-ups.

9 7.8.1 NRT/Buffering mode

10 When NRT is enabled on a processor, the diag drain timer is set to a larger value, and the buffer
11 threshold is adjusted to hold more data before forwarding it to the apps processor.

12 7.8.1.1 DCI
13 A DCI client can request NRT mode by using the following API commands:
14 1. To vote for Real-Time or NRT mode:
15

16 int diag_dci_vote_real_time(int client_id, int real_time);

17

18 ¨ Parameters – MODE_REALTIME or MODE_NONREALTIME

19 ¨ Return values
20 – DIAG_DCI_NOT_SUPPORTED – Client is not supported
21 – DIAG_DCI_PARAM_FAIL – Incorrect parameter
22 – DIAG_DCI_NO_ERROR – No error
23 – DIAG_DCI_SEND_DATA_FAIL – Writing to the kernel or peripheral failed
24 2. To retrieve the current Diag mode:
25

26 int diag_dci_get_real_time_status(int *real_time);

27

28 ¨ Parameters – Pointer to store the mode value

29 ¨ Return value
30 – DIAG_DCI_SEND_DATA_FAIL – Writing to the kernel or peripheral failed
31 – DIAG_DCI_PARAM_FAIL – Incorrect parameter
32 – DIAG_DCI_NO_ERROR – No error
33 When there is more than one client in the system, a client voting for Real-Time data takes
34 precedence over a client voting for NRT data. Clients vote for their preferred mode and the apps
35 processor diag makes a decision on the final mode considering all the active diag clients (includes
36 not just DCI clients but also other diag logging modes) and the state of the USB connection.

80-NA157-61 E 61 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Diag Consumer Interface

1 7.8.2 Power management on the apps processor

2 In NRT mode, the number of apps processor wake-ups is reduced by buffering more data on the
3 non-HLOS processors. If there are no active processes, the APSS might go to power collapse and,
4 therefore, the diag kernel driver would drop packets to be sent to the user space application.
5 If registered using the diag_register_dci_signal_data() function, the diag user space library signals
6 the client that there is data for it to process. In this signal handler, the user space application must
7 use its own power management scheme to keep the APSS awake until the time it processes the
8 data. It must acquire the wakeup source (or other suitable power-related object) in this signal
9 handler and release it when processing is done.
10

80-NA157-61 E 62 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 8 Listeners

2 NOTE: This chapter is not applicable to APQ targets.

3 8.1 Single listener

4 A peripheral task can register for and receive notification when the specified log/event/F3 is
5 generated on the same processor.
6 The API used to add a log listener is:
7

8 boolean diag_add_log_listener (const unsigned int log_code,

9 const diag_log_listener listener,
10 void *param);
11

12 When it is called, param is passed unmodified to the registered function.

13 This function returns:
14 n TRUE – Listener is added successfully to Listener table
15 n FALSE – Listener function is not added to Listener table
16 The API used to remove a log listener is:
17

18 boolean diag_remove_log_listener (const unsigned int log_code,

19 const diag_log_listener listener,
20 void *param);
21

22 Similarly, APIs are available for F3s and events in diag.h.

80-NA157-61 E 63 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Listeners

1 8.2 Extended listener

2 A peripheral task can register for and receive notification for multiple logs/events/F3 generation.
3 This reduces the overhead of registering many listeners if the listener can be common to a set of
4 logs/events/F3s.
5 The API used to add an extended log listener is:
6

7 boolean diag_add_log_listener_ext (const uint16* logs, const unsigned int

8 num_logs,const diag_log_listener_ext listener,
9 void *param);
10

11 The listener is called if any one of the logs specified by the logs array is generated. num_logs
12 should be the number of logs present in the logs array.
13 The API used to remove an extended log listener is:
14

15 boolean diag_remove_log_listener_ext (const diag_log_listener_ext

16 listener);
17

18 Similarly, APIs are available for F3s and events in diag.h.

19

80-NA157-61 E 64 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 9 Debugging

NOTE: This chapter was added to this document revision.

3 This chapter gives information on troubleshooting QPST port connection issues, collecting QPST
4 port traces, and various techniques and scripts available for analyzing other port connection
5 status. In addition, techniques are described for debugging commands on the APSS and modem
6 processor.

7 9.1 QPST disconnect/“No Phone” status

8 The QPST connection is established by continuously sending and receiving a response to one of
9 the following commands:
10 n 0x0C – Modem polling command
11 n 0x4B 04 0E 00 – Modem command
12 n 0x4B 08 02 00 – Modem command
13 n 0x4B 32 03 00 – Apps polling command/Core BSP polling command
14 QPST has a state machine that sends the above commands, as well as other commands, for other
15 non-Diag modes (such as Download mode) to detect which mode the target is in. Once a response
16 is received for one of these commands, QPST stays with this command and continuously polls
17 with this command to keep the QPST connection alive.
18 The 0x4B 32 03 00 is a diag subsystem command that Diag created to replace the modem polling
19 commands for modem-less configurations and Core Image builds.
20 The QPST client apps need to know the online/offline status of the device. The apps polling
21 response is assumed to be always offline. The modem responses contain the online/offline status
22 in the response.
23 The QPST polling algorithm is as follows:
24 n Case 1 – Modem is available
25 ¨ If a peripheral has registered for one of the polling commands listed above, i.e., modem,
26 the polling command will be forwarded to the registered peripheral.
27 ¨ The registered handler will generate the response and the QPST connection will be
28 established.
29 n Case 2 – Modem is not available, i.e., APQ
30 ¨ If none of the normal polling commands is registered, then Master Diag will respond to
31 the apps polling command.
32 ¨ The QPST connection will be established.

80-NA157-61 E 65 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 n Case 3 – Modem comes up late

2 ¨ Master Diag will respond to the apps polling command since none of the other polling
3 commands will be registered initially.
4 ¨ The QPST connection will be established at this time.
5 ¨ Once the modem is available and has registered the polling commands, Master Diag will
6 start responding to the apps polling command with 0x13 (Invalid command).
7 ¨ This forces QPST to restart the polling state machine which retries 0xC, etc.
8 ¨ The 0xC command will be forwarded to the modem, which generates the response; QPST
9 connection may be lost for a few seconds during this transition but will quickly be
10 reestablished.
11 n Case 4 – Subsystem restart is performed on modem
12 ¨ QPST connection is established with the 0xC command with the modem.
13 ¨ A command is sent to the modem to perform SSR.
14 ¨ The modem closes SMD channels with apps, which proceeds to remove the modem
15 registrations from its Slave table.
16 ¨ Subsequent 0xC requests from QPST result in an error response by Master Diag on the
17 apps processor. This forces QPST to retry the polling sequence.
18 ¨ Eventually the apps polling request is sent and responded to by Master Diag, and the
19 QPST connection is reestablished.
20 ¨ When the modem comes back up, the algorithm follows the “modem comes up late” case
21 above.
22 ¨ The QPST connection may be lost for a few seconds during this transition but will
23 quickly be reestablished.
24 This section describes some common procedures to follow when “No Phone” displays for your
25 phone on the QPST Configuration→Ports tab and also provides some tips on isolating and
26 identifying the problem.

27 9.1.1 QPST port trace

28 QPST sends polling requests to the UE every 600 ms (default value) and waits 400 ms (default
29 value) to receive the corresponding response. If QPST does not receive a response within three
30 attempts (default value), a diag/QPST disconnect occurs.
31 Diag sleep vote is not connected to the USB cable attach/detach; it is connected to the presence of
32 pending traffic in the diag buffers. On a device that was at some point connected to QXDM Pro, a
33 mask configuration file is saved. Masks are read from this file on reboot, even when QXDM Pro
34 is closed; consequently, some diag traffic may be generated on the device, even when QXDM Pro
35 is not connected.
36 To avoid this, disconnect from QXDM Pro with Options→Communications→Disconnect. With
37 on-device logging, push the NULL mask config file to the device.
38 During a diag/QPST disconnect, issues may occur, and a port trace should be collected to record
39 communication between QPST and diag as the issue occurs.

80-NA157-61 E 66 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 To capture the trace:

2 1. Go to QPST Configuration and select the Ports tab.
3 2. Hold Shift and right-click the device port and select Port Trace.

5 3. Select Debugging and Port Traffic from the pop-up dialog window and click OK.

7 A port trace file (PortTrace_COMx) will be created in the QPST Data directory (QPST
8 Configuration→Help→Open Log File Directory).
9 4. Reproduce the issue.
10 5. Once the issue is seen, stop Port trace by selecting Turned Off from the Port Trace options.
11 6. Analyze the generated PortTrace_COMx to investigate the issue.

80-NA157-61 E 67 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.1.2 Packet interpretation

2 The following is a snippet of a port trace:
3

4 COM3<0C 14 3A 7E
5 2008/11/05 14:37:45.454: 780: P: 12 20 115200 size: 4 --> QueueCount=0
6 2008/11/05 14:37:45.454: 1 reads queued
7 COM3<0C E1 00 E1 F1 1B 04 74 01 00 C8 11 03 00 C8 11
8 03 00 FC 01 FC 01 00 00 00 FF 00 00 00 00 00 00
9 00 00 F6 02 00 00 00 00 00 00 00 00 00 00 00 00
10 F3 28 7E
11

12 To interpret these bytes, refer to [Q3]. The > and < shown in the snippet reflect the direction of
13 the byte stream from/to QPST and the COM port. For example:
14 n COM3<0C 14 3A 7E – QPST sent 0C 14 3A 7E (the request packet) to COM3
15 n COM3>0C E1 ... 7E – Response packet sent from COM3 to QPST
16 In the snippet above:
17 n The last byte, 7E, is the end of the message tag for every diag packet.
18 n The last 2 bytes before the last byte 7E are those for the checksum.
19 n The first 1 byte is the command code, and the matching command definition is found in [Q3].
20 The screenshots here shows the request packet interpretation in QPST port trace.

21

80-NA157-61 E 68 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 This screenshot shows the response packet interpretation in QPST port trace.

3 9.1.3 Ports
4 n If you do not see the expected port, or the port displays “No Phone,” click Add New Port in
5 QPST to determine if the desired port is listed. If so, select the desired port.
6 n Check in Windows Device Manager/Ports. Is there a Diagnostics USB port present? If a
7 Diagnostics USB port is not listed, then it is a USB problem.
8 n Unplug the USB cable, wait for 30 sec, and plug it back in. You should see the port entry for
9 your phone disappear and reappear. If you do not see the port entry disappear and reappear, it
10 is a USB problem.

11 9.1.4 Modem
12 Check to see if the modem is running. In the Windows Device Manager:
13 1. Click Modems.
14 2. Right-click the QTI USB modem entry and select Properties.
15 3. Click Diagnostics.
16 4. Click Query Modem to determine the status of the modem. It is running if the response is
17 “Success.”

80-NA157-61 E 69 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.1.5 QPST and QXDM Pro

2 It may be necessary to kill off QPST and QXDM Pro. To do this:
3 1. Make sure there are no lingering QPST or QXDM Pro processes (check with Windows Task
4 Manager on the Processes tab). If there are any lingering QPST or QXDM processes, kill off
5 those processes.
6 2. Restart QPST. If in QPST Configuration on the Ports tab you see your device and the entry is
7 normal, i.e., no longer displays “No Phone,” then it is a tools problem.

8 9.1.6 ADB shell

9 Is the ADB shell working? Enter adb devices on the command line. Is your device present?
10 n If so, enter adb shell to verify that the shell is working.
11 n If not, enter adb kill-server. Reenter adb devices. If you still do not see your device, reboot
12 your device.
13 If the ADB shell is working, execute the SMD loopback test:
14 1. Enter the command:
15

16 adb shell
17

18 2. Then enter the following commands:

19

20 cd /data/kernel-tests
21 chmod 777 *
22 ./smd_pkt_loopback_test
23

24 3. Monitor the output from the test. If it does not say “Passed,” then it is an SMD problem.

25 9.1.7 Debugfs
26 The diag implementation of debugfs provides some visibility into the current state of the apps
27 Linux Diag. To use debugfs, log into an ADB shell and set up debugfs by entering the following
28 commands:
29

30 mkdir /data/debugfs
31 mount -t debugfs 0/data/debugfs
32

33 To run diag debugfs:

34 1. Navigate to:
35

36 cd /data/debugfs/diag
37

80-NA157-61 E 70 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 2. In the /data/debugfs/diag directory, execute any of the following commands to obtain

2 information.
3 ¨ General diag status
4

5 cat status
6

7 ¨ Display the registration table, i.e., all messages that are currently registered with apps
8 Linux Diag.
9

10 cat table
11

12 ¨ Note that this table is quite large. To output to a file on a PC, from a Windows command
13 window, enter the command:
14

15 adb shell cat /data/debugfs/diag/table | tee <somefilename.txt>

16

17 If the process_id is -1, then the command is a registration from one of the peripherals and the
18 client contains the ID of the peripheral. The IDs are defined as follows:
19 ¨ Modem – 0
20 ¨ ADSP – 1
21 ¨ WCNSS – 2
22 ¨ APSS – 3
23 Otherwise, the process_id is the process ID of the app that registered for the command that is
24 running on the apps processor. In this case, the client should be 1 (for apps).
25 3. Display the current pending status of the work structs.
26

27 cat work_pending
28

29 4. If the device supports HSIC, display the Diag HSIC driver status.
30

31 cat hsic
32

33 To run SMD debugfs:

34 1. Navigate to:
35

36 cd /data/debugfs/smd
37

80-NA157-61 E 71 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 2. The tbl and ch commands provide information on the SMD channels opened, i.e., their status
2 and the bytes read/written over these channels:
3 ¨ tbl
4

5 cat tbl

6
7

8 DIAG_2 -> DCI Logs, F3s, events

9 DIAG_2_CMD -> DCI commands, responses
10 DIAG_CNTL -> Configuration based info, masks, registration tables,
11 ontrol messages
12 DIAG -> QXDM/ SD card logging Logs, F3s, events
13 DIAG_CMD -> QXDM/ SD card logging commands, responses
14

15 ¨ cat
16

17 cat ch
18

80-NA157-61 E 72 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

2 9.2 Linux APSS

3 Global structure “driver” is the main data structure and can be viewed in Trace32.
4

5 struct diagchar_dev *driver

6 9.2.1 Command/Response routing

7 APSS maintains a Master Dispatch table that tracks all commands to be serviced locally as well
8 as by other processors. For an incoming command request, it checks this table. If the request is
9 not found in the table, an error response is sent to the client. Otherwise, the request is forwarded
10 to the servicing handler.
11 SSIDs and commands can be seen under driver→table.

12

80-NA157-61 E 73 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 An example of the modem loopback command is as follows:

2 75 18 41 0 1 2 3
3 ¨ Command code (1 byte) − 75
4 ¨ Subsystem ID (1 byte) − 18
5 ¨ Subsystem command code (2 bytes) − 41 0
6 ¨ Payload (N bytes) − 1 2 3
7 Table 9-1 shows the modem loopback command entry in the command dispatch table
8 (driver→table).

9 Table 9-1 Modem loopback command structure in APSS Linux dispatch table
cmd_code subsys_id client_id cmd_code_lo cmd_code_hi process_id
255 18 0 41 41 -1

10 The apps processor forwards this command request to the modem according to client_id.
11 To check if a Linux process registered to service a command is running:

12

80-NA157-61 E 74 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 If a command is found in the dispatch table, and something goes wrong with the command
2 handler that returns a NULL response, no response will be sent by diag.

3 9.2.2 F3 masks
4 F3 masks can be seen as driver→msg_masks.
5 As shown here, every SSID is composed of 4 bytes. The masks start from index 5. Highlighted
6 entries refer to Call Manager (SSID 5) and Diagnostic Services (SSID 7) masks.

80-NA157-61 E 75 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.2.3 Log masks

2 The log mask information is stored in driver→log_masks sequentially as mask entries. Each
3 mask entry has the following members:
4 n equip_id (4 bytes) – Log equipment ID
5 n num_items (4 bytes) – Number of mask items
6 n index (4 bytes) – Index within the mask array to find the mask information for this equipment
7 ID
8 In the following screenshot, use the index to find mask information for this particular equip_id
9 within driver→log_masks.

10

80-NA157-61 E 76 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.2.4 Kernel logs

2 To see or collect the kernel messages, enter either of the two commands from a command
3 window.
4 The first command displays the kernel messages to the command window and places them in the
5 kmsg.txt file. This command will continue running and updating with the latest messages as they
6 occur. To stop, press Ctrl+C in the window.
7

8 adb shell cat /proc/kmsg | tee kmsg.txt

9

10 The second command displays the kernel messages to the command window and places them in
11 the dmesg.txt file. This command shows the kernel messages that currently exist and after
12 displaying them, stops and returns to the command line.
13

14 adb shell dmesg | tee dmesg.txt

15

16 If there are difficulties using the diag user space library when running a user space app, make sure
17 the app was successful in its call to initialize the diag user space library by checking the return
18 value from Diag_LSM_Init():
19 n 1 (TRUE) – Call is successful
20 n 0 (FALSE) – Initialization has failed
21 One of the main causes of failure is permissions. The /dev/diag port has 660 permissions, which
22 allows user and group read/write permissions. Running the app with any of the following should
23 allow access to the /dev/diag port:
24 n Run as user root
25 n Run as user system
26 n Run with qcom_diag group permissions

27 9.3 Modem processor

28 9.3.1 Command/response handling

29 For the exchange of Rx/Tx data packets, Data Service Memory (DSM) pool buffers are shared in
30 between diag and the SIO communications layer.
31 The following sequence of MPSS APIs and signals are set during a command packet processing:
32 1. diagcomm_sio_inbound_pkt_notify()
33 ¨ Enqueues DSM to diagcomm_sio_rx_wmq
34 ¨ Sets DIAG_RX_SIG
35 2. Diag handles DIAG_RX_SIG
36 ¨ Calls diag_process_rx()
37 ¨ Reads the Rx packet from DSM into diag_req_inbound[]

80-NA157-61 E 77 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 3. diagpkt_process_request()
2 ¨ Search Command Dispatch table (diagpkt_master_table); if present, call callback, which
3 returns the pointer to the response
4 – diagpkt_commit() on the rsp pointer to commit rsp to diag buffer
5 • Queues rsp packet onto response queue, diagpkt_rsp_q
6 • Sets DIAG_RX_RSP_SIG
7 ¨ If not present in the table, sends an error response
8 – diagpkt_err_rsp()
9 4. diagpkt_rsp_send()
10 ¨ diagbuf_send_pkt()

11

12 9.3.2 Diag Tx routing (logs, events, F3s)

13 This section describes MPSS APIs and signal handling for the Diag Tx channel.
14 1. DIAG_TX_SIG is set if diagbuf gets data.
15 2. diag_tcb handles DIAG_TX_SIG.
16 ¨ Enqueues DSM to diagcomm_sio_tx_wmq[]
17 ¨ Transmits DSM to SIO Layer

80-NA157-61 E 78 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.3 Log packet generation

2 Log packets (see Section 2.2.4) are generated by a client and sent to diag for forwarding.
3 Figure 9-1 shows the procedure. The client first checks to see if a mask for the desired log has
4 been set. If so, it allocates memory from the diag buffer. In case of insufficient memory, the log
5 packet is dropped by the client.

7 Figure 9-1 Log packet generation call flow

8 9.3.3.1 Log mask structures

9 n log_composite_mask – Composite log mask for all streams
10 n log_listener_mask – Single Log Listeners’ mask
11 n log_listener_ext_mask – Extended Log Listeners’ mask
12 n diag_log_preset_mask[0] – QXDM Pro/On-device logging stream log mask
13 n diag_log_dci_mask – DCI stream log mask

80-NA157-61 E 79 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.3.2 Checking the log mask value for a log code

2 The log code is 2 bytes as follows:
3 n Equipment ID – Most significant 4 bits
4 n Item number – Least significant 12 bits
5 To check the log mask value for a log code, find the correct index in the above log mask arrays:
6 Index = log_mask_offset_tbl[equipment id] + (Item number/8)
7 Log code = 0x11EB example:
8 n Equipment ID = 1
9 n Item number = 1EB
10 n log_mask_offset_tbl[1] = 1
11 ¨ 491/8 = 61 with remainder of 3
12 ¨ 8 * 61 = 491 – 488 = 3
13 ¨ Index of 1 + 61 = 62
14 ¨ Corresponds to the third bit in log_mask[0][62]
15 n log_mask[0][62] = 00001000.
16 n Since the value in the third bit is 0, the mask value for this log code is not set.

80-NA157-61 E 80 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.4 Event report generation

2 Event report generation is similar to log packet generation. The client checks for masks, requests
3 memory, and submits event reports to diag. Diag then forwards the reports to either the Listeners
4 or QXDM/DCI client as shown in Figure 9-2.

6 Figure 9-2 Event report generation call flow

7 9.3.4.1 Event mask structures

8 n diag_event_preset_mask[0] – QXDM Pro/On-device logging stream Event masks
9 n diag_event_dci_mask – DCI stream Event masks

80-NA157-61 E 81 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.4.2 Checking the event mask value for an Event ID

2 Given an Event ID, the index to the above array is calculated by:
3 Index = (event_id/8)
4 event_id = 0x0112 = 274 example:
5 n Index = 274/8 = 34 with remainder of 2
6 n This corresponds to the second bit in diag_event_mask[34]
7 n diag_event_mask[34] = 11111011
8 n Since the second bit is 1, the mask is set.

9 9.3.5 F3 messages generation

10 As shown in Figure 9-3, a subsystem client pushes F3 messages to the diag buffer. Once the
11 buffer threshold is touched or the drain timer expires, F3s are forwarded to the SIO layer. Notice
12 that F3s are also saved in the F3 trace buffer to be extracted out of a RAM dump.

13

14 Figure 9-3 F3 message generation call flow

80-NA157-61 E 82 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.5.1 Checking the message mask value for a given SSID

2 msg_enabled_mask is a bitmask that suggests which stream masks are set. An entry in
3 msg_mask_tbl consists of:
4 n ssid_first – First value of SSID in the range
5 n ssid_last – Last value of SSID in the range
6 n *bt_mask_array – Pointer to build time mask array
7 n *rt_mask_array – Pointer to runtime mask array
8 Determine the range in which a given SSID belongs and once the range is obtained, check the
9 runtime mask array to determine if the mask value is set.

10 9.3.6 Diag signals

11 Diag signals are handled in diag_handle_sigs(). They can be checked as diag_tcb->sigs. Major
12 signals of interest are:
13 n DIAG_TX_SIG
14 ¨ Set whenever there is data committed to diag buffer
15 ¨ Handled by calling diagbuf_drain() to drain the data out
16 n DIAG_RX_SIG
17 ¨ Set whenever an inbound request is received by diag and enqueued to SIO Rx watermark
18 queue
19 ¨ Handled by calling diag_process_rx() and eventually diagpkt_process_request() to route
20 the command to the appropriate local handler or forward to the processor that registered
21 the command
22 n DIAG_RX_RSP_SIG
23 ¨ Set in diagpkt_commit() whenever a response packet is queued to the response queue
24 diagpkt_rsp_q
25 ¨ Handled by calling diagpkt_rsp_send() and eventually diagbuf_send_pkt() to dequeue
26 and drain the response out
27 n DIAG_DRAIN_TIMER_SIG
28 ¨ Set whenever diag_drain_timer expires (default is 200 ms); this timer is set whenever
29 there is data committed to diag buffer to drain data in low traffic scenario
30 ¨ Handled by calling diagbuf_drain() to drain data from diag buffer to transport layer
31 n DIAG_EVENT_DRAIN_SIG
32 ¨ Set whenever event_stale() is called, indicating that diag is ready to send an event report
33 packet for primary queue events
34 ¨ Handled by calling event_drain() to drain events from primary event queue event_q to
35 transport layer

80-NA157-61 E 83 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 n DIAG_EVENT_DRAIN_SEC_SIG
2 ¨ Set whenever event_stale_sec() is called, indicating that Diag is ready to send an event
3 report packet for secondary queue events
4 ¨ Handled by calling event_drain_sec() to drain events from secondary event queue
5 event_q_sec to transport layer
6 n DIAG_EVENT_TIMER_SIG
7 ¨ Set whenever event_stale_timer expires
8 ¨ Handled by calling event_stale(), which calls event_drain() to drain events from event_q
9 to transport layer
10 n DIAG_EVENT_TIMER_SEC_SIG
11 ¨ Set whenever event_stale_timer_sec expires
12 ¨ Handled by calling event_stale_sec(), which calls event_drain() to drain events from
13 event_q_sec to transport layer
14

80-NA157-61 E 84 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.7 DSM debugging

2 DSM pool buffers are shared between the SIO Communications Layer and Diag to Rx/Tx data packets as shown in Figure 9-4.

4 Figure 9-4 Diag DSM pools and watermark queues

5 The “lock” in DSM pool is a mutex lock used by DSM Layer to manage the flow control, as per the above callback threshold values. This
6 should be a 4-byte positive value. Make sure FEATURE_DSM_REX or a similar DSM feature is defined to initialize the “lock” field in a
7 DSM pool structure.

80-NA157-61 E 85 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 To determine whether data flow is blocked or not, check:

2 n allowflow (outgoing traffic)
3 n ballowflow (incoming traffic on MDM products from the modem)
4 For example, say the total DSM items is 749, it is necessary to determine what is causing the Low
5 mem event threshold to be so high, i.e., 707?
6 The idea behind this implementation was to include Buffering mode. However, the related Diag
7 code still makes it to the CRM releases, which creates confusion. The Buffering mode is for
8 APQ+MDM chipsets where the need to wake up APQ every time MDM has data to transmit is
9 reduced. Rather, data is “buffered” as much as possible on MDM Cortex-A5 (this is where the
10 aforementioned DSM item pool comes in). In this example, this pool has 749 items, but only 50
11 are used in Regular mode, while the remaining 700 come in when Buffering mode is enabled,
12 wasting a lot of space in the process.
13 This implementation was required since there was a QPST disconnect issue where polling
14 responses were not getting received. Due to this large DSM pool, many DSM items got queued
15 (instead of dropping logs/events), which caused required polling response to lag behind in the
16 watermark queue, and hence cause QPST timeout. Therefore, the window is now kept to 50 items
17 for the regular logging mode; the pool size could not be changed dynamically, so it was adjusted,
18 so that 50 was its apparent size.

80-NA157-61 E 86 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.8 Sleep voting

2 Figure 9-5 shows the diag sleep voting call flow.

4 Figure 9-5 Diag sleep voting call flow

5 Check for the following:

6 n diag_enable_sleep_voting should be TRUE
7 n diag_sleep_state should be 1 (DIAG_SLEEP_STATE_ASLEEP)
8 n allowflow should be 1
9 n ballot_mask should be 0
10 ¨ This is a bitmask for all services, i.e., buffer, log, and F3 (event masks do not affect diag
11 sleep).
12 ¨ If any of these bits are set or if ballot_mask > 0, diag will prevent power collapse unless
13 the Communications Layer connection is broken.

80-NA157-61 E 87 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 n diag_cx_state
2 ¨ First LSB is for DIAG_CX_COMM_S, i.e., Communications Layer connection. If set to
3 0, the channel is not connected; hence, diag will vote for sleep.
4 n diagbuf_head/diagbuf_tail
5 ¨ Both pointers should be equal, showing an empty buffer.
6 ¨ If diagbuf_head is less than diagbuf_tail, it is wrapped, and if diagbuf_head is more than
7 128 k, it is secretly wrapped.
8 n diag_tcb.sigs
9 ¨ DIAG_DRAIN_TIMER_SIG 0x00200000 (set on drain timer expiration)
10 ¨ DIAG_DRAIN_TIMER_LEN 200 ms
11 ¨ DIAG_TX_SIG 0x00000080 (when client commits data to diag buffer)
12 ¨ DIAG_RX_RSP_SIG 0x00000200 (when responses are generated for Rx
13 traffic)

14

80-NA157-61 E 88 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.9 F3 trace
2 This feature maintains a circular buffer of debug (F3) messages, showing the last n messages sent
3 from the processor. This buffer is separate from other buffers used by diag. It uses an independent
4 message mask that is configured at compile time or (on the modem) by NV items. The
5 masks/filter used by QXDM for debug messages do not apply to the F3 trace buffer.
6 The recover_f3.cmm script is used to extract and process messages from the F3 trace buffer.
7 F3 trace has certain limitations:
8 n It is not supported by all diag MSG APIs, e.g., MSG_SPRINTF is not supported.
9 n It only supports legacy MSG levels (HIGH, MED, LOW, etc.). Messages sent using custom
10 message levels (which are supported by diag) will not be recorded in the F3 trace buffer.

11 9.3.10 Timestamps
12 Each diag packet contains a timestamp field. The timestamp represents the time the packet was
13 allocated, not the time the packet was sent. The timestamp is generated locally on each processor
14 as follows:
15 n Diag reads the timestamp using the time API available on the image it is running on.
16 n Diag does not control or set the timestamp in any way.
17 Timestamp differences or jumps in QXDM Pro logs between packets generally mean either one
18 of the following:
19 n The time value was updated on the individual processor.
20 or
21 n The packets are being sent from different processors, and the timestamps between the
22 processors are not synchronized.

80-NA157-61 E 89 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Debugging

1 9.3.11 Common issues

2 9.3.11.1 Error fatal in diagbuf_check_overrun_pattern

3 This error fatal is usually due to a client overwriting the diag buffer. A 2-byte 0xDEAD pattern is
4 appended to every packet allocated from diag buffer. For example, if a client requests a 4-byte
5 buffer using log_alloc() and writes more than 4 bytes to the log pointer, a subsequent
6 log_commit() call by the client to commit the log packet to the diag buffer results in this error
7 fatal as shown below.

80-NA157-61 E 90 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 10 Code Structure

NOTE: This chapter was added to this document revision.

3 10.1 L4/Rex
4 Diag public API files
5 n core\api\services\
6 ¨ diag.h
7 ¨ diag_fusion.h
8 ¨ diag_LSM.h
9 ¨ diagbuf.h
10 ¨ diagcmd.h – Defines command codes and SSIDs
11 ¨ diagcomm.h
12 ¨ diagdiag.h
13 ¨ diagdsm.h
14 ¨ diagnv.h
15 ¨ diagpkt.h
16 ¨ event.h
17 ¨ event_defs.h – Defines event IDs
18 ¨ log.h
19 ¨ log_codes.h – Defines log codes (additional log codes defined in log_codes_umts.h,
20 log_codes_wcdma.h, log_codes_gsm.h)
21 ¨ msg.h
22 ¨ msg_diag_service.h
23 ¨ msg_mask.h
24 ¨ msg_pkt_defs.h
25 ¨ msg_qsr.h
26 ¨ msg_wince.h
27 ¨ msgcfg.h – Defines F3 SSIDs
28 ¨ msgtgt.h – Defines levels for each SSID (High, Med, Low, etc.)

80-NA157-61 E 91 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Code Structure

1 Diag source files

2 n core\services\diag\
3 ¨ DCM\common\src\
4 – diag.c – Main driver file, pertaining to task diag_tcb
5 – diagbuf.c – Routines for managing diag output buffer
6 – diagcomm_sio.c – SIO Layer notification routines, meant for Slave processor
7 – diagcomm_smd.c – Meant for Master processor only
8 – diagdsm.c – Diag DSM routines
9 – diaglog.c – Log packet support
10 – msg.c – F3 message support
11 – event.c – Event report support
12 ¨ DCM\rtos\src\
13 – log_api.c – External API for clients using Log service
14 – msg_api.c – External API for clients using F3 message service
15 – event_api.c – External API for clients using Events service
16 – diagpkt.c – Command/response packet support

17 10.2 Linux

18 10.2.1 LA
19 Diag public files
20 n kernel\drivers\char\diag\..

21 Diag proprietary code

22 n vendor\qcom\proprietary\diag\
23 ¨ src\.. – LSM Layer source
24 ¨ mdlog\diag_mdlog.c – Writes diag traffic to SD card
25 ¨ uart_log\diag_uart_log.c – Writes diag traffic to UART port
26 ¨ socket_log\diag_socket_log.c – Writes diag traffic to socket (Ethernet/Wi-Fi/data
27 connection)
28 ¨ dci_client\diag_dci_client.c – Sample DCI client
29 ¨ klog\diag_klog.c – Displays kernel messages on QXDM
30 ¨ PktRsptest\PktRspTest.c – Sample app to demo Command/Response service
31 ¨ test\test_diag.c – Demos usage of all diag services

80-NA157-61 E 92 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Code Structure

1 10.2.2 LE
2 Diag public files
3 n kernel\drivers\char\diag\..

4 Diag proprietary code

5 n diag\
6 ¨ src\.. – LSM layer source
7 ¨ dci_client\diag_dci_client.c – Sample DCI client
8 ¨ klog\diag_klog.c – Displays kernel messages on QXDM
9 ¨ mdlog\diag_mdlog.c – Writes diag traffic to SD card
10 ¨ uart_log\diag_uart_log.c – Writes diag traffic to UART port
11 ¨ PktRsptest\PktRspTest.c – Sample app to demo Command/Response service
12 ¨ test\test_diag.c – Demos usage of all diag services
13

80-NA157-61 E 93 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 11 Case Study

NOTE: This chapter was added to this document revision.

3 11.1 Packet drop

4 In this scenario, diag packets (F3s, Logs) were sometimes dropped if the device LCD was turned
5 OFF. After turning the LCD back on, the diag traffic flow resumed.
6 If APSS was made to hold a wake-up source all the time, the issue did not occur.
7 End-to-end debugging was needed across diag and SMD modules to root cause the issue.

8 11.1.1 Creating IPC buffer on APSS

9 The IPC buffer allows saving debug messages in an allocated RAM buffer.
10

11 #include <mach/msm_ipc_logging.h>
12 void *ipc_log_context_create(int max_num_pages, const char *mod_name);
13 int ipc_log_string(void *ilctxt, const char *fmt, ...);
14

15 11.1.2 Using MPM timecount

16 The MPM timecount register is 64 bit, and it can be read by any processor. Hence, it is very
17 useful in logging timestamp for certain events and later on correlating these events from separate
18 processors.
19

20 APSS API:
21 #include arch_timer.h
22 cycle_t arch_counter_get_cntpct(void);
23

24 MPSS API:
25 #include "DDITimetick.h" //for DalTimetick APIs
26 #include "DalDevice.h" //for DAL data types
27 #include "DALStdErr.h" //for DAL return code
28 static __inline DALResult DalTimetick_Attach(const char *pSystemTimer,
29 DalDeviceHandle** phDalHandle);
30 static __inline DALResult DalTimetick_GetTimetick64(DalDeviceHandle *
31 _h, DalTimetickTime64Type * ticks);
32

80-NA157-61 E 94 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Case Study

1 Debug patches are used to record events using common MPM timecount on APSS and MPSS.
2 MPSS Diag starts a timer when DSMs are exhausted. The timer is cleared when DSMs are freed
3 up. When this timer expires, if DSMs are still not available, crash dumps of the SMD state are
4 gathered.
5 1. MPSS SMD sent the last interrupt at 0x8C64122AF, for which diag must have queued the
6 DSM at 0x8C6412237.
7 After that, several DSMs were queued with SIO until 0x8C7BB15EC. Diag started dropping
8 packets from this point onward, finally leading to a crash at 0x8CAB21F8B.

9
10

11 2. MPSS sent the last IRQ at 0x8C64122AF and APSS received the last IRQ at 0x8C6414B9D.
12 By backtracking in these logs up to ~10 IRQs, it is possible to match a sent IRQ with a
13 received one with the initial time gap in microseconds and then milliseconds.
14 With that mapping, a matching received IRQ is not seen on APSS for the IRQ sent by MPSS.
15 Since the last IRQ on APSS happened a little after the last one sent from MPSS, it is likely
16 that APSS serviced the last two sent IRQs collectively only one time.
17

80-NA157-61 E 95 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Case Study

1 After the last received IRQ, APSS goes into power collapse at the time when diag had to write packets to the SD card. This is clearly
2 an issue that needs to be fixed. A patch was released for the SS for holding wakeup object from when diag is notified to read SMD
3 data, until the time when it is written fully to the user space app. At this point, it is not possible to tell if this issue has led to the
4 subsequent unusual events, i.e., MPSS SMD waiting for ACK interrupt from APSS to empty DSMs, etc.

80-NA157-61 E 96 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Case Study

1 3. After correlating the Kernel log (yellow highlighting) with the rest of the logs (IPC log, red
2 boldface), it can be seen that while the APSS is goes into power collapse, MPSS sends it
3 interrupts to read SMD data. The APSS SMD driver notifies diag, but diag fails to send
4 packets to user space since the APSS has gone into power collapse. The MPSS diag then
5 starts dropping packets and eventually crashes. Later when APSS has resumed, diag writes
6 previously pending packets to user space.
7

8 <6>[ 251.902803] [0: kworker/u:1: 35] PM: suspend entry 2014-

9 02-24 07:15:32.108895202 UTC ßAP entering power collapse
10 <6>[ 251.902854] [0: kworker/u:1: 35] PM: Syncing filesystems
11 ... done.
12 <4>[ 251.938022] [0: kworker/u:1: 35] Freezing user space
13 processes ... (elapsed 0.03 seconds) done.
14 <4>[ 251.973559] [0: kworker/u:1: 35] Freezing remaining
15 freezable tasks ... (elapsed 0.02 seconds) done.
16 <4>[ 251.993855] [0: kworker/u:1: 35] Suspending console(s)
17 (use no_console_suspend to debug)
18 …
19 <MPSS Sends interrupt at 0x8C640D0C5>
20 <MPSS Sends interrupt at 0x8C64122AF>
21 [ 252.173] AP receives interrupt at 0x8C6414B9D
22 [ 252.173865696] AP Diag receives packets at 0x00000008c6414ea3
23

24 …
25 <4>[ 252.381492] [0: kworker/u:1: 35] Disabling non-boot CPUs
26 ...
27 <6>[ 252.381753] [0: kworker/u:1: 35] msm_pm_enter
28 <6>[ 252.381753] [0: kworker/u:1: 35] msm_pm_enter: power
29 collapse
30 …
31 <6>[ 252.381753] [0: kworker/u:1: 35] Enabled clock count: 14
32 [ POWER COLLAPSE starts, but Diag has not sent packets to
33 userspace ]
34

35 <6>[ 252.381753] [0: kworker/u:1: 35] msm_pm_enter:

36 return
37 <4>[ 252.381753] [0: kworker/u:1: 35] gic_show_resume_irq: 174
38 triggered
39 <4>[ 252.381753] [0: kworker/u:1: 35] gic_show_resume_irq: 200
40 triggered
41 <6>[ 252.388608] [0: kworker/u:1: 35] PM: noirq resume of devices
42 complete after 6.084 msecs
43 <6>[ 252.396527] [0: kworker/u:1: 35] PM: early resume of devices
44 complete after 5.746 msecs
45 …

80-NA157-61 E 97 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Case Study

1 <MPSS Diag is dropping packets from 0x00000008CAB1D190 to

2 0x00000008CAB21F8B>
3

4 <3>[ 252.473090]I[0: swapper/0: 0] SMSM: MPSS SMSM state

5 changed to SMSM_RESET.+++ wakeup source Active =
6 smsm_snapshot ßMPSS crashed
7 <3>[ 252.473349]I[0: swapper/0: 0] Fatal error on the MPSS.
8 <3>[ 252.473434]I[0: swapper/0: 0] MPSS subsystem failure
9 reason: diagbuf.c:975:Diag has dropped 50 Message packets, DSM items
10 are full.
11 …
12 <4>[ 252.899014] [0: kworker/0:1: 27] --- wakeup source
13 Deactive = qpnp-vadc-ee1e7c00
14 <4>[ 252.899158] [0: kworker/0:1: 27] +++ wakeup source Active
15 = qpnp-vadc-ee1e7c00
16 <4>[ 252.899420] [0: kworker/u:1: 35] done.
17 <6>[ 252.900850] [0: kworker/u:1: 35] PM: suspend exit 2014-
18 02-24 07:15:36.748986189 UTC
19 [ POWER COLLAPSE ends ]
20 …
21 <3>[ 252.998431] [0: kworker/0:1: 27] get_prop_batt_temp:
22 get_bat_temp: adc_code(32806) physical (256)
23 <3>[ 253.097232] [0: UEventObserver: 917] get_prop_batt_temp:
24 get_bat_temp: adc_code(32806) physical (256)
25

26 [ 253.104444394] AP Diag sends pending packets to userspace at

27 0x00000008cb7cf284
28

29 <6>[ 253.492406] [0: kworker/u:1: 35] PM: suspend entry 2014-02-24

30 07:15:37.340529522 UTC
31 <6>[ 253.492977] [0: kworker/u:1: 35] PM: Syncing filesystems ...
32 done.
33

80-NA157-61 E 98 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 A Problem Areas for Opening a Diag Case

NOTE: This appendix was added to this document revision.

3 It is important to correctly file diag software problems with the proper problem area code. This
4 will ensure problem assignments are sent to the diag support team for a more prompt resolution.

5 Apps processor
6 The following shows the list of possible values for Problem Area 3 when reporting apps
7 processor diag issues.

9 When filing a diag software problem support case for an apps processor, select a problem area as
10 follows:
11 n DCI – Usage, Design, Implementation (DCI); see Chapter 7
12 n OnDevice/SD logging – See Chapter 4; logs required are mask configuration file (.cfg) and
13 log file (.qmdl); possible issues include:
14 ¨ Cannot save traffic or traffic stops from a core or chipset (in case of fused chipsets)
15 ¨ Cannot execute mdlog script
16 ¨ Packet timestamp synchronization issue
17 ¨ Throughput concerns
18 n Other – Diag listener issues, etc.
19 n Port disconnect – Diag port is lost in QPST/QXDM Pro and goes to Waiting state; QPST port
20 trace logs as described in Chapter 9 are required
21 n Socket logging – Diag over Ethernet or Wi-Fi
22 n UART logging – Configuring diag service over UART; see Chapter 6

80-NA157-61 E 99 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Problem Areas for Opening a Diag Case

1 Other processor
2 The following shows the list of possible values for Problem Area 3 when reporting other
3 processor diag issues.

5 When filing a diag software problem support case for a nonapps processor, select a problem area
6 as follows:
7 n DCI – DCI
8 n Initialization – Command/log registrations, etc.
9 n Other – Diag Listener issues, etc.
10 n Security – Diag security concerns
11 n Sleep issues – Diag voting against sleep/diag waking up the core intermittently; logs required
12 are core RAM dump with matching ELF/vmlinux; reproduction steps
13

80-NA157-61 E 100 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 1 B Defining Custom Android Permissions
2 for Diag

NOTE: This appendix was added to this document revision.

4 This appendix discusses the QCOM_DIAG custom Android permissions. It describes how to
5 declare these permissions and how to enable an APK to use them. The implementation of these
6 permissions provides a mapping between the high-level Android permission and the low-level
7 Linux permission. See [R1] for information on the mapping.

8 B.1 Enabling use of custom permissions by a system APK

9 The framework of a system APK is used to create the QCOM_DIAG permissions. The APK can
10 be a minimal APK because it is not required to execute anything or even to be selectable on the
11 device apps. However, it must be present in the system image.

12 B.1.1 Declaring custom Android permission

13 The APK’s AndroidManifest.xml file must declare the permission, using the format here:
14

15 <permission android:description="@string/desc"
16 android:label="@string/label"
17 android:name="com.qualcomm.permission.QCOM_DIAG"
18 android:protectionLevel="signatureOrSystem"/>
19

20 If the APK needs to use these permissions, it must declare its need in the APK’s
21 AndroidManifest.xml file using the format here:
22

23 <uses-permission android:name="com.qualcomm.permission.QCOM_DIAG"/>
24

25 NOTE: The protection level for this permission is signatureOrSystem. This requires that the APK be
26 either part of the system image or a signed APK to use either of these permissions.

80-NA157-61 E 101 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Defining Custom Android Permissions for Diag

1 B.1.2 Mapping custom Android permission to Linux permission

2 As part of the APK’s source, there must be a mapping .xml file that declares the mapping
3 between the Android permission and the Linux permission. The mapping format is:
4

5 <permissions>
6 <permission name="com.qualcomm.permission.QCOM_DIAG" >
7 <group gid="qcom_diag" />
8 </permission>
9 </permissions>

10 B.1.3 Additional modifications to APK’s Android.mk file

11 It is often recommended that a module be optionally included in the system image. The following
12 will accomplish this.
13

14 LOCAL_MODULE_TAG := optional
15

16 For information on how to add the APK to the system image, see Section B.1.5.
17 The following will cause the APK to be signed with the platform certificate:
18

19 LOCAL_CERTIFICATE := platform
20

21 B.1.4 Proper placement of APK’s mapping .xml file

22 This APK’s mapping .xml file must be placed in the /system/etc/permissions folder. Addition to
23 the APK’s Android.mk file in the following manner will accomplish this:
24

25 LOCAL_MODULE := com.qualcomm.qcom_diag.xml
26 LOCAL_MODULE_TAGS := optional
27 LOCAL_MODULE_CLASS := ETC
28 LOCAL_MODULE_PATH := $(TARGET_OUT_ETC)/permissions
29

30 where the name of the mapping .xml file is com.qualcomm.qcom_diag.xml.

80-NA157-61 E 102 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Defining Custom Android Permissions for Diag

1 B.1.5 Making the APK part of the system image

2 The APK and its mapping .xml file must be part of the system image. Because of
3 LOCAL_MODULE_TAGS := optional in the APK’s Android.mk file, these files are not
4 automatically added to the system image. Adding the files can be accomplished by explicitly
5 listing the APK and the mapping .xml file in the device-vendor.mk file. If these files were to be
6 listed in the diag project, the following lines would be added to the list of files in the diag project:
7

8 DIAG += com.qualcomm.diag.qcom_diag
9 DIAG += com.qualcomm.qcom_diag.xml
10

11 where the APK name is com.qualcomm.diag.qcom_diag and the mapping .xml file is
12 com.qualcomm.qcom_diag.xml.
13 The device-vendor.mk file can be found in <build_root>/vendor/qcom/proprietary/common/
14 config, where build_root is the root folder of the Android source code.

15 B.2 Enabling use of custom permissions by a nonsystem

16 APK
17 Because the protection level of the QCOM_DIAG is signatureOrSystem, an APK that is not a
18 part of the system image that wishes to use these permissions must declare that it needs them. It
19 must also then be signed.

20 B.2.1 Using custom Android permissions

21 The APK must denote that it needs to use the custom permissions. This can be done by adding the
22 following to its AndroidManifest.xml file:
23

24 <uses-permission android:name="com.qualcomm.permission.QCOM_DIAG"/>
25

80-NA157-61 E 103 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
 Defining Custom Android Permissions for Diag

1 B.2.2 Signing an unsigned APK

2 Because the custom permission declares the protection level as signatureOrSystem, any APK that
3 is not a part of the system image must be signed in order to use that permission. Signing can be
4 performed by exporting the APK as an unsigned APK and then signing it with signapk.jar tool as:
5

6 java –jar
7 <build_root>/out/host/<your_host>/framework/signapk.jar
8 <build_root>/build/target/product/security/platform.x509.pem
9 <build_root>/build/target/product/security/platform.pk8 unsigned_app.apk
10 signed_app.apk
11

12 where build_root is the root folder of the Android source code.

13 NOTE: This command will sign the APK only for this particular build.

14 Signing an APK with the platform key will allow that APK to use any permission protected by
15 the platform key.
16

80-NA157-61 E 104 Confidential and Proprietary – Qualcomm Technologies, Inc.

MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION