Asynchronous formatted output (log.h)

The API is defined in the header file sysroot-*-kos/include/kos/log.h from the KasperskyOS SDK.

The API enables formatted output similar to functions of the printf family but asynchronously, meaning while executing non-blocking calls. For example, this provides the capability for formatted output in interrupt handlers in which you could not otherwise execute calls that are blocking calls and therefore have an indeterminate duration.

Information about API functions is provided in the table below.

Using the API

The standard scenario for API usage includes the following steps:

Create a log.
To complete this step, call the KosLogCreateEx() or KosLogCreate() function. A log is an object that contains a queue of formatted strings that are organized according to the FIFO (First In, First Out) principle. Creating a log automatically creates a thread that runs a loop to extract the first string from the queue in this log and perform one of the following actions:
- Puts the string extracted from the log into the diagnostic output that is written, for example, to a COM port or USB port (version 3.0 or later, with DbC support) depending on the kernel configuration.
  This variant is applied if the log was created by calling the KosLogCreateEx() function with the RTL_NULL value in the logFunc parameter or by calling the KosLogCreate() function.
- It passes the string extracted from the log to the callback function defined via the logFunc parameter of the KosLogCreateEx() function.
  The callback function receives the pointer to the formatted string and the size of this string (without taking into account the terminating zero, in bytes) via its own buf and len parameters, respectively. For example, this callback function may write the formatted string to the buffer instead of sending it to diagnostic output.
When using the KosLogCreate() function, the maximum number of formatted strings in a log and their maximum size (taking into account the terminating zero, in bytes) are defined by the KOS_LOG_QUEUE_CAPACITY_DEFAULT and KOS_LOG_MSG_SIZE_DEFAULT constants, respectively. The KosLogCreateEx() function lets you define these log parameters.
Print formatted output.
To print a formatted string, you must add this string to the log by calling the KosLogVWrite() or KosLogWrite() function. Optionally, the KosLogWrite() function receives a sequence of parameters (...) whose values must be put into the formatted string. The KosLogVWrite() function receives the list of values to put into the formatted string via the ap parameter of the rtl_va_list type. Therefore, this function must be used together with the rtl_va_start() and rtl_va_end() macros defined in the header file sysroot-*-kos/include/rtl/stdarg.h from the KasperskyOS SDK.

If the log is completed filled, the KosLogVWrite() and KosLogWrite() functions end with the rcOutOfMemory error. In addition, the thread that extracts the formatted strings from the log puts a message about data loss into the diagnostic output or uses another method to pass this message (depending on the implementation of the callback function defined via the logFunc parameter of the KosLogCreateEx() function).
Delete the log.
To complete this step, call the KosLogDestroy() function.

Prior to deletion, you can verify that the log is empty by calling the KosLogIsEmpty() function.

Information about API functions

log.h functions

Function	Information about the function
`KosLogCreateEx()`	Purpose Creates a log. Parameters [in] `msgSize` – maximum size of formatted strings in the log, taking into account the terminating zero (in bytes). It must not exceed the value of the `KOS_LOG_MSG_SIZE_MAX` constant. [in] `capacity` – maximum number of formatted strings in the log. It must not exceed the value of the `KOS_LOG_QUEUE_CAPACITY_MAX` constant. [in,optional] `logFunc` – ID of the callback function that is called when each formatted string is extracted from the log, or `RTL_NULL` to put the formatted strings extracted from the log into diagnostic output. [out] `outH` – pointer to the log ID. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosLogCreate()`	Purpose Creates a log with the default parameters. Parameters [out] `outH` – pointer to the log ID. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosLogDestroy()`	Purpose Deletes a log. Parameters [in] `handle` – log identifier. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosLogVWrite()`	Purpose Adds a formatted string to a log. Parameters [in] `handle` – log identifier. [in] `fmt` – pointer to the formatting string (just like for functions of the `printf` family). [in] `ap` – list of parameters whose values must be put into the formatted string. The list type is defined in the header file `sysroot-*-kos/include/rtl/stdarg.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. Additional information Thread-safe function. Non-blocking call.
`KosLogWrite()`	Purpose Adds a formatted string to a log. Parameters [in] `handle` – log identifier. [in] `fmt` – pointer to the formatting string (just like for functions of the `printf` family). [in,optional] `...` – sequence of parameters whose values must be put into the formatted string. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. Additional information Thread-safe function. Non-blocking call.
`KosLogIsEmpty()`	Purpose Verifies whether a log is empty. Parameters [in] `handle` – log identifier. Returned values If the verification is successful, the function returns `rtl_true`, otherwise it returns `rtl_false`.

Page top