union CallingConvention [src]

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.

Fields

autoThe 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.

@"async"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.

nakedFunctions 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.

@"inline"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.

x86_64_sysv: 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

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

aarch64_aapcs: CommonOptions

aarch64_aapcs_darwin: CommonOptions

aarch64_aapcs_win: CommonOptions

aarch64_vfabi: CommonOptions

aarch64_vfabi_sve: CommonOptions

arm_aapcs: CommonOptionsARM Architecture Procedure Call Standard

arm_aapcs_vfp: CommonOptionsARM Architecture Procedure Call Standard Vector Floating-Point

arm_interrupt: ArmInterruptOptions

mips64_n64: CommonOptions

mips64_n32: CommonOptions

mips64_interrupt: MipsInterruptOptions

mips_o32: CommonOptions

mips_interrupt: MipsInterruptOptions

riscv64_lp64: CommonOptions

riscv64_lp64_v: CommonOptions

riscv64_interrupt: RiscvInterruptOptions

riscv32_ilp32: CommonOptions

riscv32_ilp32_v: CommonOptions

riscv32_interrupt: RiscvInterruptOptions

sparc64_sysv: CommonOptions

sparc_sysv: CommonOptions

powerpc64_elf: CommonOptions

powerpc64_elf_altivec: CommonOptions

powerpc64_elf_v2: CommonOptions

powerpc_sysv: CommonOptions

powerpc_sysv_altivec: CommonOptions

powerpc_aix: CommonOptions

powerpc_aix_altivec: CommonOptions

wasm_mvp: CommonOptionsThe standard wasm32 and wasm64 calling convention, as specified in the WebAssembly Tool Conventions.

arc_sysv: CommonOptionsThe standard arc calling convention.

avr_gnu

avr_builtin

avr_signal

avr_interrupt

bpf_std: CommonOptionsThe standard bpfel/bpfeb calling convention.

csky_sysv: CommonOptions

csky_interrupt: CommonOptions

hexagon_sysv: CommonOptions

hexagon_sysv_hvx: CommonOptions

lanai_sysv: CommonOptionsThe standard lanai calling convention.

loongarch64_lp64: CommonOptionsThe standard loongarch64 calling convention.

loongarch32_ilp32: CommonOptionsThe standard loongarch32 calling convention.

m68k_sysv: CommonOptions

m68k_gnu: CommonOptions

m68k_rtd: CommonOptions

m68k_interrupt: CommonOptions

msp430_eabi: CommonOptionsThe standard msp430 calling convention.

propeller_sysv: CommonOptionsThe standard propeller calling convention.

s390x_sysv: CommonOptions

s390x_sysv_vx: CommonOptions

ve_sysv: CommonOptionsThe standard ve calling convention.

xcore_xs1: CommonOptions

xcore_xs2: CommonOptions

xtensa_call0: CommonOptions

xtensa_windowed: CommonOptions

amdgcn_device: CommonOptions

amdgcn_kernel

amdgcn_cs: CommonOptions

nvptx_device

nvptx_kernel

spirv_device

spirv_kernel

spirv_fragment

spirv_vertex

Members

AAPCS (Constant)
AAPCSVFP (Constant)
archs (Function)
ArmInterruptOptions (struct)
Async (Constant)
c (Constant)
C (Constant)
CommonOptions (struct)
eql (Function)
Fastcall (Constant)
Fragment (Constant)
Inline (Constant)
Interrupt (Constant)
kernel (Constant)
Kernel (Constant)
MipsInterruptOptions (struct)
Naked (Constant)
RiscvInterruptOptions (struct)
Signal (Constant)
Stdcall (Constant)
SysV (Constant)
Tag (Constant)
Thiscall (Constant)
Unspecified (Constant)
Vectorcall (Constant)
Vertex (Constant)
Win64 (Constant)
winapi (Constant)
withStackAlign (Function)
X86RegparmOptions (struct)

