The calling convention of a function defines how arguments and return values are passed, as well as any other requirements which callers and callees must respect, such as register preservation and stack alignment.
This data structure is used by the Zig language code generation and therefore must be kept in sync with the compiler implementation.
pub const CallingConvention = union(enum(u8))pub const CallingConvention = union(enum(u8)) {
pub const Tag = @typeInfo(CallingConvention).@"union".tag_type.?;
/// This is an alias for the default C calling convention for this target.
/// Functions marked as `extern` or `export` are given this calling convention by default.
pub const c = builtin.target.cCallingConvention().?;
pub const winapi: CallingConvention = switch (builtin.target.cpu.arch) {
.x86_64 => .{ .x86_64_win = .{} },
.x86 => .{ .x86_stdcall = .{} },
.aarch64 => .{ .aarch64_aapcs_win = .{} },
.thumb => .{ .arm_aapcs_vfp = .{} },
else => unreachable,
};
pub const kernel: CallingConvention = switch (builtin.target.cpu.arch) {
.amdgcn => .amdgcn_kernel,
.nvptx, .nvptx64 => .nvptx_kernel,
.spirv32, .spirv64 => .{ .spirv_kernel = .{ .x = 1, .y = 1, .z = 1 } },
else => unreachable,
};
/// The default Zig calling convention when neither `export` nor `inline` is specified.
/// This calling convention makes no guarantees about stack alignment, registers, etc.
/// It can only be used within this Zig compilation unit.
auto,
/// The calling convention of a function that can be called with `async` syntax. An `async` call
/// of a runtime-known function must target a function with this calling convention.
/// Comptime-known functions with other calling conventions may be coerced to this one.
async,
/// Functions with this calling convention have no prologue or epilogue, making the function
/// uncallable in regular Zig code. This can be useful when integrating with assembly.
naked,
/// This calling convention is exactly equivalent to using the `inline` keyword on a function
/// definition. This function will be semantically inlined by the Zig compiler at call sites.
/// Pointers to inline functions are comptime-only.
@"inline",
// Calling conventions for the `x86_64` architecture.
x86_64_sysv: CommonOptions,
x86_64_x32: CommonOptions,
x86_64_win: CommonOptions,
x86_64_regcall_v3_sysv: CommonOptions,
x86_64_regcall_v4_win: CommonOptions,
x86_64_vectorcall: CommonOptions,
x86_64_interrupt: CommonOptions,
// Calling conventions for the `x86` architecture.
x86_sysv: X86RegparmOptions,
x86_win: X86RegparmOptions,
x86_stdcall: X86RegparmOptions,
x86_fastcall: CommonOptions,
x86_thiscall: CommonOptions,
x86_thiscall_mingw: CommonOptions,
x86_regcall_v3: CommonOptions,
x86_regcall_v4_win: CommonOptions,
x86_vectorcall: CommonOptions,
x86_interrupt: CommonOptions,
// Calling conventions for the `x86_16` architecture.
x86_16_cdecl: CommonOptions,
x86_16_stdcall: CommonOptions,
x86_16_regparmcall: CommonOptions,
x86_16_interrupt: CommonOptions,
// Calling conventions for the `aarch64` and `aarch64_be` architectures.
aarch64_aapcs: CommonOptions,
aarch64_aapcs_darwin: CommonOptions,
aarch64_aapcs_win: CommonOptions,
aarch64_vfabi: CommonOptions,
aarch64_vfabi_sve: CommonOptions,
/// The standard `alpha` calling convention.
alpha_osf: CommonOptions,
// Calling convetions for the `arm`, `armeb`, `thumb`, and `thumbeb` architectures.
/// ARM Architecture Procedure Call Standard
arm_aapcs: CommonOptions,
/// ARM Architecture Procedure Call Standard Vector Floating-Point
arm_aapcs_vfp: CommonOptions,
arm_interrupt: ArmInterruptOptions,
// Calling conventions for the `mips64` and `mips64el` architectures.
mips64_n64: CommonOptions,
mips64_n32: CommonOptions,
mips64_interrupt: MipsInterruptOptions,
// Calling conventions for the `mips` and `mipsel` architectures.
mips_o32: CommonOptions,
mips_interrupt: MipsInterruptOptions,
// Calling conventions for the `riscv64` architecture.
riscv64_lp64: CommonOptions,
riscv64_lp64_v: CommonOptions,
riscv64_interrupt: RiscvInterruptOptions,
// Calling conventions for the `riscv32` architecture.
riscv32_ilp32: CommonOptions,
riscv32_ilp32_v: CommonOptions,
riscv32_interrupt: RiscvInterruptOptions,
// Calling conventions for the `sparc64` architecture.
sparc64_sysv: CommonOptions,
// Calling conventions for the `sparc` architecture.
sparc_sysv: CommonOptions,
// Calling conventions for the `powerpc64` and `powerpc64le` architectures.
powerpc64_elf: CommonOptions,
powerpc64_elf_altivec: CommonOptions,
powerpc64_elf_v2: CommonOptions,
// Calling conventions for the `powerpc` and `powerpcle` architectures.
powerpc_sysv: CommonOptions,
powerpc_sysv_altivec: CommonOptions,
powerpc_aix: CommonOptions,
powerpc_aix_altivec: CommonOptions,
/// The standard `wasm32` and `wasm64` calling convention, as specified in the WebAssembly Tool Conventions.
wasm_mvp: CommonOptions,
/// The standard `arc`/`arceb` calling convention.
arc_sysv: CommonOptions,
arc_interrupt: ArcInterruptOptions,
// Calling conventions for the `avr` architecture.
avr_gnu,
avr_builtin,
avr_signal,
avr_interrupt,
/// The standard `bpfel`/`bpfeb` calling convention.
bpf_std: CommonOptions,
// Calling conventions for the `csky` architecture.
csky_sysv: CommonOptions,
csky_interrupt: CommonOptions,
// Calling conventions for the `hexagon` architecture.
hexagon_sysv: CommonOptions,
hexagon_sysv_hvx: CommonOptions,
/// The standard `hppa` calling convention.
hppa_elf: CommonOptions,
/// The standard `hppa64` calling convention.
hppa64_elf: CommonOptions,
kvx_lp64: CommonOptions,
kvx_ilp32: CommonOptions,
/// The standard `lanai` calling convention.
lanai_sysv: CommonOptions,
/// The standard `loongarch64` calling convention.
loongarch64_lp64: CommonOptions,
/// The standard `loongarch32` calling convention.
loongarch32_ilp32: CommonOptions,
// Calling conventions for the `m68k` architecture.
m68k_sysv: CommonOptions,
m68k_gnu: CommonOptions,
m68k_rtd: CommonOptions,
m68k_interrupt: CommonOptions,
m88k_sysv: CommonOptions,
/// The standard `microblaze`/`microblazeel` calling convention.
microblaze_std: CommonOptions,
microblaze_interrupt: MicroblazeInterruptOptions,
/// The standard `msp430` calling convention.
msp430_eabi: CommonOptions,
msp430_interrupt: CommonOptions,
/// The standard `or1k` calling convention.
or1k_sysv: CommonOptions,
/// The standard `propeller` calling convention.
propeller_sysv: CommonOptions,
// Calling conventions for the `s390x` architecture.
s390x_sysv: CommonOptions,
s390x_sysv_vx: CommonOptions,
// Calling conventions for the `sh`/`sheb` architecture.
sh_gnu: CommonOptions,
sh_renesas: CommonOptions,
sh_interrupt: ShInterruptOptions,
/// The standard `ve` calling convention.
ve_sysv: CommonOptions,
// Calling conventions for the `xcore` architecture.
xcore_xs1: CommonOptions,
xcore_xs2: CommonOptions,
// Calling conventions for the `xtensa`/`xtensaeb` architecture.
xtensa_call0: CommonOptions,
xtensa_windowed: CommonOptions,
// Calling conventions for the `amdgcn` architecture.
amdgcn_device: CommonOptions,
amdgcn_kernel,
amdgcn_cs: CommonOptions,
// Calling conventions for the `nvptx` and `nvptx64` architectures.
nvptx_device,
nvptx_kernel,
// Calling conventions for kernels and shaders on the `spirv32` and `spirv64` architectures.
spirv_device,
spirv_vertex,
spirv_kernel: SpirvKernelOptions,
spirv_fragment: SpirvFragmentOptions,
spirv_task: SpirvKernelOptions,
spirv_mesh: SpirvMeshOptions,
// Calling conventions for the `ez80` architecture.
ez80_cet,
ez80_tiflags,
/// Options shared across most calling conventions.
pub const CommonOptions = struct {
/// The boundary the stack is aligned to when the function is called.
/// `null` means the default for this calling convention.
incoming_stack_alignment: ?u64 = null,
};
/// Options for x86 calling conventions which support the regparm attribute to pass some
/// arguments in registers.
pub const X86RegparmOptions = struct {
/// The boundary the stack is aligned to when the function is called.
/// `null` means the default for this calling convention.
incoming_stack_alignment: ?u64 = null,
/// The number of arguments to pass in registers before passing the remaining arguments
/// according to the calling convention.
/// Equivalent to `__attribute__((regparm(x)))` in Clang and GCC.
register_params: u2 = 0,
};
/// Options for the `arc_interrupt` calling convention.
pub const ArcInterruptOptions = struct {
/// The boundary the stack is aligned to when the function is called.
/// `null` means the default for this calling convention.
incoming_stack_alignment: ?u64 = null,
/// The kind of interrupt being received.
type: InterruptType,
pub const InterruptType = enum(u2) {
ilink1,
ilink2,
ilink,
firq,
};
};
/// Options for the `arm_interrupt` calling convention.
pub const ArmInterruptOptions = struct {
/// The boundary the stack is aligned to when the function is called.
/// `null` means the default for this calling convention.
incoming_stack_alignment: ?u64 = null,
/// The kind of interrupt being received.
type: InterruptType = .generic,
pub const InterruptType = enum(u3) {
generic,
irq,
fiq,
swi,
abort,
undef,
};
};
/// Options for the `microblaze_interrupt` calling convention.
pub const MicroblazeInterruptOptions = struct {
/// The boundary the stack is aligned to when the function is called.
/// `null` means the default for this calling convention.
incoming_stack_alignment: ?u64 = null,
type: InterruptType = .regular,
pub const InterruptType = enum(u2) {
/// User exception; return with `rtsd`.
user,
/// Regular interrupt; return with `rtid`.
regular,
/// Fast interrupt; return with `rtid`.
fast,
/// Software breakpoint; return with `rtbd`.
breakpoint,
};
};
/// Options for the `mips_interrupt` and `mips64_interrupt` calling conventions.
pub const MipsInterruptOptions = struct {
/// The boundary the stack is aligned to when the function is called.
/// `null` means the default for this calling convention.
incoming_stack_alignment: ?u64 = null,
/// The interrupt mode.
mode: InterruptMode = .eic,
pub const InterruptMode = enum(u4) {
eic,
sw0,
sw1,
hw0,
hw1,
hw2,
hw3,
hw4,
hw5,
};
};
/// Options for the `riscv32_interrupt` and `riscv64_interrupt` calling conventions.
pub const RiscvInterruptOptions = struct {
/// The boundary the stack is aligned to when the function is called.
/// `null` means the default for this calling convention.
incoming_stack_alignment: ?u64 = null,
/// The privilege mode.
mode: PrivilegeMode,
pub const PrivilegeMode = enum(u2) {
supervisor,
machine,
};
};
/// Options for the `sh_interrupt` calling convention.
pub const ShInterruptOptions = struct {
/// The boundary the stack is aligned to when the function is called.
/// `null` means the default for this calling convention.
incoming_stack_alignment: ?u64 = null,
save: SaveBehavior = .full,
pub const SaveBehavior = enum(u3) {
/// Save only fpscr (if applicable).
fpscr,
/// Save only high-numbered registers, i.e. r0 through r7 are *not* saved.
high,
/// Save all registers normally.
full,
/// Save all registers using the CPU's fast register bank.
bank,
};
};
pub const SpirvKernelOptions = struct {
x: u32,
y: u32,
z: u32,
};
pub const SpirvFragmentOptions = struct {
pub const DepthAssumption = enum(u2) {
none = 0,
greater = 1,
less = 2,
unchanged = 3,
};
pixel_centered_integer: bool = false,
depth_assumption: DepthAssumption = .none,
};
pub const SpirvMeshOptions = struct {
pub const StageOutput = enum(u2) {
output_points = 0,
output_lines = 1,
output_triangles = 2,
};
stage_output: StageOutput = .output_triangles,
max_primitives: u32 = 1,
max_vertices: u32 = 3,
};
/// Returns the array of `std.Target.Cpu.Arch` to which this `CallingConvention` applies.
/// Asserts that `cc` is not `.auto`, `.@"async"`, `.naked`, or `.@"inline"`.
pub fn archs(cc: CallingConvention) []const std.Target.Cpu.Arch {
return std.Target.Cpu.Arch.fromCallingConvention(cc);
}
pub fn eql(a: CallingConvention, b: CallingConvention) bool {
return std.meta.eql(a, b);
}
pub fn withStackAlign(cc: CallingConvention, incoming_stack_alignment: u64) CallingConvention {
const tag: CallingConvention.Tag = cc;
var result = cc;
@field(result, @tagName(tag)).incoming_stack_alignment = incoming_stack_alignment;
return result;
}
}