Documentation

Overview of Operation

The following pseudocode shows the execution of a main program.

main()
{
  Initialization (including installation of rt_OneStep as an 
    interrupt service routine for a real-time clock)
  Initialize and start timer hardware
  Enable interrupts
  While(not Error) and (time < final time)
    Background task
  EndWhile
  Disable interrupts (Disable rt_OneStep from executing)
  Complete any background tasks
  Shutdown
}

The pseudocode is a design for a harness program to drive your model. The main program only partially implements this design. You must modify it according to your specifications.

Guidelines for Modifying the Main Program

This section describes the minimal modifications you should make in your production version of the main program module to implement your harness program.

Overview of Operation

The operation of rt_OneStep depends upon

Permitted Solver Modes for Embedded Real-Time System Target Files summarizes the permitted solver modes for single-rate and multirate models. Note that for a single-rate model, only SingleTasking solver mode is allowed.

The generated code for rt_OneStep (and associated timing data structures and support functions) is tailored to the number of rates in the model and to the solver mode. The following sections discuss each possible case.

Single-Rate Single-Tasking Operation

The only valid solver mode for a single-rate model is SingleTasking. Such models run in “single-rate” operation.

The following pseudocode shows the design of rt_OneStep in a single-rate program.

rt_OneStep()
{
  Check for interrupt overflow or other error
  Enable "rt_OneStep" (timer) interrupt
  Model_Step()  -- Time step combines output,logging,update
}

For the single-rate case, the generated model_step function is

void model_step(void)

Single-rate rt_OneStep is designed to execute model_step within a single clock period. To enforce this timing constraint, rt_OneStep maintains and checks a timer overrun flag. On entry, timer interrupts are disabled until the overrun flag and other error conditions have been checked. If the overrun flag is clear, rt_OneStep sets the flag, and proceeds with timer interrupts enabled.

The overrun flag is cleared only upon successful return from model_step. Therefore, if rt_OneStep is reinterrupted before completing model_step, the reinterruption is detected through the overrun flag.

Reinterruption of rt_OneStep by the timer is an error condition. If this condition is detected rt_OneStep signals an error and returns immediately. (Note that you can change this behavior if you want to handle the condition differently.)

Note that the design of rt_OneStep assumes that interrupts are disabled before rt_OneStep is called. rt_OneStep should be noninterruptible until the interrupt overflow flag has been checked.

Multirate Multitasking Operation

In a multirate multitasking system, code generation uses a prioritized, preemptive multitasking scheme to execute the different sample rates in your model.

The following pseudocode shows the design of rt_OneStep in a multirate multitasking program.

rt_OneStep()
{
  Check for base-rate interrupt overrun
  Enable "rt_OneStep" interrupt
  Determine which rates need to run this time step

  Model_Step0()        -- run base-rate time step code

  For N=1:NumTasks-1   -- iterate over sub-rate tasks
    If (sub-rate task N is scheduled)
    Check for sub-rate interrupt overrun
      Model_StepN()    -- run sub-rate time step code
    EndIf
  EndFor
}

Task Identifiers.  The execution of blocks having different sample rates is broken into tasks. Each block that executes at a given sample rate is assigned a task identifier (tid), which associates it with a task that executes at that rate. Where there are NumTasks tasks in the system, the range of task identifiers is 0..NumTasks-1.

Prioritization of Base-Rate and Subrate Tasks.  Tasks are prioritized, in descending order, by rate. The base-rate task is the task that runs at the fastest rate in the system (the hardware clock rate). The base-rate task has highest priority (tid 0). The next fastest task (tid 1) has the next highest priority, and so on down to the slowest, lowest priority task (tid NumTasks-1).

The slower tasks, running at multiples of the base rate, are called subrate tasks.

Rate Grouping and Rate-Specific model_step Functions.  In a single-rate model, the block output computations are performed within a single function, model_step. For multirate, multitasking models, the code generator tries to use a different strategy. This strategy is called rate grouping. Rate grouping generates separate model_step functions for the base rate task and each subrate task in the model. The function naming convention for these functions is

model_stepN

