National Instruments AutoCode NI MATRIX User Manual

NI MATRIXx

AutoCodeTM Reference

AutoCode Reference

April 2007 370768C-01

Support

Worldwide Technical Support and Product Information

ni.com

National Instruments Corporate Headquarters

11500 North Mopac Expressway Austin, Texas 78759-3504 USA Tel: 512 683 0100

Worldwide Offices

Australia 1800 300 800, Austria 43 662 457990-0, Belgium 32 (0) 2 757 0020, Brazil 55 11 3262 3599, Canada 800 433 3488, China 86 21 5050 9800, Czech Republic 420 224 235 774, Denmark 45 45 76 26 00, Finland 385 (0) 9 725 72511, France 33 (0) 1 48 14 24 24, Germany 49 89 7413130, India 91 80 41190000, Israel 972 3 6393737, Italy 39 02 413091, Japan 81 3 5472 2970, Korea 82 02 3451 3400, Lebanon 961 (0) 1 33 28 28, Malaysia 1800 887710, Mexico 01 800 010 0793, Netherlands 31 (0) 348 433 466, New Zealand 0800 553 322, Norway 47 (0) 66 90 76 60, Poland 48 22 3390150, Portugal 351 210 311 210, Russia 7 495 783 6851, Singapore 1800 226 5886, Slovenia 386 3 425 42 00, South Africa 27 0 11 805 8197, Spain 34 91 640 0085, Sweden 46 (0) 8 587 895 00, Switzerland 41 56 2005151, Taiwan 886 02 2377 2222, Thailand 662 278 6777, Turkey 90 212 279 3031, United Kingdom 44 (0) 1635 523545

For further support information, refer to the Technical Support and Professional Services appendix. To comment on National Instruments documentation, refer to the National Instruments Web site at ni.com/info and enter the info code feedback.

Important Information

Warranty

The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives notice of such defects during the warranty period. National Instruments does not warrant that the operation of the software shall be uninterrupted or error free.

A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside of the package before any equipment will be accepted for warranty work. National Instruments will pay the shipping costs of returning to the owner parts which are covered by warranty.

National Instruments believes that the information in this document is accurate. The document has been carefully reviewed for technical accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right to make changes to subsequent editions of this document without prior notice to holders of this edition. The reader should consult National Instruments if errors are suspected. In no event shall National Instruments be liable for any damages arising out of or related to this document or the information contained in it.

XCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF

MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. CUSTOMER’S RIGHT TO RECOVER DAMAGES CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF NATIONAL

NSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID BY THE CUSTOMER. NATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR DAMAGES RESULTING

FROM LOSS OF DATA, PROFITS, USE OF PRODUCTS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This limitation of

the liability of National Instruments will apply regardless of the form of action, whether in contract or tort, including negligence. Any action against National Instruments must be brought within one year after the cause of action accrues. National Instruments shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided herein does not cover damages, defects, malfunctions, or service failures caused by owner’s failure to follow the National Instruments installation, operation, or maintenance instructions; owner’s modification of the product; owner’s abuse, misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties, or other events outside reasonable control.

Copyright

Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of National Instruments Corporation.

National Instruments respects the intellectual property of others, and we ask our users to do the same. NI software is protected by copyright and other intellectual property laws. Where NI software may be used to reproduce software or other materials belonging to others, you may use NI software only to reproduce materials that you may reproduce in accordance with the terms of any applicable license or other legal restriction.

Trademarks

AutoCode™, DocumentIt™, MATRIXx™, National Instruments™, NI™, ni.com™, SystemBuild™, and Xmath™ are trademarks of National Instruments Corporation. Refer to the Terms of Use section on ni.com/legal for more information about National Instruments trademarks.

Other product and company names mentioned herein are trademarks or trade names of their respective companies.

Members of the National Instruments Alliance Partner Program are business entities independent from National Instruments and have no agency, partnership, or joint-venture relationship with National Instruments.

Patents

For patents covering National Instruments products, refer to the appropriate location: Help»Patents in your software, the patents.txt file on your CD, or

ni.com/patents.

WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS

(1) NATIONAL INSTRUMENTS PRODUCTS ARE NOT DESIGNED WITH COMPONENTS AND TESTING FOR A LEVEL OF RELIABILITY SUITABLE FOR USE IN OR IN CONNECTION WITH SURGICAL IMPLANTS OR AS CRITICAL COMPONENTS IN ANY LIFE SUPPORT SYSTEMS WHOSE FAILURE TO PERFORM CAN REASONABLY BE EXPECTED TO CAUSE SIGNIFICANT INJURY TO A HUMAN.

(2) IN ANY APPLICATION, INCLUDING THE ABOVE, RELIABILITY OF OPERATION OF THE SOFTWARE PRODUCTS CAN BE IMPAIRED BY ADVERSE FACTORS, INCLUDING BUT NOT LIMITED TO FLUCTUATIONS IN ELECTRICAL POWER SUPPLY, COMPUTER HARDWARE MALFUNCTIONS, COMPUTER OPERATING SYSTEM SOFTWARE FITNESS, FITNESS OF COMPILERS AND DEVELOPMENT SOFTWARE USED TO DEVELOP AN APPLICATION, INSTALLATION ERRORS, SOFTWARE AND HARDWARE COMPATIBILITY PROBLEMS, MALFUNCTIONS OR FAILURES OF ELECTRONIC MONITORING OR CONTROL DEVICES, TRANSIENT FAILURES OF ELECTRONIC SYSTEMS (HARDWARE AND/OR SOFTWARE), UNANTICIPATED USES OR MISUSES, OR ERRORS ON THE PART OF THE USER OR APPLICATIONS DESIGNER (ADVERSE FACTORS SUCH AS THESE ARE HEREAFTER COLLECTIVELY TERMED “SYSTEM FAILURES”). ANY APPLICATION WHERE A SYSTEM FAILURE WOULD CREATE A RISK OF HARM TO PROPERTY OR PERSONS (INCLUDING THE RISK OF BODILY INJURY AND DEATH) SHOULD NOT BE RELIANT SOLELY UPON ONE FORM OF ELECTRONIC SYSTEM DUE TO THE RISK OF SYSTEM FAILURE. TO AVOID DAMAGE, INJURY, OR DEATH, THE USER OR APPLICATION DESIGNER MUST TAKE REASONABLY PRUDENT STEPS TO PROTECT AGAINST SYSTEM FAILURES, INCLUDING BUT NOT LIMITED TO BACK-UP OR SHUT DOWN MECHANISMS. BECAUSE EACH END-USER SYSTEM IS CUSTOMIZED AND DIFFERS FROM NATIONAL INSTRUMENTS' TESTING PLATFORMS AND BECAUSE A USER OR APPLICATION DESIGNER MAY USE NATIONAL INSTRUMENTS PRODUCTS IN COMBINATION WITH OTHER PRODUCTS IN A MANNER NOT EVALUATED OR CONTEMPLATED BY NATIONAL INSTRUMENTS, THE USER OR APPLICATION DESIGNER IS ULTIMATELY RESPONSIBLE FOR VERIFYING AND VALIDATING THE SUITABILITY OF NATIONAL INSTRUMENTS PRODUCTS WHENEVER NATIONAL INSTRUMENTS PRODUCTS ARE INCORPORATED IN A SYSTEM OR APPLICATION, INCLUDING, WITHOUT LIMITATION, THE APPROPRIATE DESIGN, PROCESS AND SAFETY LEVEL OF SUCH SYSTEM OR APPLICATION.

