Writing S-Functions

Creating Level 2 Fortran S-Functions

To use the features of a level 2 S-function with Fortran code, you must write a skeleton S-function in C that has code for interfacing to Simulink and also calls your Fortran code.

Using the C-MEX S-function as a gateway is quite simple if you are writing the Fortran code from scratch. If instead your Fortran code already exists as a stand-alone simulation, there is some work to be done to identify parts of the code that need to be registered with Simulink, such as identifying continuous states if you are using variable-step solvers or getting rid of static variables if you want to have multiple copies of the S-function in a Simulink model (see Porting Legacy Code).

Template File

The file matlabroot/simulink/src/sfungate.c is a C-MEX template file for calling into a Fortran subroutine. It works with a simple Fortran subroutine if you modify the Fortran subroutine name in the code.

C/Fortran Interfacing Tips

The following are some tips for creating the C-to-Fortran gateway S-function.

Mex Environment

Remember that mex -setup needs to find both the C and the Fortran compilers. If you install or change compilers, you must run mex -setup.

Test the installation and setup using sample MEX files from MATLAB's C and Fortran MEX examples in matlabroot/extern/examples/mex, as well as Simulink's examples, which are located in matlabroot/simulink/src.

Compiler Compatibility

Your C and Fortran compilers need to use the same object format. If you use the compilers explicitly supported by the mex command this is not a problem. When you use the C gateway to Fortran, it is possible to use Fortran compilers not supported by the mex command, but only if the object file format is compatible with the C compiler format. Common object formats include ELF and COFF.

The compiler must also be configurable so that the caller cleans up the stack instead of the callee. Compaq Visual Fortran (formerly known as Digital Fortran) is one compiler whose default stack cleanup is the callee.

Symbol Decorations

Symbol decorations can cause run-time errors. For example, g77 decorates subroutine names with a trailing underscore when in its default configuration. You can either recognize this and adjust the C function prototype or alter the Fortran compiler's name decoration policy via command line switches, if the compiler supports this. See the Fortran compiler manual about altering symbol decoration policies.

If all else fails, use utilities such as od (octal dump) to display the symbol names. For example, the command

• od -s 2 <file>
  

lists strings and symbols in binary (.obj) files.

These binary utilities can be obtained for Windows as well. MKS is one company that has commercial versions of powerful UNIX utilities, although most can also be obtained free on the Web. hexdump is another common program for viewing binary files. As an example, here is the output of

• od -s 2 sfun_atmos_for.o
  

on Linux.

•      0000115 EÈÙ
       0000136 EÈÙ
       0000271 EȺ 
       0000467 ÇEÈ@
       0000530 ÇEÈ 
       0000575 EÈÙEäØ5@
       0001267 CfVC-ò:C
       0001323 :|.-:8Æ#8ýKw6
       0001353 ?333@
       0001364 333À
       0001414 01.01
       0001425 GCC: (GNU) egcs-2.91.66 19990314/Linux
       0001522 .symtab
       0001532 .strtab
       0001542 .shstrtab
       0001554 .text
       0001562 .rel.text
       0001574 .data
       0001602 .bss
       0001607 .note
       0001615 .comment
       0003071 sfun_atmos_for.for
       0003101 gcc2_compiled.
       0003120 rearth.0
       0003131 gmr.1
       0003137 htab.2
       0003146 ttab.3
       0003155 ptab.4
       0003164 gtab.5
       0003173 atmos_
       0003207 exp
       0003213 pow_d
  

Note that Atmos has been changed to atmos_, which the C program must call to be successful.

With Compaq Visual Fortran, the symbol is suppressed, so that Atmos becomes ATMOS (no underscore).

Fortran Math Library

Fortran math library symbols might not match C math library symbols. For example, A^B in Fortran calls library function pow_dd, which is not in the C math library. In these cases, you must tell mex to link in the Fortran math library. For gcc environments, these routines are usually found in /usr/local/lib/libf2c.a, /usr/lib/libf2c.a, or equivalent.

The mex command becomes

• mex -L/usr/local/lib -lf2c cmex_c_file fortran_object_file
  

Note    On UNIX, the -lf2c option follows the conventional UNIX library linking syntax, where '-l' is the library option itself and 'f2c' is the unique part of the library file's name, libf2c.a. Be sure to use the -L option for the library search path, because -I is only followed while searching for include files.

The f2c package can be obtained for Windows and UNIX environments from the Internet. The file libf2c.a is usually part of g77 distributions, or else the file is not needed as the symbols match. In obscure cases, it must be installed separately, but even this is not difficult once the need for it is identified.

On Windows, using Microsoft Visual C/C++ and Compaq Visual Fortran 6.0 (formerly known as Digital Fortran), this example can be compiled using the following mex commands (each command is on one line).

• mex -v COMPFLAGS#"$COMPFLAGS /iface:cref" -c sfun_atmos_sub.for 
  -f ..\..\bin\win32\mexopts\df60opts.bat
  mex -v LINKFLAGS#"$LINKFLAGS dfor.lib dfconsol.lib dfport.lib 
  /LIBPATH:$DF_ROOT\DF98\LIB" sfun_atmos.c sfun_atmos_sub.obj
  

See matlabroot/simulink/src/sfuntmpl_fortran.txt and matlabroot/simulink/src/sfun_atmos.c for the latest information on compiling Fortran for C on Windows.

CFortran

Or you can try using CFortran to create an interface. CFortran is a tool for automated interface generation between C and Fortran modules, in either direction. Search the Web for cfortran or visit

• http://www-zeus.desy.de/~burow/cfortran/
  

for downloading.

Obtaining a Fortran Compiler

On Windows, using Visual C/C++ with Fortran is best done with Compaq Visual Fortran, Absoft, Lahey, or other third-party compilers. See Compaq (www.compaq.com) and Absoft (www.absoft.com) for Windows, Linux, and Sun compilers and see Lahey (www.lahey.com) for more choices in Windows Fortran compilers.

For Sun (Solaris) and other commercial UNIX platforms, you can purchase the computer vendor's Fortran compiler, a third-party Fortran such as Absoft, or even use the Gnu Fortran port for that platform (if available).

As long as the compiler can output the same object (.o) format as the platform's C compiler, the Fortran compiler will work with the gateway C-MEX S-function technique.

Gnu Fortran (g77) can be obtained free for several platforms from many download sites, including tap://www.redhat.com in the download area. A useful keyword on search engines is g77.

Inline Code Generation Example

Constructing the Gateway