where N is a task identifier. For example, for a model named my_model that has three rates, the following functions are generated:

void my_model_step0 (void);
void my_model_step1 (void);
void my_model_step2 (void);

Each model_stepN function executes the blocks sharing tid N; in other words, the block code that executes within task N is grouped into the associated model_stepN function.

Scheduling model_stepN Execution.  On each clock tick, rt_OneStep maintains scheduling counters and event flags for each subrate task. The counters are implemented as taskCounter arrays indexed on tid. The event flags are implemented as arrays indexed on tid.

The scheduling counters and task flags for sub-rates are maintained by rt_OneStep. The scheduling counters are basically clock rate dividers that count up the sample period associated with each sub-rate task. A pair of tasks that exchanges data maintains an interaction flag at the faster rate. Task interaction flags indicate that both fast and slow tasks are scheduled to run.

The event flags indicate whether or not a given task is scheduled for execution. rt_OneStep maintains the event flags based on a task counter that is maintained by code in the main program module for the model. When a counter indicates that a task's sample period has elapsed, the main code sets the event flag for that task.

On each invocation, rt_OneStep updates its scheduling data structures and steps the base-rate task (rt_OneStep calls model_step0 because the base-rate task must execute on every clock step). Then, rt_OneStep iterates over the scheduling flags in tid order, unconditionally calling model_stepN for any task whose flag is set. The tasks are executed in order of priority.

Preemption.  Note that the design of rt_OneStep assumes that interrupts are disabled before rt_OneStep is called. rt_OneStep should be noninterruptible until the base-rate interrupt overflow flag has been checked (see pseudocode above).

The event flag array and loop variables used by rt_OneStep are stored as local (stack) variables. Therefore, rt_OneStep is reentrant. If rt_OneStep is reinterrupted, higher priority tasks preempt lower priority tasks. Upon return from interrupt, lower priority tasks resume in the previously scheduled order.

Overrun Detection.  Multirate rt_OneStep also maintains an array of timer overrun flags. rt_OneStep detects timer overrun, per task, by the same logic as single-rate rt_OneStep.

Multirate Single-Tasking Operation

In a multirate single-tasking program, by definition, sample times in the model must be an integer multiple of the model's fixed-step size.

In a multirate single-tasking program, blocks execute at different rates, but under the same task identifier. The operation of rt_OneStep, in this case, is a simplified version of multirate multitasking operation. Rate grouping is not used. The only task is the base-rate task. Therefore, only one model_step function is generated:

void model_step(void)

On each clock tick, rt_OneStep checks the overrun flag and calls model_step. The scheduling function for a multirate single-tasking program is rate_scheduler (rather than rate_monotonic_scheduler). The scheduler maintains scheduling counters on each clock tick. There is one counter for each sample rate in the model. The counters are implemented in an array (indexed on tid) within the Timing structure within rtModel.

The counters are clock rate dividers that count up the sample period associated with each subrate task. When a counter indicates that a sample period for a given rate has elapsed, rate_scheduler clears the counter. This condition indicates that blocks running at that rate should execute on the next call to model_step, which is responsible for checking the counters.

Guidelines for Modifying rt_OneStep

rt_OneStep does not require extensive modification. The only required modification is to reenable interrupts after the overrun flags and error conditions have been checked. If applicable, you should also

Comments in rt_OneStep indicate the place to add your code.

In multirate rt_OneStep, you can improve performance by unrolling for and while loops.

In addition, you may choose to modify the overrun behavior to continue execution after error recovery is complete.

Also observe the following cautionary guidelines:

Overview

In most cases, the easiest strategy for deploying generated code is to use the Generate an example main program option to generate the ert_main.c or .cpp module (see Generate a Standalone Program).

However, if you turn the Generate an example main program option off, you can use a static main module as an example or template for developing your embedded applications. Static main modules provided by MathWorks^® include:

The static main module is not part of the generated code; it is provided as a basis for your custom modifications, and for use in simulation. If your existing applications depend upon a static ert_main.c (developed in releases before R2012b), rt_main.c, rt_malloc_main.c, or rt_cppclass_main.cpp, you may need to continue using a static main program module.