Conventions

The following conventions are used in this manual:

<> Angle brackets that contain numbers separated by an ellipsis represent a

range of values associated with a bit or signal name—for example, DIO<3..0>.

» The » symbol leads you through nested menu items and dialog box options

to a final action. The sequence File»Page Setup»Options directs you to pull down the File menu, select the Page Setup item, and select Options from the last dialog box.

This icon denotes a note, which alerts you to important information.

This icon denotes a caution, which advises you of precautions to take to avoid injury, data loss, or a system crash.

bold Bold text denotes items that you must select or click in the software, such

as menu items and dialog box options. Bold text also denotes parameter names.

italic Italic text denotes variables, emphasis, a cross-reference, or an introduction

to a key concept. Italic text also denotes text that is a placeholder for a word or value that you must supply.

monospace Text in this font denotes text or characters that you should enter from the

keyboard, sections of code, programming examples, and syntax examples. This font is also used for the proper names of disk drives, paths, directories, programs, subprograms, subroutines, device names, functions, operations, variables, filenames, and extensions.

monospace bold Bold text in this font denotes the messages and responses that the computer

automatically prints to the screen. This font also emphasizes lines of code that are different from the other examples.

monospace italic

Italic text in this font denotes text that is a placeholder for a word or value that you must supply.

Chapter 1 Introduction

Manual Organization .....................................................................................................1-1

General Information.......................................................................................................1-2

Configuration File..........................................................................................................1-2

Language-Specific Information .....................................................................................1-2

Structure and Content of the Generated Code ...............................................................1-3

Using MATRIXx Help ..................................................................................................1-3

Additional Netscape Information ....................................................................1-3

Related Publications ......................................................................................................1-4

Chapter 2 C Language Reference

Stand-Alone Simulation.................................................................................................2-1

Compiling on Various Supported Platforms ...................................................2-1

Stand-Alone Library ......................................................................................................2-2

System-Specific Files ......................................................................................2-2

Target-Specific Utilities ..................................................................................2-5

enable( ), disable( ), and background( ) Functions ...........................2-6

error( ) and fatalerr( ) Functions .......................................................2-6

fatalerr( ): Stand-Alone Utilities Detected Errors .............................2-7

ERROR: Conditions Detected in the Generated Code......................2-8

Implementation_Initialize( ) Function ..............................................2-9

Implementation_Terminate( ) Function............................................2-9

External_Input ( ) Function...............................................................2-10

External_Output ( ) Function ............................................................2-10

UserCode Blocks ...........................................................................................................2-10

Linking Handwritten UCBs with AutoCode Applications..............................2-11

Implementing Handwritten UCBs ....................................................2-13

Linking Handwritten UCBs (for AutoCode) with SystemBuild .....................2-16

Variable Interface UCB...................................................................................2-18

Interface Ordering .............................................................................2-18

Inputs and Outputs ............................................................................2-18

Function Prototype............................................................................2-19

Linking a Variable Interface UCB with the Simulator .....................2-20

Procedure SuperBlocks..................................................................................................2-20

Generating Reusable Procedures.....................................................................2-20

Linking Procedures with the SystemBuild Simulator .....................................2-20

Contents

Linking Procedures with Real-Time Applications or Simulator .................... 2-22

Invoking Generated Procedures Directly.......................................... 2-22

Invoking Procedures Using Generated UCB Wrapper Function...... 2-24

Invoking Procedures Using Generated Subsystem Function ........... 2-25

C Fixed-Point Arithmetic .............................................................................................. 2-26

Fixed-Point AutoCode/C Implementation ...................................................... 2-26

Generated Code with Fixed-Point Variables .................................................. 2-28

Fixed-Point Data Types .................................................................................. 2-28

User Types ...................................................................................................... 2-30

Overflow Protection........................................................................................ 2-31

Stand-Alone Files............................................................................................ 2-31

Macro Interface ...............................................................................................2-32

Function Interface ........................................................................................... 2-33

Fixed-Point Conversion and Arithmetic Macros ............................................ 2-35

Conversion Macros...........................................................................2-35

Arithmetic Macros............................................................................ 2-38

Implementation of the Addition and Subtraction Macros ................ 2-40

Selecting Wordsize Extension in the Preprocessor Macro ............... 2-42

32-Bit Multiplication and Division Macros...................................... 2-42

32-Bit Multiplication ........................................................................ 2-42

32-Bit Division ................................................................................. 2-43

16-Bit by 8-Bit Division ................................................................... 2-43

32-Bit by 16-Bit Division ................................................................. 2-43

Fixed-Point Relational Macros ....................................................................... 2-44

Some Relevant Issues...................................................................................... 2-45

Chapter 3 Ada Language Reference

Stand-Alone Simulation ................................................................................................ 3-1

