W elcome to
Fintronic USA

redball.gif (326 bytes)About Fintronic USA

redball.gif (326 bytes)Main announcements

redball.gif (326 bytes)What's new at Fintronic

redball.gif (326 bytes)What our customers are saying...

redball.gif (326 bytes)Support for SystemC

redball.gif (326 bytes)Support for Verilog 2001

redball.gif (326 bytes)Third party tools integrated with FinSim(Specman, Denali, Debussy, Undertow, Vera, VirSim, HDL Score, Comet, Meteor, NelSim, Pivot, DeskPOD, @Designer 2.1)


User Defined Function, yprime, written in C and called from a FinSimMath module

This example runs on FinSim version 10_08_24 or higher. It shows how the user defined yprime function can be invoked in FinSimMath. An example how the same function is implemented as a MatLab Mex file can be found here.

To run the example one must:

1) Have the header file, which in this case is called lib_z.h

2) Have the FinSimMath file, which in this case is called z.v

3) Have the C file containing the implementation of the functions invoked in FinSimMath, which in this case is called lib_z.c.

4) Have the finpli.mak file containing information regarding which .o files are necesary

5) Invoke finvc with the proper options.

All this necessary information to run the example is presented below.

1. Header File

The header file in this example is called lib_z.h and is presented below:

The argument y, is the input arrray.

The argument t is unused and its purpose is to show that a real number can be passed as an argument.

The argument yp is the output. All the other arguments are generated automatically given the following invocation of finvc,

which is as follows:

    finvc +FM -ch lib_z.h +Insert_dimension_info +Insert_file_line b.v -a

2. FinSimMath Description

The file containing the FinSimMath code invoking the yprime function in this example is called z.v and is presented below:

 module top;
`include "finsimmath.h"
real Yp[1:4], Y[1:4], t;
initial begin
   t = 3.1415926;
   $InitM(Y, $I1);
   Yp = yprime(Y, t);

The arguments of C functions callable from FinSimMath can be real values (64 bits floating), characters (8 bits), short integers (16 bits), integers (32 bits), long integers (64 bits), pointers of the above mentioned types, and pointers of type simSIgnalPT corresponding to arrays (single or multi-dimensional) arguments passed to the FinSimMath call.

The formal arguments of C functions callable from FinSimMath are either corresponding to actual arguments that are going to be passed at invocation or to actual arguments that are being implicitly passed at invocation. For each actual argument that is an array there are a number of optional implicit arguments that are automatically inserted by the FinSimMath compiler just before the array.

The implicit optional arguments are generated by using + options: +Insert_dimension_info, +Insert_type_info, +Insert_view_info, +Insert_file_line.

The implicit arguments are:

a) number of original arguments (i.e. number of inputs plus 1, since there can be only one argument corresponding to the left hand side),

b) before each original argument the following implicit arguments are generated if the option +Insert_dimension_info is used.

i) number of dimensions

ii) for each dimension, the start index and the end index.

In case +Insert_type_info is used, the type of each original argument is provided as the first implicit argument associated to the given original argument. The type is of type int and provides the type of the array.

In case the +Insert_view_info is used, the view information of each original argument is inserted after the type information in case it exists and before the dimension related info. The view information is of type long and provides a pointer to the indirection table for the given "view as" construct.

The options to insert apply to all actual arguments that are arrays. In case some arrays do not have the arguments to insert (e.g. +Insert_view_info is used, but the array is not a view) the missing arguments to insert will contain the value zero.

C functions that return a value which is an array will have the output appended to the list of arguments and will be preceded by all the appropriate implicit arguments.

3. C File

The C code implementing the yprime function in this example is called lib_b.c and is presented below.

#include "stdio.h"
#include "math.h"
#include "finc.h"
simSignalPT yprime(long file, int line, int nrOrigArgs,
     int nrDim_y, int st1y, int end1y, simSignalPT y, double t,
     int nrDim_yp, int st1yp, int end1yp, simSignalPT yp)
  /* declaration of internal objects needed */
  int szy, szyp;
  double mu, mus, r1, r2, *YP, *Y;
  simSignalPT fileP;

  /* extract file pointer and line number from arguments provided */
  fileP = (simSignalPT) file;
  szy = (st1y > end1y) ? (st1y-end1y+1) : (end1y-st1y+1);
  szyp  = (st1yp > end1yp) ? (st1yp-end1yp+1) : (end1yp-st1yp+1);

  printf("unused parameter t = %lf\n", t);

  if ((szyp != szy) || (nrDim_y != 1) || 
      (nrDim_yp != 1) || (nrOrigArgs != 3))  {
    printf(" Error in file = %s, line = %d: yprime must return an array of the same size as the array passed as the first argument.\n", 
           fileP, line);

  Y = finAllocateAndReadReal(y, 1, szy);
  YP = (double *)calloc(szyp, sizeof(double));

  /* from array Y compute result */
  mu = 1/82.45;
  mus = 1-mu;
  r1 = sqrt((Y[0]+mu)*(Y[0]+mu)+ Y[2]*Y[2]);
  r2 = sqrt((Y[0]-mus)*(Y[0]-mus)+ Y[2]*Y[2]);
  if ((r1 == 0.0) || (r2 == 0.0)) {
    printf(" Error in file = %s, line = %d: divide by zero, yprime cannot be computed.\n", 
           fileP, line);
  YP[0] = Y[1];
  YP[1] = 2*Y[3]+Y[0]-mus*(Y[0]+mu)/(r1*r1*r1)-mu*(Y[0]-mus)/(r2*r2*r2);
  YP[2] = Y[3];
  YP[3] = -2*Y[1]+Y[2]-mus*Y[2]/(r1*r1*r1)-mu*Y[2]/(r2*r2*r2);

  finWriteReal(YP, yp, 1, szyp);


4. Object files

The object files corresponding to the user defined C functions can be specified either in the file finpli.mak in the variable FINUSERCOBJ:


or via the environment variable with the same name:

setenv FINUSERCOBJ lib_z.o

More than one object files can be specified. If used, the file finpli.mak has to be in the local directory where finbuild, the linker of the FinSimMath compiler, is called.

If the specified object file does not exist, finbuild will attempt to compile it using a default compilation rule that calls the C compiler on the corresponding .c file.

5. Invocation of finvc related to C code callable from FinSimMath

In FinSim, the header files providing the prototypes of the C functions are passed to the finvc compiler with the -ch option. This option can be specified any number of times if more than one header file is required. Note that the header files must be self-sufficient (as all well written header files ought to be),eader file should be included in the 1st header file. If any of the header files is in a different directory, the user can specify the include directory by using the +incdir option the same way as for Verilog header files.

The actual invocation of finvc for this example is:

finvc +FM -ch lib_z.h +Insert_dimension_info +Insert_file_line z.v.

Copyright 1999-2016, Fintronic USA, Inc. All rights reserved.

Copyright 1999-2021, Fintronic USA, Inc.   All rights reserved.