IPA link step control file

The IPA link step control file is a fixed-length or variable-length format file that contains additional IPA processing directives. The CONTROL suboption of the IPA compiler option identifies this file.

The IPA link step issues an error message if any of the following conditions exist in the control file:

The control file directives have invalid syntax.
There are no entries in the control file.
Duplicate names exist in the control file.

You can specify the following directives in the control file.

csect=csect_names_prefix

Supplies information that the IPA link step uses to name the CSECTs for each partition that it creates. The csect_names_prefix parameter is a comma-separated list of tokens that is used to construct CSECT names.

The behavior of the IPA link steps varies depending upon whether you specify the CSECT option with a qualifier.

If you do not specify the CSECT option with a qualifier, the IPA link step does the following:
- Truncates each name prefix or pads it at the end with @ symbols, if necessary, to create a 7 character token
- Uppercases the token
- Adds a suffix to specify the type of CSECT, as follows:
  C
  
  code
  
  S
  
  static data
  
  T
  
  test
If you specify the CSECT option with a non-null qualifier, the IPA link step does the following:
- Uppercases the token
- Adds a suffix to specify the type of CSECT, as follows where qualifier is the qualifier you specified for CSECT and nameprefix is the name you specified in the IPA link step Control File:
  qualifier#nameprefix#C
  
  code
  
  qualifier#nameprefix#S
  
  static data
  
  qualifier#nameprefix#T
  
  test
If you specify the CSECT option with a null qualifier, the IPA link step does the following:
- Uppercases the token
- Adds a suffix to specify the type of CSECT, as follows where nameprefix is the name you specified in the IPA link step Control File:
  nameprefix#C
  
  code
  
  nameprefix#S
  
  static data
  
  nameprefix#T
  
  test

The IPA link step issues an error message if you specify the CSECT option but no control file, or did not specify any csect directives in the control file. In this situation, IPA generates a CSECT name and an error message for each partition.

The IPA link step issues a warning or error message (depending upon the presence of the CSECT option) if you specify CSECT name prefixes, but the number of entries in the csect_names list is fewer than the number of partitions that IPA generated. In this situation, for each unnamed partition, the IPA link step generates a CSECT name prefix with format @CSnnnn, where nnnn is the partition number. If you specify the CSECT option, the IPA link step also generates an error message for each unnamed partition. Otherwise, the IPA link step generates a warning message for each unnamed partition.

noexports

Removes the "export" flag from all symbols (functions and variables) in IPA and non-IPA input files. When the METAL option is specified, the directive is not supported.

export=name[,name]

Specifies a list of symbols (functions and variables) to export by setting the symbol "export" flag. When the METAL option is specified, the directive is not supported. Note: Only symbols defined within IPA objects can be exported using this directive.

inline=name[,name]

Specifies a list of functions that are desirable for the compiler to inline. The functions may or may not be inlined.

inline=name[,name] from name[,name]

Specifies a list of functions that are desirable for the compiler to inline, if the functions are called from a particular function or list of functions. The functions may or may not be inlined.

noinline=name[,name]

Specifies a list of functions that the compiler will not inline.

noinline=name[,name] from name[,name]

Specifies a list of functions that the compiler will not inline, if the functions are called from a particular function or list of functions.

exits=name[,name]

Specifies names of functions that represent program exits. Program exits are calls that can never return, and can never call any procedure that was compiled with the IPA compile step.

lowfreq=name[,name]

Specifies names of functions that are expected to be called infrequently. These functions are typically error handling or trace functions.

partition=small|medium|large|unsigned-integer

Specifies the size of each program partition that the IPA link step creates. When partition sizes are large, it usually takes longer to complete the code generation, but the quality of the generated code is usually better.

For a finer degree of control, you can use an unsigned-integer value to specify the partition size. The integer is in ACUs (Abstract Code Units), and its meaning may change between releases. You should only use this integer for very short term tuning efforts, or when the number of partitions (and therefore the number of CSECTs in the output object module) must remain constant.

The size of a CSECT cannot exceed 16 MB with the XOBJ format. Large CSECTs require the GOFF option.

The default for this directive is medium.

partitionlist=partition_number[,partition_number]

Used to reduce the size of an IPA Link listing. If the IPA Link control file contains this directive and the LIST option is active, a pseudo-assembly listing is generated for only these partitions.

