Note di Implementazione ICD - Discrepanze e Decisioni

Documento: Tracciamento discrepanze tra specifica ICD e implementazione di riferimento
Riferimento ICD: ICD_DECD_FTH - GRIFO-F_TH, Data Exchange Control Document for, rev -A, Draft 2
Implementazione di Riferimento: GrifoScope C++ (th_b1553_icd.h)
Data Prima Revisione: Dicembre 2025

🎯 Principio Guida

In caso di discrepanza tra ICD documento e implementazione C++ GrifoScope, si segue SEMPRE l'implementazione C++.

Motivazioni:

GrifoScope è il software di riferimento testato e funzionante sul campo
Il simulatore radar GRIFO-F/TH risponde ai messaggi codificati secondo l'implementazione C++
La compatibilità binaria con il sistema esistente è requisito critico
L'ICD documento potrebbe contenere errori di trascrizione o versioni superate

📋 Discrepanze Identificate

1. Designation Control Field (A2/01 e B7/01)

ICD Documento (Sezione 7.1.2.1 - Tab. A2/01-B):

Field B: Designation Control
Bit No: 04, 05, 06, 07 (4 bits)
NOT VALID = decimal 15 (0b1111)

Implementazione C++ GrifoScope (th_b1553_icd.h, linee 434-444):

typedef idd_bitfield_u16_t<IDD_REVBIT16(6), 3, des_control_t> des_control_field_t;
//                          IDD_REVBIT16(6) → LSB position = 15-6 = 9
//                                       ^^^ Width = 3 bits (NON 4!)

enum des_control_t {
  LOCK_ON,           // 0
  LOCK_ON_DTT,       // 1
  TRANS_HPT_BUT,     // 2
  REJECT,            // 3
  LOCK_ON_STT,       // 4
  DES_TRACK_LABEL,   // 5
  EXEC_SAR,          // 6
  NOT_VALID          // 7 (massimo rappresentabile con 3 bits)
};

Decisione Implementativa:

✅ Adottato: 3 bits, range 0-7, NOT_VALID = 7
❌ Scartato: 4 bits, range 0-15, NOT_VALID = 15

Impatto:

Tutti i bit successivi in Word A2/01 e B7/01 shiftati di 1 posizione verso sinistra
File modificati:
- pybusmonitor1553/lib1553/constants.py: DesignationControl enum corretta
- pybusmonitor1553/lib1553/messages/msg_a2.py: designation_ctrl width=3
- pybusmonitor1553/lib1553/messages/msg_b7.py: designation_status width=3

Verifica Compatibilità:

# Test: tools/compare_a2_messages.py
# Risultato: ✓ MATCH binario al 100% con encoding C++ atteso
Phase 1: Expected=0x0E88, Actual=0x0E88 ✓
Phase 2: Expected=0x0E00, Actual=0x0E00 ✓

🔍 Metodologia di Verifica

Quando si implementano nuovi messaggi o si modificano strutture esistenti:

Step 1: Confronto ICD vs C++

# Leggere definizione ICD documento
doc/ICD_DECD_FTH...md → Sezione specifica messaggio

# Verificare implementazione C++ (fonte di verità)
___OLD/_old/cpp/GrifoScope/GrifoSdkEif/pub/TH/th_b1553_icd.h

Step 2: Analisi Typedef C++

La macro IDD_REVBIT16(N) converte bit ICD MSB-first a LSB position:

#define IDD_REVBIT16(pos) (15 - pos)

// Esempio:
typedef idd_bitfield_u16_t<IDD_REVBIT16(8), 1, stby_selection_t> stby_field_t;
// IDD_REVBIT16(8) = 15-8 = 7 (LSB shift position)
// Width = 1 bit
// In MSB numbering: 15-7 = Bit 8 (ICD)

Step 3: Implementazione Python

# msg_aX.py o msg_bX.py
field_name = EnumField(
    word_index=X,
    start_bit=N,    # Numero bit ICD (MSB-first, 0-15)
    width=W,        # Width da C++ typedef
    enum_cls=EnumClass
)

# La classe Field calcola automaticamente:
# _shift = 16 - (start_bit + width)

Step 4: Test Binario

# Creare test dedicato simile a tools/compare_a2_messages.py
# Verificare encoding word-per-word contro valori attesi C++
assert actual_word == expected_cpp_word, f"Mismatch: 0x{actual_word:04X} != 0x{expected_cpp_word:04X}"

📊 Tabella Riepilogativa Campi Critici

Messaggio	Word	Campo	ICD Bits	C++ Bits	Python start_bit	Python width
A2	01	master_mode	00-03	00-03	0	4
A2	01	designation_ctrl	04-07 ❌	04-06 ✅	4	3
A2	01	int_bit_req	08 ❌	07 ✅	7	1
A2	01	standby_cmd	09 ❌	08 ✅	8	1
A2	01	freeze_cmd	10 ❌	09 ✅	9	1
A2	01	pwr_up_stop	11 ❌	10 ✅	10	1
A2	01	reserved	12 ❌	11 ✅	11	1
A2	01	silence	13 ❌	12 ✅	12	1
B7	01	master_mode_tb	00-03	00-03	0	4
B7	01	designation_status	04-07 ❌	04-06 ✅	4	3
B7	01	int_bit_status	08 ❌	07 ✅	7	1
B7	01	standby_status	09 ❌	08 ✅	8	1
B7	01	freeze_status	10 ❌	09 ✅	9	1
B7	01	degraded_status	11 ❌	10 ✅	10	1
B7	01	reserved	12 ❌	11 ✅	11	1
B7	01	rf_radiation_status	13 ❌	12 ✅	12	1
B7	01	transition_status	14 ❌	13 ✅	13	1
B7	01	last_acq_result	15 ❌	14 ✅	14	1

Legenda:

❌ = ICD documento (ERRATO, non usare)
✅ = Implementazione C++ (CORRETTO, usato nel codice)

🔄 Storia Revisioni

Data	Autore	Modifiche
2025-12-12	AI/Developer	Documento creato. Identificata discrepanza Designation Control (3 vs 4 bits). Corretti A2/01 e B7/01. Verificata compatibilità binaria.

📞 Contatti e Segnalazioni

Se vengono identificate nuove discrepanze:

Non modificare il codice basandosi solo sull'ICD documento
Verificare sempre con th_b1553_icd.h C++
Documentare in questo file la discrepanza trovata
Testare compatibilità binaria con test dedicato
Aggiornare tabella riepilogativa

🔗 Riferimenti

ICD Documento: doc/ICD_DECD_FTH - GRIFO-F_TH, Data Exchange Control Document for, rev -A, Draft 2.md
Header C++ Riferimento: ___OLD/_old/cpp/GrifoScope/GrifoSdkEif/pub/TH/th_b1553_icd.h
Implementazione Simulator: ___OLD/_old/cpp/GrifoScope/GrifoMCS/GADS/MCS/MCS_G346/g346/g346_a1a2.cpp
Architettura Tecnica: doc/Technical-Architecture.md (Sezione 2.4)
Test Compatibilità: tools/compare_a2_messages.py

6.0 KiB Raw Permalink Blame History