プログラムによる生成のための Model Composer API - 2022.1 日本語

Vitis Model Composer ユーザー ガイド (UG1483)

Document ID
UG1483
Release Date
2022-05-26
Version
2022.1 日本語

概要

Model Composer のプログラム生成用スクリプト (PG API スクリプト) は、xBlockxSignalxInport、および xOutport の各オブジェクトをインスタンシエーションして相互に接続することにより、Model Composer サブシステムを構築する MATLAB M 関数ファイルです。これは、Model Composer のダイアグラム (サブシステムなど) をプログラムで構築する方法です。この後例を挙げて説明するように、Model Composer のプログラム スクリプトの最上位の関数は、そのエントリ ポイントであり、xBlock コントラクターを使用して呼び出す必要があります。コンストラクターの終了時に、MATLAB は対応する Model Composer サブシステムを対応するモデルに追加します。モデルが開いていない場合は、新しい無題のモデルが作成され、その中に Model Composer サブシステムが挿入されます。

xBlock コンストラクターにより、xBlock オブジェクトが生成されます。オブジェクトはライブラリ ブロックから作成でき、またはサブシステムにもなります。xSignal オブジェクトは、ソース ブロックとターゲットを接続するワイヤに相当します。xInport オブジェクトは Simulink Inport をインスタンシエートし、xOutport オブジェクトは Simulink Outport をインスタンシエートします。

この API には、Simulink ダイアグラムをプログラミング生成スクリプトに変換する xlsub2script というヘルパー関数もあります。

API は、学習モード、プロダクション モード、デバッグ モードの 3 つのモードで動作します。 学習モードでは、物理的なスクリプト ファイルなしで、コマンドを入力できます。API を習得する際には非常に便利です。このモードでは、すべてのブロック、ポート、サブシステムが untiled という名前の Simulink モデルに追加されます。新しい学習セッションを始める前に必ず、引数なしで xBlock を実行するか、無題のモデルを閉じてください。プロダクション モードでは、M 関数ファイルが必要で、xBlock コンストラクターから起動します。サブシステムが生成されます。サブシステムは、既存のモデルに組み込むことも、新しいモデルに挿入することもできます。デバッグ モードは、新しいオブジェクトが作成されるか新しい接続が確立されるたびに、Simulink ダイアグラムで再配線が実行されることを除き、プロダクション モードと同様に動作します。スクリプトにブレークポイントを設定、スクリプトをシングル ステップ実行するなど、スクリプトをデバッグする際に非常に便利です。

xBlock

xBlock コンストラクターにより、xBlock オブジェクトが生成されます。オブジェクトはライブラリ ブロックから作成でき、またはサブシステムにもなります。xBlock コンストラクターには、3 つの使い方があります。

  • 現在のサブシステムにリーフ ブロックを追加する。
  • 現在のサブシステムにサブシステムを追加する。
  • 最上位サブシステムをモデルに添付する。

xBlock には 4 つの引数を指定し、次のように起動します。

block = xBlock(source, params, inports, outports);

source 引数が文字列の場合は、ライブラリ ブロック名であると想定されます。ソース ブロックが xbsIndex_r4 ライブラリまたは Simulink のビルトイン ライブラリにある場合は、ライブラリ名を付けずにブロック名を使用できます。たとえば、xBlock('AddSub', ...) を呼び出すのは、xBlock('xbsIndex_r4/AddSub',...) と同じです。xbsIndex_r4 ライブラリまたはビルトイン ライブラリにないソース ブロックには、xBlock('xbsTest_r4/Assert Relation', ...) のように、絶対パスを使用する必要があります。source 引数が関数ハンドルの場合は、PG API 関数として解釈されます。MATLAB 構造体であれば、最上位をモデルにどのように添付するのかを指定するコンフィギュレーション構造体として扱われます。

params 引数は、パラメーターを設定します。位置ベースのバインディングの場合はセル配列、名前ベースのバインディングの場合は MATLAB 構造体を指定します。source パラメーターがライブラリ内のブロックの場合、この引数はセル配列である必要があります。source パラメーターが関数ポインターの場合、この引数はセル配列である必要があります。

