www.coware.com

A

Manually Creating Custom-Coded Blocks

The SPW Block Wizard automates much of the work involved in creating a custom-coded block. It is recommended that you use the Block Wizard instead of manually creating your blocks. For more information, see "Creating Custom-Coded Blocks with the Block Wizard" in the Simulator User's Guide.

Introduction

SPW comes with an extensive library of signal-processing blocks. Additional blocks are available in optional SPW libraries such as the Communications Library-Floating Point.

In addition to these blocks, you can create your own blocks, either by building them hierarchically (such as the notch60 block in Chapter 3) or by specifying the block behavior using C or C++ code. A block whose function you program yourself in C or C++ is called a custom-coded block. Once programmed, a custom-coded block can be used like any other library block.

Briefly, these are the steps in creating a custom-coded block:

  1. Create the symbol model.
  2. Create the parameter screen model.
  3. Generate the source code template file(s).
  4. Insert the signal-processing source code into the applicable template file.
  5. Compile the code.
  6. Test the new block.

The first part of the tutorial shows you how to create a simple custom-coded block for the SPB-I simulator. Then it shows you the additional steps required to make the block work with the SPB-C simulator. Finally, the tutorial presents some examples of blocks coded in C++.

Create the Symbol

The block you will create initially is a simple comparator with two inputs, x and y. The output z is 1.0 when x is greater than y and -1.0 when x is less than y. If x and y are exactly equal, the output z remains unchanged from the previous output sample. In the case where the x and y inputs are equal at the very beginning of the simulation, a block parameter setting determines the initial output value.

To create a block symbol, you can use commands such as Add-Box, Add-Port, Add-Line, and Add-Text to build the symbol element by element. However, it is usually easier to copy an existing symbol and modify it as needed.

Display an Existing Symbol

  1. Open a new BDE design window.
  2. Execute the following command: 
    3. File-Open
  3. In the dialog box, toggle on the Logical Name option.
  4. In the Select field, enter the following name:

    5. spb/eq_real.symbol

  5. Click on the OK button.
  6. Execute the following command: 
    7. View-Zoom To Fit 
 
    
The design window displays the Equal Real symbol as shown in Figure A-1.
Figure A-1  "Equal Real" Block Symbol View

Modify the Existing Symbol

  1. Press and hold the right mouse button. In the pop-up menu, select the following command: 
    2. Snap Off
  2. Double-click on the text note in the center of the block that says "=REAL".
  3. In the dialog box, change the text from "=REAL" to "COMP".
  4. Click on the OK button.
  5. Using the middle mouse button, move the text note so that it is centered between the left and right sides of the symbol box, as shown in Figure A-2.
Figure A-2  Modified Symbol View

Save the Modified Symbol

  1. Execute the following command: 
    2. File-Save As
  2. In the New Filename field, enter the following name:

    3. yourlib/comp.symbol

  3. Toggle on the Group Name option and enter the following name in the Group Name field:

    4. >Blocks>User Blocks>Comparator

  4. Verify that the Model Type button is set to Symbol.

    5. BDE automatically sets the Model Type button to Symbol based on the view name, ".symbol". BDE does some extra error checking when you save a symbol view.

  5. Click on the OK button.

    6. BDE saves the modified symbol view under the specified name.

Note: If you copy a symbol view from an optional SPW block library (such as the Communications Library-Floating Point), you cannot save the modified view directly with the File-Save As command because of licensing requirements. In that case, you can use the commands Select-All, Edit-Copy, File-New, and Edit-Paste to enable saving with the File-Save As command.

Create the Parameter Screen

Every custom-coded block must have an associated parameter screen (a ".params" view). Certain parameters must be present in this view in order for the block to work properly. You can optionally add other parameters to specify an initial value or to control an aspect of the signal-processing algorithm.

To create the parameter screen, you can use commands such as Add-Box, Add-Line, and Add-Text, and Add-Parameter to build the parameter screen element by element. However, it is usually easier to copy an existing parameter screen and modify it as needed.

