src/libcore/ffi.rs

   1 #![stable(feature = "", since = "1.30.0")]
   2
   3 #![allow(non_camel_case_types)]
   4 #![cfg_attr(stage0, allow(dead_code))]
   5
   6 //! Utilities related to FFI bindings.
   7
   8 use ::fmt;
   9
  10 /// Equivalent to C's `void` type when used as a [pointer].
  11 ///
  12 /// In essence, `*const c_void` is equivalent to C's `const void*`
  13 /// and `*mut c_void` is equivalent to C's `void*`. That said, this is
  14 /// *not* the same as C's `void` return type, which is Rust's `()` type.
  15 ///
  16 /// Ideally, this type would be equivalent to [`!`], but currently it may
  17 /// be more ideal to use `c_void` for FFI purposes.
  18 ///
  19 /// [`!`]: ../../std/primitive.never.html
  20 /// [pointer]: ../../std/primitive.pointer.html
  21 // NB: For LLVM to recognize the void pointer type and by extension
  22 //     functions like malloc(), we need to have it represented as i8* in
  23 //     LLVM bitcode. The enum used here ensures this and prevents misuse
  24 //     of the "raw" type by only having private variants.. We need two
  25 //     variants, because the compiler complains about the repr attribute
  26 //     otherwise.
  27 #[repr(u8)]
  28 #[stable(feature = "raw_os", since = "1.1.0")]
  29 pub enum c_void {
  30     #[unstable(feature = "c_void_variant", reason = "should not have to exist",
  31                issue = "0")]
  32     #[doc(hidden)] __variant1,
  33     #[unstable(feature = "c_void_variant", reason = "should not have to exist",
  34                issue = "0")]
  35     #[doc(hidden)] __variant2,
  36 }
  37
  38 #[stable(feature = "std_debug", since = "1.16.0")]
  39 impl fmt::Debug for c_void {
  40     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  41         f.pad("c_void")
  42     }
  43 }
  44
  45 /// Basic implementation of a `va_list`.
  46 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
  47               not(target_arch = "x86_64")),
  48           all(target_arch = "aarch4", target_os = "ios"),
  49           windows))]
  50 #[unstable(feature = "c_variadic",
  51            reason = "the `c_variadic` feature has not been properly tested on \
  52                      all supported platforms",
  53            issue = "27745")]
  54 extern {
  55     type VaListImpl;
  56 }
  57
  58 #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
  59               not(target_arch = "x86_64")),
  60           windows))]
  61 impl fmt::Debug for VaListImpl {
  62     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  63         write!(f, "va_list* {:p}", self)
  64     }
  65 }
  66
  67 /// AArch64 ABI implementation of a `va_list`. See the
  68 /// [Aarch64 Procedure Call Standard] for more details.
  69 ///
  70 /// [AArch64 Procedure Call Standard]:
  71 /// http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf
  72 #[cfg(all(target_arch = "aarch64", not(windows)))]
  73 #[repr(C)]
  74 #[derive(Debug)]
  75 #[unstable(feature = "c_variadic",
  76            reason = "the `c_variadic` feature has not been properly tested on \
  77                      all supported platforms",
  78            issue = "27745")]
  79 struct VaListImpl {
  80     stack: *mut (),
  81     gr_top: *mut (),
  82     vr_top: *mut (),
  83     gr_offs: i32,
  84     vr_offs: i32,
  85 }
  86
  87 /// PowerPC ABI implementation of a `va_list`.
  88 #[cfg(all(target_arch = "powerpc", not(windows)))]
  89 #[repr(C)]
  90 #[derive(Debug)]
  91 #[unstable(feature = "c_variadic",
  92            reason = "the `c_variadic` feature has not been properly tested on \
  93                      all supported platforms",
  94            issue = "27745")]
  95 struct VaListImpl {
  96     gpr: u8,
  97     fpr: u8,
  98     reserved: u16,
  99     overflow_arg_area: *mut (),
 100     reg_save_area: *mut (),
 101 }
 102
 103 /// x86_64 ABI implementation of a `va_list`.
 104 #[cfg(all(target_arch = "x86_64", not(windows)))]
 105 #[repr(C)]
 106 #[derive(Debug)]
 107 #[unstable(feature = "c_variadic",
 108            reason = "the `c_variadic` feature has not been properly tested on \
 109                      all supported platforms",
 110            issue = "27745")]
 111 struct VaListImpl {
 112     gp_offset: i32,
 113     fp_offset: i32,
 114     overflow_arg_area: *mut (),
 115     reg_save_area: *mut (),
 116 }
 117
 118 /// A wrapper for a `va_list`
 119 #[lang = "va_list"]
 120 #[derive(Debug)]
 121 #[unstable(feature = "c_variadic",
 122            reason = "the `c_variadic` feature has not been properly tested on \
 123                      all supported platforms",
 124            issue = "27745")]
 125 #[repr(transparent)]
 126 #[cfg(not(stage0))]
 127 pub struct VaList<'a>(&'a mut VaListImpl);
 128
 129 // The VaArgSafe trait needs to be used in public interfaces, however, the trait
 130 // itself must not be allowed to be used outside this module. Allowing users to
 131 // implement the trait for a new type (thereby allowing the va_arg intrinsic to
 132 // be used on a new type) is likely to cause undefined behavior.
 133 //
 134 // FIXME(dlrobertson): In order to use the VaArgSafe trait in a public interface
 135 // but also ensure it cannot be used elsewhere, the trait needs to be public
 136 // within a private module. Once RFC 2145 has been implemented look into
 137 // improving this.
 138 mod sealed_trait {
 139     /// Trait which whitelists the allowed types to be used with [VaList::arg]
 140     ///
 141     /// [VaList::va_arg]: struct.VaList.html#method.arg
 142     #[unstable(feature = "c_variadic",
 143                reason = "the `c_variadic` feature has not been properly tested on \
 144                          all supported platforms",
 145                issue = "27745")]
 146     pub trait VaArgSafe {}
 147 }
 148
 149 macro_rules! impl_va_arg_safe {
 150     ($($t:ty),+) => {
 151         $(
 152             #[unstable(feature = "c_variadic",
 153                        reason = "the `c_variadic` feature has not been properly tested on \
 154                                  all supported platforms",
 155                        issue = "27745")]
 156             impl sealed_trait::VaArgSafe for $t {}
 157         )+
 158     }
 159 }
 160
 161 impl_va_arg_safe!{i8, i16, i32, i64, usize}
 162 impl_va_arg_safe!{u8, u16, u32, u64, isize}
 163 impl_va_arg_safe!{f64}
 164
 165 #[unstable(feature = "c_variadic",
 166            reason = "the `c_variadic` feature has not been properly tested on \
 167                      all supported platforms",
 168            issue = "27745")]
 169 impl<T> sealed_trait::VaArgSafe for *mut T {}
 170 #[unstable(feature = "c_variadic",
 171            reason = "the `c_variadic` feature has not been properly tested on \
 172                      all supported platforms",
 173            issue = "27745")]
 174 impl<T> sealed_trait::VaArgSafe for *const T {}
 175
 176 #[cfg(not(stage0))]
 177 impl<'a> VaList<'a> {
 178     /// Advance to the next arg.
 179     #[unstable(feature = "c_variadic",
 180                reason = "the `c_variadic` feature has not been properly tested on \
 181                          all supported platforms",
 182                issue = "27745")]
 183     pub unsafe fn arg<T: sealed_trait::VaArgSafe>(&mut self) -> T {
 184         va_arg(self)
 185     }
 186
 187     /// Copy the `va_list` at the current location.
 188     #[unstable(feature = "c_variadic",
 189                reason = "the `c_variadic` feature has not been properly tested on \
 190                          all supported platforms",
 191                issue = "27745")]
 192     pub unsafe fn copy<F, R>(&mut self, f: F) -> R
 193             where F: for<'copy> FnOnce(VaList<'copy>) -> R {
 194         #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
 195                       not(target_arch = "x86_64")),
 196                   all(target_arch = "aarch4", target_os = "ios"),
 197                   windows))]
 198         let mut ap = va_copy(self);
 199         #[cfg(all(any(target_arch = "aarch64", target_arch = "powerpc", target_arch = "x86_64"),
 200                   not(windows)))]
 201         let mut ap_inner = va_copy(self);
 202         #[cfg(all(any(target_arch = "aarch64", target_arch = "powerpc", target_arch = "x86_64"),
 203                   not(windows)))]
 204         let mut ap = VaList(&mut ap_inner);
 205         let ret = f(VaList(ap.0));
 206         va_end(&mut ap);
 207         ret
 208     }
 209 }
 210
 211 #[cfg(not(stage0))]
 212 extern "rust-intrinsic" {
 213     /// Destroy the arglist `ap` after initialization with `va_start` or
 214     /// `va_copy`.
 215     fn va_end(ap: &mut VaList);
 216
 217     /// Copy the current location of arglist `src` to the arglist `dst`.
 218     #[cfg(any(all(not(target_arch = "aarch64"), not(target_arch = "powerpc"),
 219                   not(target_arch = "x86_64")),
 220               windows))]
 221     fn va_copy<'a>(src: &VaList<'a>) -> VaList<'a>;
 222     #[cfg(all(any(target_arch = "aarch64", target_arch = "powerpc", target_arch = "x86_64"),
 223               not(windows)))]
 224     fn va_copy(src: &VaList) -> VaListImpl;
 225
 226     /// Loads an argument of type `T` from the `va_list` `ap` and increment the
 227     /// argument `ap` points to.
 228     fn va_arg<T: sealed_trait::VaArgSafe>(ap: &mut VaList) -> T;
 229 }