.. _chg__0_14__0_15:

0.14.x → 0.15.x
===============

No structural change: no field was renamed, moved, added or removed, and every 0.14 workspace
keeps its layout. What changed is that a set of constraints the model always intended is now
declared on the fields themselves — which makes them visible in the JSON Schema exported from
:class:`~flync.model.flync_model.FLYNCModel`, and makes a few previously-tolerated values fail
validation.

Breaking — YAML schema
----------------------

Empty identifiers and references are rejected
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Required identifier and reference strings now declare ``min_length=1``. An empty value was
previously accepted and only surfaced further along as a confusing reference error (an empty
``pdu_ref`` reported as ``unknown PDU ''``), or silently produced an unnamed object.

Affected are the required ``name``, ``id``, ``label``, ``group``, ``service``, ``profile_id``,
``ecu_name``, ``controller_name``, ``interface_name``, ``bus_name`` and ``*_ref``
(``pdu_ref``, ``bus_ref``, ``socket_ref``, ``frame_ref``) fields across every domain.

.. code-block:: yaml

   # no longer valid
   - name: ""
     pdu_ref: ""

Optional fields are unaffected: leaving one out, or setting it to ``null`` where the model
allows that, behaves exactly as before.

Negative values are rejected on quantities that cannot be negative
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``ge=0`` was added to:

* MACsec MKA timers — ``hello_time``, ``bounded_hello_time``, ``life_time``,
  ``sak_retire_time`` (matching ``sak_rekey_time``, which already declared it),
* PTP time-receiver timeouts — ``sync_timeout``, ``sync_followup_timeout``,
* HTB shaping — ``classid``, ``rate``, ``ceil``, ``priority``, and ``HTBFilter.filter_priority``,

Container PDU header field widths are capped at 32 bits
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``ContainerPDUHeader.id_length_bits`` and ``ContainerPDUHeader.length_field_bits`` now
declare ``le=32`` in addition to the existing ``multiple_of=8``. Widths above 32 bits were
previously accepted although no supported container format uses one.

.. code-block:: yaml

   header:
     id_length_bits: 40     # no longer valid, must be 0, 8, 16, 24 or 32
     length_field_bits: 64  # no longer valid, must be 0, 8, 16, 24 or 32

Additive — YAML schema
----------------------

New optional instrumentation overlay
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The optional ``instrumentation/`` folder (:ref:`flync_4_instrumentation <instrumentation>`) wraps the
measurement points under an ``Instrumentation`` container on the root model:
``flync_model.instrumentation`` is ``None`` without the folder, otherwise an
``Instrumentation`` whose ``measurement_points`` load from
``instrumentation/measurement_points.flync.yaml``. Each measurement point is identified by
its ASAM CMP / TECMP interface ids and taps exactly one medium:

* ``type: ethernet_ports`` — one or two ECU ports of a point-to-point Ethernet link, one
  ``interface_id`` per port (two ports must be the two ends of the same connection),
* ``type: ethernet_bus`` — one interface id for an ``ethernet_multidrop`` segment, by connection id,
* ``type: can_bus`` — one interface id plus the ``payload_types`` captured on the bus
  (``can_fd`` is required exactly on ``fd_enabled`` buses),
* ``type: lin_bus`` — one interface id for a LIN bus.

``name`` and every interface id are unique across the overlay, and ``flync_model.instrumentation``
is an ``Instrumentation`` instance carrying ``.measurement_points``. No 0.14 workspace has the
folder, so workspaces keep their layout; adding the overlay is purely optional.