Supported Ada Compilers for the Stand-Alone Library ................................. 3-1

Supplied Templates ....................................................................................................... 3-2

ada_rt.tpl Template ......................................................................................... 3-2

ada_sim.tpl Template ...................................................................................... 3-2

ada_fxpt_sys.tpl Template .............................................................................. 3-2

ada_fxpt_sub.tpl Template.............................................................................. 3-2

Stand-Alone Library...................................................................................................... 3-3

System-Specific Files...................................................................................... 3-3

Data Types........................................................................................ 3-5

Target-Specific Utilities .................................................................................. 3-6

Enable( ), Disable( ), and Background( ) Procedures....................... 3-7

Error Procedure( ) Procedure............................................................3-7

Implementation_Initialize( ) Procedure............................................ 3-8

Implementation_Terminate( ) Procedure.......................................... 3-10

AutoCode Reference vi ni.com

Contents

External_Input ( ) Procedure.............................................................3-10

External_Output( ) Procedure ...........................................................3-11

UserCode Blocks ...........................................................................................................3-11

Linking Handwritten UCBs with AutoCode Applications..............................3-11

Calling UCBs...................................................................................................3-12

Procedure SuperBlocks..................................................................................................3-14

Generating Reusable Procedures.....................................................................3-14

Linking Procedures with Real-Time Applications or Simulator.....................3-14

Ada Fixed-Point Arithmetic...........................................................................................3-16

How to Generate Real-Time Code ..................................................................3-16

Fixed-Point AutoCode/Ada Architecture ........................................................3-16

Fixed-Point Data Types ....................................................................3-17

Generic Functions .............................................................................3-17

Instantiated Functions .......................................................................3-17

Package Dependencies......................................................................3-18

Generated Code with Fixed-Point Variables...................................................3-19

User Types.......................................................................................................3-19

System-Level Parameters to Generate User Types...........................3-20

Overflow Protection ........................................................................................3-20

Stand-Alone Files ............................................................................................3-21

Compilation Example......................................................................................3-21

Fixed-Point Type Declarations........................................................................3-23

Generic Functions............................................................................................3-23

Bit-Wise Functions..........................................................................................3-26

Instantiated Functions Package .......................................................................3-26

Operator Instantiations......................................................................3-26

Conversion Function Instantiations ..................................................3-27

Sample Package ................................................................................3-28

Addition and Subtraction Functions ................................................................3-29

Multiplication and Division Functions ............................................................3-31

32-Bit Multiplication.........................................................................3-31

32-Bit Division..................................................................................3-31

Conversion Functions......................................................................................3-31

Language-Defined Conversion .........................................................3-32

Truncation Conversion...................................................................... 3-32

Explicit Rounding Conversion..........................................................3-32

Using System-Level Parameters to Generate Instantiations ...........................3-33

Using Subsystem-Level Parameters to Generate Instantiations......................3-33

System Scope Operators and Conversions........................................3-34

Known Ada Compiler Problems .....................................................................3-35

Comparing Results to SystemBuild’s Simulator.............................................3-35

No-Op Conversion Function ...........................................................................3-36

Contents

Chapter 4 Generating Code for Real-Time Operating Systems

Real-Time Operating System Configuration File.......................................................... 4-1

Configuration Items ........................................................................................ 4-2

Table Syntax ................................................................................................... 4-2

Table Naming Convention................................................................ 4-3

Table Column Contents .................................................................... 4-3

Table Orderings ................................................................................ 4-3

File Comments.................................................................................. 4-3

RTOS Configuration File Contents................................................................. 4-3

Processors Table ............................................................................... 4-3

Scheduler Priority Table................................................................... 4-4

Subsystem Table............................................................................... 4-4

Interrupt Procedure SuperBlock Table ............................................. 4-5

Background Procedure SuperBlock Table........................................ 4-6

Startup Procedure SuperBlock Table ............................................... 4-7

Processor IP Name Table ................................................................. 4-7

Version Table ................................................................................... 4-8

Using the Configuration File...........................................................................4-8

Chapter 5 Generated Code Architecture

Symbolic Name Creation .............................................................................................. 5-1

Default Names................................................................................................. 5-1

Signal Naming................................................................................................. 5-2

Duplicate Names ............................................................................................. 5-2

Selection of a Signal Name............................................................................. 5-2

Subsystem and Procedure Boundaries.............................................. 5-2

Typecheck Feature and Data Types ................................................................ 5-2

Global Storage ............................................................................................................... 5-3

Percent vars (%var)......................................................................................... 5-3

Global Variable Blocks................................................................................... 5-3

Sequencing Variable Blocks............................................................. 5-3

Global Variable Block and %var Equivalence ................................. 5-4

Optimization for Read-From Variable Blocks ................................. 5-4

Global Scope Signal Capability ...................................................................... 5-4

Subsystems .................................................................................................................... 5-5

Discrete and Continuous SuperBlocks Versus Subsystems............................ 5-5

Top-Level SuperBlock ..................................................................... 5-6

Block Ordering................................................................................................ 5-6

Interface Layers............................................................................................... 5-6

Scheduler External Interface Layer................................................................. 5-7

AutoCode Reference viii ni.com

Contents

System External Interface Layer .....................................................................5-7

Discrete Subsystem Interface Layer................................................................5-8

Single-Rate System ...........................................................................5-8

Multi-Rate System ............................................................................5-8

Sample and Hold...............................................................................5-8

Static Data Within Subsystems .......................................................................5-9

iinfo ...................................................................................................5-9

R_P and I_P ......................................................................................5-9

State Data ..........................................................................................5-9

Procedure Data..................................................................................5-10

Pre-init Phase...................................................................................................5-10

Init, Output, and State Phases..........................................................................5-10

Copy Back and Duplicates ..............................................................................5-10

Error Handling.................................................................................................5-11

Standard Procedures ......................................................................................................5-11

Structure-Based Interface ................................................................................5-11

Unrolled Interface............................................................................................5-12

Phases and Error Handling ..............................................................................5-12

Referenced Percent Variables..........................................................................5-12

Procedure Arguments ......................................................................................5-15

U, Y, S, and I.....................................................................................5-15

