pmloglib

API Summary

The pmloglib provides the API, which enables applications to format the messages and put these messages to the syslog.

Overview of the API

(click to expand)

This library supports instrumenting code to produce runtime text output  to indicate run status.
We differentiate output into two types, tracing and logging.

Tracing code is for detailed debugging for use by individual component development. It is turned on only locally and only as needed, and is not included in the main build or release product. The system that supports for tracing code will not be as efficient in this case as it will lean more towards ease of use.

Logging code, on the other hand, is included in the main build and release product. The purpose is to log errors and important diagnostics information in the device logs. 

Logging code may also support more verbose diagnostic levels which may be turned on dynamically as needed on the device. The intent of the system is that logging code which is not enabled has minimal performance impact. In particular, a logging call which is not enabled should not result in a library call or evaluation of parameters.

This is enabled by requiring logging clients to initialize a logging context that is managed by the PmLog system. The context includes a memory field that can be quickly checked by the logging call to know whether the call is enabled.

The pmloglib service provides the following core features:

  • Context support
  • Filter messages by id
  • Route messages by parameters
  • Provides C API for other components
  • Provide configuration through the pmlogctl utility

The pmloglib supports contexts. Through the pmloglib API, you can configure the contexts, use different files for different contexts and manage the filtering level.

By default, the pmloglib provides 2 contexts:

  • Executable files
  • Dynamic libraries that are used by the executable file

The messages are formatted on the key - value basis. The key serves as a tag, by using which it is possible to get all messages that are marked by a certain key.

 

Example usage:


    PmLogContext    gMyContext;

    void MyComponentInit(void)
    {
         // Get a pointer to the context for this component.
         // The context is created if it does not already exist.
         PmLogGetContext("PmMyComponent", &gMyContext);
    }

    void MyComponentRun(void)
    {
         int err;

        PmLogDebug(gMyContext, "Calling Foo");
         err = Foo();
         if (err)
         {
            PmLogError(gMyContext, "FOOERR", 1, PMLOGKFV(ERROR_CODE,"%d",err), "");
         }
     }

 

Below are the list of functions which are exported :

# Exported functions
{
global:
### Public interface (PmLogLib.h) ###
    PmLogGetNumContexts;
    PmLogGetIndContext;
    PmLogFindContext;
    PmLogGetContext;
    PmLogGetContextInline;
    PmLogGetContextName;
    PmLogGetContextLevel;
    PmLogSetContextLevel;
    PmLogPrint_;
    PmLogVPrint_;
    PmLogDumpData_;
    PmLogLevelToString;
    PmLogStringToLevel;
    PmLogFacilityToString;
    PmLogStringToFacility;
    PmLogGetErrDbgString;
    PmLogString_;
    _PmLogMsgKV;
    PmLogGetLibContext;
    PmLogSetLibContext;
   
### Private interface (PmLogLibPrv.h) ###
    PmLogPrvGlobals;
    PmLogPrvLock;
    PmLogPrvUnlock;
    PmLogPrvTest;
    PmLogPrvReadConfigs; 
local:
    *;
};


Open All


PmLogDumpData_

Description

Logs the specified binary data as text dump to the specified context. Specify kPmLogDumpFormatDefault for the formatting parameter. For efficiency, this method should not be used directly, but instead use the wrappers (e.g., PmLogDumpData, ...) that bypass the library call if the logging is not enabled.

Parameters

Name

Required

Type

Description

context Required PmLogContext

Type definition for the logging context as returned by PmLogGetContext method. This is a read-only data. Clients should treat this as an opaque structure, however it is

referenced by the macro/inline functions here.

level Required PmLogLevel

Type definition for discrete logging level. The values are intentionally identical to the equivalent syslog priority value.

data Required const void *

Logs the specified binary data as text dump to the specified context

numBytes Required size_t

Size of the input data length

format Required const PmLogDumpFormat *

