Documentation on the new 64 bit instructions

[Colin Paice]

I've been working on calling an assembler program from a 64 bit C program,
and have been struggling.Is there is a good guide on how to use these new
instructions?
For example1)
"You need to use a LLGTR R1... instruction to clear the register before
using a L R1... because without it the high part of the register will have
some 64 bit rubbish in it"

2)
I used

BAKR R14,0
PR
But it kept returning in 24 bit mode. It needs BSM 14,0 before the
BAKR.__

The POP tells you all about the instructions - but not how to use it. The
z/OS doc says use BACK/PR without mentioning the BSM.


Colin Paice

[Mike Hochee]

Hi Colin,

You may want to check out MVS Programming: Assembler Services Guide https://www-40.ibm.com/servers/resourcelink/svc00100.nsf/pages/zOSV2R3sa231368/$file/ieaa600_v2r3.pdf
And if you're running under LE, there will be a Language Environment pub or two that may provide some guidance.
While probably not specifically addressing your issue, John Ehrman's text 'Assembler Language Programming for IBM System z Servers V2' is quite an excellent reference regarding the instructions and usage... http://zseries.marist.edu/enterprisesystemseducation/assemblerlanguageresources/Assembler.V2.alntext%20V2.00.pdf

HTH,
Mike

-----Original Message-----
From: IBM Mainframe Assembler List <ASSEMBL...@LISTSERV.UGA.EDU> On Behalf Of Colin Paice
Sent: Tuesday, June 28, 2022 12:04 PM
To: ASSEMBL...@LISTSERV.UGA.EDU
Subject: Documentation on the new 64 bit instructions

Caution! This message was sent from outside your organization.

[Abe Kornelis]

Colin,

Maybe I'm preaching to the choir. If so, please ignore :-)

Please don't confuse using 64-bit registers with running in amode 64.
These are independent of one another.
When running in amode 31 or 24 you can still use the full set of
64-bit instructions available on your hardware.

Obviously, for modal instructions such as LA, the behaviour of the
instruction
will vary depending on the amode in effect at the time of execution.

Kind regards,
Abe Kornelis
==========

Op 28/06/2022 om 18:03 schreef Colin Paice:

[Peter Relson]

Not that BAKR is a "new 64 bit instruction" (neither "new" nor "64 bit"), but POp does tell you what you need to do to use the instruction by describing exactly how the instruction behaves. How you do what you need to do is your choice.

You made an unfounded assumption related to how PR works.

You don't "have" to do a BSM prior to the BAKR. And, in fact, in some cases it would be wrong to do so (the typical example is if your interface is invoked via BASSM). If you want the PR paired with a BAKR to return in AMODE 31 then the address saved must indicate AMODE 31. How you accomplish that is up to you.

Peter Relson
z/OS Core Technology Design

[Colin Paice]

Peter,
You are right .. BAKR is neither new nor 64 bit.

It seems I need the BSM because the C code does a BALR to my assembler
routine.
Someone told me

*BALR 14,15 in amode 64 just saves the updated PSW and doesn’t set any
addressing bits, so it is suitable for a straight BR 14 as the return
instruction. BAKR gets the amode bits to save in the stack entry from bit
32 and bit 63 of the input register, and the R14 loaded by BALR has both
off, so the stack entry is built for amode 24 return.*

Which is why I need the BSM.

I would be happy to do it differently, but I cant change the generated C
code.

regards

Colin

[Mike Hochee]

Here's another that seems relevant to what you're doing... https://share.confex.com/share/118/webprogram/Handout/Session10409/Trimodal%20Handout.pdf

-----Original Message-----
From: IBM Mainframe Assembler List <ASSEMBL...@LISTSERV.UGA.EDU> On Behalf Of Colin Paice
Sent: Tuesday, June 28, 2022 12:04 PM
To: ASSEMBL...@LISTSERV.UGA.EDU
Subject: Documentation on the new 64 bit instructions

Caution! This message was sent from outside your organization.

[Peter Relson]

For the case where you get control in the same AMODE as the caller (e.g., BALR, BASR, BRASL, etc), and you want to use BAKR/PR to save/restore registers, and your return address is in reg 14, then it is true that

BSM 14,0
BAKR 14,0

is the easiest way to set things up so that PR returns in the AMODE of the caller. There are other, long-winded, ways to accomplish this (that quite possibly no one uses).

The principles of operation is not, for the most part, a user's guide. It is a user's manual.

[Robert Raicer]

In response to the original post from:
Colin Paice <colin...@GMAIL.COM>
..................................................................
You might want to consider using a small "glue" code segment like
that shown below at start of your function.  The basic ideas are:

. The glue code is invoked by the caller in whatever addressing
  mode the caller chooses.  The general expectation is that the
  caller has done nothing to change the addressing mode when
  effecting the call.

. The glue code does not alter any GPR other than R15 which is used
  to contain a pure 64-bit address of the desired target code
  segment.

. The glue code uses BAKR to create a Linkage Stack entry with all
  of the callers GPRs (with the exception of GPR 15) and ARs as
  they were when the glue code was entered, and effect a transfer
  of control to the desired target function.

. The target function exits via PR which, among other things,
  restores GPRs 2-14 and ARs 2-14 from the Linkage stack.  This PR
  causes a transfer of control to the instruction immediately
  following the BAKR.

. The glue code returns control to caller in the addressing mode in
  effect at the time the glue code was entered.

There are always going to be unusual situations where this scheme
will need to be adjusted.  However, I believe that in the great
majority of situations (including yours) this will do the job
nicely.


         XGR   R15,R15                  * In combination these two
         LARL  R15,TARGET               * instructions place into
*                                       * GPR 15 a pure 64-bit
*                                       * address of the function
*                                       * to be invoked without
*                                       * needing to be aware of
*                                       * (or do anything
*                                       * explicitly related to)
*                                       * the current addressing
*                                       * mode.
*
         BAKR  0,R15                    Create a Linkage Stack
*                                       entry and invoke the target
*                                       function without changing
*                                       the addressing mode.
*
         BR    R14                      Return to the caller.
*
TARGET   DC    0D
*        :
*        : The code of the intended function being invoked
*        : by the original caller
*        :
         PR    ,                        Return to the "glue" code
*                                       segment with GPRs 2-14
*                                       and ARs 2-14 restored.
*
*                                       GPRs 0, 1 and 15 (and the
*                                       corresponding ARs) contain
*                                       whatever the target
*                                       function put into them.