When developing applications using a static main module, you should copy the module to your working folder and rename it before making modifications. For example, you could rename rt_main.c to model_rt_main.c. Also, you must modify the template makefile or toolchain settings such that the build process creates a corresponding object file, such as model_rt_main.obj (on UNIX^®, model_rt_main.o), in the build folder.

The static main module contains

For single-rate models, the operation of rt_OneStep and the main function are essentially the same in the static main module as they are in the automatically generated version described in Deploy Generated Standalone Executable Programs To Target Hardware. For multirate, multitasking models, however, the static and generated code are slightly different. The next section describes this case.

Rate Grouping and the Static Main Program

Targets based on the ERT target sometimes use a static main module and disallow use of the Generate an example main program option. This is done because target-specific modifications have been added to the static main module, and these modifications would not be preserved if the main program were regenerated.

Your static main module may or may not use rate grouping compatible model_stepN functions. If your main module is based on the static rt_main.c, rt_malloc_main.c, or rt_cppclass_main.cpp module, it does not use rate-specific model_stepN function calls. It uses the old-style model_step function, passing in a task identifier:

void model_step(int_T tid);

By default, when the Generate an example main program option is off, the ERT target generates a model_step “wrapper” for multirate, multitasking models. The purpose of the wrapper is to interface the rate-specific model_stepN functions to the old-style call. The wrapper code dispatches to the model_stepN call with a switch statement, as in the following example:

void mymodel_step(int_T tid) /* Sample time:  */
{

  switch(tid) {
   case 0 :
    mymodel_step0();
    break;
   case 1 :
    mymodel_step1();
    break;
   case 2 :
    mymodel_step2();
    break;
   default :
    break;
  }
}

The following pseudocode shows how rt_OneStep calls model_step from the static main program in a multirate, multitasking model.

rt_OneStep()
{
  Check for base-rate interrupt overflow
  Enable "rt_OneStep" interrupt
  Determine which rates need to run this time step

  ModelStep(tid=0)     --base-rate time step

  For N=1:NumTasks-1  -- iterate over sub-rate tasks
    Check for sub-rate interrupt overflow
    If (sub-rate task N is scheduled)
      ModelStep(tid=N)    --sub-rate time step
    EndIf
  EndFor
}

You can use the TLC variable RateBasedStepFcn to specify that only the rate-based step functions are generated, without the wrapper function. If your target calls the rate grouping compatible model_stepN function directly, set RateBasedStepFcn to 1. In this case, the wrapper function is not generated.

You should set RateBasedStepFcn prior to the %include "codegenentry.tlc" statement in your system target file. Alternatively, you can set RateBasedStepFcn in your target_settings.tlc file.

Modify the Static Main Program

As with the generated ert_main.c or .cpp, you should make a few modifications to the main loop and rt_OneStep. See Guidelines for Modifying the Main Program and Guidelines for Modifying rt_OneStep.

Also, you should replace the rt_OneStep call in the main loop with a background task call or null statement.

Other modifications you may need to make are

Modify Static Main to Allocate and Access Model Instance Data

If you are using a static main program module, and your model is configured for Reusable function code interface packaging, but the model configuration parameter Use dynamic memory allocation for model initialization is cleared, model instance data must be allocated statically or dynamically by the calling main code. Pointers to the individual model data structures (such as Block IO, DWork, and Parameters) must be set up in the top-level real-time model data structure.

To support main modifications, the build process generates a subset of the following real-time model (RTM) macros, based on the data requirements of your model, into model.h.

Use these macros in your static main program to access individual model data structures within the RTM data structure. For example, suppose that the example model rtwdemo_reusable is configured with Reusable function code interface packaging, Use dynamic memory allocation for model initialization cleared, Pass root-level I/O as set to Individual arguments, and Optimization pane option Remove root level I/O zero initialization cleared. Building the model generates the following model data structures and model entry-points into rtwdemo_reusable.h:

/* Block states (auto storage) for system '<Root>' */
typedef struct {
  real_T Delay_DSTATE;                 /* '<Root>/Delay' */
} D_Work;