Display an Existing Parameter Screen

  1. Open a new BDE design window.
  2. Execute the following command: 
    3. File-Open
  3. In the dialog box, toggle on the Logical Name option.
  4. In the Select field, enter the following name:

    5. spb/hold.params

  5. Click on the OK button.

    6. BDE displays the "hold" block parameter screen view in the design window as shown in A-3.

Figure A-3  "Hold" Parameter Screen View

The parameter screen consists of a box, a line, several text notes, and two parameters. These are the parameters:

The FEED_TYPE parameter is not visible or editable in context windows. It tells the simulator the "feed through" characteristics of the block ports. The simulator needs to know this information in order to schedule the block for simulation.

Modify the Existing Parameter Screen

  1. Execute the following command: 
    2. View-Zoom To Fit
  2. Double-click on the text note that says "HOLD BLOCK PARAMETERS".
  3. In the dialog box, change the word "HOLD" to "COMP".
  4. Click on the OK button.

    5. The text note is modified to say "COMP BLOCK PARAMETERS".

Save the Modified Parameter Screen

  1. Execute the following command: 
    2. File-Save As
  2. In the New Filename field, enter the following name:

    3. yourlib/comp.params

  3. Toggle off the Group Name option.
  4. Verify that the Model Type button is set to Other.
  5. Click on the OK button.

    6. BDE saves the modified parameter screen view.

Note: If you copy a parameter screen view from an optional SPW block library (such as the Communications Library-Floating Point), you cannot save the modified view directly with the File-Save As command because of licensing requirements. In that case, you can use the commands Select-All, Edit-Copy, File-New, and Edit-Paste to enable saving with the File-Save As command.

Generate the SPB-I Template Files

The SPW Simulation Prepare Block control window is a tool that prepares a new custom-coded block for use with the SPB-I simulator.

  1. In the design window containing the new symbol view (yourlib/comp.symbol), execute the following command: 
    2. Tools-Simulator-Prepare Block (SPB-I) 
 
    
This displays the SPW Simulation Prepare Block control window shown in Figure A-4.
Figure A-4  SPW Simulation Prepare Block Control Window

  1. Verify that the C button is toggled on.
  2. In the control window, click on the Template button.

    3. After a brief delay, you should see a message indicating successful template file generation.

Edit the SPB-I Template Files

The Prepare Block program generates two template files, spb.c and spb.h. The spb.c file contains the code that implements the block function. The spb.h file declares the variables used in the spb.c program. You must edit these files to specify the operation of the block.

It is not necessary to declare the input variables, output variables, and parameter variables used in your custom code because the template file generator declares them for you. It knows how to do this by looking at the ports used in the symbol and the parameters used in the parameter screen.

Edit the ".c" File

  1. Click on the View C Code button.

    2. This opens a text editor containing the spb.c file. The text editor (usually "vi") is determined by the EDITOR environment variable setting.

  2. Find the "Initialize Function" section of the file, shown in Figure A-5. You can either scroll down the file or search for the string "In_comp".
Figure A-5  "Initialize Function" Section Before Editing

  1. Delete the four lines shown in boldface type in A-5.
  2. Replace the deleted text with the following new line:
    3. spb_state->prev_z = P_initial_value; 
 
    
The edited section of text is shown in Figure A-6. 

    
 
    
This new line sets the state variable "prev_z" to the value assigned to the "initial_value" parameter. This is done once, prior to the first simulation iteration.
Figure A-6  "Initialize Function" Section After Editing

  1. Find the "Run Output" section of the file. You can find it by searching for the string "Ro_comp".
  2. Insert the lines of text shown in bold in Figure A-7.

    3. These new lines of code define the behavior of the block in each simulation iteration.

Figure A-7  "Run Output" Section After Editing

  1. Use the appropriate text editor command to save the edited file and exit from the text editor.

Edit the ".h" File

  1. Click on the View Header button.

    2. This opens a text editor containing the spb.h file.

  2. Find the "State Structure" section of the file, which is near the beginning of the file.
  3. Add the state variable declaration shown in bold in Figure A-8.

    4. This new line declares the state variable used in your custom code. All other variables used in your custom code were created automatically by the Prepare Block software.

Figure A-8  "State Structure" Section After Editing

  1. Use the appropriate text editor command to save the edited file and exit from the text editor.

