doc.go

Documentation: cmd/internal/obj/ppc64

     1  // Copyright 2019 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package ppc64 implements a PPC64 assembler that assembles Go asm into
     7  the corresponding PPC64 instructions as defined by the Power ISA 3.0B.
     8  
     9  This document provides information on how to write code in Go assembler
    10  for PPC64, focusing on the differences between Go and PPC64 assembly language.
    11  It assumes some knowledge of PPC64 assembler. The original implementation of
    12  PPC64 in Go defined many opcodes that are different from PPC64 opcodes, but
    13  updates to the Go assembly language used mnemonics that are mostly similar if not
    14  identical to the PPC64 mneumonics, such as VMX and VSX instructions. Not all detail
    15  is included here; refer to the Power ISA document if interested in more detail.
    16  
    17  Starting with Go 1.15 the Go objdump supports the -gnu option, which provides a
    18  side by side view of the Go assembler and the PPC64 assembler output. This is
    19  extremely helpful in determining what final PPC64 assembly is generated from the
    20  corresponding Go assembly.
    21  
    22  In the examples below, the Go assembly is on the left, PPC64 assembly on the right.
    23  
    24  1. Operand ordering
    25  
    26    In Go asm, the last operand (right) is the target operand, but with PPC64 asm,
    27    the first operand (left) is the target. The order of the remaining operands is
    28    not consistent: in general opcodes with 3 operands that perform math or logical
    29    operations have their operands in reverse order. Opcodes for vector instructions
    30    and those with more than 3 operands usually have operands in the same order except
    31    for the target operand, which is first in PPC64 asm and last in Go asm.
    32  
    33    Example:
    34      ADD R3, R4, R5		<=>	add r5, r4, r3
    35  
    36  2. Constant operands
    37  
    38    In Go asm, an operand that starts with '$' indicates a constant value. If the
    39    instruction using the constant has an immediate version of the opcode, then an
    40    immediate value is used with the opcode if possible.
    41  
    42    Example:
    43      ADD $1, R3, R4		<=> 	addi r4, r3, 1
    44  
    45  3. Opcodes setting condition codes
    46  
    47    In PPC64 asm, some instructions other than compares have variations that can set
    48    the condition code where meaningful. This is indicated by adding '.' to the end
    49    of the PPC64 instruction. In Go asm, these instructions have 'CC' at the end of
    50    the opcode. The possible settings of the condition code depend on the instruction.
    51    CR0 is the default for fixed-point instructions; CR1 for floating point; CR6 for
    52    vector instructions.
    53  
    54    Example:
    55      ANDCC R3, R4, R5		<=>	and. r5, r3, r4 (set CR0)
    56  
    57  4. Loads and stores from memory
    58  
    59    In Go asm, opcodes starting with 'MOV' indicate a load or store. When the target
    60    is a memory reference, then it is a store; when the target is a register and the
    61    source is a memory reference, then it is a load.
    62  
    63    MOV{B,H,W,D} variations identify the size as byte, halfword, word, doubleword.
    64  
    65    Adding 'Z' to the opcode for a load indicates zero extend; if omitted it is sign extend.
    66    Adding 'U' to a load or store indicates an update of the base register with the offset.
    67    Adding 'BR' to an opcode indicates byte-reversed load or store, or the order opposite
    68    of the expected endian order. If 'BR' is used then zero extend is assumed.
    69  
    70    Memory references n(Ra) indicate the address in Ra + n. When used with an update form
    71    of an opcode, the value in Ra is incremented by n.
    72  
    73    Memory references (Ra+Rb) or (Ra)(Rb) indicate the address Ra + Rb, used by indexed
    74    loads or stores. Both forms are accepted. When used with an update then the base register
    75    is updated by the value in the index register.
    76  
    77    Examples:
    78      MOVD (R3), R4		<=>	ld r4,0(r3)
    79      MOVW (R3), R4		<=>	lwa r4,0(r3)
    80      MOVWZU 4(R3), R4		<=>	lwzu r4,4(r3)
    81      MOVWZ (R3+R5), R4		<=>	lwzx r4,r3,r5
    82      MOVHZ  (R3), R4		<=>	lhz r4,0(r3)
    83      MOVHU 2(R3), R4		<=>	lhau r4,2(r3)
    84      MOVBZ (R3), R4		<=>	lbz r4,0(r3)
    85  
    86      MOVD R4,(R3)		<=>	std r4,0(r3)
    87      MOVW R4,(R3)		<=>	stw r4,0(r3)
    88      MOVW R4,(R3+R5)		<=>	stwx r4,r3,r5
    89      MOVWU R4,4(R3)		<=>	stwu r4,4(r3)
    90      MOVH R4,2(R3)		<=>	sth r4,2(r3)
    91      MOVBU R4,(R3)(R5)		<=>	stbux r4,r3,r5
    92  
    93  4. Compares
    94  
    95    When an instruction does a compare or other operation that might
    96    result in a condition code, then the resulting condition is set
    97    in a field of the condition register. The condition register consists
    98    of 8 4-bit fields named CR0 - CR7. When a compare instruction
    99    identifies a CR then the resulting condition is set in that field
   100    to be read by a later branch or isel instruction. Within these fields,
   101    bits are set to indicate less than, greater than, or equal conditions.
   102  
   103    Once an instruction sets a condition, then a subsequent branch, isel or
   104    other instruction can read the condition field and operate based on the
   105    bit settings.
   106  
   107    Examples:
   108      CMP R3, R4			<=>	cmp r3, r4	(CR0 assumed)
   109      CMP R3, R4, CR1		<=>	cmp cr1, r3, r4
   110  
   111    Note that the condition register is the target operand of compare opcodes, so
   112    the remaining operands are in the same order for Go asm and PPC64 asm.
   113    When CR0 is used then it is implicit and does not need to be specified.
   114  
   115  5. Branches
   116  
   117    Many branches are represented as a form of the BC instruction. There are
   118    other extended opcodes to make it easier to see what type of branch is being
   119    used.
   120  
   121    The following is a brief description of the BC instruction and its commonly
   122    used operands.
   123  
   124    BC op1, op2, op3
   125  
   126      op1: type of branch
   127          16 -> bctr (branch on ctr)
   128          12 -> bcr  (branch if cr bit is set)
   129          8  -> bcr+bctr (branch on ctr and cr values)
   130  	4  -> bcr != 0 (branch if specified cr bit is not set)
   131  
   132  	There are more combinations but these are the most common.
   133  
   134      op2: condition register field and condition bit
   135  
   136  	This contains an immediate value indicating which condition field
   137  	to read and what bits to test. Each field is 4 bits long with CR0
   138          at bit 0, CR1 at bit 4, etc. The value is computed as 4*CR+condition
   139          with these condition values:
   140  
   141          0 -> LT
   142          1 -> GT
   143          2 -> EQ
   144          3 -> OVG
   145  
   146  	Thus 0 means test CR0 for LT, 5 means CR1 for GT, 30 means CR7 for EQ.
   147  
   148      op3: branch target
   149  
   150    Examples:
   151  
   152      BC 12, 0, target		<=>	blt cr0, target
   153      BC 12, 2, target		<=>	beq cr0, target
   154      BC 12, 5, target		<=>	bgt cr1, target
   155      BC 12, 30, target		<=>	beq cr7, target
   156      BC 4, 6, target		<=>	bne cr1, target
   157      BC 4, 1, target		<=>	ble cr1, target
   158  
   159      The following extended opcodes are available for ease of use and readability:
   160  
   161      BNE CR2, target		<=>	bne cr2, target
   162      BEQ CR4, target		<=>	beq cr4, target
   163      BLT target			<=>	blt target (cr0 default)
   164      BGE CR7, target		<=>	bge cr7, target
   165  
   166    Refer to the ISA for more information on additional values for the BC instruction,
   167    how to handle OVG information, and much more.
   168  
   169  5. Align directive
   170  
   171    Starting with Go 1.12, Go asm supports the PCALIGN directive, which indicates
   172    that the next instruction should be aligned to the specified value. Currently
   173    8 and 16 are the only supported values, and a maximum of 2 NOPs will be added
   174    to align the code. That means in the case where the code is aligned to 4 but
   175    PCALIGN $16 is at that location, the code will only be aligned to 8 to avoid
   176    adding 3 NOPs.
   177  
   178    The purpose of this directive is to improve performance for cases like loops
   179    where better alignment (8 or 16 instead of 4) might be helpful. This directive
   180    exists in PPC64 assembler and is frequently used by PPC64 assembler writers.
   181  
   182    PCALIGN $16
   183    PCALIGN $8
   184  
   185    Functions in Go are aligned to 16 bytes, as is the case in all other compilers
   186    for PPC64.
   187  
   188  6. Shift instructions
   189  
   190    The simple scalar shifts on PPC64 expect a shift count that fits in 5 bits for
   191    32-bit values or 6 bit for 64-bit values. If the shift count is a constant value
   192    greater than the max then the assembler sets it to the max for that size (31 for
   193    32 bit values, 63 for 64 bit values). If the shift count is in a register, then
   194    only the low 5 or 6 bits of the register will be used as the shift count. The
   195    Go compiler will add appropriate code to compare the shift value to achieve the
   196    the correct result, and the assembler does not add extra checking.
   197  
   198    Examples:
   199  
   200      SRAD $8,R3,R4		=>	sradi r4,r3,8
   201      SRD $8,R3,R4		=>	rldicl r4,r3,56,8
   202      SLD $8,R3,R4		=>	rldicr r4,r3,8,55
   203      SRAW $16,R4,R5		=>	srawi r5,r4,16
   204      SRW $40,R4,R5		=>	rlwinm r5,r4,0,0,31
   205      SLW $12,R4,R5		=>	rlwinm r5,r4,12,0,19
   206  
   207    Some non-simple shifts have operands in the Go assembly which don't map directly
   208    onto operands in the PPC64 assembly. When an operand in a shift instruction in the
   209    Go assembly is a bit mask, that mask is represented as a start and end bit in the
   210    PPC64 assembly instead of a mask. See the ISA for more detail on these types of shifts.
   211    Here are a few examples:
   212  
   213      RLWMI $7,R3,$65535,R6 	=>	rlwimi r6,r3,7,16,31
   214      RLDMI $0,R4,$7,R6 		=>	rldimi r6,r4,0,61
   215  
   216    More recently, Go opcodes were added which map directly onto the PPC64 opcodes. It is
   217    recommended to use the newer opcodes to avoid confusion.
   218  
   219      RLDICL $0,R4,$15,R6		=>	rldicl r6,r4,0,15
   220      RLDICR $0,R4,$15,R6		=>	rldicr r6.r4,0,15
   221  
   222  Register naming
   223  
   224  1. Special register usage in Go asm
   225  
   226    The following registers should not be modified by user Go assembler code.
   227  
   228    R0: Go code expects this register to contain the value 0.
   229    R1: Stack pointer
   230    R2: TOC pointer when compiled with -shared or -dynlink (a.k.a position independent code)
   231    R13: TLS pointer
   232    R30: g (goroutine)
   233  
   234    Register names:
   235  
   236    Rn is used for general purpose registers. (0-31)
   237    Fn is used for floating point registers. (0-31)
   238    Vn is used for vector registers. Slot 0 of Vn overlaps with Fn. (0-31)
   239    VSn is used for vector-scalar registers. V0-V31 overlap with VS32-VS63. (0-63)
   240    CTR represents the count register.
   241    LR represents the link register.
   242  
   243  */
   244  package ppc64
   245
View as plain text