core/ffi/
va_list.rs

1//! C's "variable arguments"
2//!
3//! Better known as "varargs".
4
5#[cfg(not(target_arch = "xtensa"))]
6use crate::ffi::c_void;
7use crate::fmt;
8use crate::intrinsics::{va_arg, va_copy, va_end};
9use crate::marker::PhantomCovariantLifetime;
10
11// There are currently three flavors of how a C `va_list` is implemented for
12// targets that Rust supports:
13//
14// - `va_list` is an opaque pointer
15// - `va_list` is a struct
16// - `va_list` is a single-element array, containing a struct
17//
18// The opaque pointer approach is the simplest to implement: the pointer just
19// points to an array of arguments on the caller's stack.
20//
21// The struct and single-element array variants are more complex, but
22// potentially more efficient because the additional state makes it
23// possible to pass variadic arguments via registers.
24//
25// The Rust `VaList` type is ABI-compatible with the C `va_list`.
26// The struct and pointer cases straightforwardly map to their Rust equivalents,
27// but the single-element array case is special: in C, this type is subject to
28// array-to-pointer decay.
29//
30// The `#[rustc_pass_indirectly_in_non_rustic_abis]` attribute is used to match
31// the pointer decay behavior in Rust, while otherwise matching Rust semantics.
32// This attribute ensures that the compiler uses the correct ABI for functions
33// like `extern "C" fn takes_va_list(va: VaList<'_>)` by passing `va` indirectly.
34//
35// The Clang `BuiltinVaListKind` enumerates the `va_list` variations that Clang supports,
36// and we mirror these here.
37//
38// For all current LLVM targets, `va_copy` lowers to `memcpy`. Hence the inner structs below all
39// derive `Copy`. However, in the future we might want to support a target where `va_copy`
40// allocates, or otherwise violates the requirements of `Copy`. Therefore `VaList` is only `Clone`.
41crate::cfg_select! {
42    all(
43        target_arch = "aarch64",
44        not(target_vendor = "apple"),
45        not(target_os = "uefi"),
46        not(windows),
47    ) => {
48        /// AArch64 ABI implementation of a `va_list`.
49        ///
50        /// See the [AArch64 Procedure Call Standard] for more details.
51        ///
52        /// `va_copy` is `memcpy`: <https://github.com/llvm/llvm-project/blob/5aee01a3df011e660f26660bc30a8c94a1651d8e/llvm/lib/Target/AArch64/AArch64ISelLowering.cpp#L12682-L12700>
53        ///
54        /// [AArch64 Procedure Call Standard]:
55        /// http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf
56        #[repr(C)]
57        #[derive(Debug, Clone, Copy)]
58        struct VaListInner {
59            stack: *const c_void,
60            gr_top: *const c_void,
61            vr_top: *const c_void,
62            gr_offs: i32,
63            vr_offs: i32,
64        }
65    }
66    all(target_arch = "powerpc", not(target_os = "uefi"), not(windows)) => {
67        /// PowerPC ABI implementation of a `va_list`.
68        ///
69        /// See the [LLVM source] and [GCC header] for more details.
70        ///
71        /// `va_copy` is `memcpy`: <https://github.com/llvm/llvm-project/blob/5aee01a3df011e660f26660bc30a8c94a1651d8e/llvm/lib/Target/PowerPC/PPCISelLowering.cpp#L3755-L3764>
72        ///
73        /// [LLVM source]:
74        /// https://github.com/llvm/llvm-project/blob/af9a4263a1a209953a1d339ef781a954e31268ff/llvm/lib/Target/PowerPC/PPCISelLowering.cpp#L4089-L4111
75        /// [GCC header]: https://web.mit.edu/darwin/src/modules/gcc/gcc/ginclude/va-ppc.h
76        #[repr(C)]
77        #[derive(Debug, Clone, Copy)]
78        #[rustc_pass_indirectly_in_non_rustic_abis]
79        struct VaListInner {
80            gpr: u8,
81            fpr: u8,
82            reserved: u16,
83            overflow_arg_area: *const c_void,
84            reg_save_area: *const c_void,
85        }
86    }
87    target_arch = "s390x" => {
88        /// s390x ABI implementation of a `va_list`.
89        ///
90        /// See the [S/390x ELF Application Binary Interface Supplement] for more details.
91        ///
92        /// `va_copy` is `memcpy`: <https://github.com/llvm/llvm-project/blob/5aee01a3df011e660f26660bc30a8c94a1651d8e/llvm/lib/Target/SystemZ/SystemZISelLowering.cpp#L4457-L4472>
93        ///
94        /// [S/390x ELF Application Binary Interface Supplement]:
95        /// https://docs.google.com/gview?embedded=true&url=https://github.com/IBM/s390x-abi/releases/download/v1.7/lzsabi_s390x.pdf
96        #[repr(C)]
97        #[derive(Debug, Clone, Copy)]
98        #[rustc_pass_indirectly_in_non_rustic_abis]
99        struct VaListInner {
100            gpr: i64,
101            fpr: i64,
102            overflow_arg_area: *const c_void,
103            reg_save_area: *const c_void,
104        }
105    }
106    all(target_arch = "x86_64", not(target_os = "uefi"), not(windows)) => {
107        /// x86_64 System V ABI implementation of a `va_list`.
108        ///
109        /// See the [System V AMD64 ABI] for more details.
110        ///
111        /// `va_copy` is `memcpy`: <https://github.com/llvm/llvm-project/blob/5aee01a3df011e660f26660bc30a8c94a1651d8e/llvm/lib/Target/X86/X86ISelLowering.cpp#26319>
112        /// (github won't render that file, look for `SDValue LowerVACOPY`)
113        ///
114        /// [System V AMD64 ABI]:
115        /// https://refspecs.linuxbase.org/elf/x86_64-abi-0.99.pdf
116        #[repr(C)]
117        #[derive(Debug, Clone, Copy)]
118        #[rustc_pass_indirectly_in_non_rustic_abis]
119        struct VaListInner {
120            gp_offset: i32,
121            fp_offset: i32,
122            overflow_arg_area: *const c_void,
123            reg_save_area: *const c_void,
124        }
125    }
126    target_arch = "xtensa" => {
127        /// Xtensa ABI implementation of a `va_list`.
128        ///
129        /// See the [LLVM source] for more details.
130        ///
131        /// `va_copy` is `memcpy`: <https://github.com/llvm/llvm-project/blob/5aee01a3df011e660f26660bc30a8c94a1651d8e/llvm/lib/Target/Xtensa/XtensaISelLowering.cpp#L1260>
132        ///
133        /// [LLVM source]:
134        /// https://github.com/llvm/llvm-project/blob/af9a4263a1a209953a1d339ef781a954e31268ff/llvm/lib/Target/Xtensa/XtensaISelLowering.cpp#L1211-L1215
135        #[repr(C)]
136        #[derive(Debug, Clone, Copy)]
137        #[rustc_pass_indirectly_in_non_rustic_abis]
138        struct VaListInner {
139            stk: *const i32,
140            reg: *const i32,
141            ndx: i32,
142        }
143    }
144
145    all(target_arch = "hexagon", target_env = "musl") => {
146        /// Hexagon Musl implementation of a `va_list`.
147        ///
148        /// See the [LLVM source] for more details. On bare metal Hexagon uses an opaque pointer.
149        ///
150        /// `va_copy` is `memcpy`: <https://github.com/llvm/llvm-project/blob/5aee01a3df011e660f26660bc30a8c94a1651d8e/llvm/lib/Target/Hexagon/HexagonISelLowering.cpp#L1087-L1102>
151        ///
152        /// [LLVM source]:
153        /// https://github.com/llvm/llvm-project/blob/0cdc1b6dd4a870fc41d4b15ad97e0001882aba58/clang/lib/CodeGen/Targets/Hexagon.cpp#L407-L417
154        #[repr(C)]
155        #[derive(Debug, Clone, Copy)]
156        #[rustc_pass_indirectly_in_non_rustic_abis]
157        struct VaListInner {
158            __current_saved_reg_area_pointer: *const c_void,
159            __saved_reg_area_end_pointer: *const c_void,
160            __overflow_area_pointer: *const c_void,
161        }
162    }
163
164    // The fallback implementation, used for:
165    //
166    // - apple aarch64 (see https://github.com/rust-lang/rust/pull/56599)
167    // - windows
168    // - powerpc64 & powerpc64le
169    // - uefi
170    // - any other target for which we don't specify the `VaListInner` above
171    //
172    // In this implementation the `va_list` type is just an alias for an opaque pointer.
173    // That pointer is probably just the next variadic argument on the caller's stack.
174    _ => {
175        /// Basic implementation of a `va_list`.
176        ///
177        /// `va_copy` is `memcpy`: <https://github.com/llvm/llvm-project/blob/87e8e7d8f0db53060ef2f6ef4ab612fc0f2b4490/llvm/lib/Transforms/IPO/ExpandVariadics.cpp#L127-L129>
178        #[repr(transparent)]
179        #[derive(Debug, Clone, Copy)]
180        struct VaListInner {
181            ptr: *const c_void,
182        }
183    }
184}
185
186/// A variable argument list, ABI-compatible with `va_list` in C.
187///
188/// This type is created in c-variadic functions when `...` is desugared. A `VaList`
189/// is automatically initialized (equivalent to calling `va_start` in C).
190///
191/// ```
192/// #![feature(c_variadic)]
193///
194/// use std::ffi::VaList;
195///
196/// /// # Safety
197/// /// Must be passed at least `count` arguments of type `i32`.
198/// unsafe extern "C" fn my_func(count: u32, ap: ...) -> i32 {
199///     unsafe { vmy_func(count, ap) }
200/// }
201///
202/// /// # Safety
203/// /// Must be passed at least `count` arguments of type `i32`.
204/// unsafe fn vmy_func(count: u32, mut ap: VaList<'_>) -> i32 {
205///     let mut sum = 0;
206///     for _ in 0..count {
207///         sum += unsafe { ap.arg::<i32>() };
208///     }
209///     sum
210/// }
211///
212/// assert_eq!(unsafe { my_func(1, 42i32) }, 42);
213/// assert_eq!(unsafe { my_func(3, 42i32, -7i32, 20i32) }, 55);
214/// ```
215///
216/// The [`VaList::arg`] method can be used to read an argument from the list. This method
217/// automatically advances the `VaList` to the next argument. The C equivalent is `va_arg`.
218///
219/// Cloning a `VaList` performs the equivalent of C `va_copy`, producing an independent cursor
220/// that arguments can be read from without affecting the original. Dropping a `VaList` performs
221/// the equivalent of C `va_end`.
222///
223/// This can be used across an FFI boundary, and fully matches the platform's `va_list`.
224#[repr(transparent)]
225#[lang = "va_list"]
226pub struct VaList<'a> {
227    inner: VaListInner,
228    _marker: PhantomCovariantLifetime<'a>,
229}
230
231impl fmt::Debug for VaList<'_> {
232    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
233        // No need to include `_marker` in debug output.
234        f.debug_tuple("VaList").field(&self.inner).finish()
235    }
236}
237
238impl VaList<'_> {
239    // Helper used in the implementation of the `va_copy` intrinsic.
240    pub(crate) const fn duplicate(&self) -> Self {
241        Self { inner: self.inner, _marker: self._marker }
242    }
243}
244
245#[rustc_const_unstable(feature = "const_c_variadic", issue = "151787")]
246impl<'f> const Clone for VaList<'f> {
247    #[inline]
248    fn clone(&self) -> Self {
249        // We only implement Clone and not Copy because some future target might not be able to
250        // implement Copy (e.g. because it allocates). For the same reason we use an intrinsic
251        // to do the copying: the fact that on all current targets, this is just `memcpy`, is an implementation
252        // detail. The intrinsic lets Miri catch UB from code incorrectly relying on that implementation detail.
253        va_copy(self)
254    }
255}
256
257#[rustc_const_unstable(feature = "const_c_variadic", issue = "151787")]
258impl<'f> const Drop for VaList<'f> {
259    fn drop(&mut self) {
260        // SAFETY: this variable argument list is being dropped, so won't be read from again.
261        unsafe { va_end(self) }
262    }
263}
264
265mod sealed {
266    pub trait Sealed {}
267
268    impl Sealed for i32 {}
269    impl Sealed for i64 {}
270    impl Sealed for isize {}
271
272    impl Sealed for u32 {}
273    impl Sealed for u64 {}
274    impl Sealed for usize {}
275
276    impl Sealed for f64 {}
277
278    impl<T> Sealed for *mut T {}
279    impl<T> Sealed for *const T {}
280}
281
282/// Types that are valid to read using [`VaList::arg`].
283///
284/// # Safety
285///
286/// The standard library implements this trait for primitive types that are
287/// expected to have a variable argument application-binary interface (ABI) on all
288/// platforms.
289///
290/// When C passes variable arguments, integers smaller than [`c_int`] and floats smaller
291/// than [`c_double`] are implicitly promoted to [`c_int`] and [`c_double`] respectively.
292/// Implementing this trait for types that are subject to this promotion rule is invalid.
293///
294/// [`c_int`]: core::ffi::c_int
295/// [`c_double`]: core::ffi::c_double
296// We may unseal this trait in the future, but currently our `va_arg` implementations don't support
297// types with an alignment larger than 8, or with a non-scalar layout. Inline assembly can be used
298// to accept unsupported types in the meantime.
299pub unsafe trait VaArgSafe: sealed::Sealed {}
300
301// i8 and i16 are implicitly promoted to c_int in C, and cannot implement `VaArgSafe`.
302unsafe impl VaArgSafe for i32 {}
303unsafe impl VaArgSafe for i64 {}
304unsafe impl VaArgSafe for isize {}
305
306// u8 and u16 are implicitly promoted to c_int in C, and cannot implement `VaArgSafe`.
307unsafe impl VaArgSafe for u32 {}
308unsafe impl VaArgSafe for u64 {}
309unsafe impl VaArgSafe for usize {}
310
311// f32 is implicitly promoted to c_double in C, and cannot implement `VaArgSafe`.
312unsafe impl VaArgSafe for f64 {}
313
314unsafe impl<T> VaArgSafe for *mut T {}
315unsafe impl<T> VaArgSafe for *const T {}
316
317impl<'f> VaList<'f> {
318    /// Read an argument from the variable argument list, and advance to the next argument.
319    ///
320    /// Only types that implement [`VaArgSafe`] can be read from a variable argument list.
321    ///
322    /// # Safety
323    ///
324    /// This function is only sound to call when there is another argument to read, and that
325    /// argument is a properly initialized value of the type `T`.
326    ///
327    /// Calling this function with an incompatible type, an invalid value, or when there
328    /// are no more variable arguments, is unsound.
329    #[inline]
330    #[rustc_const_unstable(feature = "const_c_variadic", issue = "151787")]
331    pub const unsafe fn arg<T: VaArgSafe>(&mut self) -> T {
332        // SAFETY: the caller must uphold the safety contract for `va_arg`.
333        unsafe { va_arg(self) }
334    }
335}
336
337// Checks (via an assert in `compiler/rustc_ty_utils/src/abi.rs`) that the C ABI for the current
338// target correctly implements `rustc_pass_indirectly_in_non_rustic_abis`.
339const _: () = {
340    #[repr(C)]
341    #[rustc_pass_indirectly_in_non_rustic_abis]
342    struct Type(usize);
343
344    const extern "C" fn c(_: Type) {}
345
346    c(Type(0))
347};
core/ffi/va_list.rs

core/ffi/
va_list.rs