/* Parameters (auto storage) */
struct Parameters_ {
  real_T k1;                           /* Variable: k1
                                        * Referenced by: '<Root>/Gain'
                                        */
};

/* Model entry point functions */
extern void rtwdemo_reusable_initialize(RT_MODEL *const rtM, real_T *rtU_In1,
  real_T *rtU_In2, real_T *rtY_Out1);
extern void rtwdemo_reusable_step(RT_MODEL *const rtM, real_T rtU_In1, real_T
  rtU_In2, real_T *rtY_Out1);

Additionally, if model configuration parameter Generate an example main program is not selected for the model, rtwdemo_reusable.h contains definitions for the RTM macros rtmGetDefaultParam, rtmsetDefaultParam, rtmGetRootDWork, and rtmSetRootDWork.

Also, for reference, the generated rtmodel.h file contains an example parameter definition with initial values (non-executing code):

#if 0

/* Example parameter data definition with initial values */
static Parameters rtP = {
  2.0                                  /* Variable: k1
                                        * Referenced by: '<Root>/Gain'
                                        */
};                                     /* Modifiable parameters */

#endif

In the definitions section of your static main file, you could use the following code to statically allocate the real-time model data structures and arguments for the rtwdemo_reusable model:

static RT_MODEL rtM_;
static RT_MODEL *const rtM = &rtM_;    /* Real-time model */
static Parameters rtP = {
  2.0                                  /* Variable: k1
                                        * Referenced by: '<Root>/Gain'
                                        */
};                                     /* Modifiable parameters */

static D_Work rtDWork;                 /* Observable states */

/* '<Root>/In1' */
static real_T rtU_In1;

/* '<Root>/In2' */
static real_T rtU_In2;

/* '<Root>/Out1' */
static real_T rtY_Out1;

In the body of your main function, you could use the following RTM macro calls to set up the model parameters and DWork data in the real-time model data structure:

int_T main(int_T argc, const char *argv[])
{
...
/* Pack model data into RTM */

rtmSetDefaultParam(rtM, &rtP);
rtmSetRootDWork(rtM, &rtDWork);

/* Initialize model */
rtwdemo_reusable_initialize(rtM, &rtU_In1, &rtU_In2, &rtY_Out1);
...
}

Follow a similar approach to set up multiple instances of model data, where the real-time model data structure for each instance has its own data. In particular, the parameter structure (rtP) should be initialized, for each instance, to the desired values, either statically as part of the rtP data definition or at run time.

Main Program Compatibility

When the Generate an example main program option is off, code generation produces slightly different rate grouping code, for compatibility with the older static ert_main.c module. See Rate Grouping and the Static Main Program for details.

Make Your S-Functions Rate Grouping Compliant

Built-in Simulink^® blocks, as well as DSP System Toolbox™ blocks, are compliant with the requirements for generating rate grouping code. However, user-written multirate inlined S-functions may not be rate grouping compliant. Noncompliant blocks generate less efficient code, but are otherwise compatible with rate grouping. To take full advantage of the efficiency of rate grouping, your multirate inlined S-functions must be upgraded to be fully rate grouping compliant. You should upgrade your TLC S-function implementations, as described in this section.

Use of noncompliant multirate blocks to generate rate-grouping code generates dead code. This can cause two problems:

To make your S-functions rate grouping compliant, you can use the following TLC functions to generate ModelOutputs and ModelUpdate code, respectively:

OutputsForTID(block, system, tid)
UpdateForTID(block, system, tid)

The code listings below illustrate generation of output computations without rate grouping (Listing 1) and with rate grouping (Listing 2). Note the following:

Listing 1: Outputs Code Generation Without Rate Grouping

%% multirate_blk.tlc

%implements "multirate_blk" "C"


