Einführung
Ein Blockdesign (englisch: block design) innerhalb eines Vivado-Projekts wird durch eine Datei dargestellt, deren Dateiname die Endung .bd hat, zum Beispiel vivado_system.bd. Diese Datei enthält alle Informationen über das Blockdesign in einem textuellen, für Menschen lesbaren Format. In älteren Versionen von Vivado wurde diese Datei im XML-Format geschrieben. Heute wird das JSON-Format verwendet, um ein Blockdesign abzubilden.
Dank des textuellen Formats ist es möglich, zwei Blockdesign-Dateien mit bekannten Werkzeugen für Textvergleiche zu vergleichen (diff und ähnliche grafische Werkzeuge). So lässt sich nachvollziehen, welche Änderungen am Blockdesign vorgenommen wurden.
Das JSON-Format hat jedoch einen erheblichen Nachteil in Bezug auf Textvergleiche: Bei den Objektdefinitionen können die Eigenschaften und ihre Werte in beliebiger Reihenfolge stehen. Daher können Werkzeuge wie diff anzeigen, dass sich der Textinhalt zweier JSON-Dateien deutlich unterscheidet, obwohl sie exakt dieselben Informationen enthalten.
Leider sind einige Teile der von Vivado erzeugten Blockdesign-Dateien von diesem Problem betroffen. Ein Textvergleich zwischen zwei .bd-Dateien zeigt daher viele irreführende Unterschiede, die auf eine inkonsistente Reihenfolge der Informationen zurückzuführen sind.
Kanonisierung einer JSON-Datei
Die natürliche Lösung für eine willkürliche Reihenfolge in einer Textdatei ist, diese Datei in eine kanonische Form zu bringen. In RFC 8785 gibt es eine strikte Definition, wie eine solche Kanonisierung durchzuführen ist. Für den Zweck des Dateivergleichs muss man dieser Norm jedoch nicht folgen. Es genügt, die willkürliche Umordnung zu vermeiden.
Eine einfache Lösung besteht darin, die Eigenschaften von Objekten alphabetisch nach ihren Namen zu sortieren. Das sorgt für eine konsistente Darstellung der Informationen in einer JSON-Datei. Diese Umsortierung der Informationen hat jedoch einen Nachteil. Normalerweise sind die Eigenschaften in einer Reihenfolge aufgelistet, die die Datei gut lesbar macht: Wichtige Eigenschaften stehen meist am Anfang der Datei, und inhaltlich zusammengehörige Eigenschaften sind gruppiert. Eine JSON-Datei in kanonischer Form ist daher etwas schwerer zu lesen.
Ein Perl-Skript
Dank des Perl-Moduls JSON ist es einfach, ein Perl-Skript (englisch: script) zu schreiben, das eine Kanonisierung einer JSON-Datei durchführt:
#!/usr/bin/perl
use warnings;
use strict;
use JSON;
local $/; # Slurp mode
my $json = JSON->new->allow_nonref->space_after->indent->canonical;
my $in = <>;
my $h = $json->decode($in);
my $out = $json->encode($h);
print $out;
Verwende dieses Skript mit einem Befehl wie diesem:
$ ./jsonize.pl vivado_system.bd > canonicalized.bd
Um Blockdesigns zu vergleichen, führe einen Textvergleich zweier kanonisierter JSON-Dateien durch.