can-api-generator 1.0.0__py3-none-any.whl

can_api_generator/msg_processor.py

@@ -0,0 +1,385 @@
+"""
+Message_processor
+=================
+
+The objects that are constructed from the cantools message and signal types and that compute the
+extra data needed to allow for proper templating to happen
+"""
+import functools
+import operator
+import copy
+import random
+from can_db_model.model import MuxMember
+from .utils import is_valid_c_identifier, converrt_to_c_identifier
+from .utils import convert_to_cantools_signal_name
+from .utils import get_signal_type_from_range, get_bit_length_from_type
+from .types import SignalType, SignalDirection, ByteOrder, SignalProcessingException, MessageProcessingException
+
+
+class CAPIMessage:
+    def __init__(self, msg, api_name: str, node_name: str,
+                 bus_name: str, require_endpoints: bool = True):
+        """
+        msg is a can_db_model.model.Message. bus_name is the database's bus
+        name (the model carries the bus at the top level, not per-message).
+
+        require_endpoints: when False, missing producers/consumers are not
+        errors. Used by the cbdb path, where the decoder is a bus observer
+        and direction metadata is irrelevant.
+        """
+        self.bus = bus_name
+        self.name = msg.name
+        self.node = node_name
+        self.arb_id = msg.id
+        self.is_extended = msg.extended
+        # prefix for the struct names
+        self.api_prefix = api_name
+        if msg.length > 8:
+            raise MessageProcessingException(
+                "Message too large for v2.0B spec",
+                self.name, node_name)
+        self.length = msg.length
+        if len(msg.producers) == 0 and require_endpoints:
+            raise MessageProcessingException("No Sender defined",
+                                             self.name, node_name)
+        self.periodic = msg.interval is not None
+        self.period = msg.interval
+        self.signals = list(
+            map(lambda sig: CAPISignal(sig, self, node_name,
+                                       require_endpoints), msg.signals))
+        self.init_message_direction(msg.producers, self.length)
+        self.update_signals_depending_on_direction()
+        self.all_signals = copy.copy(self.signals)
+        self.build_mux_tree()
+
+    def init_message_direction(self, senders, length):
+        if self.node in senders:
+            self.direction = SignalDirection.TX
+            if any(map(lambda s: s.direction == SignalDirection.RX
+                       or s.direction == SignalDirection.RT,
+                       self.signals)):
+                self.direction = SignalDirection.RT
+        elif any(map(lambda s: s.direction == SignalDirection.RX,
+                     self.signals)):
+            self.direction = SignalDirection.RX
+        elif length == 0:
+            self.direction = SignalDirection.RX
+        else:
+            self.direction = SignalDirection.NA
+
+    def update_signals_depending_on_direction(self):
+        if self.direction == SignalDirection.NA:
+            if any(map(lambda s: s.direction == SignalDirection.RX,
+                       self.signals)):
+                self.direction = SignalDirection.RX
+                self.signals = list(filter(
+                    lambda s: s.direction == SignalDirection.RX
+                    or s.direction == SignalDirection.RT
+                    or s.is_multiplex,
+                    self.signals
+                ))
+                for s in self.signals:
+                    s.direction = SignalDirection.RX
+        elif self.direction == SignalDirection.TX:
+            self.signals = list(
+                filter(lambda s: s.direction != SignalDirection.RX,
+                       self.signals))
+            for s in self.signals:
+                s.direction = SignalDirection.TX
+        elif self.direction == SignalDirection.RT:
+            for s in self.signals:
+                if s.direction == SignalDirection.NA:
+                    if s.is_multiplex:
+                        s.direction = SignalDirection.RT
+                    else:
+                        s.direction = SignalDirection.TX
+        elif self.direction == SignalDirection.RX:
+            self.signals = list(
+                filter(lambda s: s.direction == SignalDirection.RX
+                       or s.direction == SignalDirection.RT
+                       or s.is_multiplex,
+                       self.signals))
+            for s in self.signals:
+                s.direction = SignalDirection.RX
+
+    def build_mux_tree(self):
+        muxes = list(filter(lambda s: s.is_multiplex, self.signals))
+        for mux in muxes:
+            multiplexed_signals = list(filter(lambda s: s.multiplexer == mux.name, self.signals))
+            mux.variants = dict([(
+                mux.labeled_defines.get(vid, vid),
+                list(filter(lambda s: s.mux_group == vid, multiplexed_signals)))
+                                 for vid in set(map(lambda s: s.mux_group, multiplexed_signals))])
+            for s in multiplexed_signals:
+                self.signals.remove(s)
+
+    def struct_name(self):
+        if ' ' not in self.name:
+            return ''.join(map(lambda s: s.capitalize(), self.name.split('_')))
+        else:
+            return ''.join(map(lambda s: s.capitalize(), self.name.split()))
+
+    def to_dict(self):
+        return {
+            'bus': self.bus,
+            'node': self.node,
+            'arb_id': hex(self.arb_id),
+            'name': converrt_to_c_identifier(self.name),
+            'kcd_name': self.name,
+            'periodic': self.periodic,
+            'period' : self.period,
+            'offset_seed': random.randrange(0, 2**32-1),
+            'api_prefix': self.api_prefix,
+            'struct_name': self.struct_name(),
+            'length': self.length,
+            'direction': str(self.direction),
+            'signals': [ s.to_dict() for s in self.signals],
+            'max_mux_len': max(list(map(lambda m: len(list(m.variants)), filter(lambda s: s.is_multiplex, self.signals))) + [1]),
+            'all_signals': [ s.to_flat_dict() for s in self.all_signals],
+        }
+
+
+class CAPISignal:
+    def __init__(self, signal, parent: CAPIMessage,
+                 node_name: str, require_endpoints: bool = True):
+        # can_db_model labels -> the {value: name} dict the rest of this
+        # method expects (the old code read cantools' signal.choices).
+        choices = {lab.value: lab.name for lab in signal.labels}
+
+        self.name = signal.name
+        self.api_var_name = self.converrt_name_to_c_identifier()
+        self.parent = parent
+        self.is_multiplex = signal.mux == "multiplexor"
+        # figure out message direction
+        if node_name in signal.consumers:
+            if len(set(signal.consumers)) > 1:
+                self.direction = SignalDirection.RT
+            else:
+                self.direction = SignalDirection.RX
+        else:
+            self.direction = SignalDirection.NA
+        # check if the wire representation is float (needed later)
+        self.is_float = signal.type in ("single", "double")
+        self.is_signed = signal.type == "signed"
+        # determin the size of the signal
+        self.byte_order = ByteOrder.LITTLE_ENDIAN
+        self.start_bit = signal.start
+        if signal.length > 64:
+            raise SignalProcessingException(
+                    "Signals larger than 64 bit are not supported",
+                    self.name, parent.name, node_name)
+        elif self.is_float:
+            # there are only two lengths allowed if a float is used
+            if signal.length not in [32, 64]:
+                raise SignalProcessingException(
+                    "Signal declared as float but the length is not 32 bit",
+                    self.name, parent.name, node_name)
+        self.length = signal.length
+        # determmin byte order (currently only little endian is supported)
+        if signal.endianness != "little":
+            raise SignalProcessingException(
+                    "Only little endian encoding is supported",
+                    self.name, parent.name, node_name)
+        # determin range of the signal
+        # The model types slope/intercept as float, but the codegen distinguishes
+        # integer scaling (emits integer division) from fractional scaling. Keep
+        # integral values as int so e.g. slope 2 yields `/ 2`, not `/ 2.0`.
+        self.scale = (int(signal.slope)
+                      if float(signal.slope).is_integer() else signal.slope)
+        self.offset = (int(signal.intercept)
+                       if float(signal.intercept).is_integer() else signal.intercept)
+        self.min = signal.min
+        self.max = signal.max
+        # presentation info for the client sidecar (not used by codegen)
+        self.unit = signal.unit
+        self.labels = dict(choices)
+        if self.is_float:
+            # we know it is a float so just put things here for now
+            self.theoretical_min = -1000000
+            self.theoretical_max = 1000000
+        elif self.is_signed:
+            self.theoretical_min = - pow(2, self.length - 1) * self.scale + self.offset
+            self.theoretical_max = (pow(2, self.length - 1) - 1) * self.scale + self.offset
+        else:
+            self.theoretical_min = self.offset
+            self.theoretical_max = (pow(2, self.length) - 1) * self.scale + self.offset
+        if 0 < self.theoretical_min or 0 > self.theoretical_max:
+            raise SignalProcessingException(
+                "0 lies outside the range of representable values, "
+                "this is not supported as it leads to large discrepencies with"
+                "the 0 initialized structs",
+                self.name, parent.name, node_name)
+
+        # determin the type of the variable holding the signal in the API
+        if self.is_float:
+            if self.length == 32:
+                self.signal_type = SignalType.FLOAT_32_BIT
+                self.api_signal_length = 32
+                self.wire_signal_type = SignalType.FLOAT_32_BIT
+            elif self.length == 64:
+                self.signal_type = SignalType.FLOAT_64_BIT
+                self.api_signal_length = 64
+                self.wire_signal_type = SignalType.FLOAT_64_BIT
+            else:
+                raise SignalProcessingException(
+                        "Only lengths of 32 and 64 bit are allowed for "
+                        "'single' data type",
+                        self.name, parent.name, node_name)
+            self.neg_sign_extension_prefix = None
+            self.neg_check_mask = None
+        elif int(self.offset) != self.offset or int(self.scale) != self.scale:
+            # Non-integer scale/offset forces the API-visible value into a float,
+            # but the wire representation is still an integer. The decode path
+            # therefore has to extract the raw integer (sign-extending if needed)
+            # before casting to float and applying the slope/intercept — it
+            # cannot reinterpret the raw bits as an IEEE 754 float.
+            self.signal_type = SignalType.FLOAT_32_BIT
+            self.api_signal_length = 32
+            if self.is_signed:
+                self.wire_signal_type = SignalType.SIGNED_64_BIT
+                wire_bits = 64
+                if self.length < wire_bits:
+                    self.neg_sign_extension_prefix = '0b' + ''.join(
+                        '0' if i < self.length else '1'
+                        for i in reversed(range(wire_bits)))
+                    self.neg_check_mask = 1 << self.length - 1
+                else:
+                    self.neg_sign_extension_prefix = None
+                    self.neg_check_mask = None
+            else:
+                self.wire_signal_type = SignalType.UNSIGNED_64_BIT
+                self.neg_sign_extension_prefix = None
+                self.neg_check_mask = None
+        else:
+            self.signal_type = get_signal_type_from_range(self.theoretical_min,
+                                                          self.theoretical_max)
+            self.wire_signal_type = self.signal_type
+            if self.signal_type is None:
+                raise SignalProcessingException(
+                        "No API type could be found to hold the values "
+                        "represented on the wire",
+                        self.name, parent.name, node_name)
+            self.api_signal_length = get_bit_length_from_type(self.signal_type)
+            if self.is_signed and self.api_signal_length > self.length:
+                self.neg_sign_extension_prefix = '0b'+''.join(['0' if i < self.length else '1' for i in reversed(range(self.api_signal_length))])
+                self.neg_check_mask = 1 << self.length - 1
+            else:
+                self.neg_sign_extension_prefix = None
+                self.neg_check_mask = None
+
+        # check if we have labled variables and build a data structure that we can use
+        self.labeled_values = dict(
+            map(lambda c: (c[0], converrt_to_c_identifier(str(c[1]))),
+                choices.items())) if choices else dict()
+        self.labeled_defines = dict(
+            map(lambda c: (c[0], self.build_lable_define(str(c[1]))),
+                choices.items())) if choices else dict()
+        self.multiplexer = (signal.mux.of
+                            if isinstance(signal.mux, MuxMember) else None)
+        if self.multiplexer:
+            self.mux_group = signal.mux.group
+        else:
+            self.mux_group = None
+
+        # do some checks for cases that are not yet supported and are
+        # a bit of an edge case
+        if self.labeled_values and self.offset != 0 and self.scale != 1:
+            raise SignalProcessingException(
+                "Having a scaled value with labels is not supported",
+                self.name, parent.name, node_name)
+        if self.is_multiplex:
+            if self.offset != 0 or self.scale != 1:
+                raise SignalProcessingException(
+                        "A Multiplex with scale or offset is not supported",
+                        self.name, parent.name, node_name)
+        self.variants = {}
+        if (len(signal.consumers) == 0 and not self.is_multiplex
+                and require_endpoints):
+            raise SignalProcessingException(
+                    "No Receiver defined",
+                    self.name, parent.name, node_name)
+
+    def signal_mask(self):
+        mask = 0
+        for i in range(self.length):
+            mask += 1 << i
+        return str(hex(mask))
+
+    def converrt_name_to_c_identifier(self):
+        ident_candidate = converrt_to_c_identifier(self.name)
+        if is_valid_c_identifier(ident_candidate):
+            return ident_candidate
+        else:
+            raise SignalProcessingException(
+                "Signal name cannot be converted into valid C identifier",
+                self.name, self.parent.name, '')
+
+    def build_lable_define(self, lable) -> str:
+        """
+        Buld the define string for the lable of signal
+        """
+        if type(lable) is int:
+            return lable
+        return self.parent.name.upper() + '_' + self.name.upper() + '_' + converrt_to_c_identifier(lable).upper()
+
+
+    def resolve_muxed_signal_name(self):
+        """
+        Generate a unique name for the C identifier in the API for signals
+
+        In some occasions involving Multiplexes, the signal names in the KCD
+        file may be identical for two signals in the same message. These signals then
+        differ by
+        """
+        if not self.is_multiplex:
+            return
+        # 
+        all_muxed_signals = functools.reduce(operator.iconcat, self.variants.values(), [])
+        all_muxed_names = list(map(lambda s: s.name, all_muxed_signals))
+        all_duplicate_signal_names = set([name for name in all_muxed_names if all_muxed_names.count(name) > 1])
+        # resolve the name for the signals that have identical names
+        for duplicate_name in all_duplicate_signal_names:
+            signals_with_duplicate_name = list(filter(lambda s: s.name == duplicate_name, all_muxed_signals))
+            for signal in signals_with_duplicate_name:
+                # match the signal to the mux index
+                for mux_val, variant_signals in self.variants.items():
+                    if signal not in variant_signals:
+                        continue
+                    matching_mux_label = list(filter(lambda lv: lv[1] == mux_val, self.labeled_defines.items()))
+                    if len(matching_mux_label) == 0:
+                        signal.api_var_name = '_'.join([self.api_var_name, str(mux_val), signal.api_var_name])
+                    else:
+                        matching_mux_label = self.labeled_values[matching_mux_label[0][0]]
+                        matching_mux_label = converrt_to_c_identifier(matching_mux_label)
+                        signal.api_var_name = '_'.join([matching_mux_label, signal.api_var_name])
+
+    def to_dict(self):
+        return {
+            'name': self.api_var_name,
+            'kcd_name': self.name,
+            'cantools_name': convert_to_cantools_signal_name(self.api_var_name),
+            'is_scaled': self.scale != 1 or self.offset != 0, # extra code needs to be included if a value is scaled (makes checks shorter in the templates)
+            'scale': self.scale,
+            'offset': self.offset,
+            'start_bit': self.start_bit,
+            'length': self.length,
+            'wire_data_type': str(self.wire_signal_type),
+            'api_length': self.api_signal_length,
+            'labeled_values': self.labeled_values.items(),
+            'label_defines': self.labeled_defines.items(),
+            'direction': str(self.direction),
+            'api_data_type': str(self.signal_type),
+            'sign_extension_prefix': self.neg_sign_extension_prefix,
+            'sign_bit_mask': hex(self.neg_check_mask) if self.neg_check_mask else None,
+            'multiplex': self.is_multiplex,
+            'mask': self.signal_mask(),
+            'theoretical_min': self.theoretical_min,
+            'theoretical_max': self.theoretical_max,
+            'mux_groups': dict([(gid, list(map(lambda v: v.to_dict(), vsigs))) for gid, vsigs in self.variants.items()]),
+        }
+
+    def to_flat_dict(self):
+        retval = self.to_dict()
+        del(retval['mux_groups'])
+        return retval
+

