================================================================================
  SOFA on CANopen FD — Address Mapping

  Module:     CANopen FD address mapping for the SOFA secure tunnel
  Files:      variants/canopen_fd/common/fbsec_co_fd_addr.{c,h}
              variants/canopen_fd/common/fbsec_co_fd_usdo.{c,h}
  Version:    V1.0 of 08-MAY-2026
  License:    Apache License, Version 2.0
              www.apache.org/licenses/LICENSE-2.0
  Author:     Embedded Systems Academy, Inc (USA) and GmbH (Germany)
================================================================================


  This is a thin companion to the main SOFA specification
  (`fieldbus_sim_secure_tunnel_spec.txt`). The main spec defines
  the cryptographic protocol (AAD, nonce, AEAD direction tags, keyid
  byte semantics) in transport-agnostic terms.

  This document covers ONLY the two mappings a CANopen FD
  integrator needs in addition: how the SOFA `device_id` field
  maps to a CANopen node id, and how the SOFA `data_id` field
  maps to a CANopen (index, subindex) pair.

  USDO PDU layout, reserved CAN IDs, and the on-wire bit allocation
  of the keyid byte are documented in code (header comments in
  `variants/canopen_fd/common/fbsec_co_fd_usdo.h`); the
  protocol-flow visualization is in `flow_diagrams.txt` (this
  directory).


--------------------------------------------------------------------------------
1. device_id <-> CANopen node id
--------------------------------------------------------------------------------

  SOFA carries a 16-bit `device_id` in its AAD prefix
  (`shared/fbsec_aead.h`, AAD bytes 4..5). On a CANopen FD
  deployment:

      device_id = (uint16_t)node_id      with node_id in 1..127

  The upper byte is zero. Both peers MUST agree on this mapping;
  the AEAD verifies it because `device_id` is part of the AAD
  prefix that the tag covers. Replay against a different node
  fails the tag check.

  Server (responder) device_id = own CANopen node id.
  Client (requester) device_id field, when supplied as a request
  parameter to the secure-tunnel API, names the TARGET server's
  node id.

  The CANopen FD wire CAN ID separately encodes the sender's node
  id in its low 7 bits (`0x600 + sender` for requests,
  `0x580 + sender` for responses). The CAN-ID-encoded sender and
  the BUF[0] receiver-node-id together form the source-of-truth
  for routing on a real CAN FD bus; the AAD `device_id` binding
  is what makes that routing tamper-evident.


--------------------------------------------------------------------------------
2. data_id <-> (index, subindex)
--------------------------------------------------------------------------------

  SOFA carries a 32-bit `data_id` in its AAD prefix
  (`shared/fbsec_aead.h`, AAD bytes 6..9). On a CANopen FD
  deployment the encoding is:

      data_id = ((index & 0xFFFF) << 16) | ((sub & 0xFF) << 8)

  The low byte stays 0x00; it is reserved for per-bus protocol
  fields that some industrial buses carry alongside the address.
  Decoders MUST reject any frame whose `data_id` low byte is
  non-zero (the SOFA FD codec does so via
  `fbsec_co_fd_data_id_is_canopen_form`).

  Worked examples (from the four SOFA demo OD entries):

       0x20100000   ->  index 0x2010  sub 0x00
       0x20200000   ->  index 0x2020  sub 0x00
       0xC0160000   ->  index 0xC016  sub 0x00
       0xC0180000   ->  index 0xC018  sub 0x00

  CiA-301 reserves indexes below 0x1000 for protocol use; SOFA
  application-data entries SHOULD live in the manufacturer-
  specific area (0x2000..0x5FFF) or the device-profile range
  matching the device class. The choice does not affect any
  byte on the wire; `data_id` is simply the index/sub pair
  promoted into the AAD.

  Helpers:
      fbsec_co_fd_data_id_from_index_sub    builds the data_id
      fbsec_co_fd_index_sub_from_data_id    extracts (index, sub)
      fbsec_co_fd_data_id_is_canopen_form   validates an inbound
                                            wire data_id

  All in `variants/canopen_fd/common/fbsec_co_fd_addr.{c,h}`.


--------------------------------------------------------------------------------
3. Everything else
--------------------------------------------------------------------------------

  - Cryptographic protocol, AEAD direction tags, AAD layout, keyid
    byte semantics, four secure-tunnel flows:
        fieldbus_sim_secure_tunnel_spec.txt

  - USDO PDU byte layout, reserved CAN IDs, SIM_* control events,
    PCAN-bridge auto-probe behavior:
        variants/canopen_fd/common/fbsec_co_fd_usdo.h
        variants/canopen_fd/bus/fbsec_co_fd_bus.c
        variants/canopen_fd/bus/fbsec_co_fd_pcan.h

  - Sequence-diagram visualization of the four flows:
        flow_diagrams.txt   (this directory)

  - Putting SOFA onto a real CANopen FD device (USDO callback
    wiring, OD entry placement, abort-code mapping):
        EmSA-UM-105-COP FBsec CANopen V01.docx, "Integration Guide" chapter


/* EOF */