Extended Procedure Information Structure .....................................................5-18

Caller Identification ..........................................................................5-18

Compatibility Issues..........................................................................5-19

Macro Procedure............................................................................................................5-20

Interface...........................................................................................................5-20

Asynchronous Procedures..............................................................................................5-21

Interrupt ...........................................................................................................5-21

Background......................................................................................................5-21

Startup..............................................................................................................5-21

Changing %var Values During Startup.............................................5-22

Condition Block.............................................................................................................5-22

Default Mode...................................................................................................5-22

No-Default Mode.............................................................................................5-22

Sequential Mode..............................................................................................5-22

BlockScript Block..........................................................................................................5-22

Inputs and Outputs...........................................................................................5-23

Environment Variables....................................................................................5-24

Local Variables................................................................................................5-24

Init, Output, and State Phases..........................................................................5-25

Default Phase ....................................................................................5-26

Contents

States ............................................................................................................... 5-26

Local Variables and Phases .............................................................. 5-27

Discrete Semantics ........................................................................... 5-27

Continuous Semantics ...................................................................... 5-29

Looping Concepts ........................................................................................... 5-29

Terminology ..................................................................................... 5-29

Loops and Scalar Code ..................................................................... 5-29

Rolling Loops with Scalar Code Generation .................................... 5-30

Vectorized Code ............................................................................... 5-31

Types of Loops ................................................................................. 5-31

Examples of Rolled and Unrolled Loops ......................................... 5-32

Parameters....................................................................................................... 5-33

Using Parameters Instead of States in a Discrete Model.................. 5-33

Optimizations .................................................................................................. 5-35

Constant Propagation/Hard-Coding ................................................. 5-35

Dead Code Elimination .................................................................... 5-35

Implicit Type Conversion................................................................. 5-36

Special Directives ........................................................................................... 5-36

UserCode Block............................................................................................................. 5-37

Phases of the UCB .......................................................................................... 5-37

Indirect Terms ................................................................................................. 5-37

Parameterized UCB Callout............................................................................ 5-38

Software Constructs....................................................................................................... 5-39

IfThenElse Block ............................................................................................ 5-39

WHILE Block ................................................................................................. 5-39

BREAK Block................................................................................................. 5-40

CONTINUE Block..........................................................................................5-40

Local Variable Block ...................................................................................... 5-40

Sequencer Block ............................................................................................. 5-41

Difference Between Local and Global Variable Blocks ............................................... 5-41

Scope...............................................................................................................5-41

Lifetime........................................................................................................... 5-41

Continuous Subsystem .................................................................................................. 5-41

Explicit Phases ................................................................................................5-42

Integrator......................................................................................................... 5-42

Limitations ...................................................................................................... 5-42

Multiprocessor Code Generation................................................................................... 5-43

Shared Memory Architecture.......................................................................... 5-43

Distributed Memory Architecture................................................................... 5-44

Shared Memory Callouts ................................................................................ 5-44

Callout Naming Convention ............................................................. 5-44

Mapping Command Options........................................................................... 5-45

Fixed-Point Support for Multiprocessor AutoCode ........................................ 5-45

AutoCode Reference x ni.com

Definitions and Conventions ...........................................................................5-45

Shared Memory Fixed-Point Callouts in AutoCode/C .....................5-46

Shared Variable Block Support.......................................................................5-47

Shared Memory Callout Option........................................................5-50

Global Variable Block Callouts.......................................................................5-51

Callout Pairs......................................................................................5-51

Non-Shared (Local) Global Variable Blocks....................................5-51

Shared Global Variable Blocks.........................................................5-53

Chapter 6 Vectorized Code Generation

Introduction....................................................................................................................6-1

How Code Is Generated...................................................................................6-1

Scalar Gain Block Example ..............................................................6-2

Vectorized Gain Block Example.......................................................6-3

Array Subscripts................................................................................6-4

Signal Connectivity .........................................................................................6-5

Block Outputs ...................................................................................6-5

Block Inputs ......................................................................................6-5

Vectorization Modes......................................................................................................6-7

Maximal Vectorization....................................................................................6-7

Mixed Vectorization........................................................................................6-7

Vector Labels and Names .................................................................6-8

Example...........................................................................................................6-8

Vectorization Features ...................................................................................................6-14

Multiple Arrays within a Block.......................................................................6-15

Split-Merge Inefficiency .................................................................................6-17

Split Vector .......................................................................................6-17

Merge ................................................................................................6-19

External Outputs..............................................................................................6-21

Copy-Back ........................................................................................6-21

Eliminating Copy-Back.....................................................................6-23

Other Copy-Back Scenarios..............................................................6-23

Vectorized Standard Procedure Interface........................................................6-23

Ada Array Aggregates and Slices....................................................................6-25

Vectorization of the BlockScript Block.........................................................................6-27

Matrix Outputs...............................................................................................................6-28

Contents

Chapter 7 Code Optimization

Read from Variable Blocks ........................................................................................... 7-1

Restart Capability .......................................................................................................... 7-5

Merging INIT Sections..................................................................................................7-8

Reuse of Temporary Block Outputs .............................................................................. 7-11

Reuse Temporaries as Specified ..................................................................... 7-11

Maximal Reuse of Temporaries...................................................................... 7-11

Constant Propagation.....................................................................................................7-13

Optimizing with Matrix Blocks..................................................................................... 7-16

Optimizing with Constant Blocks ................................................................... 7-16

Optimizing with Callout Blocks ..................................................................... 7-17

Optimizing with Inverse Blocks ....................................................... 7-17

Optimizing with Division Blocks ..................................................... 7-17

Summary........................................................................................................................ 7-19

Chapter 8 AutoCode Sim Cdelay Scheduler

Introduction ................................................................................................................... 8-1

Task Posting Policies..................................................................................................... 8-2

Standard AutoCode Scheduler ......................................................................................8-3

Scheduler Pipeline........................................................................................... 8-5

Managing DataStores in the Scheduler........................................................... 8-7

Sim Cdelay Scheduler ................................................................................................... 8-9

State Transition Diagrams of Tasks under Sim Cdelay................................................. 8-10