Compile the Custom Code

  1. Click on the Compile button.

    2. After a brief delay, you should see a message indicating successful completion.

  2. Check for error messages. If an error occurs, execute the following command: 
    3. File-Open Results-Errors 
 
    
Use the View C File or View Header button to edit and correct the file containing the error. Then click on the Compile button to recompile the corrected file.

Test the New Block

In the following exercise, you feed the "comp" block a sine wave and a cosine wave and record the results.

Build the Test System

  1. Open a new BDE design window.
  2. Add two instances of the following block:

    3. >Blocks>Signal Gen/Store>Signal Sources>Data

  3. Add one instance of each of the following blocks:

    4. >Blocks>Signal Gen/Store>Signal Sink>Data

    >Blocks>User Blocks>Comparator

  4. Connect the blocks as shown in Figure A-9.
Figure A-9  Test Block Diagram for Comparator

  1. Set the Library/File parameters of the Source and Sink blocks as follows:

    2. Top Signal Source: 'yourlib/sin1'

    Bottom Signal Source: 'yourlib/cos1'

    Signal Sink: 'yourlib/comp_out'

  2. Set the GET_SIM Signal Display Order parameters of the Source blocks as indicated in A-9. (Double-click on each block to display its parameter screen.)
  3. Double click on the 0<8> line on the sink block.
  4. Add an [8] so that the total line is 0<8>[8]. This final [8] tells the block how many elements it should write out for each iteration.
  5. Execute the following command: 
    6. File-Save As
  6. In the New Filename field, enter the following name:

    7. yourlib/comptest.system

  7. Click on the OK button.

Create the Input Signals

  1. Start SigCalc if you have not already done so.
  2. Click on the Gen-Sine button.
  3. In the dialog box, set the sine wave characteristics as follows:

    4. Amplitude: 1

    Frequency: 0.01

    Phase in Degrees: 0.0

    Number of Points: 2000

    Sampling Frequency: 1

  4. Click on the OK button.
  5. Select the signal and then save it under the name yourlib/sin1.
  6. Create another signal just like the last one, except set the Phase in Degrees 90.0 instead of 0.0.
  7. Save the new signal under the name yourlib/cos1.

Run the Test Simulation

  1. In the design window containing the test system, execute the following command: 
    2. Tools-Simulation Manager
  2. In the Simulation Manager window, set the Number of Samples field to 2000.
  3. Verify that the Simulation Manager fields and options are set as follows:
    • Design: yourlib/comptest.system
    • Configuration: config/bde.default
    • Engine: SPB-I
    • Create and Run buttons on
    • Debug button off
    • Number of Samples: 2000
    • Noise Seed: 1
  4. In the Simulation Manager, execute the following command: 
    5. File-Save As 
 
    
The New Logical Name field should be filled in by default with the name yourlib/comptest.toolrun.
  5. Click on the OK button.
  6. Click on the Start button and allow the simulation to run to completion.

View the Test Simulation Results

  1. Click on the SigCalc button.
  2. In the simulation Files Preview dialog box, click on the OK button.

    3. You should get the results shown in Figure A-10.

Figure A-10  Test Simulation Results

  1. Select both S2 and S3, the two input signals.
  2. Move the target marker so that it points to the middle of S1.
  3. Execute the following command: 
    4. View-Overlay-Add

S2 and S3 are displayed as "overlay" signals over S1. This shows exactly where the input signals cross, which is where the output signal should switch between -1 and +1.

Preparing the Block for SPB-C

The custom-coded block that you just created and tested works with the standard SPB-I simulator, but not with the SPB-C simulator. To prepare a block for SPB-C, you must separately generate, edit, and compile an "expression" (.expr) file for the block using a separate Prepare Block control window.

Generate the SPB-C Template File

  1. In the design window containing the symbol view (yourlib/comp.symbol), execute the following command: 
    2. Tools-Simulator-Prepare Block (SPB-C) 
 
    
This displays the SPB-C Prepare Block control window shown in Figure A-11.
Figure A-11  SPB-C Prepare Block Control Window

  1. In the control window, click on the Create Template button.

    2. After a brief delay, you should see a message indicating successful template file generation.

