1//! Types and values provided by the Zig language.
2
3const builtin = @import("builtin");
4const std = @import("std.zig");
5const root = @import("root");
6
7pub const assembly = @import("lang/assembly.zig");
8
9/// This data structure is used by the Zig language code generation and
10/// therefore must be kept in sync with the compiler implementation.
11pub const StackTrace = struct {
12 index: usize,
13 instruction_addresses: []usize,
14};
15
16/// This data structure is used by the Zig language code generation and
17/// therefore must be kept in sync with the compiler implementation.
18pub const GlobalLinkage = enum(u2) {
19 internal,
20 strong,
21 weak,
22 link_once,
23};
24
25/// This data structure is used by the Zig language code generation and
26/// therefore must be kept in sync with the compiler implementation.
27pub const SymbolVisibility = enum(u2) {
28 default,
29 hidden,
30 protected,
31};
32
33/// This data structure is used by the Zig language code generation and
34/// therefore must be kept in sync with the compiler implementation.
35pub const AtomicOrder = enum {
36 unordered,
37 monotonic,
38 acquire,
39 release,
40 acq_rel,
41 seq_cst,
42};
43
44/// This data structure is used by the Zig language code generation and
45/// therefore must be kept in sync with the compiler implementation.
46pub const ReduceOp = enum {
47 And,
48 Or,
49 Xor,
50 Min,
51 Max,
52 Add,
53 Mul,
54};
55
56/// This data structure is used by the Zig language code generation and
57/// therefore must be kept in sync with the compiler implementation.
58pub const AtomicRmwOp = enum {
59 /// Exchange - store the operand unmodified.
60 /// Supports enums, integers, and floats.
61 Xchg,
62 /// Add operand to existing value.
63 /// Supports integers and floats.
64 /// For integers, two's complement wraparound applies.
65 Add,
66 /// Subtract operand from existing value.
67 /// Supports integers and floats.
68 /// For integers, two's complement wraparound applies.
69 Sub,
70 /// Perform bitwise AND on existing value with operand.
71 /// Supports integers.
72 And,
73 /// Perform bitwise NAND on existing value with operand.
74 /// Supports integers.
75 Nand,
76 /// Perform bitwise OR on existing value with operand.
77 /// Supports integers.
78 Or,
79 /// Perform bitwise XOR on existing value with operand.
80 /// Supports integers.
81 Xor,
82 /// Store operand if it is larger than the existing value.
83 /// Supports integers and floats.
84 Max,
85 /// Store operand if it is smaller than the existing value.
86 /// Supports integers and floats.
87 Min,
88};
89
90/// The code model puts constraints on the location of symbols and the size of code and data.
91/// The selection of a code model is a trade off on speed and restrictions that needs to be selected on a per application basis to meet its requirements.
92/// A slightly more detailed explanation can be found in (for example) the [System V Application Binary Interface (x86_64)](https://github.com/hjl-tools/x86-psABI/wiki/x86-64-psABI-1.0.pdf) 3.5.1.
93///
94/// This data structure is used by the Zig language code generation and
95/// therefore must be kept in sync with the compiler implementation.
96pub const CodeModel = enum(u4) {
97 default,
98 extreme,
99 kernel,
100 large,
101 medany,
102 medium,
103 medlow,
104 medmid,
105 normal,
106 small,
107 tiny,
108};
109
110/// Deprecated, to be removed after 0.18.0
111pub const OptimizeMode = Optimize;
112
113/// This data structure is used by the Zig language code generation and
114/// therefore must be kept in sync with the compiler implementation.
115pub const Optimize = enum {
116 /// Safety checks enabled. Optimize for bug detection, accurate debug info,
117 /// and compilation speed (in that order).
118 debug,
119 /// Safety checks enabled. Optimize for runtime performance.
120 safe,
121 /// Safety checks disabled. Optimize for runtime performance.
122 fast,
123 /// Safety checks disabled. Optimize for machine code size, then runtime performance.
124 small,
125
126 /// Deprecated, to be removed after 0.18.0
127 pub const Debug: @This() = .debug;
128 /// Deprecated, to be removed after 0.18.0
129 pub const ReleaseSafe: @This() = .safe;
130 /// Deprecated, to be removed after 0.18.0
131 pub const ReleaseFast: @This() = .fast;
132 /// Deprecated, to be removed after 0.18.0
133 pub const ReleaseSmall: @This() = .small;
134 /// Deprecated, to be removed after 0.18.0
135 pub fn fromString(s: []const u8) ?@This() {
136 return std.StaticStringMap(@This()).initComptime(&.{
137 .{ "Debug", .debug },
138 .{ "ReleaseSafe", .safe },
139 .{ "ReleaseFast", .fast },
140 .{ "ReleaseSmall", .small },
141 .{ "debug", .debug },
142 .{ "safe", .safe },
143 .{ "fast", .fast },
144 .{ "small", .small },
145 }).get(s);
146 }
147
148 /// Returns whether illegal behavior safety checks are enabled based on the
149 /// provided optimization mode.
150 pub fn runtimeSafety(o: @This()) bool {
151 return switch (o) {
152 .debug, .safe => true,
153 .fast, .small => false,
154 };
155 }
156};
157
158/// The calling convention of a function defines how arguments and return values are passed, as well
159/// as any other requirements which callers and callees must respect, such as register preservation
160/// and stack alignment.
161///
162/// This data structure is used by the Zig language code generation and
163/// therefore must be kept in sync with the compiler implementation.
164pub const CallingConvention = union(enum(u8)) {
165 pub const Tag = @typeInfo(CallingConvention).@"union".tag_type.?;
166
167 /// This is an alias for the default C calling convention for this target.
168 /// Functions marked as `extern` or `export` are given this calling convention by default.
169 pub const c = builtin.target.cCallingConvention().?;
170
171 pub const winapi: CallingConvention = switch (builtin.target.cpu.arch) {
172 .x86_64 => .{ .x86_64_win = .{} },
173 .x86 => .{ .x86_stdcall = .{} },
174 .aarch64 => .{ .aarch64_aapcs_win = .{} },
175 .thumb => .{ .arm_aapcs_vfp = .{} },
176 else => unreachable,
177 };
178
179 pub const kernel: CallingConvention = switch (builtin.target.cpu.arch) {
180 .amdgcn => .amdgcn_kernel,
181 .nvptx, .nvptx64 => .nvptx_kernel,
182 .spirv32, .spirv64 => .{ .spirv_kernel = .{ .x = 1, .y = 1, .z = 1 } },
183 else => unreachable,
184 };
185
186 /// The default Zig calling convention when neither `export` nor `inline` is specified.
187 /// This calling convention makes no guarantees about stack alignment, registers, etc.
188 /// It can only be used within this Zig compilation unit.
189 auto,
190
191 /// The calling convention of a function that can be called with `async` syntax. An `async` call
192 /// of a runtime-known function must target a function with this calling convention.
193 /// Comptime-known functions with other calling conventions may be coerced to this one.
194 async,
195
196 /// Functions with this calling convention have no prologue or epilogue, making the function
197 /// uncallable in regular Zig code. This can be useful when integrating with assembly.
198 naked,
199
200 /// This calling convention is exactly equivalent to using the `inline` keyword on a function
201 /// definition. This function will be semantically inlined by the Zig compiler at call sites.
202 /// Pointers to inline functions are comptime-only.
203 @"inline",
204
205 // Calling conventions for the `x86_64` architecture.
206 x86_64_sysv: CommonOptions,
207 x86_64_x32: CommonOptions,
208 x86_64_win: CommonOptions,
209 x86_64_regcall_v3_sysv: CommonOptions,
210 x86_64_regcall_v4_win: CommonOptions,
211 x86_64_vectorcall: CommonOptions,
212 x86_64_interrupt: CommonOptions,
213 x86_64_preserve_none: CommonOptions,
214
215 // Calling conventions for the `x86` architecture.
216 x86_sysv: X86RegparmOptions,
217 x86_win: X86RegparmOptions,
218 x86_mingw: X86RegparmOptions,
219 x86_stdcall: X86RegparmOptions,
220 x86_fastcall: CommonOptions,
221 x86_thiscall: CommonOptions,
222 x86_thiscall_mingw: CommonOptions,
223 x86_regcall_v3: CommonOptions,
224 x86_regcall_v4_win: CommonOptions,
225 x86_vectorcall: CommonOptions,
226 x86_interrupt: CommonOptions,
227
228 // Calling conventions for the `x86_16` architecture.
229
230 x86_16_cdecl: CommonOptions,
231 x86_16_stdcall: CommonOptions,
232 x86_16_regparmcall: CommonOptions,
233 x86_16_interrupt: CommonOptions,
234
235 // Calling conventions for the `aarch64` and `aarch64_be` architectures.
236 aarch64_aapcs: CommonOptions,
237 aarch64_aapcs_darwin: CommonOptions,
238 aarch64_aapcs_win: CommonOptions,
239 aarch64_vfabi: CommonOptions,
240 aarch64_vfabi_sve: CommonOptions,
241 aarch64_preserve_none: CommonOptions,
242
243 /// The standard `alpha` calling convention.
244 alpha_osf: CommonOptions,
245
246 // Calling convetions for the `arm`, `armeb`, `thumb`, and `thumbeb` architectures.
247 /// ARM Architecture Procedure Call Standard
248 arm_aapcs: CommonOptions,
249 /// ARM Architecture Procedure Call Standard Vector Floating-Point
250 arm_aapcs_vfp: CommonOptions,
251 arm_interrupt: ArmInterruptOptions,
252
253 // Calling conventions for the `mips64` and `mips64el` architectures.
254 mips64_n64: CommonOptions,
255 mips64_n32: CommonOptions,
256 mips64_interrupt: MipsInterruptOptions,
257
258 // Calling conventions for the `mips` and `mipsel` architectures.
259 mips_o32: CommonOptions,
260 mips_interrupt: MipsInterruptOptions,
261
262 // Calling conventions for the `riscv64` architecture.
263 riscv64_lp64: CommonOptions,
264 riscv64_lp64_v: CommonOptions,
265 riscv64_interrupt: RiscvInterruptOptions,
266
267 // Calling conventions for the `riscv32` architecture.
268 riscv32_ilp32: CommonOptions,
269 riscv32_ilp32_v: CommonOptions,
270 riscv32_interrupt: RiscvInterruptOptions,
271
272 // Calling conventions for the `sparc64` architecture.
273 sparc64_sysv: CommonOptions,
274
275 // Calling conventions for the `sparc` architecture.
276 sparc_sysv: CommonOptions,
277
278 // Calling conventions for the `powerpc64` and `powerpc64le` architectures.
279 powerpc64_elf: CommonOptions,
280 powerpc64_elf_altivec: CommonOptions,
281 powerpc64_elf_v2: CommonOptions,
282
283 // Calling conventions for the `powerpc` and `powerpcle` architectures.
284 powerpc_sysv: CommonOptions,
285 powerpc_sysv_altivec: CommonOptions,
286 powerpc_aix: CommonOptions,
287 powerpc_aix_altivec: CommonOptions,
288
289 /// The standard `wasm32` and `wasm64` calling convention, as specified in the WebAssembly Tool Conventions.
290 wasm_mvp: CommonOptions,
291
292 /// The standard `arc`/`arceb` calling convention.
293 arc_sysv: CommonOptions,
294 arc_interrupt: ArcInterruptOptions,
295
296 // Calling conventions for the `avr` architecture.
297 avr_gnu,
298 avr_builtin,
299 avr_signal,
300 avr_interrupt,
301
302 /// The standard `bpfel`/`bpfeb` calling convention.
303 bpf_std: CommonOptions,
304
305 // Calling conventions for the `csky` architecture.
306 csky_sysv: CommonOptions,
307 csky_interrupt: CommonOptions,
308
309 // Calling conventions for the `hexagon` architecture.
310 hexagon_sysv: CommonOptions,
311 hexagon_sysv_hvx: CommonOptions,
312
313 /// The standard `hppa` calling convention.
314 hppa_elf: CommonOptions,
315
316 /// The standard `hppa64` calling convention.
317 hppa64_elf: CommonOptions,
318
319 kvx_lp64: CommonOptions,
320 kvx_ilp32: CommonOptions,
321
322 /// The standard `lanai` calling convention.
323 lanai_sysv: CommonOptions,
324
325 /// The standard `loongarch64` calling convention.
326 loongarch64_lp64: CommonOptions,
327
328 /// The standard `loongarch32` calling convention.
329 loongarch32_ilp32: CommonOptions,
330
331 // Calling conventions for the `m68k` architecture.
332 m68k_sysv: CommonOptions,
333 m68k_gnu: CommonOptions,
334 m68k_rtd: CommonOptions,
335 m68k_interrupt: CommonOptions,
336
337 m88k_sysv: CommonOptions,
338
339 /// The standard `microblaze`/`microblazeel` calling convention.
340 microblaze_std: CommonOptions,
341 microblaze_interrupt: MicroblazeInterruptOptions,
342
343 /// The standard `msp430` calling convention.
344 msp430_eabi: CommonOptions,
345 msp430_interrupt: CommonOptions,
346
347 /// The standard `or1k` calling convention.
348 or1k_sysv: CommonOptions,
349
350 /// The standard `propeller` calling convention.
351 propeller_sysv: CommonOptions,
352
353 // Calling conventions for the `s390x` architecture.
354 s390x_sysv: CommonOptions,
355 s390x_sysv_vx: CommonOptions,
356
357 // Calling conventions for the `sh`/`sheb` architecture.
358 sh_gnu: CommonOptions,
359 sh_renesas: CommonOptions,
360 sh_interrupt: ShInterruptOptions,
361
362 /// The standard `ve` calling convention.
363 ve_sysv: CommonOptions,
364
365 // Calling conventions for the `xcore` architecture.
366 xcore_xs1: CommonOptions,
367 xcore_xs2: CommonOptions,
368
369 // Calling conventions for the `xtensa`/`xtensaeb` architecture.
370 xtensa_call0: CommonOptions,
371 xtensa_windowed: CommonOptions,
372
373 // Calling conventions for the `amdgcn` architecture.
374 amdgcn_device: CommonOptions,
375 amdgcn_kernel,
376 amdgcn_cs: CommonOptions,
377
378 // Calling conventions for the `nvptx` and `nvptx64` architectures.
379 nvptx_device,
380 nvptx_kernel,
381
382 // Calling conventions for kernels and shaders on the `spirv32` and `spirv64` architectures.
383 spirv_device,
384 spirv_vertex,
385 spirv_kernel: SpirvKernelOptions,
386 spirv_fragment: SpirvFragmentOptions,
387 spirv_task: SpirvKernelOptions,
388 spirv_mesh: SpirvMeshOptions,
389
390 // Calling conventions for the `ez80` architecture.
391 ez80_cet,
392 ez80_tiflags,
393
394 // Calling convention used by
395 // [snake2p example program](https://github.com/benanderman/spork-8/blob/1bce10a2c3a3888a3f4ca8208112afbc5973fda4/Code/programs/snake2p.asm)
396 spork8,
397
398 /// Options shared across most calling conventions.
399 pub const CommonOptions = struct {
400 /// The boundary the stack is aligned to when the function is called.
401 /// `null` means the default for this calling convention.
402 incoming_stack_alignment: ?u64 = null,
403 };
404
405 /// Options for x86 calling conventions which support the regparm attribute to pass some
406 /// arguments in registers.
407 pub const X86RegparmOptions = struct {
408 /// The boundary the stack is aligned to when the function is called.
409 /// `null` means the default for this calling convention.
410 incoming_stack_alignment: ?u64 = null,
411 /// The number of arguments to pass in registers before passing the remaining arguments
412 /// according to the calling convention.
413 /// Equivalent to `__attribute__((regparm(x)))` in Clang and GCC.
414 register_params: u2 = 0,
415 };
416
417 /// Options for the `arc_interrupt` calling convention.
418 pub const ArcInterruptOptions = struct {
419 /// The boundary the stack is aligned to when the function is called.
420 /// `null` means the default for this calling convention.
421 incoming_stack_alignment: ?u64 = null,
422 /// The kind of interrupt being received.
423 type: InterruptType,
424
425 pub const InterruptType = enum(u2) {
426 ilink1,
427 ilink2,
428 ilink,
429 firq,
430 };
431 };
432
433 /// Options for the `arm_interrupt` calling convention.
434 pub const ArmInterruptOptions = struct {
435 /// The boundary the stack is aligned to when the function is called.
436 /// `null` means the default for this calling convention.
437 incoming_stack_alignment: ?u64 = null,
438 /// The kind of interrupt being received.
439 type: InterruptType = .generic,
440
441 pub const InterruptType = enum(u3) {
442 generic,
443 irq,
444 fiq,
445 swi,
446 abort,
447 undef,
448 };
449 };
450
451 /// Options for the `microblaze_interrupt` calling convention.
452 pub const MicroblazeInterruptOptions = struct {
453 /// The boundary the stack is aligned to when the function is called.
454 /// `null` means the default for this calling convention.
455 incoming_stack_alignment: ?u64 = null,
456 type: InterruptType = .regular,
457
458 pub const InterruptType = enum(u2) {
459 /// User exception; return with `rtsd`.
460 user,
461 /// Regular interrupt; return with `rtid`.
462 regular,
463 /// Fast interrupt; return with `rtid`.
464 fast,
465 /// Software breakpoint; return with `rtbd`.
466 breakpoint,
467 };
468 };
469
470 /// Options for the `mips_interrupt` and `mips64_interrupt` calling conventions.
471 pub const MipsInterruptOptions = struct {
472 /// The boundary the stack is aligned to when the function is called.
473 /// `null` means the default for this calling convention.
474 incoming_stack_alignment: ?u64 = null,
475 /// The interrupt mode.
476 mode: InterruptMode = .eic,
477
478 pub const InterruptMode = enum(u4) {
479 eic,
480 sw0,
481 sw1,
482 hw0,
483 hw1,
484 hw2,
485 hw3,
486 hw4,
487 hw5,
488 };
489 };
490
491 /// Options for the `riscv32_interrupt` and `riscv64_interrupt` calling conventions.
492 pub const RiscvInterruptOptions = struct {
493 /// The boundary the stack is aligned to when the function is called.
494 /// `null` means the default for this calling convention.
495 incoming_stack_alignment: ?u64 = null,
496 /// The privilege mode.
497 mode: PrivilegeMode,
498
499 pub const PrivilegeMode = enum(u2) {
500 supervisor,
501 machine,
502 };
503 };
504
505 /// Options for the `sh_interrupt` calling convention.
506 pub const ShInterruptOptions = struct {
507 /// The boundary the stack is aligned to when the function is called.
508 /// `null` means the default for this calling convention.
509 incoming_stack_alignment: ?u64 = null,
510 save: SaveBehavior = .full,
511
512 pub const SaveBehavior = enum(u3) {
513 /// Save only fpscr (if applicable).
514 fpscr,
515 /// Save only high-numbered registers, i.e. r0 through r7 are *not* saved.
516 high,
517 /// Save all registers normally.
518 full,
519 /// Save all registers using the CPU's fast register bank.
520 bank,
521 };
522 };
523
524 pub const SpirvKernelOptions = struct {
525 x: u32,
526 y: u32,
527 z: u32,
528 };
529
530 pub const SpirvFragmentOptions = struct {
531 pub const DepthAssumption = enum(u2) {
532 none = 0,
533 greater = 1,
534 less = 2,
535 unchanged = 3,
536 };
537
538 pixel_centered_integer: bool = false,
539 depth_assumption: DepthAssumption = .none,
540 };
541
542 pub const SpirvMeshOptions = struct {
543 pub const StageOutput = enum(u2) {
544 output_points = 0,
545 output_lines = 1,
546 output_triangles = 2,
547 };
548
549 stage_output: StageOutput = .output_triangles,
550 max_primitives: u32 = 1,
551 max_vertices: u32 = 3,
552 x: u32,
553 y: u32,
554 z: u32,
555 };
556
557 /// Returns the array of `std.Target.Cpu.Arch` to which this `CallingConvention` applies.
558 /// Asserts that `cc` is not `.auto`, `.@"async"`, `.naked`, or `.@"inline"`.
559 pub fn archs(cc: CallingConvention) []const std.Target.Cpu.Arch {
560 return std.Target.Cpu.Arch.fromCallingConvention(cc);
561 }
562
563 pub fn eql(a: CallingConvention, b: CallingConvention) bool {
564 return std.meta.eql(a, b);
565 }
566
567 pub fn withStackAlign(cc: CallingConvention, incoming_stack_alignment: u64) CallingConvention {
568 const tag: CallingConvention.Tag = cc;
569 var result = cc;
570 @field(result, @tagName(tag)).incoming_stack_alignment = incoming_stack_alignment;
571 return result;
572 }
573};
574
575/// This data structure is used by the Zig language code generation and
576/// therefore must be kept in sync with the compiler implementation.
577pub const AddressSpace = enum(u5) {
578 // CPU address spaces.
579 generic,
580 gs,
581 fs,
582 ss,
583
584 // x86_16 extra address spaces.
585 /// Allows addressing the entire address space by storing both segment and offset.
586 far,
587
588 // GPU address spaces.
589 global,
590 constant,
591 param,
592 shared,
593 local,
594 input,
595 output,
596 uniform,
597 push_constant,
598 storage_buffer,
599 physical_storage_buffer,
600
601 // AVR address spaces.
602 flash,
603 flash1,
604 flash2,
605 flash3,
606 flash4,
607 flash5,
608
609 // Propeller address spaces.
610
611 /// This address space only addresses the cog-local ram.
612 cog,
613
614 /// This address space only addresses shared hub ram.
615 hub,
616
617 /// This address space only addresses the "lookup" ram
618 lut,
619
620 // Web Assembly
621 externref,
622 funcref,
623};
624
625/// This data structure is used by the Zig language code generation and
626/// therefore must be kept in sync with the compiler implementation.
627pub const SourceLocation = struct {
628 /// The name chosen when compiling. Not a file path.
629 module: [:0]const u8,
630 /// Relative to the root directory of its module.
631 file: [:0]const u8,
632 fn_name: [:0]const u8,
633 line: u32,
634 column: u32,
635};
636
637pub const TypeId = std.meta.Tag(Type);
638
639/// This data structure is used by the Zig language code generation and
640/// therefore must be kept in sync with the compiler implementation.
641pub const Type = union(enum) {
642 type,
643 void,
644 bool,
645 noreturn,
646 int: Int,
647 float: Float,
648 pointer: Pointer,
649 array: Array,
650 @"struct": Struct,
651 comptime_float,
652 comptime_int,
653 undefined,
654 null,
655 optional: Optional,
656 error_union: ErrorUnion,
657 error_set: ErrorSet,
658 @"enum": Enum,
659 @"union": Union,
660 @"fn": Fn,
661 @"opaque": Opaque,
662 frame: Frame,
663 @"anyframe": AnyFrame,
664 vector: Vector,
665 enum_literal,
666 spirv: Spirv,
667
668 /// This data structure is used by the Zig language code generation and
669 /// therefore must be kept in sync with the compiler implementation.
670 pub const Int = struct {
671 signedness: Signedness,
672 bits: u16,
673 };
674
675 /// This data structure is used by the Zig language code generation and
676 /// therefore must be kept in sync with the compiler implementation.
677 pub const Float = struct {
678 bits: u16,
679 };
680
681 /// This data structure is used by the Zig language code generation and
682 /// therefore must be kept in sync with the compiler implementation.
683 pub const Pointer = struct {
684 size: Size,
685 attrs: Attributes,
686 child: type,
687
688 /// The type of the sentinel is the element type of the pointer, which is
689 /// the value of the `child` field in this struct. However there is no way
690 /// to refer to that type here, so we use `*const anyopaque`.
691 /// See also: `sentinel`
692 sentinel_ptr: ?*const anyopaque,
693
694 /// Loads the pointer type's sentinel value from `sentinel_ptr`.
695 /// Returns `null` if the pointer type has no sentinel.
696 pub inline fn sentinel(comptime ptr: Pointer) ?ptr.child {
697 const sp: *const ptr.child = @ptrCast(@alignCast(ptr.sentinel_ptr orelse return null));
698 return sp.*;
699 }
700
701 /// This data structure is used by the Zig language code generation and
702 /// therefore must be kept in sync with the compiler implementation.
703 pub const Size = enum(u2) {
704 one,
705 many,
706 slice,
707 c,
708 };
709
710 /// This data structure is used by the Zig language code generation and
711 /// therefore must be kept in sync with the compiler implementation.
712 pub const Attributes = struct {
713 @"const": bool = false,
714 @"volatile": bool = false,
715 @"allowzero": bool = false,
716 @"addrspace": ?AddressSpace = null,
717 @"align": ?usize = null,
718 };
719 };
720
721 /// This data structure is used by the Zig language code generation and
722 /// therefore must be kept in sync with the compiler implementation.
723 pub const Array = struct {
724 len: comptime_int,
725 child: type,
726
727 /// The type of the sentinel is the element type of the array, which is
728 /// the value of the `child` field in this struct. However there is no way
729 /// to refer to that type here, so we use `*const anyopaque`.
730 /// See also: `sentinel`.
731 sentinel_ptr: ?*const anyopaque,
732
733 /// Loads the array type's sentinel value from `sentinel_ptr`.
734 /// Returns `null` if the array type has no sentinel.
735 pub inline fn sentinel(comptime arr: Array) ?arr.child {
736 const sp: *const arr.child = @ptrCast(@alignCast(arr.sentinel_ptr orelse return null));
737 return sp.*;
738 }
739 };
740
741 /// This data structure is used by the Zig language code generation and
742 /// therefore must be kept in sync with the compiler implementation.
743 pub const ContainerLayout = enum(u2) {
744 auto,
745 @"extern",
746 @"packed",
747 };
748
749 /// This data structure is used by the Zig language code generation and
750 /// therefore must be kept in sync with the compiler implementation.
751 pub const Struct = struct {
752 is_tuple: bool,
753 layout: ContainerLayout,
754 /// Always `null` if `layout != .@"packed"`.
755 backing_integer: ?type,
756
757 field_names: []const [:0]const u8,
758 /// Guaranteed to have the same length as `field_names`.
759 field_types: []const type,
760 /// Guaranteed to have the same length as `field_names`.
761 field_attrs: []const FieldAttributes,
762
763 decl_names: []const [:0]const u8,
764
765 pub const FieldAttributes = struct {
766 @"comptime": bool = false,
767 /// `null` means the field alignment is not explicitly specified. The field will still
768 /// be aligned to at least `@alignOf` the field type.
769 @"align": ?usize = null,
770 /// The type of the default value is the type of this struct field. However, that type
771 /// is not known here, so we use a type-erased pointer instead, which must be cast to
772 /// a pointer to the field type.
773 ///
774 /// See also: `defaultValue`.
775 default_value_ptr: ?*const anyopaque = null,
776
777 /// Loads the field's default value from `default_value_ptr`.
778 /// `FieldType` must exactly match the corresponding element of `Struct.field_types`.
779 /// Returns `null` if the field has no default value.
780 pub inline fn defaultValue(comptime attrs: FieldAttributes, comptime FieldType: type) ?FieldType {
781 const dp: *const FieldType = @ptrCast(@alignCast(attrs.default_value_ptr orelse return null));
782 return dp.*;
783 }
784 };
785 };
786
787 /// This data structure is used by the Zig language code generation and
788 /// therefore must be kept in sync with the compiler implementation.
789 pub const Optional = struct {
790 child: type,
791 };
792
793 /// This data structure is used by the Zig language code generation and
794 /// therefore must be kept in sync with the compiler implementation.
795 pub const ErrorUnion = struct {
796 error_set: type,
797 payload: type,
798 };
799
800 /// This data structure is used by the Zig language code generation and
801 /// therefore must be kept in sync with the compiler implementation.
802 pub const ErrorSet = struct {
803 error_names: ?[]const [:0]const u8,
804 };
805
806 /// This data structure is used by the Zig language code generation and
807 /// therefore must be kept in sync with the compiler implementation.
808 pub const Enum = struct {
809 tag_type: type,
810 mode: Mode,
811
812 field_names: []const [:0]const u8,
813 /// Guaranteed to have the same length as `field_names`.
814 field_values: []const comptime_int,
815
816 decl_names: []const [:0]const u8,
817
818 /// This data structure is used by the Zig language code generation and
819 /// therefore must be kept in sync with the compiler implementation.
820 pub const Mode = enum { exhaustive, nonexhaustive };
821 };
822
823 /// This data structure is used by the Zig language code generation and
824 /// therefore must be kept in sync with the compiler implementation.
825 pub const Union = struct {
826 layout: ContainerLayout,
827 tag_type: ?type,
828 /// Always `null` if `layout != .@"packed"`.
829 backing_integer: ?type,
830
831 field_names: []const [:0]const u8,
832 /// Guaranteed to have the same length as `field_names`.
833 field_types: []const type,
834 /// Guaranteed to have the same length as `field_names`.
835 field_attrs: []const FieldAttributes,
836
837 decl_names: []const [:0]const u8,
838
839 pub const FieldAttributes = struct {
840 /// `null` means the field alignment is not explicitly specified. The field will still
841 /// be aligned to at least `@alignOf` the field type.
842 @"align": ?usize = null,
843 };
844 };
845
846 /// This data structure is used by the Zig language code generation and
847 /// therefore must be kept in sync with the compiler implementation.
848 pub const Fn = struct {
849 attrs: Attributes,
850 is_generic: bool,
851 /// `null` means the return type is generic, i.e. it depends on a function argument.
852 return_type: ?type,
853
854 /// A `null` element represents either an `anytype` parameter, or a parameter with a generic
855 /// type, i.e. where the type depends on a previous function argument.
856 param_types: []const ?type,
857 /// Guaranteed to have the same length as `param_types`.
858 param_attrs: []const ParamAttributes,
859
860 pub const ParamAttributes = struct {
861 @"noalias": bool = false,
862 };
863
864 pub const Attributes = struct {
865 @"callconv": CallingConvention = .auto,
866 varargs: bool = false,
867 };
868 };
869
870 /// This data structure is used by the Zig language code generation and
871 /// therefore must be kept in sync with the compiler implementation.
872 pub const Spirv = union(enum(u2)) {
873 sampler,
874 image: Image,
875 sampled_image: type,
876 runtime_array: type,
877
878 pub const Image = struct {
879 usage: Usage,
880 format: Format,
881 dim: Dimensionality,
882 depth: Depth,
883 access: Access,
884 arrayed: bool,
885 multisampled: bool,
886
887 pub const Usage = union(enum(u2)) {
888 unknown: type,
889 sampled: type,
890 storage: type,
891 };
892
893 pub const Format = enum(u4) {
894 unknown,
895 rgba32f,
896 rgba32i,
897 rgba32u,
898 rgba16f,
899 rgba16i,
900 rgba16u,
901 rgba8unorm,
902 rgba8snorm,
903 rgba8i,
904 rgba8u,
905 r32f,
906 r32i,
907 r32u,
908 };
909
910 pub const Dimensionality = enum(u2) {
911 @"1d",
912 @"2d",
913 @"3d",
914 cube,
915 };
916
917 pub const Depth = enum(u2) { unknown, depth, not_depth };
918
919 pub const Access = enum(u2) { unknown, read_only, write_only, read_write };
920 };
921 };
922
923 /// This data structure is used by the Zig language code generation and
924 /// therefore must be kept in sync with the compiler implementation.
925 pub const Opaque = struct {
926 decl_names: []const [:0]const u8,
927 };
928
929 /// This data structure is used by the Zig language code generation and
930 /// therefore must be kept in sync with the compiler implementation.
931 pub const Frame = struct {
932 function: *const anyopaque,
933 };
934
935 /// This data structure is used by the Zig language code generation and
936 /// therefore must be kept in sync with the compiler implementation.
937 pub const AnyFrame = struct {
938 child: ?type,
939 };
940
941 /// This data structure is used by the Zig language code generation and
942 /// therefore must be kept in sync with the compiler implementation.
943 pub const Vector = struct {
944 len: comptime_int,
945 child: type,
946 };
947};
948
949/// This data structure is used by the Zig language code generation and
950/// therefore must be kept in sync with the compiler implementation.
951pub const FloatMode = enum {
952 strict,
953 optimized,
954};
955
956/// This data structure is used by the Zig language code generation and
957/// therefore must be kept in sync with the compiler implementation.
958pub const Endian = enum {
959 big,
960 little,
961
962 pub const native = builtin.target.cpu.arch.endian();
963 pub const foreign: Endian = @fromBackingInt(@intCast(1 - @backingInt(native)));
964};
965
966/// This data structure is used by the Zig language code generation and
967/// therefore must be kept in sync with the compiler implementation.
968pub const Signedness = enum(u1) {
969 signed,
970 unsigned,
971};
972
973/// This data structure is used by the Zig language code generation and
974/// therefore must be kept in sync with the compiler implementation.
975pub const OutputMode = enum {
976 Exe,
977 Lib,
978 Obj,
979};
980
981/// This data structure is used by the Zig language code generation and
982/// therefore must be kept in sync with the compiler implementation.
983pub const LinkMode = enum(u1) {
984 static,
985 dynamic,
986};
987
988/// This data structure is used by the Zig language code generation and
989/// therefore must be kept in sync with the compiler implementation.
990pub const UnwindTables = enum {
991 none,
992 sync,
993 async,
994};
995
996/// This data structure is used by the Zig language code generation and
997/// therefore must be kept in sync with the compiler implementation.
998pub const WasiExecModel = enum {
999 command,
1000 reactor,
1001};
1002
1003/// This data structure is used by the Zig language code generation and
1004/// therefore must be kept in sync with the compiler implementation.
1005pub const CallModifier = enum {
1006 /// Equivalent to function call syntax.
1007 auto,
1008 /// Prevents tail call optimization. This guarantees that the return
1009 /// address will point to the callsite, as opposed to the callsite's
1010 /// callsite. If the call is otherwise required to be tail-called
1011 /// or inlined, a compile error is emitted instead.
1012 never_tail,
1013 /// Guarantees that the call will not be inlined. If the call is
1014 /// otherwise required to be inlined, a compile error is emitted instead.
1015 never_inline,
1016 /// Asserts that the function call will not suspend. This allows a
1017 /// non-async function to call an async function.
1018 no_suspend,
1019 /// Guarantees that the call will be generated with tail call optimization.
1020 /// If this is not possible, a compile error is emitted instead.
1021 always_tail,
1022 /// Guarantees that the call will be inlined at the callsite.
1023 /// If this is not possible, a compile error is emitted instead.
1024 always_inline,
1025 /// Evaluates the call at compile-time. If the call cannot be completed at
1026 /// compile-time, a compile error is emitted instead.
1027 compile_time,
1028};
1029
1030/// This data structure is used by the Zig language code generation and
1031/// therefore must be kept in sync with the compiler implementation.
1032pub const VaListAarch64 = extern struct {
1033 __stack: *anyopaque,
1034 __gr_top: *anyopaque,
1035 __vr_top: *anyopaque,
1036 __gr_offs: c_int,
1037 __vr_offs: c_int,
1038};
1039
1040/// This data structure is used by the Zig language code generation and
1041/// therefore must be kept in sync with the compiler implementation.
1042pub const VaListAlpha = extern struct {
1043 __base: *anyopaque,
1044 __offset: c_int,
1045};
1046
1047/// This data structure is used by the Zig language code generation and
1048/// therefore must be kept in sync with the compiler implementation.
1049pub const VaListArm = extern struct {
1050 __ap: *anyopaque,
1051};
1052
1053/// This data structure is used by the Zig language code generation and
1054/// therefore must be kept in sync with the compiler implementation.
1055pub const VaListHexagon = extern struct {
1056 __current_saved_reg_area_pointer: *anyopaque,
1057 __saved_reg_area_end_pointer: *anyopaque,
1058 __overflow_area_pointer: *anyopaque,
1059};
1060
1061/// This data structure is used by the Zig language code generation and
1062/// therefore must be kept in sync with the compiler implementation.
1063pub const VaListPowerPc = extern struct {
1064 gpr: u8,
1065 fpr: u8,
1066 reserved: c_ushort,
1067 overflow_arg_area: *anyopaque,
1068 reg_save_area: *anyopaque,
1069};
1070
1071/// This data structure is used by the Zig language code generation and
1072/// therefore must be kept in sync with the compiler implementation.
1073pub const VaListS390x = extern struct {
1074 __gpr: c_long,
1075 __fpr: c_long,
1076 __overflow_arg_area: *anyopaque,
1077 __reg_save_area: *anyopaque,
1078};
1079
1080/// This data structure is used by the Zig language code generation and
1081/// therefore must be kept in sync with the compiler implementation.
1082pub const VaListSh = extern struct {
1083 __va_next_o: *anyopaque,
1084 __va_next_o_limit: *anyopaque,
1085 __va_next_fp: *anyopaque,
1086 __va_next_fp_limit: *anyopaque,
1087 __va_next_stack: *anyopaque,
1088};
1089
1090/// This data structure is used by the Zig language code generation and
1091/// therefore must be kept in sync with the compiler implementation.
1092pub const VaListX86_64 = extern struct {
1093 gp_offset: c_uint,
1094 fp_offset: c_uint,
1095 overflow_arg_area: *anyopaque,
1096 reg_save_area: *anyopaque,
1097};
1098
1099/// This data structure is used by the Zig language code generation and
1100/// therefore must be kept in sync with the compiler implementation.
1101pub const VaListXtensa = extern struct {
1102 __va_stk: *c_int,
1103 __va_reg: *c_int,
1104 __va_ndx: c_int,
1105};
1106
1107/// This data structure is used by the Zig language code generation and
1108/// therefore must be kept in sync with the compiler implementation.
1109pub const VaList = switch (builtin.cpu.arch) {
1110 .amdgcn,
1111 .msp430,
1112 .nvptx,
1113 .nvptx64,
1114 .powerpc64,
1115 .powerpc64le,
1116 .x86,
1117 => *u8,
1118 .arc,
1119 .arceb,
1120 .avr,
1121 .bpfel,
1122 .bpfeb,
1123 .csky,
1124 .hppa,
1125 .hppa64,
1126 .kvx,
1127 .lanai,
1128 .loongarch32,
1129 .loongarch64,
1130 .m68k,
1131 .microblaze,
1132 .microblazeel,
1133 .mips,
1134 .mipsel,
1135 .mips64,
1136 .mips64el,
1137 .riscv32,
1138 .riscv32be,
1139 .riscv64,
1140 .riscv64be,
1141 .sparc,
1142 .sparc64,
1143 .spirv32,
1144 .spirv64,
1145 .ve,
1146 .wasm32,
1147 .wasm64,
1148 .xcore,
1149 => *anyopaque,
1150 .aarch64, .aarch64_be => switch (builtin.os.tag) {
1151 .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos, .windows => *u8,
1152 else => switch (builtin.zig_backend) {
1153 else => VaListAarch64,
1154 .stage2_llvm => @compileError("disabled due to miscompilations"),
1155 },
1156 },
1157 .alpha => VaListAlpha,
1158 .arm, .armeb, .thumb, .thumbeb => VaListArm,
1159 .hexagon => if (builtin.target.abi.isMusl()) VaListHexagon else *u8,
1160 .powerpc, .powerpcle => VaListPowerPc,
1161 .s390x => VaListS390x,
1162 .sh, .sheb => VaListSh, // This is wrong for `sh_renesas`: https://github.com/ziglang/zig/issues/24692#issuecomment-3150779829
1163 .x86_64 => switch (builtin.os.tag) {
1164 .uefi, .windows => switch (builtin.zig_backend) {
1165 else => *u8,
1166 .stage2_llvm => @compileError("disabled due to miscompilations"),
1167 },
1168 else => VaListX86_64,
1169 },
1170 .xtensa, .xtensaeb => VaListXtensa,
1171 else => @compileError("VaList not supported for this target yet"),
1172};
1173
1174/// This data structure is used by the Zig language code generation and
1175/// therefore must be kept in sync with the compiler implementation.
1176pub const PrefetchOptions = struct {
1177 /// Whether the prefetch should prepare for a read or a write.
1178 rw: Rw = .read,
1179 /// The data's locality in an inclusive range from 0 to 3.
1180 ///
1181 /// 0 means no temporal locality. That is, the data can be immediately
1182 /// dropped from the cache after it is accessed.
1183 ///
1184 /// 3 means high temporal locality. That is, the data should be kept in
1185 /// the cache as it is likely to be accessed again soon.
1186 locality: u2 = 3,
1187 /// The cache that the prefetch should be performed on.
1188 cache: Cache = .data,
1189
1190 pub const Rw = enum(u1) {
1191 read,
1192 write,
1193 };
1194
1195 pub const Cache = enum(u1) {
1196 instruction,
1197 data,
1198 };
1199};
1200
1201/// This data structure is used by the Zig language code generation and
1202/// therefore must be kept in sync with the compiler implementation.
1203pub const ExportOptions = struct {
1204 name: []const u8,
1205 linkage: GlobalLinkage = .strong,
1206 section: ?[]const u8 = null,
1207 visibility: SymbolVisibility = .default,
1208};
1209
1210/// This data structure is used by the Zig language code generation and
1211/// therefore must be kept in sync with the compiler implementation.
1212pub const ExternOptions = struct {
1213 name: []const u8,
1214 library_name: ?[]const u8 = null,
1215 linkage: GlobalLinkage = .strong,
1216 visibility: SymbolVisibility = .default,
1217 /// Setting this to `true` makes the `@extern` a runtime value.
1218 is_thread_local: bool = false,
1219 is_dll_import: bool = false,
1220 relocation: Relocation = .any,
1221 decoration: ?Decoration = null,
1222
1223 pub const Decoration = union(enum) {
1224 location: u32,
1225 flat: u32,
1226 descriptor: Descriptor,
1227
1228 pub const Descriptor = struct {
1229 set: u32,
1230 binding: u32,
1231 };
1232 };
1233
1234 pub const Relocation = enum(u1) {
1235 /// Any type of relocation is allowed.
1236 any,
1237 /// A program-counter-relative relocation is required.
1238 /// Using this value makes the `@extern` a runtime value.
1239 pcrel,
1240 };
1241};
1242
1243/// This data structure is used by the Zig language code generation and
1244/// therefore must be kept in sync with the compiler implementation.
1245pub const BranchHint = enum(u3) {
1246 /// Equivalent to no hint given.
1247 none,
1248 /// This branch of control flow is more likely to be reached than its peers.
1249 /// The optimizer should optimize for reaching it.
1250 likely,
1251 /// This branch of control flow is less likely to be reached than its peers.
1252 /// The optimizer should optimize for not reaching it.
1253 unlikely,
1254 /// This branch of control flow is unlikely to *ever* be reached.
1255 /// The optimizer may place it in a different page of memory to optimize other branches.
1256 cold,
1257 /// It is difficult to predict whether this branch of control flow will be reached.
1258 /// The optimizer should avoid branching behavior with expensive mispredictions.
1259 unpredictable,
1260};
1261
1262/// This enum is set by the compiler and communicates which compiler
1263/// implementation is used to produce machine code.
1264///
1265/// In theory, Zig code should be agnostic to the backend that implements the
1266/// language. The only reason to observe this value is to **work around
1267/// problems with compiler implementations.**
1268///
1269/// A common pitful is failing the compilation if the compiler backend does not
1270/// match a whitelist of backends; a more resilient strategy is to detect that
1271/// a known problem would occur in a blacklist of backends.
1272///
1273/// The enum is nonexhaustive so that alternate Zig language implementations
1274/// may choose a random number as their tag, thereby avoiding conflicts with
1275/// other implementations, and codebases can interact with these values even if
1276/// this upstream enum does not have a name for the number. Of course, upstream
1277/// is happy to accept patches to add additional Zig implementations to this
1278/// enum.
1279///
1280/// This data structure is part of the Zig language specification.
1281pub const CompilerBackend = enum(u64) {
1282 /// It is allowed for a compiler implementation to not reveal its identity,
1283 /// in which case this value is appropriate. Be cool and make sure your
1284 /// code supports `other` Zig compilers!
1285 other = 0,
1286 /// The original Zig compiler created in 2015 by Andrew Kelley. Implemented
1287 /// in C++. Used LLVM. Deleted from the ZSF ziglang/zig codebase on
1288 /// December 6th, 2022.
1289 stage1 = 1,
1290 /// The reference implementation self-hosted compiler of Zig, using the
1291 /// LLVM backend.
1292 stage2_llvm = 2,
1293 /// The reference implementation self-hosted compiler of Zig, using the
1294 /// backend that generates C source code.
1295 ///
1296 /// Note that one can observe whether the compilation will output C code
1297 /// directly with `object_format` value rather than the `compiler_backend` value.
1298 stage2_c = 3,
1299 /// The reference implementation self-hosted compiler of Zig, using the
1300 /// WebAssembly backend.
1301 stage2_wasm = 4,
1302 /// The reference implementation self-hosted compiler of Zig, using the
1303 /// arm backend.
1304 stage2_arm = 5,
1305 /// The reference implementation self-hosted compiler of Zig, using the
1306 /// x86_64 backend.
1307 stage2_x86_64 = 6,
1308 /// The reference implementation self-hosted compiler of Zig, using the
1309 /// aarch64 backend.
1310 stage2_aarch64 = 7,
1311 /// The reference implementation self-hosted compiler of Zig, using the
1312 /// x86 backend.
1313 stage2_x86 = 8,
1314 /// The reference implementation self-hosted compiler of Zig, using the
1315 /// riscv64 backend.
1316 stage2_riscv64 = 9,
1317 /// The reference implementation self-hosted compiler of Zig, using the
1318 /// sparc64 backend.
1319 stage2_sparc64 = 10,
1320 /// The reference implementation self-hosted compiler of Zig, using the
1321 /// spirv backend.
1322 stage2_spirv = 11,
1323 /// The reference implementation self-hosted compiler of Zig, using the
1324 /// powerpc backend.
1325 stage2_powerpc = 12,
1326 /// The reference implementation self-hosted compiler of Zig, using the
1327 /// loongarch backend.
1328 stage2_loongarch = 13,
1329 /// The Zig Software Foundation self-hosted implementation of Zig. Backend
1330 /// originally contributed by Ben Anderman in 2026.
1331 zsf_spork8 = 14,
1332
1333 _,
1334};
1335
1336/// This function type is used by the Zig language code generation and
1337/// therefore must be kept in sync with the compiler implementation.
1338pub const TestFn = struct {
1339 name: []const u8,
1340 func: *const fn () anyerror!void,
1341};
1342
1343/// This namespace is used by the Zig compiler to emit various kinds of safety
1344/// panics. These can be overridden by making a public `panic` namespace in the
1345/// root source file.
1346pub const panic: type = p: {
1347 if (@hasDecl(root, "panic")) {
1348 if (@TypeOf(root.panic) != type) {
1349 // Deprecated; make `panic` a namespace instead.
1350 break :p std.debug.FullPanic(struct {
1351 fn panic(msg: []const u8, ra: ?usize) noreturn {
1352 root.panic(msg, @errorReturnTrace(), ra);
1353 }
1354 }.panic);
1355 }
1356 break :p root.panic;
1357 }
1358 break :p switch (builtin.zig_backend) {
1359 .stage2_loongarch,
1360 .stage2_powerpc,
1361 .stage2_riscv64,
1362 => std.debug.simple_panic,
1363 else => std.debug.FullPanic(std.debug.defaultPanic),
1364 };
1365};
1366
1367pub noinline fn returnError() void {
1368 @branchHint(.unlikely);
1369 @setRuntimeSafety(false);
1370 const st = @errorReturnTrace().?;
1371 if (st.index < st.instruction_addresses.len)
1372 st.instruction_addresses[st.index] = @returnAddress();
1373 st.index += 1;
1374}