Compiler

Inline Assembly Statements

The __asm statement allows the introduction of embedded assembly code fragments among C source statements. Usiing these types of statements allows C programs invoke IBM MVS^™ system services directly via system-provided assembly macros. Full details of inline assembly statements can be found in: z/OS XL C/C++ Language Reference^©, Chapter 7. Statements.

The syntax of the __asm statement is:

	__asm ("assembler statement"
		: /* output definitions */
		: /* input definitions */
		: /* clobber list */
);

Example

The TIMEUSED macro returns an 8-byte integer in a doubleword storage area that you specify which represents a normalized time value used. The format of the number is time-of-day (TOD) clock or microseconds time format. The z/Architecture Principles of Operation states: The TOD clock nominally is incremented by adding a one in bit position 51 every microsecond. In models having a higher or lower resolution, a different bit position is incremented at such a frequency that the rate of advancing the clock is the same as if a one were added in bit position 51 every microsecond.

The following example invokes the macro from a C program, and returns the time used value.

#pragma export(timeUsed)                           
#include                                 
extern long long int timeUsed()                    
{                                                  
   long long unsigned int workTime;                
                                                   
   workTime = 0;                                   
                                                   
     __asm(" TIMEUSED STORADR=%0,ECT=YES"          
     : "=m"(workTime)  // output  definition       
     :                           // no input                 
     : "r15");         // clobber list             
                                                   
  return workTime;                                 
 }                                                                        
 

In this example, the "%0" is placeholder for what will be substituted by the compiler. The output definition tells the compiler to use the memory location to store the result. The clobber list specifies R15, because the TIMEUSED macro will return a return code in R15.

A portion of the Assembler code generated with the Metal option is shown below:

         USING @@LIT@1,3    
                                    
         LA    2,@3workTime 
                                   
* {                                                   
*    long long unsigned int workTime;                 
*                                                     
*    workTime = 0;                                    
         MVGHI @3workTime,0                           
*                                                     
*      __asm(" TIMEUSED STORADR=%0,ECT=YES"    
          
         TIMEUSED STORADR=0(2),ECT=YES 
                              
*      : "=m"(workTime)  // output  definition        
*      :                           // no input                  
*      : "r15");         // clobber list              
*                                                     
*   return workTime;                                  
         LG    0,@3workTime                           
         SRAG  15,0,32                                
*  }                                                  
@1L1     DS    0H                                                       		 
	  

The compiler inserts code that loads the address of the C work variable into R2, and also adds STORADR=0(2), as the address for the macro to store the result.

The syntax of the __asm statement is:

__asm [volatile] ( code_format_string ) : [output] : [input] : [clobbers] 

The parameters for the __asm statement include:

volatile

The qualifier volatile instructs the compiler to perform only minimal optimizations on the assembly block.

code_format_string

The code_format_string is the source text of the asm instructions and is a string literal similar to a printf format specifier.

output

The output consists of zero, one or more output operands, separated by commas. Each operand consists of a constraint(C_expression) pair. The output operand must be constrained by the = or + modifier.

input

The input consists of zero, one or more input operands, separated by commas. Each operand consists of a constraint (C_expression) pair.

clobbers

clobbers is a comma-separated list of register names enclosed in double quotes. If an asm instruction updates registers that are not listed in the input or output of the asm statement, the registers must be listed as clobbered registers. The following register names are valid: r0 or R0 to r15 or R15

Modifier

Modifier can be one of the following:

• = - Indicates that the operand is write-only for this instruction. The previous value is discarded and replaced by output data.
• + - Indicates that the operand is both read and written by the instruction.
• & - Indicates that the operand may be modified before the instruction is finished using the input operands; a register that is used as input should not be reused here.

Constraint

The constraint is a string literal that describes the kind of operand that is permitted, one character per constraint. The following constraints are supported:

• a - Use an address register (general purpose register except r0)
• d - Use a data register (equivalent to the r constraint)
• g - Use a general register, memory, or immediate operand.
• i - Use an immediate integer or string literal operand.
• m - Use a memory operand supported by the machine.
• n - Use an immediate integer.
• o - Use a memory operand that is offsetable.
• r - Use a general register.
• s - Use a string literal operand.
• 0, 1, 2, … - A matching constraint. Allocate the same register in output as in the corresponding input.
• I, J, K Constant values. Fold the expression in the operand and substitute the value into the % specifier.

C_expression

The C_expression is a C expression whose value is used as the operand for the asm instruction. Output operands must be modifiable lvalues. The C_expression must be consistent with the constraint specified on it. For example, if i is specified, the operand must be an integer constant number.

References

1. z/OS Metal C Programming Guide and Reference
2. z/OS XL C/C++ Language Reference

All references copyright^© IBM Corporation.