Edit the SPB-C Expression File

The Prepare Block program generates one template file, cgs.expr. This file contains the code that implements the block function. You must edit the file to specify the operation of the block.

  1. Click on the Edit Template button.

    2. This opens a text editor containing the cgs.expr file.

  2. Examine the contents of the file.

    3. The variable names in the file are based on the names of the ports in the symbol view and the name of the parameter in the parameter screen view, as indicated in Table A-1.

    Table A-1  Variable Names in the Expression File
    Original Name
    Variable Name in .EXPR File
    hold (input port)
    I_hold
    x (input port)
    I_x
    y (input port)
    I_y
    z (output port)
    O_z
    initial_value (parameter)
    P_initial_value

  3. Delete the two lines of text in the Initialization Code Section (near the end of the file).
  4. Insert new text into the State Declarations, Initialization Code, and Run Output Code sections as shown in Figure A-12.
Figure A-12  Expression File After Editing

The editing changes shown in Figure A-12 define the block as follows:

Compile the SPB-C Custom Code

  1. Click on the Compile Template button.

    2. After a brief delay, you should see a message indicating successful completion.

  2. Check for error messages. If an error occurs, execute the following command: 
    3. File-Open Results-Errors 
 
    
Use the Edit Template button to edit and correct the expression file. Then click on the Compile Template button to recompile the corrected file.

Test the New Block with SPB-C

In the following exercise, you use the same test system and test signals that you used for the SPB-I simulation test.

  1. Display the test system "yourlib/comptest.system" in a design window if it is not already displayed.
  2. If the Simulation Manager is not already open, execute the following command in the design window:
    3. Tools-Simulation Manager
  3. In the Simulation Manager window, change the Engine button from SPB-I to SPB-C.
  4. Verify that the Simulation Manager fields and options are set as follows:
    • Design: yourlib/comptest.system
    • Configuration: config/bde.default
    • Engine: SPB-C
    • Create and Run buttons on
    • Number of Samples: 2000
    • Noise Seed: 1
  5. Click on the Start button.
  6. Allow the simulation to run to completion.
  7. Click on the SigCalc button.
  8. In the simulation Files Preview dialog box, click on the OK button.

    9. You should see the same results as for the SPB-I simulation, shown in Figure A-10.

Custom Coding in C++

If you are familiar with the C++ programming language, you can write your SPB-I code in C++ rather than C. The procedure is basically the same as for using C. The only difference is that you toggle on the C++ button rather than the C button in the Simulation Prepare Block (SPB-I) control window.

With the C++ button toggled on, the template generator creates a C++ template file called spb.C, which you modify by entering C++ code rather than C code. When you click on the Compile button, the program invokes the C++ compiler to generate the block code. Then you can use the custom-coded block like any other block.

In the following exercise, you copy an existing library block, write the code for it in C++, and test its operation in a simulation. The custom-coded block should operate just like the original standard library block.

Display the Existing Symbol

The existing function that you will copy is the following block:

>Blocks>Multirate>Conversion>Scalar to Vector

This block takes a specified number of double-precision input samples in sequence and combines them into a single output vector. The block operates as a static multirate block, as described in "Static Multirate Simulation" in Chapter 7, "Simulator Theory of Operation"

  1. Open a new BDE design window.
  2. Execute the following command: 
    3. File-Open
  3. In the dialog box, toggle on the Logical Name option.
  4. In the Select field, enter the following name:

    5. multirate/scal2vec.symbol

  5. Click on the OK button.
  6. Execute the following command: 
    7. View-Zoom To Fit 
 
    
The design window displays the Scalar to Vector symbol as shown in Figure A-13.
Figure A-13  "Scalar to Vector" Block Symbol

Modify the Existing Symbol

  1. Double-click on the text note that says "SCALAR TO".
  2. In the dialog box, change the text from "SCALAR TO" to "Vectorize".
  3. Click on the OK button.
  4. Similarly, change the text note that says "VECTOR" to say "(C++ CCB)".
  5. Using the middle mouse button, move the text note so that it is centered between the left and right sides of the symbol box, as shown in Figure A-14.
