David Ng | cac0b62 | 2012-10-18 19:13:49 -0700 | [diff] [blame] | 1 | STM Logging |
| 2 | =========== |
| 3 | |
| 4 | This library provides an interface for userspace application to log via STM. |
| 5 | Note that the task must already have write permission to the stm device node. |
| 6 | |
| 7 | This file describes the STM logging API's and associate definitions. |
| 8 | |
| 9 | |
| 10 | 1) Definitions: |
| 11 | ~~~~~~~~~~~~~~~ |
| 12 | 1.1) Header file includes: |
| 13 | #include <stdint.h> |
| 14 | #include <linux/coresight-stm.h> |
| 15 | #include <stm_log.h> // stmlog.h resides in /vendor/qcom/opensource/stmlog/inc |
| 16 | // and must be part of the compiler include search path |
| 17 | |
| 18 | 1.2) Linking: |
| 19 | The STM logging library is available in dynamic library form. |
| 20 | |
| 21 | 1.3) Entity ID: |
| 22 | Description: |
| 23 | Entity ID is an unsigned byte value (range 0-255) and are pre-allocated |
| 24 | for each individual clients. The entity ID allocation is defined in the |
| 25 | kernel file /usr/include/linux/coresight-stm.h. Refer to the kernel |
| 26 | header file for instructions on allocating a new entity ID. |
| 27 | |
| 28 | Note that entity ID's are not verified at runtime for clients, so it is |
| 29 | possible for a different client to (incorrectly) use the wrong ID. |
| 30 | |
| 31 | |
| 32 | 2) Initialization functions: |
| 33 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 34 | |
| 35 | 2.1) stm_log_initdefaults(uint32_t init_mask, |
| 36 | uint8_t entity_id, |
| 37 | uint8_t proto_id, |
| 38 | uint32_t options) |
| 39 | Description: |
| 40 | Optional initialization function to specify the default entity ID, protocol |
| 41 | ID and/or options for stm logging. Takes effect on all subsequent calls |
| 42 | to the STM logging API. |
| 43 | |
| 44 | If this function is not called then a compile-time default is used with |
| 45 | entity ID of zero (OST_ENTITY_NONE). |
| 46 | |
| 47 | Parameters: |
| 48 | init_mask: Indicate which default parameter(s) is being set (bitmask). |
| 49 | STM_DFLT_ENTITY |
| 50 | STM_DFLT_PROTOCOL |
| 51 | STM_DFLT_OPTIONS |
| 52 | entity_id: Specify the default entity ID |
| 53 | proto_id: Specify the default protocol ID |
| 54 | options: Specify the default options; refer to kernel's coresight-stm.h |
| 55 | Currently available options are: |
| 56 | STM_OPTION_NONE |
| 57 | STM_OPTION_TIMESTAMPED |
| 58 | STM_OPTION_GUARANTEED |
| 59 | |
| 60 | Example: |
| 61 | // Set default entity id to 5 and enable log timestamps |
| 62 | stmlog_initdefaults(STM_DFLT_ENTITY | STM_DFLT_OPTIONS, |
| 63 | 5, 0, STM_OPTION_TIMESTAMPED); |
| 64 | |
| 65 | |
| 66 | 3) Logging functions: |
| 67 | ~~~~~~~~~~~~~~~~~~~~~ |
| 68 | |
| 69 | 3.1) stm_log(const char *format, ...) |
| 70 | Description: |
| 71 | Generate a log via STM using the default entity/protocol ID and options. |
| 72 | The parameters are passed to vsprintf() for parsing and so %d/%s/etc. |
| 73 | parameters are valid. |
| 74 | |
| 75 | Parameters: |
David Ng | 7ad27f2 | 2012-10-26 12:34:24 -0700 | [diff] [blame] | 76 | Same parameters as printf(). Refer to man pages for printf() for details. |
David Ng | cac0b62 | 2012-10-18 19:13:49 -0700 | [diff] [blame] | 77 | |
| 78 | Examples: |
| 79 | stm_log("event X"); |
| 80 | stm_log("event Y, data %d", varY); |
| 81 | |
| 82 | 3.2) stm_logbin(int length, void *data) |
| 83 | Description: |
David Ng | 7ad27f2 | 2012-10-26 12:34:24 -0700 | [diff] [blame] | 84 | Generate a binary log via STM using the default entity/protocol ID and |
| 85 | options. |
| 86 | |
| 87 | Parameters: |
| 88 | length: Length of binary log data in bytes |
| 89 | data: Binary data |
David Ng | cac0b62 | 2012-10-18 19:13:49 -0700 | [diff] [blame] | 90 | |
| 91 | 3.3) stm_log_ex(uint8_t entity_id, |
| 92 | uint8_t proto_id, |
| 93 | uint32_t options, |
| 94 | const char *format, ...) |
| 95 | Description: |
| 96 | An extended form of stmlog() to explicitly specify all options for logging |
| 97 | (e.g. override the entity/protocol ID's or options). |
| 98 | |
| 99 | Parameters: |
| 100 | entity_id: Specify the default entity ID |
| 101 | proto_id: Specify the default protocol ID |
| 102 | options: Specify the default options |
David Ng | 7ad27f2 | 2012-10-26 12:34:24 -0700 | [diff] [blame] | 103 | ...: Same as stm_log() |
David Ng | cac0b62 | 2012-10-18 19:13:49 -0700 | [diff] [blame] | 104 | |
| 105 | 3.4) stm_logbin_ex(uint8_t entity_id, |
| 106 | uint8_t proto_id, |
| 107 | uint32_t options, |
| 108 | int length, |
| 109 | void *data) |
David Ng | 7ad27f2 | 2012-10-26 12:34:24 -0700 | [diff] [blame] | 110 | Description: |
| 111 | Generate a binary log via STM using the specified entity/protocol ID and |
| 112 | options. |
| 113 | |
| 114 | Parameters: |
| 115 | entity_id: Specify the default entity ID |
| 116 | proto_id: Specify the default protocol ID |
| 117 | options: Specify the default options |
| 118 | ...: Same as stm_logbin() |
| 119 | |
| 120 | |
| 121 | 4) Limitations: |
| 122 | ~~~~~~~~~~~~~~~ |
| 123 | |
| 124 | 4.1) stm_log() and stm_log_ex() |
| 125 | Log strings via stm_log() or stm_log_ex() are automatically truncated to a |
| 126 | maximum of 1024 bytes including the terminating NULL character. |
| 127 | |
| 128 | 4.2) stm_logbin() and stm_logbin_ex() |
| 129 | A single log via stm_logbin() or stm_logbin_ex() that is greater than 2048 |
| 130 | bytes are broken down into individual packets up to 2048 bytes before |
| 131 | sending over the underlying STM transport. The header is replicated for |
| 132 | each log. |