Tag: assembler

Putting assembler code inside a C program

I was using a RACF service, and the documentation casually says “the application must free the returned storage”.

C does not provide facilities to use the STORAGE RELEASE z/OS service, so I had to write some assembler code to do this. It wasn’t difficult, I just fell over many little problems.

The IBM extension to the C language ASM is defined in the documentation.

I think of asm() as a special macro.

  • You pass in strings of assembler code. asm() will format it, and split the line if it would be longer than 72 characters.
  • If you want multiple lines you should end each line with \n (standard printf in C).
  • Lines starting with “*” are treated as comments, and produce no code
  • You can start your line with just one blank, before the instruction and it will be formatted as properly aligned assembler code, wrapping onto new lines if needed.
  • You do not use the C variable names in the assembler source.
    • You specified a mapping like [length] “m”(lDeletestorage), it takes the C variable lDeletestorage, determines its storage address such as it is offset 40 from register 5 (40(5)) and assigns this value to “length”
    • In the assembler code you specify ” L 2,%[length] \n” and it substitutes the value for %[length]. This instruction becomes ” L 2,40(5) “
    • At first glance it you would think it should be able to substitute the value directly, but you need to specify meta information about the field (is it used read only or read/write, is it a storage location, or a literal string). This is why there is this indirection
  • You need to specify which registers are modified so the C code can either save/restore their values, or just use different registers.

My code