can_api_generator/templates/canframe.jinja

@@ -0,0 +1,12 @@
+#ifndef CANFRAME_H
+#define CANFRAME_H
+#include <stdint.h>
+
+typedef struct CanFrame {
+    uint16_t {{ length_member_name }};
+    uint32_t {{ arb_id_member_name }};
+    uint64_t {{ payload_member_name }};
+} CanFrame;
+#endif
+
+

can_api_generator/templates/declaration_macros.jinja

@@ -0,0 +1,23 @@
+{% macro declare_message_struct(message) -%}
+struct {{ message.struct_name }} {
+{%- for signal in message.all_signals %}
+    {{ signal.api_data_type }} {{ signal.name }};
+{%- endfor %}
+};
+{%- endmacro %}
+
+{% macro generate_msg_defines(message) -%}
+// Message specific defines
+#define {{ message.name | upper }}_ID {{ message.arb_id }}
+#define {{ message.name | upper }}_LENGTH {{ message.length }}
+{%- endmacro %}
+
+{% macro generate_label_defines(message) -%}
+{%- for signal in message.all_signals %}
+{%- if signal.label_defines | length > 0 %}// Defines for specific values of {{ signal.name }} as specified by the kcd
+{% endif -%}
+{% for val in signal.label_defines -%}
+    #define {{ val[1] }} {{ val[0] }}
+{% endfor -%}
+{%- endfor -%}
+{%- endmacro -%}

