An Arch defines how to generate assembly for a specific architecture. // build tag // whether loops preserve carry flag across iterations // name of architecture // length of word in bits (32 or 64) // length of word in bytes (4 or 8) HasShiftWide reports whether the Arch has working LshWide/RshWide instructions.
If not, calling them will panic.
func NewAsm(arch *Arch) *Asm
var Arch386 *Arch
var ArchAMD64 *Arch
var ArchARM *Arch
var ArchARM64 *Arch
var ArchLoong64 *Arch
var ArchMIPS *Arch
var ArchMIPS64x *Arch
var ArchPPC64x *Arch
var ArchRISCV64 *Arch
var ArchS390X *Arch
An Asm is an assembly file being written. // architecture Add emits dst = src1+src2, with the specified carry behavior. AddWords emits dst = src1*WordBytes + src2.
It does not set or use the carry flag. AltCarry returns the secondary carry register, or else the zero Reg. And emits dst = src1 & src2
It may modify the carry flag. Carry returns the carry register, or else the zero Reg. ClearCarry clears the carry flag.
The ‘which’ parameter must be AddCarry or SubCarry to specify how the flag will be used.
(On some systems, the sub carry's actual processor bit is inverted from its usual value.) Comment emits a line comment to the assembly output. ConvertCarry converts the carry flag in dst from the internal format to a 0 or 1.
The carry flag is left in an undefined state. EOL appends an end-of-line comment to the previous line. Enabled reports whether the optional CPU feature is considered
to be enabled at this point in the assembly output. Fatalf reports a fatal error by panicking.
Panicking is appropriate because there is a bug in the generator,
and panicking will show the exact source lines leading to that bug. Free frees a previously allocated register.
If r is not a register (if it's an immediate or a memory reference), Free is a no-op. FreeAll frees all known registers. Func starts a new function in the assembly output. HasRegShift reports whether the architecture can use shift expressions as operands. Imm returns a Reg representing an immediate (constant) value. IsZero reports whether r is a zero immediate or the zero register. Jmp jumps to the label. JmpEnable emits a test for the optional CPU feature that jumps to label if the feature is present.
If JmpEnable returns false, the feature is not available on this architecture and no code was emitted. JmpNonZero jumps to the label if src is non-zero.
It may modify the carry flag unless a.Arch,CarrySafeLoop is true. JmpZero jumps to the label if src is zero.
It may modify the carry flag unless a.Arch.CarrySafeLoop is true. Label emits a label with the given name. Lsh emits dst = src << shift.
It may modify the carry flag. LshReg returns a shift-expression operand src<<shift.
If a.HasRegShift() == false, LshReg panics. LshWide emits dst = src << shift with low bits shifted from adj.
It may modify the carry flag. Mov emits dst = src. MulWide emits dstlo = src1 * src2 and dsthi = (src1 * src2) >> WordBits.
The carry flag is left in an undefined state.
If dstlo or dsthi is the zero Reg, then those outputs are discarded. Neg emits dst = -src.
It may modify the carry flag. Or emits dst = src1 | src2
It may modify the carry flag. Printf emits to the assembly output. Reg allocates a new register. RegHint allocates a new register, with a hint as to its purpose. RegsUsed returns a snapshot of which registers are currently allocated,
which can be passed to a future call to [Asm.SetRegsUsed]. RestoreCarry restores the carry flag from src.
src is left in an undefined state. Ret returns. Rsh emits dst = src >> shift.
It may modify the carry flag. RshReg returns a shift-expression operand src>>shift.
If a.HasRegShift() == false, RshReg panics. RshWide emits dst = src >> shift with high bits shifted from adj.
It may modify the carry flag. SLTU emits dst = src2 < src1 (0 or 1), using an unsigned comparison. SaveCarry saves the carry flag into dst.
The meaning of the bits in dst is architecture-dependent.
The carry flag is left in an undefined state. SaveConvertCarry saves and converts the carry flag into dst: 0 unset, 1 set.
The carry flag is left in an undefined state. SetOption changes whether the optional CPU feature should be
considered to be enabled. SetRegsUsed sets which registers are currently allocated.
The argument should have been returned from a previous
call to [Asm.RegsUsed]. Sub emits dst = src2-src1, with the specified carry behavior. Unfree reallocates a previously freed register r.
If r is not a register (if it's an immediate or a memory reference), Unfree is a no-op.
If r is not free for allocation, Unfree panics.
A Free paired with Unfree can release a register for use temporarily
but then reclaim it, such as at the end of a loop body when it must be restored. Xor emits dst = src1 ^ src2
It may modify the carry flag. ZR returns the zero register (the specific register guaranteed to hold the integer 0),
or else the zero Reg (Reg{}, which has r.Valid() == false).
func NewAsm(arch *Arch) *Asm
A Carry is a flag field explaining how an instruction sets and uses the carry flags.
Different operations expect different sets of bits.
Add and Sub expect: UseCarry or 0, SetCarry, KeepCarry, or SmashCarry; and AltCarry or 0.
ClearCarry, SaveCarry, and ConvertCarry expect: AddCarry or SubCarry; and AltCarry or 0.
func (*Asm).Add(src1, src2, dst Reg, carry Carry)
func (*Asm).ClearCarry(which Carry)
func (*Asm).ConvertCarry(which Carry, dst Reg)
func (*Asm).SaveConvertCarry(which Carry, dst Reg)
func (*Asm).Sub(src1, src2, dst Reg, carry Carry)
const AddCarry
const AltCarry
const KeepCarry
const SetCarry
const SmashCarry
const SubCarry
const UseCarry
A Func represents a single assembly function.Asm*AsmNamestring Arg allocates a new register, copies the named argument (or result) into it,
and returns that register. ArgHint is like Arg but uses a register allocation hint. ArgPtr is like Arg but returns a RegPtr. Pipe creates and returns a new pipe for use in the function f. StoreArg stores src into the named argument (or result).
func (*Asm).Func(decl string) *Func
A Pipe manages the input and output data pipelines for a function's
memory operations.
The input is one or more equal-length slices of words, so collectively
it can be viewed as a matrix, in which each slice is a row and each column
is a set of corresponding words from the different slices.
The output can be viewed the same way, although it is often just one row. AtUnrollEnd sets a function to call at the end of an unrolled sequence.
See [Pipe.Loop] for details. AtUnrollStart sets a function to call at the start of an unrolled sequence.
See [Pipe.Loop] for details. Done frees all the registers allocated by the pipe. DropInput deletes the named input from the pipe,
usually because it has been exhausted.
(This is not used yet but will be used in a future generator.) LoadN returns the next n columns of input words as a slice of rows.
Regs for inputs that have been marked using p.SetMemOK will be direct memory references.
Regs for other inputs will be newly allocated registers and must be freed. LoadPtrs loads the slice pointer arguments into registers,
assuming that the slice length n has already been loaded
into the register n.
Start will call LoadPtrs if it has not been called already.
LoadPtrs only needs to be called explicitly when code needs
to use LoadN before Start, like when the shift.go generators
read an initial word before the loop. Loop emits code for the loop, calling block repeatedly to emit code that
handles a block of N input columns (for arbitrary N = len(in[0]) chosen by p).
block must call p.StoreN(out) to write N output columns.
The out slice is a pre-allocated matrix of uninitialized Reg values.
block is expected to set each entry to the Reg that should be written
before calling p.StoreN(out).
For example, if the loop is to be unrolled 4x in blocks of 2 columns each,
the sequence of calls to emit the unrolled loop body is:
start() // set by pAtUnrollStart
... reads for 2 columns ...
block()
... writes for 2 columns ...
... reads for 2 columns ...
block()
... writes for 2 columns ...
end() // set by p.AtUnrollEnd
Any registers allocated during block are freed automatically when block returns. Restart prepares to loop over an additional n columns,
beyond a previous loop run by p.Start/p.Loop. SetBackward sets the pipe to process the input and output columns in reverse order.
This is needed for left shifts, which might otherwise overwrite data they will read later. SetHint records that the inputs from the named vector
should be allocated with the given register hint.
If the hint indicates a single register on the target architecture,
then SetHint calls SetMaxColumns(1), since the hinted register
can only be used for one value at a time. SetLabel sets the label prefix for the loops emitted by the pipe.
The default prefix is "loop". SetMaxColumns sets the maximum number of
columns processed in a single loop body call. SetUseIndexCounter sets the pipe to use an index counter if possible,
meaning the loop counter is also used as an index for accessing the slice data.
This clever trick is slower on modern processors, but it is still necessary on 386.
On non-386 systems, SetUseIndexCounter is a no-op. Start prepares to loop over n columns.
The factors give a sequence of unrolling factors to use,
which must be either strictly increasing or strictly decreasing
and must include 1.
For example, 4, 1 means to process 4 elements at a time
and then 1 at a time for the final 0-3; specifying 1,4 instead
handles 0-3 elements first and then 4 at a time.
Similarly, 32, 4, 1 means to process 32 at a time,
then 4 at a time, then 1 at a time.
One benefit of using 1, 4 instead of 4, 1 is that the body
processing 4 at a time needs more registers, and if it is
the final body, the register holding the fragment count (0-3)
has been freed and is available for use.
Start may modify the carry flag.
Start must be followed by a call to Loop1 or LoopN,
but it is permitted to emit other instructions first,
for example to set an initial carry flag. StoreN writes regs (a slice of rows) to the next n columns of output, where n = len(regs[0]).
func (*Func).Pipe() *Pipe
A Reg is an allocated register or other assembly operand.
(For example, a constant might have name "$123"
and a memory reference might have name "0(R8)".) IsImm reports whether r is an immediate value. IsMem reports whether r is a memory value. String returns the assembly syntax for r. Valid reports whether is valid, meaning r is not the zero value of Reg (a register with no name).
Reg : expvar.Var
Reg : fmt.Stringer
func (*Asm).AltCarry() Reg
func (*Asm).Carry() Reg
func (*Asm).Imm(x int) Reg
func (*Asm).LshReg(shift, src Reg) Reg
func (*Asm).Reg() Reg
func (*Asm).RegHint(hint Hint) Reg
func (*Asm).RshReg(shift, src Reg) Reg
func (*Asm).ZR() Reg
func (*Func).Arg(name string) Reg
func (*Func).ArgHint(name string, hint Hint) Reg
func (*Pipe).LoadN(n int) [][]Reg
func (*Asm).Add(src1, src2, dst Reg, carry Carry)
func (*Asm).AddWords(src1 Reg, src2, dst RegPtr)
func (*Asm).And(src1, src2, dst Reg)
func (*Asm).ConvertCarry(which Carry, dst Reg)
func (*Asm).Free(r Reg)
func (*Asm).IsZero(r Reg) bool
func (*Asm).JmpNonZero(src Reg, label string)
func (*Asm).JmpZero(src Reg, label string)
func (*Asm).Lsh(shift, src, dst Reg)
func (*Asm).LshReg(shift, src Reg) Reg
func (*Asm).LshWide(shift, adj, src, dst Reg)
func (*Asm).Mov(src, dst Reg)
func (*Asm).MulWide(src1, src2, dstlo, dsthi Reg)
func (*Asm).Neg(src, dst Reg)
func (*Asm).Or(src1, src2, dst Reg)
func (*Asm).RestoreCarry(src Reg)
func (*Asm).Rsh(shift, src, dst Reg)
func (*Asm).RshReg(shift, src Reg) Reg
func (*Asm).RshWide(shift, adj, src, dst Reg)
func (*Asm).SaveCarry(dst Reg)
func (*Asm).SaveConvertCarry(which Carry, dst Reg)
func (*Asm).SLTU(src1, src2, dst Reg)
func (*Asm).Sub(src1, src2, dst Reg, carry Carry)
func (*Asm).Unfree(r Reg)
func (*Asm).Xor(src1, src2, dst Reg)
func (*Func).StoreArg(src Reg, name string)
func (*Pipe).LoadPtrs(n Reg)
func (*Pipe).Restart(n Reg, factors ...int)
func (*Pipe).Start(n Reg, factors ...int)
func (*Pipe).StoreN(regs [][]Reg)
A RegPtr is like a Reg but expected to hold a pointer.
The separate Go type helps keeps pointers and scalars separate and avoid mistakes;
it is okay to convert to Reg as needed to use specific routines. String returns the assembly syntax for r. Valid reports whether is valid, meaning r is not the zero value of RegPtr (a register with no name).
RegPtr : expvar.Var
RegPtr : fmt.Stringer
func (*Func).ArgPtr(name string) RegPtr
func (*Asm).AddWords(src1 Reg, src2, dst RegPtr)
A RegsUsed is a snapshot of which registers are allocated.
func (*Asm).RegsUsed() RegsUsed
func (*Asm).SetRegsUsed(used RegsUsed)
Package-Level Functions (only one)
NewAsm returns a new Asm preparing assembly
for the given architecture to be written to file.
OptionAltCarry checks whether there is an add instruction
that uses a secondary carry flag, so that two different sums
can be accumulated in parallel with independent carry flags.
Some architectures (MIPS, Loong64, RISC-V) provide this
functionality natively, indicated by asm.Carry().Valid() being true.
The pages are generated with Goldsv0.7.7-preview. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
