PG API Examples - 2022.1 English

Hello World

In this example, you will run the PG API in the learning mode where you can type the commands in the MATLAB® command shell.

1. To start a new learning session, in MATLAB command console, run: xBlock.
2. Type the following three commands in MATLAB command console to create a new Subsystem named 'Subsystem' inside a new model named 'untitled'.

   [a, b] = xInport('a', 'b'); 
   s = xOutport('s'); 
   adder = xBlock('AddSub', struct('latency', 1), {a, b}, {s});

   Figure 1. Subsystem Example

The above commands create the Subsystem with two Simulink Inports a and b, an adder block having a latency of one, and a Simulink Outport s. The two Inports source the adder which in turn sources the Subsystem outport. The AddSub parameter refers to the AddSub block inside the xbsIndex_r4 library. By default, if the full block path is not specified, xBlock will search xbsIndex_r4 and built-in libraries in turn. The library must be loaded before using xBlock. So please use load_system to load the library before invoking xBlock.

MACC

1. Run this example in the learning mode. To start a new learning session, run: xBlock.
2. Type the following commands in the MATLAB console window to create a multiply-accumulate function in a new Subsystem.

   [a, b] = xInport('a', 'b'); 
   mac = xOutport('mac'); 
   m = xSignal; 
   mult = xBlock('Mult', struct('latency', 0, 'use_behavioral_HDL', 'on'), {a, b}, 
   {m}); 
   acc = xBlock('Accumulator', struct('rst', 'off', 'use_behavioral_HDL', 'on'), {m}, 
   {mac});

By directing Model Composer to generate behavioral HDL, the two blocks should be packed into a single DSP48 block. As of this writing, Vivado synthesis only does so if you force the multiplier block to be combinational.

Figure 2. Forcing a Mult Block

mult_ins = mult.getInSignals 
mult_ins{1} 
mult_ins{2} 
src_a = mult_ins{1}.getSrc 
src_a{1} 
m_dst = m.getDst 
m_dst{1} 
m_dst{1}.block

MACC in a Masked Subsystem

If you want a particular Subsystem to be generated by the PG API and pass parameters from the mask parameters of that Subsystem to PG API, you need to run the PG API in production mode, where you need to have a physical M-function file and pass that function to the xBlock constructor.

1. Create the top-level PG API M-function file MACC_sub.m with the following lines.

   function MACC_sub(latency, nbits) 
   [a, b] = xInport('a', 'b'); 
   mac = xOutport('mac'); 
   if latency <= 0 
      error('latency must be positive'); 
   elseif latency == 1 
      a_in = a; b_in = b; 
   else 
      [a_in, b_in] = xSignal; 
      dblock1 = xBlock('Delay', struct('latency', latency - 1, 'reg_retiming', 'on'), 
   {a}, {a_in}); 
      block2 = xBlock('Delay', struct('latency', latency - 1, 'reg_retiming', 'on'), 
   {b}, {b_in}); 
   end 
   m = xSignal; 
   mult = xBlock('Mult', struct('latency', 0, 'use_behavioral_HDL', 'on'), {a_in, 
   b_in}, {m}); 
   acc = xBlock('Accumulator', struct('rst', 'off', 'n_bits', nbits, 
   'use_behavioral_HDL', 'on'), {m}, {mac});

   Figure 3. Top-Level PG API M-Function File
   
   
   
2. To mask the Subsystem defined by the script, add two mask parameters latency and nbits.
   Figure 4. Adding Latency Parameter
   
   
3. Then put the following lines to the mask initialization of the Subsystem.

   config.source = str2func('MACC_sub'); 
   config.toplevel = gcb; 
   xBlock(config, {latency, nbits});

   In the production mode, the first argument of the xBlock constructor is a MATLAB struct for configuration, which must have a source field and a toplevel field. The source field is a function pointer pointing to the M-function and the toplevel is a string specifying the Simulink Subsystem. If the top-level field is 1, an untitled model is created and a Subsystem inside that model is created.

   Figure 5. Adding nbits Parameter
   
   

   Alternatively you can use the MATLAB struct call to create the toplevel configuration:

   xBlock(struct('source', str2func(MACC_sub), 'toplevel', gcb),{latency, 
   
    nbits});

   Then click OK.

   You'll get the following Subsystem.

   Figure 6. Creating Toplevel Configuration
   
   
4. Set the mask parameters as shown in the following figure, then click OK.
   Figure 7. Adding Mask Parameters
   
   

   The following diagram is generated:

   Figure 8. Generated Diagram
   
   

config.source = str2func('MACC_sub'); 
config.toplevel = gcb; 
config.debug = 1; 
xBlock(config, {latency, nbits});

By setting the debug field of the configuration struct to be 1, you run the PG API in debug mode where every action will trigger an auto layout.

config.source = str2func('MACC_sub'); 
config.toplevel = gcb; 
config.depend = {'MACC_sub.m'}; 
xBlock(config, {latency, nbits});

The depend field of the configuration struct is a cell array. Each element of the array is a file name. You can put a p-file name or an M-file name. You can also put a name without a suffix. The xBlock will use the first in the path.