$AutoMap$

How to use AutoMap in your source code

This is related to the use of AutoMap and AutoLink v3.00
The following file will explain how to use AutoMap generated files for complex MPI data-types generation, and how to generate those files.

Warning :AutoMap is only designed to generate data-types out of their C definition (to use with MPI). To work with data-types containing pointers, AutoLink, an MPI solution is available, as an extension to AutoMap, from the MPI data-type tools home page.

1) Create output files

1.1) Preparing structure file

1.1.1) Rules

To prepare the structure file to be processed by AutoMap, a few rules are to be explained :

a begin mark /*~ AM_Begin */ must be placed before the type definitions.
an end mark /*~ AM_End */ must be inserted after the type definitions.
each type that the user want to recognize must have /*~ AM */ after the typedef declaration, and before the last semi-colon (;) of the line.
each type referred to does not have to be AutoMap marked to be processed. If type A uses type B, but user only want know about type A, it is not necessary to AutoMap mark type B; both type will be created.
Warning : AutoMap does not work with struct alone, all types must be used as typedef struct.

1.1.2) Example

The following lines are a very simple example of a possible use of AutoMap to generate AutoMap (MPI data-types) output files.
Let's call the following file for future references "struct.h"

/*~ AM_Begin */

typedef struct {
  int class;
  double d[6];
  char b[7];
  int c[8];
} Partstruct /*~ AM */;

/*~ AM_End */

1.2) Running AutoMap

1.2.1) Concept

You must run AutoMap in the directory where you want the output files to be generated.
To run AutoMap, if it is in your path, simply type the name or your AutoMap executable, otherwise put the full pathname to it, and the name of the executable.
AutoMap options are :

AutoMap [-help] [-v] [-log] [-noAL] filename
        -help : Will print this help menu
        -v    : Verbose mode
        -log  : Will generate the "logbook.txt" for this run
        -noAL : Will not generate the entries for use with AutoLink
        filename : name of the C typedef definition file to analyze

Since we do not want to generate AutoLink output files, we have to use the "no AutoLink" (-noAL) option.
When using AutoMap, you may want to have a look at the log file (logbook.txt) that AutoMap generates when asked to (-log option); but this is for users who want to understand to the lowest level how AutoMap works. For other users, should they want to follow the processing of AutoMap, it is easy to run it in "verbose" (-v option) mode, so that you can see if all the data-types you expected are generated.
In the generated code, it is possible to work a Padding correction option, that will change the way MPI data-types are generated. This option is only useful should you encounter some problem with MPI C data-types padding (as we encounter in earlier versions of SGI MPI and MPICH), and is usable by defining AM_PC in your compilation.
The filename is the name of the file containing the data-types to be AutoMap created, formatted as defined in section 1.1.

1.2.2) Example

We run AutoMap on the file "struct.h" defined previously, in verbose mode :

AutoMap -v -log -noAL struct.h

, gives us :

Information on this run : 
 - Will not generate AutoLink output files
 - Will process file : struct.h
Creating AutoMap log file ... done
Creating the AST ... done
Updating the AST ... done
Writing mpitypes.inc (& mpitypes.h) ... done
--> Generated output for :
----> Partstruct (userType)
--> done
Cleaning the AST ... done
Closing log file ... done
AutoMap finished without error

Output files can be found in current directory.
AutoMap remarks can be found in the logbook file.
0 Errors, 0 Warnings, Highest Severity 0

, telling us that output for data-type Partstruct has been generated,for their MPI type creation.
The file generated are :

mpitypes.inc : contains the function required to create the MPI data-types.
mpitypes.h : to define functions and types prototypes.
logbook.txt : to store the generation log (only generated because of the -log option).

2) Use of Output files in user code

2.1) Edit user code

2.1.1) Concept

To use AutoMap, you should have the following files :

mpitypes.inc
mpitypes.h

, also the user code (here called userprog.c) and the type definition file (here struct.h).
The following pictures explains mostly the use of those files :

To be able to use AutoMap, in your main code, please, include in the following order the following files :

mpi.h
struct.h
mpitypes.inc

In any deported code that should use AutoMap defined types, include in the following order (* means that it is not always required)

mpi.h (*)
struct.h (*)
mpitypes.h

2.1.2) Example

If the main code definition is done in userprog.c:

#include <mpi.h>
#include "struct.h"
#include "mpitypes.inc"

, will make AutoMap data-types available to user code.

2.2) Use of AutoMap functions

In AutoMap, the user is able to send complex data-types in the same way as standard MPI data-types, provided the user follow some simple rules.
At the beginning of the main program, the user will have to initialize the new MPI data-types by calling the function Build_MPI_Types() (defined in the generated file mpitypes.inc), after a call to MPI_Init.
The actual name of each generated MPI data-type to use for comamnds such as MPI_Send or MPI_Recv, is made up of the initial name as written in the struct.h file, to which the prefix AM_ is added (in the case of our example AM_Partstruct).
Before finishing the MPI program by calling MPI_Finalize, it is wise to properly free MPI generated types (created by AutoMap) by calling the AutoMap provided function Free_MPI_Types().

2.3) Example suites

Provided with AutoMap are some tests suites. Please refer to the README file of your AutoMap distribution.
You may also want to check the am.example.c file for more typdef examples.

3) Troubleshooting

Please check the following :

You did not forget the begin (/*~ AM_Begin */) and end (/*~ AM_End */) marker, before and after the type definitions.
You did use the AutoMap type marker (/*~ AM */) on the type you desire to work with.
You did not use the AutoMap type marker on a struct alone.
You used the proper options when launching AutoMap
You included the proper file.
You used AutoMap function.

Should you encounter another problem, please send your struct.h file and a -log mode for AutoMap. Add to it your type definition file, command lines, and a small example of how you use AutoMap and AutoLink to martial.michel@nist.gov with [AMpb] in the subject.

Page created : 1997
Last update : 26 Oct 2001
By : SAVG