91 lines
3.0 KiB
Groff
91 lines
3.0 KiB
Groff
.TH GASM-ASM 1 "2026-09-19" "gasm" "User Commands"
|
|
.SH NAME
|
|
gasm-asm \- assemble Plan 9 assembly without the Go toolchain
|
|
.SH SYNOPSIS
|
|
.B gasm asm [\-\-format raw|elf|goobj] [\-I dir] [\-p pkg] [\-GOARCH arch] [\-GOOS os] [\-o out] <file>
|
|
.SH DESCRIPTION
|
|
Assemble FILE without the Go toolchain: every TEXT function is encoded
|
|
to machine code and printed as a hex dump. Supported architectures:
|
|
amd64 (including VEX/AVX2 and EVEX/AVX-512), arm64 (AArch64 integer,
|
|
FP, conditional select, CRC32 and MOV pseudo), riscv64 (RV64IMAFDC and
|
|
RVC) and loong64 (LoongArch base ISA).
|
|
.PP
|
|
With
|
|
.B \-o
|
|
the output is written to a file instead. The
|
|
.B \-\-format
|
|
flag selects what is written:
|
|
.B raw
|
|
(the default) concatenates the functions and the data section into one
|
|
self-consistent image;
|
|
.B elf
|
|
emits a relocatable object (.text/.data sections, a symbol table and
|
|
one relocation per static-symbol reference, in the architecture's own
|
|
form: R_X86_64_PC32 on amd64, R_AARCH64_*, R_RISCV_* or R_LARCH_* on the
|
|
others) that links with the
|
|
system toolchain;
|
|
.B goobj
|
|
emits the Go toolchain's own object format, which cmd/link consumes
|
|
directly (it requires
|
|
.BR \-p ,
|
|
the package path, and the installed Go toolchain: the object preamble is
|
|
captured from
|
|
.B go tool asm
|
|
and the format version from
|
|
.BR "go version" ).
|
|
.PP
|
|
.B raw
|
|
and
|
|
.B elf
|
|
need no toolchain at all.
|
|
.PP
|
|
Framed functions receive the stack-split guard and the trailing
|
|
morestack block, byte-identical to the toolchain's output, so split
|
|
functions link too.
|
|
.PP
|
|
A file that includes go_asm.h gets that header generated from the Go
|
|
files beside it, type-checked for the target.
|
|
.B \-GOOS
|
|
selects the type-checking GOOS for that header, because a GOOS-specific
|
|
file needs its platform's defines: sys_darwin_arm64.s fails against the
|
|
ambient GOOS (machTimebaseInfo_numer is missing from a linux type-check)
|
|
and assembles with
|
|
.BR "\-GOOS darwin" .
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-\-format \fIraw|elf|goobj\fR
|
|
Output format; the default is raw.
|
|
.TP
|
|
.B \-I \fIdir\fR
|
|
Directory to search for #include files; may be repeated, searched in
|
|
order after the source directory.
|
|
.TP
|
|
.B \-p \fIpkg\fR
|
|
Package path for --format goobj, qualifying the exported symbols.
|
|
.TP
|
|
.B \-GOARCH \fIarch\fR
|
|
Target architecture: amd64, arm64, riscv64 or loong64; overrides the
|
|
file-name suffix, which is how the suffix-less majority of GOROOT's
|
|
files (cpu_x86.s, stub.s, ...) become assemblable.
|
|
.TP
|
|
.B \-GOOS \fIos\fR
|
|
Operating system for the generated go_asm.h: any GOOS go/build
|
|
recognises in file names; the default is the host's.
|
|
.TP
|
|
.B \-o \fIfile\fR
|
|
Write the output to this file instead of a hex dump on stdout.
|
|
.SH EXIT STATUS
|
|
Exits 0 on success, 1 when parsing or assembly fails, and 2 on a usage
|
|
error.
|
|
.SH EXAMPLES
|
|
.nf
|
|
gasm asm \-o hello.bin hello_amd64.s raw image
|
|
gasm asm \-\-format elf \-o k.o k_amd64.s linkable ELF object
|
|
gasm asm \-\-format goobj \-p pkg/path \-o k.o k_amd64.s Go object for go build
|
|
gasm asm \-GOARCH amd64 cpu_x86.s arch override
|
|
.fi
|
|
.SH SEE ALSO
|
|
.BR gasm (1),
|
|
.BR gasm\-dis (1),
|
|
.BR gasm\-verify (1)
|