if ( pDeletestorage != 0 )
{
  int freerc = 0;  
  #define ASM_PREFIX " SYSSTATE ARCHLVL=2 \n" 
  asm( 
     ASM_PREFIX 
     " L     2,%[length] \n"
     " L     4,%[a] \n"
     " STORAGE RELEASE,LENGTH=(2),ADDR=(4),COND=YES,RTCD=%[rc] "
     : [rc] "+m"(freerc) //* output
     : [length] "m"(lDeletestorage, 
       [a] "m"(pDeletestorage)
     :"r0", "r1" , "r2" , "r4" , "r15" ); 
  printf("Storage release rc %i\n",rc);
}
  • if ( pDeletestorage != 0 ) If there is a block of storage to release
  • {
  • int freerc = 0; define and preset the return code
  • #define ASM_PREFIX ” SYSSTATE ARCHLVL=2 \n” see below. The \n makes a new line
  • asm( generate the code
  • ASM_PREFIX insert the SYSTATE code
  • ” L 2,%[length] \n” Load register 2 with the value of the variable length defined below
  • ” L 4,%[a] \n” Load register 4 with the value of the variable a(ddress) defined below
  • ” STORAGE RELEASE,LENGTH=(2),ADDR=(4),COND=YES,RTCD=%[rc] “ issue the storage macro
  • : After the first : is a list of output variables
    • [rc] “+m”(freerc) //* output [rc] matches the name in the RTCD=%[rc]
      • “+” means Indicates that the operand is both read and written by the instruction
      • “m” is use a memory object – that is, a variable. Other options are literal values or registers.
      • (freerc) is the name of the C variable
  • : After the second : is a list of input variables
    • [length] “m”(lDeletestorage),
    • [a] “m”(pDeletestorage)
  • : After the third : is a list of register that are changed (clobbered)
    • “r0”, “r1” , “r2” , “r4” , “r15”
  • );
  • printf(“Storage release rc %i”,rc);
  • }

You have to pass the data to the macro using registers. You can either select registers yourself, or let the compiler pick them for you. See Using registers with my program as a more correct way of coding the program.

Note: If you pick the registers yourself, they may be unavailable if you compile it as a 64 bit program or as XPLINK, so using Using registers with my program is better.g

With the SYSSTATE ARCHLVL=2

This statement sets the minimum architecture to  z/Architecture (which includes Jump instructions).

The generated code was

* SYSSTATE ARCHLVL=2                                              
* THE VALUE OF SYSSTATE IS NOW SET TO ASCENV=P AMODE64=NO ARCHLVX01-SYSS 
*        L=2 OSREL=00000000 RMODE64=NO 
  L     2,1368(13)                                                 
  L     4,1364(13)  
                                               
  STORAGE RELEASE,LENGTH=(2),ADDR=(4),COND=YES,RTCD=1372(13)       
  LR     0,2                          .STORAGE LENGTH            
  LR     1,4                          .ADDRESS OF STORAGE        
  LHI    15,X'0001'                   .Add in parameters     
  L      14,16(0,0)                   .CVT ADDRESS                
  L      14,772(14,0)                 .ADDR SYST LINKAGE TABLE    
  L      14,204(14,0)                 .OBTAIN LX/EX FOR RELEASE  
  PC     0(14)                        .PC TO STORAGE RTN         
  ST     15,1372(13)                  .SAVE RETURN CODE

Where

  L     2,1368(13)       
  L     4,1364(13)

is loading the registers with the variable data from the C code,

and

  ST     15,1372(13)                  .SAVE RETURN CODE

saves the return code into the C variable.

Without the SYSSTATE ARCHLVL=2

The code failed to compile because of addressability issues.

         L     2,1368(13)                                              
         L     4,1364(13)                                              
         STORAGE RELEASE,LENGTH=(2),ADDR=(4),COND=YES,RTCD=1372(13)    
         CNOP   0,4                                                    
         B      IHB0001B                     .BRANCH AROUND DATA 
*** ASMA307E No active USING for operand IHB0001B       
IHB0001F DC     BL1'00000000'                                          
         DC     AL1(0*16)                    .KEY                      
         DC     AL1(0)                       .SUBPOOL                  
         DC     BL1'00000001'                .FLAGS                    
IHB0001B DS     0F                                                     
         LR     0,2                          .STORAGE LENGTH           
         LR     1,4                          .ADDRESS OF STORAGE       
         L      15,IHB0001F                  .CONTROL INFORMATION 
*** ASMA307E No active USING for operand IHB0001F 
         L      14,16(0,0)                   .CVT ADDRESS              
         L      14,772(14,0)                 .ADDR SYST LINKAGE TABLE  
         L      14,204(14,0)                 .OBTAIN LX/EX FOR RELEASE 
         PC     0(14)                        .PC TO STORAGE RTN        
         ST     15,1372(13)                  .SAVE RETURN CODE

In days of old you had base registers to locate data and instructions. Data reference was relative to (USING) a base register. Branching within a program used one or more base register. A re-entrant program would get dynamic storage, and this would be addressed by its own base register.

Modern instructions include the Jump instruction. This says jump this many half words to the instruction. These instructions do not need a base register.

With SYSSTATE ARCHLVL=2, the generated code for the C part of the program used the jump instructions, and did not need a base register. Assembler macros that generate code the old way, need a base register.

Using old instruction, to load a value into a register, it was loaded from storage – which needed a base register to locate the storage. For example

IHB0001F DC     BL1'00000000'                                          
         DC     AL1(0*16)                    .KEY                      
         DC     AL1(0)                       .SUBPOOL                  
         DC     BL1'00000001'                .FLAGS   
...
         L      15,IHB0001F                  .CONTROL INFORMATION

Modern instructions have the “constant” value as part of the instruction

 LHI    15,X'0001'

This effectively clears register 15 and loads the value 0x0001 into the bottom. (To be accurate it moves 0x0001 to the bottom half, then propagates the sign bit to the upper half word. The sign bit is 0.)

Using registers

The z/OS uses registers 14,15,0,1 for linkage, and these are likely to be used when using macros. Register 3 was used by the C code to locate storage, so I used registers 2 and 4.

Using variables

Reading the documentation, it seems I should be able to say 

 " STORAGE RELEASE,LENGTH=%[length],ADDR=(4),COND=YES,RTCD=%[rc] "
                : ...
                : [length] "m"(lDeletestorage), 
                  [a] "m"(pDeletestorage)
                :...

passing in a variable. This does not work, because C does not pass in “lDeletestorage”, but the offset and register.

For example the storage for variable lDeleteme is 1368 off register 13.

It can be used in a Load instruction

  L     2,1368(13)

But not every where. In the macro it get substituted.

STORAGE RELEASE,LENGTH=1368(13),ADDR=(4),COND=YES,RTCD=1372(13)
 L      0,=A(1368(13))               .STORAGE LENGTH  
*** ASMA035S Invalid delimiter - 1368(13)

Passing back the return code using RTCD=%[rc]. The macro checks to see if the value of RTCD is a register, if not then use the value in a store instruction.

Using registers

You can specify that you want to use a register, and the ASM() will pick registers for you.

 int res = 0x12345678;        
 int newRes = 55;
 __asm(" SR %[rx],%[rx]  clear \n"
       " SR %[rx],%[ry]  them  \n"  
       "  LR %[rx],%[ry] COLINS\n" 
              
       :  [rx]"=r"(res)   // output
       :  [ry]"r"(newRes) // input
      );

This generates code

     L        r4,newRes(,r13,1380) 
*     SR    2,2                     clear         
*     SR    2,4                     them          
*     LR    2,4                     COLINS        
      SR       r2,r2 
      SR       r2,r4 
      LR       r2,r4 
 
      LR       r0,r2 
      ST       r0,res(,r13,1376)

It has selected to use registers 2 and 4.

Where

  • L r4,newRes(,r13,1380) loads the input value into a register of its choice
  • *… these are comments of the coded instructions
  • SR.. LR.. are the generated instructions
  • LR r0,r2 , ST r0,res(,r13,1376) saves the variable defined as output back into C storage.
Using registers with my program

The compiler decides which registers to user ( r2 and r4). When I compiled this code as 64 bit (using option lp64) it used registers 6 and 7.

asm( ASM_PREFIX 
     " STORAGE RELEASE,LENGTH=(%[length]),ADDR=(%[a]),COND=YES,RTCD=%[rc] "
    : [rc] "+m"(freerc) //* output
    : [length]  "r"(lDeleteme), 
      [a] "r"(pDeleteme)
    :"r0", "r1" , "r15" );

This generates

 *          asm( 
            L        r2,lDeleteme(,r13,1368) 
            L        r4,pDeleteme(,r13,1364) 
         SYSSTATE ARCHLVL=2 

         STORAGE RELEASE,LENGTH=(2),ADDR=(4),COND=YES,RTCD=1372(13)     
         LR     0,2                          .STORAGE LENGTH            
         LR     1,4                          .ADDRESS OF STORAGE        
         LHI    15,X'0001'                   .Add in parameters    @PCA 
         L      14,16(0,0)                   .CVT ADDRESS               
         L      14,772(14,0)                 .ADDR SYST LINKAGE TABLE   
         L      14,204(14,0)                 .OBTAIN LX/EX FOR RELEASE  
         PC     0(14)                        .PC TO STORAGE RTN         
         ST     15,1372(13)                  .SAVE RETURN CODE

Using the different data types.

This is not explained very well in the documentation.

Using literal integer constants

The code 

asm( "LABEL LA     4,%[i] \n" 
     : 
     : [i] "i"(99)
     : "r4" );

Generates

 * LABEL    LA    4,99                    Colins             
             LA       r4,99

The label I specified on the instruction is not added to the created instruction.

Using literal string constants

Instead of using this capability, you could use C constants, and the “m” definition.

The code

asm( "LABEL LA     4,%[i] Colins \n" 
     : 
     : [i] "i"("ABCD")
     : "r4" );

Gives a compile error

10 LABEL    LA    4,ABCD                  Colins    
 *** ASMA044E Undefined symbol - ABCD

The code

asm("LABEL LA     4,%[i] Colins \n" 
                : 
                : [i] "i"("=C'ABCD'")
                : "r4" );

Generates

* LABEL    LA    4,=C'ABCD'              Colins          
           LA    r4,0(,r3)
... 
Start of ASM Literals 
000360  C1C2C3C4     =C'ABCD'

Using a memory operand that is offsetable (o)

The code

asm("LABEL LA     4,%[i] Colins \n" 
                    "LABEL2 LA    4,%[j] Colins2\n"
                : 
                : [i] "o"(res),
                 [j]  "m"(res)  
                : "r4" );

produced

* LABEL    LA    4,1376(13)              Colins      
* LABEL2   LA    4,1376(13)              Colins2     
               LA       r4,1376(r13,) 
               LA       r4,1376(r13,)

So it looks like the “o” operand is the same as specifying “m”.

64 bit programming

When you compile in 64 bit code (option lp64). The asm() works just as well It is better to use Using registers with my program so you do not have to guess which registers you can use.

My code

asm( ASM_PREFIX 
     " STORAGE RELEASE,LENGTH=(%[l]),ADDR=(%[a]),COND=YES,RTCD=%[rc] "
     : [rc] "+m"(freerc) //* output
     : [l]  "r"(lDeleteme), 
       [a] "r"(pDeleteme)
     :"r0", "r1" , "r15"
    );

Generated

    LLGF     r6,lDeleteme(,r4,3504) 
    LG       r7,pDeleteme(,r4,3496) 
    SYSSTATE ARCHLVL=2
...

Where the LLGF loads the 32 bit length variable into register 6, and LG loads the 64 bit address variable into register 7.

Compiling the code

I used the shell script

name=irrseq
export _C89_CCMODE=1 
p1="-Wc,arch(8),target(zOSV2R3),list,source,ilp32,gonum,asm,float(ieee)" 
p5="                           -I.                            " 


p7="-Wc,ASM,ASMLIB(//'SYS1.MACLIB') -Wa,LIST,RENT" 

p8="-Wc,LIST(c.lst),SOURCE,NOWARN64,XREF,SHOWINC " 
                                                                                                                   
xlc  $p1 $p5 $p7  $p8   -c $name.c -o $name.o 
                                                                                                                   
l1="-Wl,LIST,MAP,XREF       " 
/bin/xlc $name.o  -o irrseq  -V   $l1    1>a

The important line, p7, contains

  • -Wc,ASM,ASMLIB(//’SYS1.MACLIB’) C compile options
    • ASM Enables inlined assembly code inside C/C++ programs.
    • ASMLIB Specifies assembler macro libraries to be used when assembling the assembler source code.
  • -Wa,LIST,RENT” Assembler options
    • LIST Instructs the assembler to produce a listing
    • RENT Specifies that the assembler checks for possible coding violations of program reenterability. 

Getting into supervisor mode and other hard things in C, is easy.

Some functions in z/OS need a user to be in a privileged state such as key zero or supervisor state. Writing the code in assembler has been pretty easy, but writing it in a C program has been hard.

For example you could write a function in assembler, and call it. This has the cross language challenges.

I recently found an easy way – just reuse some code from Zowe. This is open source, so you need to follow the license

This program and the accompanying materials are made available under the terms of the Eclipse Public License v2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html

SPDX-License-Identifier: EPL-2.0

Copyright Contributors to the Zowe Project.

The code uses __asm() Inline assembly statements (IBM extension).

The functions are

  • ddnameExists
  • wtoMessage
  • wtoPrintf3
  • atomicIncrement compare and swap
  • testauth
  • extractPSW
  • supervisorMode or back to problem state
  • setKey
  • getExternalSecurityManager
  • getCVT
  • getATCVT
  • getIEACSTBL
  • getCVTPrefix
  • getECVT
  • getTCB
  • getSTCB
  • getOTCB
  • getASCB
  • getASXB
  • getASSB
  • getJSAB
  • getCurrentACEE
  • getFirstChildTCB
  • getParentTCB
  • getNextSiblingTCB
  • resolveSymbolBySyscall Input: A symbol starting with & and not ending with .
  • resolveSymbol Input: A symbol starting with & and not ending with .
  • lots of saf functions see here
  • loadByName
  • getDSAB Data Set Association Block
  • isCallerLocked
  • isCallerCrossMemory

Some of these need to be APF protected, so although it is easy to use the above code, you may still need to get the load library APF authorised, and the code approved.


For example

Get into supervisor state

The code here.

int supervisorMode(int enable){
// Use MODESET macro for requests
  int currentPSW = extractPSW();
  if (enable){
    if (currentPSW & PROBLEM_STATE){
      __asm(ASM_PREFIX
            " MODESET MODE=SUP \n"
            :
            :
            :"r0","r1","r15");
      return TRUE;
    } else{
      return FALSE;  /* do nothing, tell caller no restore needed */
    }
  } else{
    if (currentPSW & PROBLEM_STATE){
      return TRUE;   /* do nothing, tell user was in problem state */
    } else{
      __asm(ASM_PREFIX
            " MODESET MODE=PROB \n"
            :
            :
            :"r0","r1","r15");
      return FALSE;
    }
  }
}

To compile it I used

// SET LOADLIB=COLIN.LOAD 
//DOCLG       EXEC   PROC=EDCCB,INFILE='ADCD.C.SOURCE(C)', 
//            CPARM='OPTF(DD:COPTS)' 
//*           CPARM='LIST,SSCOMM,SOURCE,LANGLVL(EXTENDED)' 
//COMPILE.ASMLIB DD  DISP=SHR,DSN=SYS1.MACLIB 
//COMPILE.COPTS DD * 
LIST,SOURCE 
aggregate(offsethex) xref 
SEARCH(//'ADCD.C.H',//'SYS1.SIEAHDR.H') 
TEST 
ASM 
RENT ILP32        LO 
OE 
NOMARGINS EXPMAC   SHOWINC XREF 
LANGLVL(EXTENDED) sscom dll 
DEFINE(_ALL_SOURCE) 
DEBUG 
/* 
...

You need to specify

  • //COMPILE.ASMLIB for the the assembler macro libraries.
  • and the compiler option ASM which enables inlined assembly code inside C/C++ programs.

I was all so easy, once I had been told about it.