Implementing the Sim Cdelay AutoCode Scheduler..................................................... 8-12

Implementation Details ................................................................................... 8-12

DataStore Priority Problem............................................................................. 8-13

Using the Sim Cdelay Scheduler................................................................................... 8-14

Template Configuration for Enhanced Performance..................................................... 8-15

Shortcomings of the Sim Cdelay Scheduler.................................................................. 8-16

Chapter 9 Global Scope Signals and Parameterless Procedures

Introduction ................................................................................................................... 9-1

Data Monitoring/Injection .............................................................................................9-2

Specifying Monitored Signals......................................................................... 9-2

Generating Code for Monitored Signals ......................................................... 9-3

Limitations ...................................................................................................... 9-4

Unsupported Blocks ......................................................................... 9-4

Connection to External Output ......................................................... 9-4

AutoCode Reference xii ni.com

Contents

Variable Block Aliasing....................................................................9-4

Monitored Signals within a Procedure SuperBlock ..........................9-4

Monitoring Procedure External Outputs ...........................................9-4

Parameterless Procedure ................................................................................................9-5

Specifying Parameterless Procedure Interface ................................................9-5

Input Specification ............................................................................9-5

Output Specification .........................................................................9-6

Using a Parameterless Procedure ....................................................................9-6

Global-to-Global Input Connection ..................................................9-6

Global Output Connection ................................................................9-6

Condition Block Code Generation ..................................................................9-7

Reusing a Parameterless Procedure.................................................................9-7

Generating Code for Parameterless Procedures ..............................................9-7

Issues and Limitations .....................................................................................9-8

Communication Between Subsystems ..............................................9-8

Variable Blocks Versus Global Scope ..............................................9-8

SystemBuild Simulator .....................................................................9-8

Connection to External Output .........................................................9-9

Recommendations ...........................................................................................9-9

Naming Convention ..........................................................................9-9

Model Documentation.......................................................................9-9

Explicit Sequencing ..........................................................................9-9

Analyzer and AutoCode Warnings ...................................................9-10

Changing Scope Class.......................................................................9-10

Command Options .........................................................................................................9-10

Appendix A Technical Support and Professional Services

Index

Introduction

This manual provides reference material for using AutoCode to write

production quality code using graphical tools. Together with the AutoCode

User Guide and the Template Programming Language User Guide,

AutoCode documentation describes how to generate robust, high-quality,

real-time C or Ada source code from SystemBuild block diagrams.

Manual Organization

This manual includes the following chapters:

• Chapter 1, Introduction, provides an overview of the rapid prototyping concept, the automatic code generation process, and the nature of real-time generated code.

• Chapter 2, C Language Reference, discusses files used to interface AutoCode and the generated C code to your specific platform and target processor, and target-specific utilities needed for simulation and testing.

• Chapter 3, Ada Language Reference, discusses files used to interface AutoCode and the generated Ada code to your specific platform and target processor, and target-specific utilities needed for simulation and testing.

• Chapter 4, Generating Code for Real-Time Operating Systems, describes the RTOS configuration file and functionality provided for generating code for real-time operating systems.

• Chapter 5, Generated Code Architecture, supplies more details about the content and framework of the generated code. This includes storage usage, various procedures, specialized blocks, and subsystems.

• Chapter 6, Vectorized Code Generation, discusses various ways to generate vectorized code. This includes describing the options available, design guidelines, and implementation details about the vectorized code.

• Chapter 7, Code Optimization, discusses how to optimize the generated code. This includes explaining the details of generating production quality code for micro controller-based applications.

Chapter 1 Introduction

• Chapter 8, AutoCode Sim Cdelay Scheduler, discusses the Sim Cdelay low-latency scheduler.

• Chapter 9, Global Scope Signals and Parameterless Procedures, discusses additional signals and procedures.

This guide also has an Index.

General Information

As an integral part of the rapid prototyping concept, AutoCode lets you generate high-level language code from a SystemBuild block diagram model quickly, automatically, and without programming skills. The AutoCode User Guide describes the processes for generating code, including the parameters that you must use. This manual provides details of how AutoCode actually works, so that you will have an idea of what to expect from AutoCode if you attempt to modify the generation of code.

Configuration File

The configuration file is a text file containing tables of information related to the generated source code components of a model, like subsystems and nonscheduled procedure SuperBlocks. Each table contains configuration information about its respective component. Various configuration files are supplied with AutoCode, including one for Real-Time Operating Systems (RTOS) as described in Chapter 4, Generating Code for Real-Time

Operating Systems. For additional configuration information, refer to the

AutoCode User Guide.

Language-Specific Information

This manual describes some of the details of AutoCode operation for both the C and Ada languages.

Specific topics include the following:

• Stand-alone (

• Fixed-point code generation

• UserCode Blocks (UCBs)

• Macro Procedure Blocks

• Procedure SuperBlocks

AutoCode Reference 1-2 ni.com

sa) files

Structure and Content of the Generated Code

This reference includes detailed descriptions about what is generated for many of the blocks used within a model. Also, the framework of the generated code is discussed to show how all of the pieces work together to form an executable simulation. This discussion is only relevant to those designers who are either writing their own templates or who are striving to optimize the generated code.

Topics include the following:

• Generating code for use within real-time operating systems

• Code architecture

• Vectorized code generation

Using MATRIXx Help

MATRIXx 7.x provides a hypertext markup language (HTML) help system. The MATRIXx Help is a self-contained system with multiple hypertext links from one component to another. This help, augmented by online and printed manuals, covers most MATRIXx topics except for installation.

Chapter 1 Introduction

The MATRIXx Help runs on Netscape. The MATRIXx CD-ROM includes the supported version. On UNIX systems, an OEM version of Navigator is automatically included in the MATRIXx installation. On PCs, Netscape must be installed independently using the Netscape installation procedure included on the MATRIXx CD.

Additional Netscape Information

For more information on Netscape products, visit the Netscape Web site at

http://home.netscape.com.

Chapter 1 Introduction

Related Publications

National Instruments provides a complete library of publications to support its products. In addition to this guide, publications that you may find particularly useful when using AutoCode include the following:

• AutoCode User Guide

