STM Logging
===========

This library provides an interface for userspace application to log via STM.
Note that the task must already have write permission to the stm device node.

This file describes the STM logging API's and associate definitions.


1) Definitions:
~~~~~~~~~~~~~~~
1.1) Header file includes:
  #include <stdint.h>
  #include <linux/coresight-stm.h>
  #include <stm_log.h>  // stmlog.h resides in /vendor/qcom/opensource/stmlog/inc
                        // and must be part of the compiler include search path

1.2) Linking:
  The STM logging library is available in dynamic library form.

1.3) Entity ID:
  Description:
    Entity ID is an unsigned byte value (range 0-255) and are pre-allocated
    for each individual clients.  The entity ID allocation is defined in the
    kernel file /usr/include/linux/coresight-stm.h.  Refer to the kernel
    header file for instructions on allocating a new entity ID.

    Note that entity ID's are not verified at runtime for clients, so it is
    possible for a different client to (incorrectly) use the wrong ID.


2) Initialization functions:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2.1) stm_log_initdefaults(uint32_t init_mask,
                          uint8_t  entity_id,
                          uint8_t  proto_id,
                          uint32_t options)
  Description:
    Optional initialization function to specify the default entity ID, protocol
    ID and/or options for stm logging.  Takes effect on all subsequent calls
    to the STM logging API.

    If this function is not called then a compile-time default is used with
    entity ID of zero (OST_ENTITY_NONE).

  Parameters:
    init_mask: Indicate which default parameter(s) is being set (bitmask).
                 STM_DFLT_ENTITY
                 STM_DFLT_PROTOCOL
                 STM_DFLT_OPTIONS
    entity_id: Specify the default entity ID
    proto_id:  Specify the default protocol ID
    options:   Specify the default options; refer to kernel's coresight-stm.h
               Currently available options are:
                 STM_OPTION_NONE
                 STM_OPTION_TIMESTAMPED
                 STM_OPTION_GUARANTEED

  Example:
    // Set default entity id to 5 and enable log timestamps
    stmlog_initdefaults(STM_DFLT_ENTITY | STM_DFLT_OPTIONS,
                        5, 0, STM_OPTION_TIMESTAMPED);


3) Logging functions:
~~~~~~~~~~~~~~~~~~~~~

3.1) stm_log(const char *format, ...)
  Description:
    Generate a log via STM using the default entity/protocol ID and options.
    The parameters are passed to vsprintf() for parsing and so %d/%s/etc.
    parameters are valid.

  Parameters:
    Same parameters as printf().  Refer to man pages for printf() for details.

  Examples:
    stm_log("event X");
    stm_log("event Y, data %d", varY);

3.2) stm_logbin(int length, void *data)
  Description:
    Generate a binary log via STM using the default entity/protocol ID and
    options.

  Parameters:
    length: Length of binary log data in bytes
    data:   Binary data

3.3) stm_log_ex(uint8_t     entity_id,
                uint8_t     proto_id,
                uint32_t    options,
                const char *format, ...)
  Description:
    An extended form of stmlog() to explicitly specify all options for logging
    (e.g. override the entity/protocol ID's or options).

  Parameters:
    entity_id: Specify the default entity ID
    proto_id:  Specify the default protocol ID
    options:   Specify the default options
    ...:       Same as stm_log()

3.4) stm_logbin_ex(uint8_t     entity_id,
                   uint8_t     proto_id,
                   uint32_t    options,
                   int         length,
                   void        *data)
  Description:
    Generate a binary log via STM using the specified entity/protocol ID and
    options.

  Parameters:
    entity_id: Specify the default entity ID
    proto_id:  Specify the default protocol ID
    options:   Specify the default options
    ...:       Same as stm_logbin()


4) Limitations:
~~~~~~~~~~~~~~~

4.1) stm_log() and stm_log_ex()
  Log strings via stm_log() or stm_log_ex() are automatically truncated to a
  maximum of 1024 bytes including the terminating NULL character.

4.2) stm_logbin() and stm_logbin_ex()
  A single log via stm_logbin() or stm_logbin_ex() that is greater than 2048
  bytes are broken down into individual packets up to 2048 bytes before
  sending over the underlying STM transport.  The header is replicated for
  each log.