inports および outports 引数は、サブシステムの入力および出力ポートの結合方法を指定します。バインディングは、位置ベースのバインディングではセル配列、名前ベースのバインディングでは MATLAB 構造体となります。Inport/Outport のバインディングを指定する際、セル配列の要素には xSignalxInport、または xOutport オブジェクトを指定できます。ポート バインディング引数が MATLAB 構造体の場合、構造体のフィールドはブロックのポート名、構造体の値はポートがバインディングされるオブジェクトになります。

2 つのポート バインディング引数はオプションです。xBlock オブジェクトの構築時に引数がない場合は、xBlock オブジェクトの bindPort メソッドでポート バインディングを指定できます。bindPort メソッドは次のように実行します。

block.bindPort(inports, outports)

ここで、inports および outports 引数は、入力ポートと出力ポートのバインディングを指定します。この場合、xBlock はソースとパラメーター バインディングの 2 つの引数のみでオブジェクト ブロックを作成します。

xBlock には、ほかに次のようなメソッドがあります。

  • names = block.getOutportNames: outport 名のセル配列を返します。
  • names = block.getInportNames: inport 名のセル配列を返します。
  • nin = block.getNumInports: inport の数を返します。
  • nout = block.getNumoutports: outport の数を返します。
  • insigs = block.getInSignals: 入力信号名のセル配列を返します。
  • outsigs = block.getOutSignals: 出力信号名のセル配列を返します。

xInport

xInport オブジェクトは、サブシステムの入力ポートを表します。

コンストラクター

port = xInport(port_name)

port_name という名前の xInport オブジェクトを作成します。

[port1, port2, port3, ...] = xInport(name1, name2, name2, ...)

名前付きの入力ポートのリストを作成します。

port = xInport

自動生成された名前の入力ポートを作成します。

xInport オブジェクトはポート バインディング用に渡すことができます。

メソッド

outsigs = port.getOutSignals

出力信号名のセル配列を返します。

xOutport

xOutport オブジェクトは、サブシステムの出力ポートを表します。

コンストラクター

port = xOutport(port_name)

port_name という名前の xOutport オブジェクトを作成します。

[port1, port2, port3, ...] = xOutport(name1, name2, name2, ...)

名前付きの出力ポートのリストを作成します。

port = xOutport

自動生成された名前の出力ポートを作成します。

xOutport オブジェクトはポート バインディング用に渡すことができます。

メソッド

port.bind(obj)

オブジェクトをポートに接続します。port は xOutport オブジェクト、obj は xSignal または xInport オブジェクトです。

insigs = port.getInSignals

入力信号名のセル配列を返します。

xSignal

xSignal オブジェクトは、ソースとターゲットを接続する信号オブジェクトを表します。

コンストラクター

sig = xSignal(sig_name)

sig_name という名前の xSignal オブジェクトが作成されます。

[sig1, sig2, sig3, ...] = xSignal(name1, name2, name2, ...)

名前付きの信号のリストを作成します。

sig = xSignal

自動生成された名前の xSignal を作成します。

xSignal オブジェクトはポート バインディング用に渡すことができます。

メソッド

sig.bind(obj)

obj to sig を接続します。sigxSignal オブジェクト、objxSignal または xInport オブジェクトです。

src = sig.getSrc

xSignal オブジェクトを駆動しているソース オブジェクトのセル配列を返します。セル配列には、最大で 1 つの要素を含めることができます。ソースが入力ポートの場合、ソース オブジェクトは xInport オブジェクトとなります。ソースがブロックの出力ポートの場合、ソース オブジェクトは構造体で、block と port の 2 つのフィールドがあります。block フィールドには xBlock オブジェクト、port フィールドにはポート インデックスが入ります。

dst = sig.getDst

xSignal オブジェクトが駆動しているデスティネーション オブジェクトのセル配列を返します。各要素は、構造体またはxOutport オブジェクトのいずれかになります。getSrc メソッドの戻り値と同じように定義されています。

xlsub2script

xlsub2script は、サブシステムを System Generator スクリプトの最上位に変換するヘルパー関数です。

xlsub2script(Subsystem) は、サブシステムを最上位のスクリプトに変換します。引数にはモデルも指定できます。

デフォルトでは、生成される M 関数ファイルの名前には、サブシステムの名前が使用され、スペースはアンダースコアに置き換えられます。xlsub2script が終了すると、生成されたスクリプトの使用方法を説明するヘルプ メッセージが表示されます。この xlsub2script 関数の主な目的は、System Generator スクリプトの学習を容易にすることです。これは、グラフィックを使用してサブシステムを構築し、そのサブシステムを PG API の M 関数に変換できる優れたユーティリティでもあります。