Source

  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,
        .spirv, .spirv32, .spirv64 => .spirv_kernel,
        else => unreachable,
    };

    /// Deprecated; use `.auto`.
    pub const Unspecified: CallingConvention = .auto;
    /// Deprecated; use `.c`.
    pub const C: CallingConvention = .c;
    /// Deprecated; use `.naked`.
    pub const Naked: CallingConvention = .naked;
    /// Deprecated; use `.@"async"`.
    pub const Async: CallingConvention = .@"async";
    /// Deprecated; use `.@"inline"`.
    pub const Inline: CallingConvention = .@"inline";
    /// Deprecated; use `.x86_64_interrupt`, `.x86_interrupt`, or `.avr_interrupt`.
    pub const Interrupt: CallingConvention = switch (builtin.target.cpu.arch) {
        .x86_64 => .{ .x86_64_interrupt = .{} },
        .x86 => .{ .x86_interrupt = .{} },
        .avr => .avr_interrupt,
        else => unreachable,
    };
    /// Deprecated; use `.avr_signal`.
    pub const Signal: CallingConvention = .avr_signal;
    /// Deprecated; use `.x86_stdcall`.
    pub const Stdcall: CallingConvention = .{ .x86_stdcall = .{} };
    /// Deprecated; use `.x86_fastcall`.
    pub const Fastcall: CallingConvention = .{ .x86_fastcall = .{} };
    /// Deprecated; use `.x86_64_vectorcall`, `.x86_vectorcall`, or `aarch64_vfabi`.
    pub const Vectorcall: CallingConvention = switch (builtin.target.cpu.arch) {
        .x86_64 => .{ .x86_64_vectorcall = .{} },
        .x86 => .{ .x86_vectorcall = .{} },
        .aarch64, .aarch64_be => .{ .aarch64_vfabi = .{} },
        else => unreachable,
    };
    /// Deprecated; use `.x86_thiscall`.
    pub const Thiscall: CallingConvention = .{ .x86_thiscall = .{} };
    /// Deprecated; use `.arm_aapcs`.
    pub const AAPCS: CallingConvention = .{ .arm_aapcs = .{} };
    /// Deprecated; use `.arm_aapcs_vfp`.
    pub const AAPCSVFP: CallingConvention = .{ .arm_aapcs_vfp = .{} };
    /// Deprecated; use `.x86_64_sysv`.
    pub const SysV: CallingConvention = .{ .x86_64_sysv = .{} };
    /// Deprecated; use `.x86_64_win`.
    pub const Win64: CallingConvention = .{ .x86_64_win = .{} };
    /// Deprecated; use `.kernel`.
    pub const Kernel: CallingConvention = .kernel;
    /// Deprecated; use `.spirv_fragment`.
    pub const Fragment: CallingConvention = .spirv_fragment;
    /// Deprecated; use `.spirv_vertex`.
    pub const Vertex: CallingConvention = .spirv_vertex;

    /// 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_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 `aarch64` and `aarch64_be` architectures.
    aarch64_aapcs: CommonOptions,
    aarch64_aapcs_darwin: CommonOptions,
    aarch64_aapcs_win: CommonOptions,
    aarch64_vfabi: CommonOptions,
    aarch64_vfabi_sve: 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` calling convention.
    arc_sysv: CommonOptions,

    // 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 `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,

    /// The standard `msp430` calling convention.
    msp430_eabi: CommonOptions,

    /// The standard `propeller` calling convention.
    propeller_sysv: CommonOptions,

    // Calling conventions for the `s390x` architecture.
    s390x_sysv: CommonOptions,
    s390x_sysv_vx: CommonOptions,

    /// 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` 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 `spirv`, `spirv32`, and `spirv64` architectures.
    spirv_device,
    spirv_kernel,
    spirv_fragment,
    spirv_vertex,

    /// 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 `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 `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,
        };
    };

    /// 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;
    }
}  