• Template Programming Language User Guide

• Xmath User Guide

• SystemBuild User Guide

• BlockScript User Guide

• DocumentIt User Guide

For additional documentation, refer to the MATRIXx Help or visit the National Instruments Web site at

ni.com/manuals.

AutoCode Reference 1-4 ni.com

C Language Reference

This chapter discusses files used to interface AutoCode and the generated C code to your specific platform and target processor. This chapter also describes target-specific utilities needed for simulation and testing.

Stand-Alone Simulation

The template provided for C code generation produces code that, when compiled and linked with stand-alone files, forms a stand-alone simulation. This simulation can be executed with MATRIXx-style data as input, and produces results that can be loaded back into Xmath for analysis. You must compile the generated code along with the stand-alone library to produce the simulation executable.

Chapter 2, Using AutoCode, of the AutoCode User Guide describes how to compile the code and stand-alone library, generate sample input data, and load the data into Xmath for analysis.

Compiling on Various Supported Platforms

The generated code usually includes platform-specific code. Most of this code is not generated by AutoCode; rather, that code exists in the template. Also, the stand-alone library has platform-specific code to deal with file I/O and floating-point numerics. You must compile the generated code and the stand-alone library with a defined preprocessor symbol appropriate for your platform (refer to Table 2-1). For example, on the Solaris platform, the compile statement is similar to:

% acc -DSOLARIS -o simulation simmodel.c sa_*.o -lm

Note

This example assumes the stand-alone library was compiled into separate object files into the current working directory and that the stand-alone header files also exist in the current working directory.

Chapter 2 C Language Reference

Table 2-1. Recognized C Preprocessor Defines for Supported Platforms

Platform Preprocessor Define Compiler Switch

AIX (IBM UNIX) IBM

Compaq Tru64 5.0 OSF1

HPUX (700 series) HP700

HPUX (other than 700) HP

SGI IRIX SGI

Sun Solaris 2.x SOLARIS

Windows 2000/NT/9x MSWIN32

Stand-Alone Library

This section describes the system-specific and target-specific stand-alone (

sa) files supplied with your system.

System-Specific Files

National Instruments furnishes files to interface AutoCode and the generated code to your development platform (AIX, Compaq, HP, SGI, Solaris, Windows) and to the target processor in your test bed or rapid-prototyping system. Both header ( source files are provided in your the distribution directories and files are shown in Table 2-2.

-DIBM

-DOSF1

-DHP700

-DHP

-DSGI

-DSOLARIS

-DMSWIN32

.h extension) and C (.c extension)

src distribution directory. The names of

Table 2-2. Distribution Directories and Files

Platform UNIX Windows

Top-Level

Environment variable:

$MTXHOME %MTXHOME%

Table 2-3. Header Files

File Purpose

sa_sys.h

Defines the development platform. Contains a C preprocessor

#define statement for each supported

platform.

sa_types.h

Defines the supported data types and certain math constants.

sa_defn.h

Defines constants for generated code, error codes, and mapping for ANSI features such as const and volatile.

sa_intgr.h

Contains definitions of integration algorithms (including user-supplied integrator) used in code generation of hybrid or continuous systems.

sa_fuzzy.h

sa_utils.h

Contains definitions of fuzzy logic support routines.

Contains external function prototypes for the stand-alone utilities.

sa_math.h

Declares certain extensions to ANSI-Standard C math functions. The

sa_math.c file, which contains the

code for the extensions, is also required.

sa_time.h

sa_user.h

Declares a time-related variable.

Furnishes a function prototype for UCBs.

Data Types

Several of the target-specific utilities are involved with data types (in the

sa_types.h file). The three following data types are defined for

the C Code Generator:

RT_FLOAT Corresponds to C type double or float, depending on

your C compiler.

RT_INTEGER Corresponds to C type integer.

RT_BOOLEAN Corresponds to C type integer.

At compilation, you must make available the which declares these types. This file is in the

sa_types.h header file, src distribution directory

on your system; you can edit a copy of it as required. The structure

STATUS_RECORD also is declared in sa_types.h to be used with

hand-coded UserCode Blocks. You can modify

AutoCode Reference 2-4 ni.com

sa_types.h if you need

to. For example, RT_INTEGER can be redefined as long int if arithmetic overflow becomes a problem on a given platform.

Target-Specific Utilities

Target-specific utilities (in sa_utils.c) perform hardware, application, and C-specific tasks that are required for simulation and testing. They can be modified to support the generated code on different target computers. As furnished, these routines simulate I/O operations that would occur in a simulation environment, using input files created using MATRIXx. These files are intended to remain unmodified for use in comparing your simulations with generated code outputs. However, for target-system usage on your rapid prototyping or end-user system, these routines can be modified or rewritten completely and recompiled for the target system. When you do this, be sure to keep a copy of the of the files in separate directories.

Chapter 2 C Language Reference

sa_utils.c file or keep separate versions

There is no requirement that the file be named

sa_utils.c; however, the

name you use must be specified at link time. Inside the file, the names of the external variables, functions, and other references must be preserved. As furnished for this release, the routines are written in C, but this is not required. If you rewrite the routines, they should still be written in a language that offers direct control of the I/O and interrupt hardware of the target computer and can be linked to the object form of the generated C program. Normally, these utilities need to be created only once for each target computer. In general, a given set of target-specific utilities need only be changed when the target hardware is modified. The routines are shown in Table 2-4.

Table 2-4. Target-Specific Utility Routines

Routine Description

Enable( )

Disable( )

Background( )

Error( ), fatalerr( )

Implementation_Initialize( )

Unmask timer interrupt.

Mask timer interrupt.

Background polling loop.

Error handlers.

Initialize I/O hardware and perform other implementation-specific initialization tasks.

Chapter 2 C Language Reference

Table 2-4. Target-Specific Utility Routines (Continued)

Routine Description

Implementation_Terminate( )

Perform implementation-specific termination tasks.

External_Input( )

External_Output( )

Signal_Remote_Dispatch( )

Collect external inputs.

Post external outputs.

Multiprocessor implementations only; signal secondary processors that a dispatch table is available.