xlsub2script(block) (block は最下位ブロック) は、ブロックを作成する xBlock 呼び出しを出力します。

xlsub2script の制限は次のとおりです。

  • サブシステムのマスク初期化コードに gcbset_paramget_param、add_block などの関数呼び出しが含まれている場合、関数はエラーになるので、マスク初期化コードを修正してこれらの Simulink 呼び出しを削除する必要があります。
  • サブシステム内でグローバル変数にアクセスできる場合は、xlsub2script を実行するトップ サブシステムに、対応するマスク パラメーターを追加する必要があります。
  • ブロックのリンクが切れていると、そのブロックは省略されます。

xlsub2script は、次のように読み出すこともできます。

xlsub2script(subsyste, options)

options は、MATLAB 構造体です。options 構造体は、forcewritebasevars の 2 つのフィールドを持つことができます。

同じサブシステムに対し xlsub2script を 2 回目に呼び出すと、xlsub2script は既存の M 関数ファイルを上書きしようとします。デフォルトでは、xlsub2script により、ファイルを上書きするかどうかを確認する質問ダイアログ ボックスが表示されます。options 引数の forcewrite フィールドが true または 1 に設定されている場合は、xlsub2script により M 関数ファイルは強制的に上書きされます。

サブシステムは、MATLAB ベースのワークスペースにある一部の変数に依存していることがあります。その場合は、xlsub2script を実行したときに、xlsub2script がこれらのベース ワークスペース変数を取得し、ベース ワークスペース変数を処理する適切なコードを生成するようにする必要があります。options 引数の basevars フィールドはそのためのものです。xlsub2script がベース ワークスペースのすべての変数を取得するようにする必要がある場合は、basevars フィールドを all に設定します。xlsub2script に変数を選択的に取得する必要がある場合は、basevars フィールドを文字列のセル配列 (各文字列は変数名) を設定します。

次に、options 引数を指定して xlsub2script を呼び出した例を示します。

xlsub2script(Subsystem, struct('forcewrite', true));
xlsub2script(Subsystem, struct('forcewrite', true, 'basevars', 

 'all'));
options.basevars = {'var1', 'var2', 'var3');
xlsub2script(Subsystem, options);
xlsub2script(Subsystem, struct('basevars', {{'var1', 'var2', 

 'var3'}}));

MATLAB では、構造体のフィールドがセル配列の場合、struct() 関数を呼び出すときに追加の {} が必要になります。

xBlockHelp

xBlockHelp(<block_name>) は、パラメーター名と、そのパラメーターに有効な値を出力します。パラメーターを指定せずに xBlockHelp を実行すると、xbsIndex_r4 ライブラリで使用可能なブロックが一覧表示されます。

たとえば、MATLAB のコマンド ラインで次を実行したとします。

xBlockHelp('AddSub')

この場合、次の表が表示されます。

'xbsIndex_r4/AddSub' Parameter Table

Parameter              Acceptable value        Type
============           ==================      ========
mode                   'Addition'              String
                       'Subtraction'           
                       'Addition or Subtraction' 
------------           ------------------      --------
use_carryin            'off'                   String
                       'on'                    
------------           ------------------      --------
use_carryout           'off'                   String
                       'on'                    
------------           ------------------      --------
en                     'off'                   String
                       'on'                    
------------           ------------------      --------
latency                An Int value            Int
------------           ------------------      --------
precision              'Full'                  String
                       'User Defined'          
------------           ------------------      --------
arith_type             'Signed  (2's comp)'    String
                       'Unsigned'              
------------           ------------------      --------
n_bits                 An Int value            Int
------------           ------------------      --------
bin_pt                 An Int value            Int
------------           ------------------      --------
quantization           'Truncate'              String
                       'Round  (unbiased: +/- Inf)' 
------------           ------------------      --------
overflow               'Wrap'                  String
                       'Saturate'              
                       'Flag as error'         
------------           ------------------      --------
use_behavioral_HDL     'off'                   String
                       'on'                    
------------           ------------------      --------
pipelined              'off'                   String
                       'on'                    
------------           ------------------      --------
use_rpm                'off'                   String
                       'on'                    
------------           ------------------      --------