はじめに
Vivado プロジェクト内のブロックデザイン (block design) は、ファイル名に .bd という拡張子が付いたファイルで表現されます。例えば vivado_system.bd です。このファイルにはブロックデザインに関するすべての情報が、テキスト形式で、しかも人間が読める形で含まれています。古いバージョンの Vivado では、このファイルは XML 形式で書かれていました。現在では、ブロックデザインの表現に JSON 形式が使われています。
テキスト形式のおかげで、2 つのブロックデザインファイルを、よく知られたテキスト比較ツール(diff や、それに類する GUI ツール)で比較することができます。これにより、ブロックデザインにどのような変更が加えられたかを追跡できます。
しかし JSON 形式には、テキストファイルの比較という観点からすると、大きな欠点が 1 つあります。オブジェクトの定義の中で、プロパティとその値が任意の順序で並べられ得るのです。したがって、2 つの JSON ファイルの情報内容が完全に同じであっても、diff などのツールは、テキスト内容が大幅に異なっているように表示することがあります。
残念ながら、Vivado が生成するブロックデザインファイルの一部にも、この問題があります。その結果、2 つの .bd ファイルをテキスト比較すると、情報の並び順が一貫していないことに起因する、誤解を招く差分が数多く表示されます。
JSON ファイルの正規化
テキストファイル内の並び順がランダムになる問題に対する自然な解決策は、そのファイルを正規形 (canonical form) にすることです。このような正規化 (canonicalization) の実行方法には、RFC 8785 に厳密な定義があります。ただし、2 つのファイルを比較する目的であれば、その標準に従う必要はありません。ランダムな並べ替えを避ければ十分です。
簡単な方法の 1 つは、オブジェクトのプロパティを、プロパティ名のアルファベット順に並べ替えることです。これにより、JSON ファイル内の情報が常に一貫した順序で表現されます。ただし、この方法で情報を並べ替えると、欠点もあります。通常、プロパティはファイルを読みやすくする順序で並んでいます。重要なプロパティはファイルの先頭側に置かれ、プロパティはその意味に応じてグループ化されています。そのため、正規形の JSON ファイルは、やや読みにくくなります。
Perl スクリプト
JSON Perl モジュールのおかげで、JSON ファイルの正規化を実行する Perl スクリプトを簡単に書けます。
#!/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;
このスクリプトは、次のようなコマンドで使います。
$ ./jsonize.pl vivado_system.bd > canonicalized.bd
ブロックデザインを比較するには、正規化した 2 つの JSON ファイルをテキスト比較してください。