%% Function: mdlOutputs =====================================================
%% Abstract:
%%
%%  Compute the two outputs (input signal decimated by the
%%  specified parameter). The decimation is handled by sample times.
%%  The decimation is only performed if the block is enabled.
%%  Each port has a different rate.
%%
%%  Note, the usage of the enable should really be protected such that
%%  each task has its own enable state. In this example, the enable
%% occurs immediately which may or may not be the expected behavior.
%%
  %function Outputs(block, system) Output
  /* %<Type> Block: %<Name> */
  %assign enable = LibBlockInputSignal(0, "", "", 0)
  {
    int_T *enabled = &%<LibBlockIWork(0, "", "", 0)>;

    %if LibGetSFcnTIDType("InputPortIdx0") == "continuous"
      %% Only check the enable signal on a major time step.
      if (%<LibIsMajorTimeStep()> && ...
                           %<LibIsSFcnSampleHit("InputPortIdx0")>) {
        *enabled = (%<enable> > 0.0);
      }
    %else
      if (%<LibIsSFcnSampleHit("InputPortIdx0")>) {
        *enabled = (%<enable> > 0.0);
      }
    %endif

    if (*enabled) {
      %assign signal = LibBlockInputSignal(1, "", "", 0)
      if (%<LibIsSFcnSampleHit("OutputPortIdx0")>) {
        %assign y = LibBlockOutputSignal(0, "", "", 0)   
        %<y> = %<signal>;
      }
      if (%<LibIsSFcnSampleHit("OutputPortIdx1")>) {
        %assign y = LibBlockOutputSignal(1, "", "", 0)
        %<y> = %<signal>;
      }
    }
  }

  %endfunction
%% [EOF] sfun_multirate.tlc

Listing 2: Outputs Code Generation With Rate Grouping

%% example_multirateblk.tlc

%implements "example_multirateblk" "C"


  %% Function: mdlOutputs =====================================================
  %% Abstract:
  %%
  %% Compute the two outputs (the input signal decimated by the
  %% specified parameter). The decimation is handled by sample times.
  %% The decimation is only performed if the block is enabled.  
  %% All ports have different sample rate.
  %%
  %% Note: the usage of the enable should really be protected such that
  %% each task has its own enable state. In this example, the enable
  %% occurs immediately which may or may not be the expected behavior.
  %%
  %function Outputs(block, system) Output



  %assign portIdxName = ["InputPortIdx0","OutputPortIdx0","OutputPortIdx1"]
  %assign portTID     = [%<LibGetGlobalTIDFromLocalSFcnTID("InputPortIdx0")>, ...
                        %<LibGetGlobalTIDFromLocalSFcnTID("OutputPortIdx0")>, ...
                        %<LibGetGlobalTIDFromLocalSFcnTID("OutputPortIdx1")>]
  %foreach i = 3
    %assign portName = portIdxName[i]
    %assign tid      = portTID[i]
    if (%<LibIsSFcnSampleHit(portName)>) {
                       %<OutputsForTID(block,system,tid)>
    }
  %endforeach

  %endfunction

  %function OutputsForTID(block, system, tid) Output
  /* %<Type> Block: %<Name> */
  %assign enable = LibBlockInputSignal(0, "", "", 0)  
  %assign enabled = LibBlockIWork(0, "", "", 0)  
  %assign signal = LibBlockInputSignal(1, "", "", 0)

  %switch(tid)
    %case LibGetGlobalTIDFromLocalSFcnTID("InputPortIdx0") 
                         %if LibGetSFcnTIDType("InputPortIdx0") == "continuous"
                           %% Only check the enable signal on a major time step.
                           if (%<LibIsMajorTimeStep()>) {  
                             %<enabled> = (%<enable> > 0.0);
                           }
                         %else
                           %<enabled> = (%<enable> > 0.0);
                         %endif
                         %break
    %case LibGetGlobalTIDFromLocalSFcnTID("OutputPortIdx0") 
                         if (%<enabled>) {
                           %assign y = LibBlockOutputSignal(0, "", "", 0)
                           %<y> = %<signal>;
                         }
                         %break
    %case LibGetGlobalTIDFromLocalSFcnTID("OutputPortIdx1") 
                         if (%<enabled>) {
                           %assign y = LibBlockOutputSignal(1, "", "", 0)
                           %<y> = %<signal>;
                         }
                         %break
    %default 
                         %% error it out
  %endswitch

  %endfunction

%% [EOF] sfun_multirate.tlc