Add verbose mode attribute handling (COVESA#292)

dlt_user_log_write_*_attr() enables to writing these types, but also support
adding "attributes" for them, i.e. a "name" and a "unit".

Signed-off-by: Martin Willers <[email protected]>

Author: mawillers

Diff for: doc/dlt_for_developers.md

@@ -631,6 +631,19 @@ if (dlt_user_log_write_start(&ctx, &ctxdata, DLT_LOG_INFO) > 0) {
 }
 ```
 
+#### Attributes
+
+In verbose mode, log message arguments can contain attributes. A "name" attribute
+describes the purpose or semantics of an argument, and a "unit" attribute
+describes its unit (if applicable - not all argument data types support having
+a "unit" attribute).
+
+```
+dlt_user_log_write_float64_attr(&myctxdata, 4.2, "speed", "m/s");
+```
+
+In non-verbose mode, these attributes are not added to the message.
+
 ### Logging parameters
 
 The following parameter types can be used. Multiple parameters can be added to
@@ -640,25 +653,45 @@ exceed 1390 bytes, including the DLT message header.
 Type | Description
 --- | ---
 DLT\_STRING(TEXT) | String
+DLT\_STRING\_ATTR(TEXT,NAME) | String (with attribute)
 DLT\_SIZED\_STRING(TEXT,LENGTH) | String with known length
+DLT\_SIZED\_STRING\_ATTR(TEXT,LENGTH,NAME) | String with known length (with attribute)
 DLT\_CSTRING(TEXT) | Constant string (not sent in non-verbose mode)
+DLT\_CSTRING\_ATTR(TEXT,NAME) | Constant string (with attribute; not sent in non-verbose mode)
 DLT\_SIZED\_CSTRING(TEXT,LENGTH) | Constant string with known length (not sent in non-verbose mode)
+DLT\_SIZED\_CSTRING\_ATTR(TEXT,LENGTH,NAME) | Constant string with known length (with attribute; not sent in non-verbose mode)
 DLT\_UTF8(TEXT) | Utf8-encoded string
+DLT\_UTF8\_ATTR(TEXT,NAME) | Utf8-encoded string (with attribute)
 DLT\_SIZED\_UTF8(TEXT,LENGTH) | Utf8-encoded string with known length
+DLT\_SIZED\_UTF8\_ATTR(TEXT,LENGTH,NAME) | Utf8-encoded string with known length (with attribute)
 DLT\_RAW(BUF,LENGTH) | Raw buffer
+DLT\_RAW\_ATTR(BUF,LENGTH,NAME) | Raw buffer (with attribute)
 DLT\_INT(VAR) | Integer variable, dependent on platform
+DLT\_INT\_ATTR(VAR,NAME,UNIT) | Integer variable, dependent on platform (with attributes)
 DLT\_INT8(VAR) |Integer 8 Bit variable
+DLT\_INT8\_ATTR(VAR,NAME,UNIT) |Integer 8 Bit variable (with attributes)
 DLT\_INT16(VAR) | Integer 16 Bit variable
+DLT\_INT16\_ATTR(VAR,NAME,UNIT) | Integer 16 Bit variable (with attributes)
 DLT\_INT32(VAR) | Integer 32 Bit variable
+DLT\_INT32\_ATTR(VAR,NAME,UNIT) | Integer 32 Bit variable (with attributes)
 DLT\_INT64(VAR) | Integer 64 bit variable
+DLT\_INT64\_ATTR(VAR,NAME,UNIT) | Integer 64 bit variable (with attributes)
 DLT\_UINT(VAR) | Unsigned integer variable
+DLT\_UINT\_ATTR(VAR,NAME,UNIT) | Unsigned integer variable (with attributes)
 DLT\_UINT8(VAR) | Unsigned 8 Bit integer variable
+DLT\_UINT8\_ATTR(VAR,NAME,UNIT) | Unsigned 8 Bit integer variable (with attributes)
 DLT\_UINT16(VAR) |Unsigned 16 Bit integer variable
+DLT\_UINT16\_ATTR(VAR,NAME,UNIT) |Unsigned 16 Bit integer variable (with attributes)
 DLT\_UINT32(VAR) | Unsigned 32 Bit integer variable
+DLT\_UINT32\_ATTR(VAR,NAME,UNIT) | Unsigned 32 Bit integer variable (with attributes)
 DLT\_UINT64(VAR) | Unsigned 64 bit integer variable
+DLT\_UINT64\_ATTR(VAR,NAME,UNIT) | Unsigned 64 bit integer variable (with attributes)
 DLT\_BOOL(VAR) | Boolean variable
+DLT\_BOOL\_ATTR(VAR,NAME) | Boolean variable (with attribute)
 DLT\_FLOAT32(VAR) | Float 32 Bit variable
+DLT\_FLOAT32\_ATTR(VAR,NAME,UNIT) | Float 32 Bit variable (with attributes)
 DLT\_FLOAT64(VAR) | Float 64 Bit variable
+DLT\_FLOAT64\_ATTR(VAR,NAME,UNIT) | Float 64 Bit variable (with attributes)
 DLT\_HEX8(UINT\_VAR) | 8 Bit hex value
 DLT\_HEX16(UINT\_VAR) | 16 Bit hex value
 DLT\_HEX32(UINT\_VAR) | 32 Bit hex value

Diff for: include/dlt/dlt_common.h

@@ -75,6 +75,7 @@
 
 #   include <netinet/in.h>
 #   include <stdio.h>
+#   include <stdbool.h>
 #   ifdef __linux__
 #      include <linux/limits.h>
 #      include <sys/socket.h>
@@ -89,8 +90,10 @@
 
 #   if defined(__GNUC__)
 #      define PURE_FUNCTION __attribute__((pure))
+#      define PRINTF_FORMAT(a,b) __attribute__ ((format (printf, a, b)))
 #   else
 #      define PURE_FUNCTION /* nothing */
+#      define PRINTF_FORMAT(a,b) /* nothing */
 #   endif
 
 #   if !defined (__WIN32__) && !defined(_MSC_VER)
@@ -1170,6 +1173,13 @@ void dlt_log_set_fifo_basedir(const char *pipe_dir);
  * @param level the level
  */
 void dlt_log_set_level(int level);
+
+/**
+ * Set whether to print "name" and "unit" attributes in console output
+ * @param state  true = with attributes, false = without attributes
+ */
+void dlt_print_with_attributes(bool state);
+
 /**
  * Initialize (external) logging facility
  * @param mode positive, 0 = log to stdout, 1 = log to syslog, 2 = log to file, 3 = log to stderr
@@ -1180,7 +1190,7 @@ void dlt_log_init(int mode);
  * @param format format string for message
  * @return negative value if there was an error or the total number of characters written is returned on success
  */
-int dlt_user_printf(const char *format, ...);
+int dlt_user_printf(const char *format, ...) PRINTF_FORMAT(1,2);
 /**
  * Log ASCII string with null-termination to (external) logging facility
  * @param prio priority (see syslog() call)

Diff for: include/dlt/dlt_user.h.in

@@ -313,6 +313,21 @@ DltReturnValue dlt_user_log_write_finish(DltContextData *log);
  */
 DltReturnValue dlt_user_log_write_bool(DltContextData *log, uint8_t data);
 
+/**
+ * Write a boolean parameter with "name" attribute into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param data  boolean parameter written into log message (mapped to uint8)
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_bool_attr(DltContextData *log, uint8_t data, const char *name);
+
 /**
  * Write a float parameter into a DLT log message.
  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
@@ -333,6 +348,38 @@ DltReturnValue dlt_user_log_write_float32(DltContextData *log, float32_t data);
  */
 DltReturnValue dlt_user_log_write_float64(DltContextData *log, double data);
 
+/**
+ * Write a float parameter with attributes into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name or @a unit is NULL, this function will add a corresponding attribute field with length 0
+ * and no content to the message for that attribute.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param data  float32_t parameter written into log message
+ * @param name  the "name" attribute (or NULL)
+ * @param unit  the "unit" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_float32_attr(DltContextData *log, float32_t data, const char *name, const char *unit);
+
+/**
+ * Write a double parameter with attributes into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name or @a unit is NULL, this function will add a corresponding attribute field with length 0
+ * and no content to the message for that attribute.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param data  float64_t parameter written into log message
+ * @param name  the "name" attribute (or NULL)
+ * @param unit  the "unit" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_float64_attr(DltContextData *log, float64_t data, const char *name, const char *unit);
+
 /**
  * Write a uint parameter into a DLT log message.
  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
@@ -347,6 +394,26 @@ DltReturnValue dlt_user_log_write_uint16(DltContextData *log, uint16_t data);
 DltReturnValue dlt_user_log_write_uint32(DltContextData *log, uint32_t data);
 DltReturnValue dlt_user_log_write_uint64(DltContextData *log, uint64_t data);
 
+/**
+ * Write a uint parameter with attributes into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name or @a unit is NULL, this function will add a corresponding attribute field with length 0
+ * and no content to the message for that attribute.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param data  unsigned int parameter written into log message
+ * @param name  the "name" attribute (or NULL)
+ * @param unit  the "unit" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_uint_attr(DltContextData *log, unsigned int data, const char *name, const char *unit);
+DltReturnValue dlt_user_log_write_uint8_attr(DltContextData *log, uint8_t data, const char *name, const char *unit);
+DltReturnValue dlt_user_log_write_uint16_attr(DltContextData *log, uint16_t data, const char *name, const char *unit);
+DltReturnValue dlt_user_log_write_uint32_attr(DltContextData *log, uint32_t data, const char *name, const char *unit);
+DltReturnValue dlt_user_log_write_uint64_attr(DltContextData *log, uint64_t data, const char *name, const char *unit);
+
 /**
  * Write a uint parameter into a DLT log message. The output will be formatted as given by the parameter type.
  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
@@ -384,6 +451,27 @@ DltReturnValue dlt_user_log_write_int8(DltContextData *log, int8_t data);
 DltReturnValue dlt_user_log_write_int16(DltContextData *log, int16_t data);
 DltReturnValue dlt_user_log_write_int32(DltContextData *log, int32_t data);
 DltReturnValue dlt_user_log_write_int64(DltContextData *log, int64_t data);
+
+/**
+ * Write an int parameter with attributes into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name or @a unit is NULL, this function will add a corresponding attribute field with length 0
+ * and no content to the message for that attribute.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param data  int parameter written into log message
+ * @param name  the "name" attribute (or NULL)
+ * @param unit  the "unit" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_int_attr(DltContextData *log, int data, const char *name, const char *unit);
+DltReturnValue dlt_user_log_write_int8_attr(DltContextData *log, int8_t data, const char *name, const char *unit);
+DltReturnValue dlt_user_log_write_int16_attr(DltContextData *log, int16_t data, const char *name, const char *unit);
+DltReturnValue dlt_user_log_write_int32_attr(DltContextData *log, int32_t data, const char *name, const char *unit);
+DltReturnValue dlt_user_log_write_int64_attr(DltContextData *log, int64_t data, const char *name, const char *unit);
+
 /**
  * Write a null terminated ASCII string into a DLT log message.
  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
@@ -449,6 +537,101 @@ DltReturnValue dlt_user_log_write_utf8_string(DltContextData *log, const char *t
  */
 DltReturnValue dlt_user_log_write_sized_utf8_string(DltContextData *log, const char *text, uint16_t length);
 
+/**
+ * Write a null-terminated ASCII string with "name" attribute into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param text  pointer to the parameter written into log message containing null termination
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_string_attr(DltContextData *log, const char *text, const char *name);
+
+/**
+ * Write a potentially non-null-terminated ASCII string with "name" attribute into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param text  pointer to the parameter written into log message
+ * @param length  length in bytes of @a text (without any termination character)
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_sized_string_attr(DltContextData *log, const char *text, uint16_t length, const char *name);
+
+/**
+ * Write a constant, null-terminated ASCII string with "name" attribute into a DLT log message.
+ * In non-verbose mode, this parameter will not be sent at all.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param text  pointer to the parameter written into log message containing null termination
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_constant_string_attr(DltContextData *log, const char *text, const char *name);
+
+/**
+ * Write a constant, potentially non-null-terminated ASCII string with "name" attribute into a DLT log message.
+ * In non-verbose mode, this parameter will not be sent at all.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param text  pointer to the parameter written into log message containing null termination
+ * @param length  length in bytes of @a text (without any termination character)
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_sized_constant_string_attr(DltContextData *log, const char *text, uint16_t length, const char *name);
+
+/**
+ * Write a null-terminated UTF-8 string with "name" attribute into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param text  pointer to the parameter written into log message containing null termination
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_utf8_string_attr(DltContextData *log, const char *text, const char *name);
+
+/**
+ * Write a potentially non-null-terminated UTF-8 string with "name" attribute into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param text  pointer to the parameter written into log message
+ * @param length  length in bytes of @a text (without any termination character)
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_sized_utf8_string_attr(DltContextData *log, const char *text, uint16_t length, const char *name);
+
 /**
  * Write a binary memory block into a DLT log message.
  * dlt_user_log_write_start has to be called before adding any attributes to the log message.
@@ -472,6 +655,39 @@ DltReturnValue dlt_user_log_write_raw(DltContextData *log, void *data, uint16_t
  */
 DltReturnValue dlt_user_log_write_raw_formatted(DltContextData *log, void *data, uint16_t length, DltFormatType type);
 
+/**
+ * Write a binary memory block with "name" attribute into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param data  pointer to the parameter written into log message.
+ * @param length  length in bytes of the parameter written into log message
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_raw_attr(DltContextData *log, const void *data, uint16_t length, const char *name);
+
+/**
+ * Write a binary memory block with "name" attribute into a DLT log message.
+ * dlt_user_log_write_start has to be called before adding any parameters to the log message.
+ * Finish building a log message by calling dlt_user_log_write_finish.
+ *
+ * If @a name is NULL, this function will add an attribute field with length 0
+ * and no content to the message.
+ *
+ * @param log  pointer to an object containing information about logging context data
+ * @param data  pointer to the parameter written into log message.
+ * @param length  length in bytes of the parameter written into log message
+ * @param type  the format information
+ * @param name  the "name" attribute (or NULL)
+ * @return value from DltReturnValue enum
+ */
+DltReturnValue dlt_user_log_write_raw_formatted_attr(DltContextData *log, const void *data, uint16_t length, DltFormatType type, const char *name);
+
 /**
  * Trace network message
  * @param handle pointer to an object containing information about one special logging context