can_api_generator/templates/dyndec_header.jinja

@@ -0,0 +1,73 @@
+#ifndef DYNDEC_H
+#define DYNDEC_H
+/*
+ * Dynamic CAN signal decoder driven by a descriptor cbdb compiled with
+ * `can-api-gen cbdb`. Generated by can-api-generator -- do not edit.
+ *
+ * The cbdb is a table of message/signal descriptors (bit positions, scale,
+ * offset, mux membership). dyndec_process_frame() decodes a received frame
+ * against the table and stores every signal as its physical value (float)
+ * in a flat store, indexed by the signal's position in the cbdb.
+ */
+#include <stdint.h>
+#include "canframe.h"
+
+#define DYNDEC_OK             0
+#define DYNDEC_ERR_MAGIC    (-1)
+#define DYNDEC_ERR_VERSION  (-2)
+#define DYNDEC_ERR_SIZE     (-3)
+#define DYNDEC_ERR_BOUNDS   (-4)
+#define DYNDEC_ERR_CAPACITY (-5)
+#define DYNDEC_ERR_ORDER    (-6)
+
+#define DYNDEC_CBDB_FORMAT_VERSION 1
+
+/* Index entry for one message record inside the cbdb. */
+typedef struct DyndecMsgRef {
+    uint32_t cbdb_offset;
+    uint16_t first_value_idx;
+    uint16_t n_signals;
+} DyndecMsgRef;
+
+typedef struct DyndecContext {
+    const uint8_t *cbdb;
+    uint32_t cbdb_size;
+    uint16_t msg_count;
+    uint16_t signal_count;
+    DyndecMsgRef *msg_index;
+    float *values;
+} DyndecContext;
+
+/*
+ * Validate `cbdb` and build the message index. `msg_index` and `values`
+ * are caller-provided storage; capacities are checked against the cbdb's
+ * message and signal counts. The cbdb memory must stay valid and unchanged
+ * for the lifetime of the context. The value store is zeroed.
+ */
+int dyndec_init(DyndecContext *ctx, const uint8_t *cbdb, uint32_t cbdb_size,
+                DyndecMsgRef *msg_index, uint16_t max_msgs,
+                float *values, uint16_t max_signals);
+
+/*
+ * Decode a received frame. Returns the matched message's index, or -1 if
+ * the arbitration id is not in the cbdb. Muxed signals are only updated
+ * when their selector matches; all other signals of the message are
+ * updated with their physical (scaled) value.
+ */
+int dyndec_process_frame(DyndecContext *ctx, const CanFrame *frame);
+
+/* Find the value-store index for a signal id; -1 if unknown. */
+int32_t dyndec_lookup(const DyndecContext *ctx, uint32_t signal_id);
+
+/* Latest stored physical value at a store index from dyndec_lookup(). */
+float dyndec_get_value(const DyndecContext *ctx, int32_t value_idx);
+
+/* Signal id stored at a given store index (for enumeration). */
+uint32_t dyndec_signal_id_at(const DyndecContext *ctx, uint16_t value_idx);
+
+uint16_t dyndec_signal_count(const DyndecContext *ctx);
+
+/* SHA-256 of the KCD file this cbdb was compiled from (32 bytes). */
+const uint8_t *dyndec_kcd_hash(const DyndecContext *ctx);
+
+#endif