partition_number is a decimal number representing an unsigned int.

safe=name[,name]

Specifies a list of safe functions that are not compiled as IPA objects. These are functions that do not call a visible (not missing) function either through a direct call or a function pointer. Safe functions can modify global variables, but may not call functions that are not compiled as IPA objects.

isolated=name[,name]

Specifies a list of isolated functions that are not compiled as IPA objects. Neither isolated functions nor functions within their call chain can refer to global variables. IPA assumes that functions that are bound from shared libraries are isolated.

pure=name[,name]

Specifies a list of pure functions that are not compiled as IPA objects. These are functions that are safe and isolated and do not indirectly alter storage accessible to visible functions. A pure function has no observable internal state nor has side-effects, defined as potentially altering any data visible to the caller. This means that the returned value for a given invocation of a function is independent of any previous or future invocation of the function.

unknown=name[,name]

Specifies a list of unknown functions that are not compiled as IPA objects. These are functions that are not safe, isolated, or pure. This is the default for all functions defined within non-IPA objects. Any function specified as unknown can make calls to other parts of the program compiled as IPA objects and modify global variables and dummy arguments. This option greatly restricts the amount of interprocedural optimization for calls to unknown functions.

missing=attribute

Specifies the characteristics of missing functions. There are two types of missing functions:

Functions dynamically linked from another DLL (defined using an IPA Link IMPORT control statement)
Functions that are statically available but not compiled with the IPA option

IPA has no visibility to the code within these functions. You must ensure that all user references are resolved at IPA Link time with user libraries or runtime libraries.

The default setting for this directive is unknown. This instructs IPA to make pessimistic assumptions about the data that may be used and modified through a call to such a missing function, and about the functions that may be called indirectly through it.

You can specify the following attributes for this directive:

safe: Specifies that the missing functions are safe. See the description for the safe directive in this topic.
isolated: Specifies that the missing functions are isolated. See the description for the isolated directive in this topic.
pure: Specifies that the missing functions are pure. See the description for the pure directive in this topic.
unknown: Specifies that the missing functions are unknown. See the description for the unknown directive in this topic. This is the default attribute.

retain=symbol-list

Specifies a list of exported functions or variables that the IPA link step retains in the final object module. The IPA link step does not prune these functions or variables during optimization.

Note: In the listed directives, name can be a regular expression. Thus, name can match multiple symbols in your application through pattern matching. The regular expression syntax supported by the IPA control file processor is as follows:

Table 1. Syntax rules for specifying regular expressions
Expression	Description
string	Matches any of the characters specified in string. For example, `test` will match `testimony`, `latest`, and `intestine`.
^string	Matches the pattern specified by string only if it occurs at the beginning of a line.
string$	Matches the pattern specified by string only if it occurs at the end of a line.
str.ing	The period ( . ) matches any single character. For example, `t.st` will match `test`, `tast`, `tZst`, and `t1st`.
string\special_char	The backslash ( \ ) can be used to escape special characters. For example, assume that you want to find lines ending with a period. Simply specifying the expression `.$` would show all lines that had at least one character of any kind in it. Specifying `\.$` escapes the period ( . ), and treats it as an ordinary character for matching purposes.
[string]	Matches any of the characters specified in string. For example, `t[a-g123]st` matches tast and test, but not `t-st` or `tAst`.
[^string]	Does not match any of the characters specified in string. For example, `t[^a-zA-Z]` st matches `t1st`, `t-st`, and `t,st` but not `test` or `tYst`.
string*	Matches zero or more occurrences of the pattern specified by string. For example, `te*st` will match `tst`, `test`, and `teeeeeest`.
string+	Matches one or more occurrences of the pattern specified by string. For example, `t(es)+t` matches `test`, `tesest`, but not `tt`.
string?	Matches zero or one occurrences of the pattern specified by string. For example, `te?st` matches either `tst` or `test`.
string{m,n}	Matches between m and n occurrence(s) of the pattern specified by string. For example, `a{2}` matches `aa`, and `b{1,4}` matches `b`, `bb`, `bbb`, and `bbbb`.
string1 \| string2	Matches the pattern specified by either string1 or string2. For example, `s \| o` matches both characters `s` and `o`.