Figure A-14  Modified Symbol

Save the Modified Symbol

  1. Execute the following command: 
    2. File-Save As
  2. In the New Filename field, enter the following name:

    3. yourlib/vectorize.symbol

  3. Click on the OK button.

The symbol view contains the following items:

Display the Existing Parameter Screen

  1. Open a new BDE design window.
  2. Execute the following command: 
    3. File-Open
  3. In the dialog box, toggle on the Logical Name option.
  4. In the Select field, enter the following name:

    5. multirate/scal2vec.params

  5. Click on the OK button.

    6. BDE displays the block parameter screen in the design window as shown in Figure A-15.

Figure A-15  "Scalar to Vector" Parameter Screen

These are the parameters:

The mrx_in_rate parameter is controlled by the out_IOVEC_LEN parameter in the symbol view. This parameter determines the operating rate of the input with respect to the output.

Modify the Existing Parameter Screen

  1. Double-click on the text note that says "SCALAR TO VECTOR BLOCK PARAMETERS".
  2. In the dialog box, change "SCALAR TO VECTOR" to "VECTORIZE".
  3. Click on the OK button.

    4. The text note is modified to say "VECTORIZE BLOCK PARAMETERS".

Save the Modified Parameter Screen

  1. Execute the following command: 
    2. File-Save As
  2. In the New Filename field, enter the following name:

    3. yourlib/vectorize.params

  3. Verify that the Model Type button is set to Other.
  4. Click on the OK button.

    5. BDE saves the modified parameter screen view.

Generate the C++ SPB-I Template Files

  1. In the design window containing the new symbol view (yourlib/vectorize.symbol), execute the following command: 
    2. Tools-Simulator-Prepare Block (SPB-I)
  2. Toggle on the C++ button.
  3. In the control window, click on the Template button.

    4. After a brief delay, you should see a message indicating successful template file generation.

The template generator creates two files: the spb.C file and the spb.h file.

Edit the C++ SPB-I Template File

  1. Click on the View C++ Code button.

    2. This opens a text editor containing the spb.C file.

  2. At the beginning of the file is the following "include" statement:

    3. #include "spb.h"

    Just after this line, insert the following new "include" statement:

    #include <string.h>

    This additional statement is required because string.h contains a function used in the custom code, strcasecmp.

  3. Find the Initialize Function section of the file, shown in Figure A-16.
Figure A-16  "Initialize Function" Section Before Editing

  1. Delete the three lines shown in boldface type in Figure A-16 and replace them with the new lines of text shown in Figure A-17.
Figure A-17  "Initialize Function" Section After Editing

  1. Find the Run Output section of the file.
  2. Similarly edit the Run Output section by deleting the three "not implemented yet" lines and inserting the new lines of text shown in boldface type in Figure A-18.
Figure A-18  "Run Output" Section After Editing (continues)

  1. Find the Termination Function section of the file.
  2. Delete the three "not implemented yet" lines from this section. (You do not need to insert any new code into this section.)
  3. Use the appropriate text editor command to save the edited file and exit from the text editor.

Note: The spb.h file does not need to be edited for this block.

Compile the C++ Custom Code

  1. Click on the Compile button.

    2. After a brief delay, you should see a message indicating successful completion.

  2. Check for error messages. If an error occurs, execute the following command: 
    3. File-Open Results-Errors 
 
    
Use the View C++ File to make any needed corrections and then click on the Compile button to recompile the corrected file.

Build the Test System

  1. Open a new BDE design window.
  2. Add the following three blocks:

    3. >Blocks>Logical>Clock/Counters>Counter Simple

    >Blocks>Signal Gen/Store>Signal Sink>Data

    >yourlib/vectorize.symbol

  3. Connect the blocks as shown in Figure A-19.