Specify kPmLogDumpFormatDefault for the formatting parameter.

currently other format support is not added

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidContext if PmLogContext_ handle is null.
  • Returns logErr if PrvCheckContext handle is not proper.
  • Returns NoData, if numbytes is zero.
  • Returns InvalidData, if input data is null. 
  • Returns InvalidFormat if default format is not allowed, when the input format is not equal to NULL.
  • Returns logErr, if it succeeds.

Example

This method is used when user wants to logs the specified binary data as text dump to the specified context.

logErr  = PmLogDumpData_(contextName, level,data, numBytes, format)

if (logErr  ==  kPmLogErr_None) {

     ErrPrint("PmLogDumpData_ call  is success);

     return RESULT_OK;

}


PmLogFindContext

Description

Finds the logging context for the named context, or NULL if the context does not exist.

Parameters

Name

Required

Type

Description

contextName Required const char *

context name 

pContext Required PmLogContext *

PmLogContext handle

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidParameter, if PmLogContext handle is null.
  • Returns Unknown, if PmLogGlobals handle is null.
  • Returns logErr, if contextName is invalid.
  • Returns None, if PmLogcontext name match found.
  • Returns ContextNotFound, if nothing context name match found.

Example

This method is used to find the context name with the previously resolved context name exist or not.

Success Cases:-

logErr = PmLogFindContext(contextName, &context);

if (logErr == kPmLogErr_None) {

     ErrPrint("Context '%s' is already defined.\n", contextName);

     return RESULT_OK;

}

Failure Case:-

logErr = PmLogFindContext(matchContextName, &matchedContext);

if (logErr != kPmLogErr_None)     {

     ErrPrint("Context '%s' not found.\n", matchContextName);

     return RESULT_PARAM_ERR;

}


PmLogGetContext

Description

Logs context for the named context. If contextName is NULL, returns the global context.Context names must be 1~31 characters long, and each character must be one of A-Z, a-z, 0-9, '_', '-', '.'. and Component hierarchies can be indicated using '.' as the path separator. E.g. "FOO.BAR" would indicate the "BAR" subcomponent of the "FOO" component.

Parameters

Name

Required

Type

Description

contextName Required const char *

Context name

pContext Required PmLogContext *

PmLogContext handle

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidContextIndex, if contextIndex is invalid.
  • Returns InvalidParameter, if PmLogContext handle is invalid.
  • Returns None, if it succeeds.

Example

This method is used to get the current context 

Example 1:

logErr = PmLogGetContext("ASM.LIB", &libContext);

if(logErr == kPmLogErr_None)

{

      PmLogSetLibContext(libContext);

}

Example 2:

logErr = PmLogGetContext(contextName, &context);

    if (logErr != kPmLogErr_None) {

       snprintf(errMsg, errMsgBuffSize, "Error getting context: %s",PmLogGetErrDbgString(logErr));

       return false;

}


PmLogGetContextInline

Description

Gets the logging context for the named context.

Parameters

Name

Required

Type

Description

contextName Required const char *

PmLogContext name 

Call Returns

Name

Required

Type

Description

context Required struct PmLogContextInfo
  • Returns PmLogContext handle if it succeeds.
  • Returns GlobalContext, if current contextName is not available.

Example

This method is used to support the trace macros that want to use a named context, but can't easily support a global variable to cache the context.
 

Example 1:

static PmLogContext ctx = PmLogGetContextInline("hbb.avcontrol");

if (NULL == ctx) {

      printf("context name does not exists.")

}
static bool checkDebugMode = false;

PmLogSetContextLevel(ctx, kPmLogLevel_Debug);

 

Example 2:

m_context = PmLogGetContextInline("bootManager");

if (NULL != m_context ) {

      printf("context name  exists.")

}


PmLogGetContextLevel

Description

Gets the logging level for the specified context. This method may be used for the global context. This should generally not be used by the components doing logging themselves. Instead just use the PmLogPrint, etc. methods which will do inline enabled checks.

Parameters

Name

Required

Type

Description

context Required PmLogContext

PmLogContext handle

levelP Required PmLogLevel *

Type definition for discrete logging level

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidContext, if context name is invalid.
  • Returns None, if it succeeds.

Example

This method is used to get the logging level for the specified context.
 
PmLogGetContext(contextName, &gmLogContext);

if(gmLogContext != NULL)

{

     logErr = PmLogGetContextLevel(gmLogContext, &logLevel);

     if (logErr == kPmLogErr_None) {

          printf("PmLogGetContextLevel call is success");

     }

}


PmLogGetContextName

Description

Gets the name of the specified context into the specified string buffer.

Parameters

Name

Required

Type

Description

context Required PmLogContext

PmLogContext handle

contextName Required char *

PmLogContext name

contextNameBuffSize Required size_t

Size of PmLogContext buffer

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidContext, if context name is invalid.
  • Returns InvalidParameter, if context name or contextNameBuffSize is invalid.
  • Returns BufferTooSmall, if contextNameBuffSize is very small.
  • Returns None, if it succeeds.

Example

This method is used to get the name of the specified context into the specified string buffer.
 
logErr = PmLogGetContextName(contextInfoP->context,contextInfoP->contextName, sizeof(contextInfoP->contextName));

if (logErr != kPmLogErr_None){

     return logErr;

}


PmLogGetIndContext

Description

Gets the context by index where index = 0 ~ numContexts-1.

Parameters

Name

Required

Type

Description

contextIndex Required int

PmLogContext index

pContext Required PmLogContext *

Pointer to PmLogContext 

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidContextIndex, if contextIndex is invalid.
  • Returns InvalidParameter, if context handle is null.
  • Returns None, if it succeeds.

Example

This method is used to get the context by index where index = 0 ~ numContexts-1.

logErr = PmLogGetIndContext(contextIndex, &context);

if(logErr != kPmLogErr_None)

{

     DbgPrint("Context no %d not found. Error no: %d", contextIndex, logErr);

}


PmLogGetNumContexts

Description

Gets the number of defined contexts, including the global context.

Parameters

Name

Required

Type

Description

pNumContexts Required int *

Number of PmLogContext 

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidParameter, if pNumContexts is null.
  • Returns Unknown, if gGlobalsP is null.
  • Returns None, if it succeeds.

Example

This method is used to get the number of defined contexts, including the global context.

Example 1:

logErr = PmLogGetNumContexts(&contextsNumber);

if (logErr != kPmLogErr_None){

     DbgPrint("No contexts found. Error no: %d", logErr);

     return false;

}

 

Example 2:

log_err = PmLogGetNumContexts(&contexts_count);

if (log_err == kPmLogErr_None) {

     printf("PmLogGetNumContexts call is success")

}


PmLogPrint_

Description

Logs the specified formatted text to the specified context.

Parameters

Name

Required

Type

Description

context Required PmLogContext

PmLogContext handle

level Required PmLogLevel

Type definition for discrete logging level.

fmt Required const char *

PmLogContext format string

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidContext, if context is invalid.
  • Returns logErr, if context and context level is invalid.
  • Returns None, if it succeeds.

Example

This method is used to log the specified formatted text to the specified context.

logErr = PmLogPrint_(context, *levelIntP, "%s", msg);

if (logErr != kPmLogErr_None)

{

     ErrPrint("Error logging: 0x%08X (%s)\n", logErr,PmLogGetErrDbgString(logErr));

     return RESULT_RUN_ERR;

}


PmLogSetContextLevel

Description

Sets the logging level for the specified context. This method may be used for the global context.

Parameters

Name

Required

Type

Description

context Required PmLogContext

PmLogContext handle

level Required PmLogLevel

PmLogContext level 

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidContext, if handle is invalid.
  • Returns InvalidLevel, if LogLevel is invalid.
  • Returns None, if it succeeds.

Example

This method is used to set the logging level for the specified context.

logErr = PmLogSetContextLevel(context, level);

if (logErr != kPmLogErr_None)

{

     snprintf(errMsg, errMsgBuffSize, "Error setting context level: %s",PmLogGetErrDbgString(logErr));

     return false;

}


PmLogString_

Description

Logs the specified string of key-value pairs and free text to the specified context.

Parameters

Name

Required

Type

Description

context Required PmLogContext

PmLogContext handle

level Required PmLogLevel

PmLogContext level 

msgid Required const char *

PmLogContext msgId

kvpairs Required const char *

String of key-value pairs

message Required const char *

Free text to the specified context

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • Returns InvalidContext, if context is NULL.
  • Returns InvalidMsgID, if msgid is invalid.
  • Returns InvalidFormat, if string of kvpairs is invalid or if string exceeds 1024 bytes.
  • Returns FormatStringFailed, if formatting of the string is not proper.
  • Returns None, if it succeeds.

Example

This method is used to log the specified string of key-value pairs and free text to the specified context.

logErr = PmLogSetContextLevel(context, level);

if (!PmLogIsEnabled(parent_ctx_, level_))

{

     err_ = kPmLogErr_LevelDisabled;

}

else if (level_ == kPmLogLevel_Debug)

{

     logErr = PmLogString_(parent_ctx_, level_, nullptr, nullptr, messages_.c_str());

}

else

{

     logErr = PmLogString_(parent_ctx_, level_,msgId_.c_str(), ("{" + kvpairs_ + "}").c_str(), messages_.c_str());

}


PmLogVPrint_

Description

Logs the specified formatted text to the specified context. For efficiency, this method should not be used directly, but instead use the wrappers (e.g., PmLogVPrint, PmLogVPrintError, ...) that bypass the library call if the logging is not enabled.

Parameters

Name

Required

Type

Description

context Required PmLogContext

PmLogContext Handle

level Required PmLogLevel

Type definition for discrete logging level 

The values are intentionally identical to the equivalent syslog priority value.

fmt Required const char *

Log format string 

args Required va_list

Variable number of arguments

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by the method. Refer to PmLogErr enumerator for values.

  • None
  • InvalidContext
  • InvalidLevel
  • InvalidFormat

Example

This method is used to log the specified formatted text to the specified context.

logErr = PmLogVPrint_(context,level,fmt,args)

if (logErr != kPmLogErr_None)

{

     return logErr;

}


PmLogLevelToString

Description

Returns the matching symbolic string for a given numeric level value.

Parameters

Name

Required

Type

Description

PmLogLevel Required PmLogLevel

 The values are intentionally identical to the equivalent syslog priority value.

Call Returns

Name

Required

Type

Description

s Required const char *

Returns the matching symbolic string. Otherwise, returns NULL if the level string is not matched.

Example

This method is used to convert numeric level value to symbolic string.

s = PmLogLevelToString(level);

if (s != NULL)

{

     return s;

}    


PmLogStringToLevel

Description

Returns the matching numeric value for a given a symbolic level string. 

Parameters

Name

Required

Type

Description

levelStrRequiredconst char *

Symbolic level string

Call Returns

Name

Required

Type

Description

nPRequiredint *

Returns the matching numeric value. Otherwise returns NULL if the level string is not matched.

Example

This method is used to convert symbolic level string to the numeric value.

s = PmLogStringToLevel(s);

if (s != NULL)

{

     return true;

}


PmLogFacilityToString

Description

Returns the matching symbolic string for a given numeric facility value.

Parameters

Name

Required

Type

Description

facility Required int

Numeric facility value

Call Returns

Name

Required

Type

Description

s Required const char *

Returns NULL if the facility is invalid. Otherwise returns the matching symbolic string.

Example

This method is used to convert the given numeric facility value to the symbolic string.

levelStr = PmLogLevelToString(level);

if (levelStr != NULL)

{

    return true;

}    


PmLogStringToFacility

Description

Returns the matching numeric value for a given symbolic facility string.

Parameters

Name

Required

Type

Description

facilityStr Required const char *

Symbolic facility string

Call Returns

Name

Required

Type

Description

nP Required int *

Returns NULL if the facility string is not matched. Otherwise returns the matching numeric value.

Example

This method is used to convert the given symbolic facility string to the numeric value.

nP = PmLogStringToFacility(facilityStr);

if (nP != NULL)

{

     return true;

}    


PmLogGetErrDbgString

Description

Returns a matching symbolic string for a given numeric error code value.

Note

  • For debugging only method, never to appear in user interface!

Parameters

Name

Required

Type

Description

logErr Required PmLogErr

Numeric error code value

Call Returns

Name

Required

Type

Description

"?" Required const char *

Always returns a matching symbolic default string.

Example

This method is used to convert the given numeric error code value to the symbolic string.

Example 1:

if (logErr != kPmLogErr_None)

{

     ErrPrint("Error getting contexts info: 0x%08X (%s)\n", logErr,PmLogGetErrDbgString(logErr));

     return RESULT_RUN_ERR;

}

Example 2:

snprintf(errMsg, errMsgBuffSize, "Error getting context: %s",PmLogGetErrDbgString(logErr));


_PmLogMsgKV

Description

Logs the specified key-value pair(s) and formatted text tagged at given level, to the specified context.

Parameters

Name

Required

Type

Description

context Required struct PmLogContextInfo

Type definition for the logging context as returned by PmLogGetContext method. This is a read-only data view.
Clients should treat this as an opaque structure, however it is referenced 
by the macro/inline functions here.

level Required PmLogLevel

Type definition for discrete logging level

flags Required unsigned int

Indicates whether to enable or disable the version of backward compatibility. 

msgid Required const char *

Message ID 

kv_count Required size_t

Indicates the number of key value pairs in the message.

check_keywords Required const char *

Checks for valid keys allowed to be passed that are seperated
by one of SOH (start of heading), ASCII char,'\\','" ' ' 

check_formats Required const char *

Contains kv_count number of '%' chars.

fmt Required const char *

Indicates the format of the string. For example, %s ,%c, %d. 

variable no of arguments Optional char

Variable numbers of arguments

Call Returns

Name

Required

Type

Description

PmLogErr Required PmLogErr

Type definition for error codes returned by this method

Example

This method is used when user wants to log the specified key-value pair(s) and formatted text, tagged at given level, to the specified context.

*(void **)(&dPmLogMsg) = dlsym(hnd, "_PmLogMsgKV");


PmLogGetLibContext

Description

Returns the context of the process loading the library. This method may be used by shared libraries instead of PmLogGetContext method. That is, libraries do not setup their own context, but make this call to invoke the context of the calling process. This makes it easier for processes to control the logging level of library messages and direct them to specified file as needed.

Parameters

Name

Required

Type

Description

voidRequiredvoid

No input parameter

Call Returns

Name

Required

Type

Description

libProcessContextRequiredstruct PmLogContextInfo

Returns the library context information.

Example

This method is used to get the current loaded library context.

error.log(PmLogGetLibContext(), "LS_SUBS_POST_FAIL");


PmLogSetLibContext

Description

Sets PmLog context.

Parameters

Name

Required

Type

Description

libContextRequiredstruct PmLogContextInfo

PmLog context information

Call Returns

Name

Required

Type

Description

voidOptionalvoid

No return parameter

Example

This method is used to set up context for a process where all library messages can be directed.

PmLogSetLibContext(lib_context);


Enumerators

PmLogErr

 Type definition for error codes returned by this module's methods.

PmLogLevel

Type definition for discrete logging level


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.