The sa_utils.c file contains comments about each of the routines as they are used for comparing simulation with generated code results.

After you generate code, link the generated code with

sa_*.o object files

(refer to Chapter 2, Using AutoCode, of the AutoCode User Guide). For example, on UNIX platforms:

cc -o

gen_ap

where

gen_ap

.c $ISI/ACC/src/sa_*.o -l

gen_ap

is the name of the generated code file.

other libraries

enable( ), disable( ), and background( ) Functions

enable( ) unmasks timer interrupts. disable( ) masks timer interrupts

to prevent re-entry of the scheduler during critical sections. and

disable( ) are not needed in some implementations. These

functions are furnished as stubs and

sa_utils.h file.

#defined as NULL in the

enable( )

The

background( ) function, as provided in sa_utils.c, merely

invokes the scheduler for the appropriate number of computation cycles and calls the error handler if any scheduler error occurs.

error( ) and fatalerr( ) Functions

void fatalerr(RT_INTEGER ERROR);

void error(RT_INTEGER NTSK,RT_INTEGER ERRORFLAG);

AutoCode Reference 2-6 ni.com

Chapter 2 C Language Reference

Two error functions are provided, fatalerr( ) and error( ). The

fatalerr( ) function reports exception conditions detected by the

functions in the

sa_utils.c file. error( ) reports conditions detected

by the generated code during execution. Not all reported conditions are errors. These functions can be invoked for deactivating all necessary functions and then passing an alarm to the external environment or for initiating recovery action. You can choose either to return from an error function or to halt the machine.

fatalerr( ): Stand-Alone Utilities Detected Errors

Several error conditions are trapped in sa_utils.c by default, but you can expand this capability in your own versions of the program, detecting your own error conditions and adding your own messages. The value that is returned is evaluated by a C language switch-case statement. Any

RT_INTEGER value can be used for an error indication, except that the

value of

–1 is reserved for use in the scheduler.

The following are generated messages displayed in the default version of the

sa_utils.c file. Most of these messages pertain to the processing of

the input and output files for execution of generated code.

INPUT FILE IS NOT IN Xmath {matrixx,ascii} FORMAT

ERROR

Save the file in MATRIXx ASCII format from Xmath, then try again.

INPUT FILE IS NOT V7.0 OR LATER

The input data file was generated using an obsolete version of MATRIXx. Save the file in MATRIXx ASCII format from Xmath, then try again.

INPUT FILE CONTAINS MORE THAN TWO ARRAYS

INPUT TIME VECTOR NOT ONE COLUMN

INPUT U DIMENSION NOT (TIME x NUMBER OF INPUTS)

The following messages indicate a bad input file.

INPUT TIME VECTOR TOO LARGE

INPUT U ARRAY TOO LARGE FOR AVAILABLE STORAGE

OUTPUT STORAGE EXCEEDS THE AVAILABLE STORAGE

The following messages indicate that the size of the input file has exceeded one or more of the storage allocation size limits established by

sa_utils.c. These limits are #defined at the very beginning of the sa_utils.c header, just after the #include header statements. Refer to

Chapter 2 C Language Reference

the comments there and adjust the limits accordingly, then recompile and relink the

ERROR OPENING THE INPUT FILE

ERROR OPENING THE OUTPUT FILE

A problem was encountered opening the input or output file. Possible causes include a file protection violation.

UNKNOWN ERROR

A value of the ERROR variable occurred that was not one of those defined for the switch-case statement. Check any error indications you may have introduced.

ERROR: Conditions Detected in the Generated Code

The RT_INTEGER variable ERROR_FLAG is passed if an error occurs in running the generated code. The following conditions are trapped, not all of which indicate that an error has occurred.

The following messages might be generated during the execution of the generated code:

Stop Block encountered in task

sa_utils.c file.

This is not necessarily an error. This refers to a SystemBuild Stop Simulation Block encountered in the execution of the generated code.

Math Error encountered in task

Check your model for overflows, division by zero, and similar problems.

User code error encountered in task

Refer to Chapter 15, UserCode Blocks, of the SystemBuild User Guide or the source listing of the USR01 routine for meanings of UCB errors. You can extend the scope of these messages, so it might be one of yours.

Unknown error encountered in task

A possible cause is an incorrect user-written error condition in the generated code.

Time overflow occurred in task

This indicates a subsystem (or task) overflow. Refer to the Scheduler Errors section of Chapter 4, Managing and Scheduling Applications, of the AutoCode User Guide for timing overflow conditions.

AutoCode Reference 2-8 ni.com

Chapter 2 C Language Reference

Implementation_Initialize( ) Function

void Implementation_Initialize (RT_FLOAT *BUS_IN RT_INTEGER, NI, RT_FLOAT BUS_OUT, RT_INTEGER NO, RT_FLOAT SCHEDULER_FREQ);

In the default version of sa_utils.c (simulation comparison), this function initializes the I/O for the system by loading input data from the user-furnished MATRIXx that you write to make the generated code work with the target computer, this routine performs implementation-specific initialization processes for the real-time system. These might include, but are not limited to, the following:

• Initialize the interrupt system of the target computer.

• Initialize the math coprocessor, if any.

• Set up shared memory and other hardware-dependent processes.

• Initialize I/O hardware.

• Initialize the clock-timer of the target system to request interrupts at the minor cycle of the control system; that is, the time period required between interrupts for synchronous operation of the tasks, as calculated by AutoCode from the block diagrams.

FSAVE input file. In the version of this routine

Implementation_Terminate( ) Function

void Implementation_Terminate(void)

In the default version of sa_utils.c (simulation comparison), this function completes the I/O processing for the execution of the system by writing output data to the output file and closing the file. In the version of this routine that you write to make the generated code work with the target computer, this routine might be called on to perform many kinds of implementation-specific shutdown processes for the real-time system in addition to data completion tasks. These might include, but are not limited to, the following:

• Disable interrupt hardware.

• Free up shared memory and other resources.

• De-initialize I/O hardware.

Chapter 2 C Language Reference

External_Input ( ) Function

RT_INTEGER External_Input(void)

External_Input( ) is for use in the simulation comparison mode; it