Figure A-19  Test Block Diagram for Vectorize Block

  1. Change the vector length parameter at the output of the Vectorize block from 128 to 8.
  2. Set the Library/File parameter of the Sink block as follows:

    3. 'yourlib/vect_out'

  3. Select the sink block and use the right mouse button to open the pop-up menu.
  4. From the pop-up menu, select Change Type...
  5. On the form that appears, change the Composite Type to Vector.
  6. Change the Element Type to Double.
  7. Click OK on the form.
  8. Double click on the block default value (0<8>) on the Sink block.

    9. The Parameter Properties form appears.

  9. Edit the value to be 0<8>[8]

    10. This specifies how many elements will be written out for each iteration.

  10. Select the junction dot at the output of the Vectorize block.
  11. Execute the following command: 
    12. Design-Multirate Edit
  12. In the Design Multirate Edit dialog box, click on the OK button.
  13. Execute the following command: 
    14. File-Save As
  14. In the New Filename field, enter the following name:

    15. yourlib/vectest.system

  15. Click on the OK button.

The Simple Counter block produces a sequence of double-precision samples: 1.0, 2.0, 3.0, and so on. The Vectorize block combines each sequence of eight input samples into a vector. Thus, the input operates eight times faster than the output. The Vector Sink block records the sequence of vectors into a signal file.

Run the Test Simulation

  1. In the design window containing the test system, execute the following command: 
    2. Tools-Simulation Manager
  2. In the Simulation Manager window, set the Number of Samples field to 3.

    3. The simulation runs until three samples are processed at the base rate node. This is equivalent to three vectors at the Vectorize block output (or 24 samples at the Vectorize block input).

  3. Verify that the Simulation Manager fields and options are set as follows:
    • Design: yourlib/vectest.system
    • Configuration: config/bde.default
    • Engine: SPB-I
    • Create and Run buttons on
    • Debug button off
    • Number of Samples: 3
    • Noise Seed: 1
  4. In the Simulation Manager, execute the following command: 
    5. File-Save As 
 
    
The New Logical Name field should be filled in by default with the name yourlib/vectest.toolrun.
  5. Click on the OK button.
  6. Click on the Start button and allow the simulation to run to completion.

View the Test Simulation Results

  1. Click on the SigCalc button.
  2. In the simulation Files Preview dialog box, click on the OK button.
  3. In the SigCalc window, set the Win Size field to 50.

    4. You should see the results shown in Figure A-20.

Figure A-20  Test Simulation Results

[

  1. Use the middle mouse button to move the signal cursor within the signal display.
  2. Using the left and right cursor arrow keys on the keyboard, move the cursor from point to point.

You should find that the signal is a simple ramp, consisting of sequence of 24 data points having the values 1, 2, 3, ... 24. The Vector Signal Sink block records each vector as a sequence of scalar values. The simulation ran for 3 vector samples, or 24 counts of the Simple Counter block. The time interval between data points is one-eighth of a second because the Simple Counter block operates eight times faster than the vector signal (which was recorded at a rate of 1.0 Hz).

Reverse the Vector Element Order

  1. In the test system, double-click on the Vectorize block.
  2. In the context window, change the First Element Loaded parameter from 'first' to 'last'.
  3. Close the context window.
  4. In the Simulation Manager, click on the Start button and allow the simulation to run to completion.
  5. Click on the SigCalc button.
  6. In the simulation Files Preview dialog box, click on the OK button.
  7. Examine the results in the SigCalc window.

    8. This time the order of the elements is reversed in each group of eight samples.

  8. Close all the open SPW windows.

For More Information

Detailed information on creating and programming custom-coded blocks is provided in other SPW manuals.

For general information on creating custom-coded blocks and writing code for SPB-I simulation, see Appendix C, "Custom-Coded Blocks for SPB-C," in the Simulator User's Guide.

For information on writing code for SPB-C simulation, see Appendix E, "Custom-Coded Blocks for SPB-C," in the Simulator User's Guide.

For information on writing C++ code for SPB-I simulation, see Appendix D, "Custom-Coded Blocks in C++," in the Simulator User's Guide.

For information on writing code for fixed-point (HDS) blocks, see Appendix E, "Custom-Coded Blocks,", in the Hardware Design System User's Guide. A fixed-point custom-coded block tutorial is provided in Chapter 5, "HDS Tutorial," in that same manual.

CoWare
 CoWare's Web Site
Phone: 1-888-269-2738
CoWare Customer Support