reads in external input data from your specified appears in input vector ( conversion is required in this version of the generated code, because all data is passed as arrays of type

SCHEDULER_STATUS, which reports on the success of the input operation

and is passed to the target version of same; every time it is called, from the hardware sensors.

External_Output ( ) Function

RT_INTEGER External_Output(void)

FSAVE input file. The data

XINPUT, an array of type RT_FLOAT, dimensioned equal to the

T- and U-vectors) defined at simulation time. No data

RT_FLOAT. The routine returns the value of

External_Input( ) routine by the scheduler. In the

sa_utils.c, the operation of this function is much the

External_Input( ) returns an input vector

External_Output( )

it posts external output data to your specified output file. The data is presented in the output required in this version of the generated code, because all data is passed as arrays of type

SCHEDULER_STATUS, which is passed to it by the scheduler. In the target

version of every time it is called, software data bus.

UserCode Blocks

This section describes how to link UserCode Blocks (UCBs) with AutoCode or SystemBuild applications. AutoCode supports all SystemBuild data types for inputs and outputs and the generation of the fixed and variable interface options. The variable interface does not include optional arguments to the user code—for example, states—if that argument is not specified in the UCB. Unless otherwise stated, the following sections describe the fixed interface option of a UCB.

is for use in the simulation comparison mode;

XOUTPUT, an array of type RT_FLOAT, dimensioned equal to

Y vector as defined at simulation time. No data conversion is

RT_FLOAT. The routine returns the value of

sa_utils.c, the operation of this function is much the same;

External_Output( ) posts an output vector to the

AutoCode Reference 2-10 ni.com

Chapter 2 C Language Reference

Linking Handwritten UCBs with AutoCode Applications

To write code for UserCode Blocks (UCBs), refer to the sa_user.c file, which is provided in your

The

sa_user.c file contains an example of a UCB function declaration

(refer to the Implementing Handwritten UCBs section). If your model has more than one UCB, each prototype must have a unique name. Make one or more copies of this file and insert the code that implements the algorithm(s) of the UCB(s). One or more uniquely-named UCB code functions can be placed inside each copy of the copies can be given any convenient names. If renamed files are included, the names can be placed into the stand-alone file compilation script (

compile_c_sa.sh) for automatic compilation. If the UCB function—for

example, USR01, refer to callout 2 of Figure 2-1—is renamed, all other occurrences of USR01 in changed appropriately, including the occurrence in directive to callout 1 of Figure 2-1.

src distribution directory.

sa_user.c file and the

sa_user.c and sa_user.h also must be

$ucb. Refer

Chapter 2 C Language Reference

Figure 2-1. Example UserCode Function File (sa_user.c)

The $ucb directive is recognized and interpreted by the automatic linking facility of the simulator in SystemBuild to distinguish between UCBs written for simulation purposes using SystemBuild only and UCBs written for linking with AutoCode applications. The exact name of the UCB function must be specified in the

$ucb directive if this UCB function is

used for simulation using SystemBuild.

The computations performed by UCBs can update both block states and outputs. Execution of each section is controlled by flags set by the simulator in the INFO structure. Refer to the Implementing Handwritten

UCBs section.

AutoCode Reference 2-12 ni.com

Chapter 2 C Language Reference

Implementing Handwritten UCBs

Arguments are passed for each call to the UCB in the following order:

INFO, T, U, NU, X, XDOT, NX, Y, NY, R_P, and I_P

Pointers to all of the arrays (U, X, XD, Y, R_P, I_P) and scalers corresponding to array sizes (

R_P and I_P arrays must be entered into the UCB dialog to ensure that

proper storage is allocated by the caller. Also, the initial conditions for states have to be specified in the dialog. Table 2-5 lists the type and purpose of UCB arguments used in the fixed calling method.

Table 2-5. UCB Calling Arguments and Data Types for the Fixed Interface

Argument Data Type Description

NU, NX, NY) are passed to each call to the UCB. The sizes of

INFO struct STATUS_RECORD*

T RT_DURATION

U[ ] RT_FLOAT

NU RT_INTEGER

X[ ] RT_FLOAT

XDOT[ ] RT_FLOAT

NX RT_INTEGER

Y[ ] RT_FLOAT

NY RT_INTEGER

R_P[ ] RT_FLOAT

I_P[ ] RT_INTEGER

A pointer to STATUS_RECORD structure representing operation requests and status.

Elapsed time.

An array (of size NU) of inputs to the UCB.

The number of inputs to the UCB.

An array (of size NX) of state variables of the UCB.

An array (also of size NX). Includes the next discrete states of and the derivative of

X for the discrete subsystems,

X for the continuous

subsystems.

The number of states (and next states).

An array (of size NY) of outputs from the UCB.

The number of outputs from the UCB.

An array of real parameters.

An array of integer parameters.

+ 220 hidden pages

National Instruments AutoCode NI MATRIX User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

AutoCode Reference

Support

Worldwide Technical Support and Product Information

National Instruments Corporate Headquarters

Worldwide Offices

Important Information

Warranty

Copyright

Trademarks

Patents

WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS

Conventions

Contents

Manual Organization

General Information

Configuration File

Language-Specific Information

Structure and Content of the Generated Code

Using MATRIXx Help

Additional Netscape Information

Related Publications

Stand-Alone Simulation

Compiling on Various Supported Platforms

Table 2-1. Recognized C Preprocessor Defines for Supported Platforms

Stand-Alone Library

System-Specific Files

Table 2-2. Distribution Directories and Files

Table 2-3. Header Files

Target-Specific Utilities

Table 2-4. Target-Specific Utility Routines

enable( ), disable( ), and background( ) Functions

error( ) and fatalerr( ) Functions

fatalerr( ): Stand-Alone Utilities Detected Errors

ERROR: Conditions Detected in the Generated Code

Implementation_Initialize( ) Function

Implementation_Terminate( ) Function

External_Input ( ) Function

External_Output ( ) Function

UserCode Blocks

Linking Handwritten UCBs with AutoCode Applications

Figure 2-1. Example UserCode Function File (sa_user.c)

Implementing Handwritten UCBs

Table 2-5. UCB Calling Arguments and Data Types for the Fixed Interface