vendor/compiler_builtins/README.md

   1 # `compiler-builtins`
   2
   3 > Porting `compiler-rt` intrinsics to Rust
   4
   5 See [rust-lang/rust#35437][0].
   6
   7 [0]: https://github.com/rust-lang/rust/issues/35437
   8
   9 ## When and how to use this crate?
  10
  11 If you are working with a target that doesn't have binary releases of std
  12 available via rustup (this probably means you are building the core crate
  13 yourself) and need compiler-rt intrinsics (i.e. you are probably getting linker
  14 errors when building an executable: `undefined reference to __aeabi_memcpy`),
  15 you can use this crate to get those intrinsics and solve the linker errors. To
  16 do that, add this crate somewhere in the dependency graph of the crate you are
  17 building:
  18
  19 ``` toml
  20 # Cargo.toml
  21 [dependencies]
  22 compiler_builtins = { git = "https://github.com/rust-lang/compiler-builtins" }
  23 ```
  24
  25 ``` rust
  26 extern crate compiler_builtins;
  27
  28 // ...
  29 ```
  30
  31 If you still get an "undefined reference to $INTRINSIC" error after that change,
  32 that means that we haven't ported `$INTRINSIC` to Rust yet! Please open [an
  33 issue] with the name of the intrinsic and the LLVM triple (e.g.
  34 thumbv7m-none-eabi) of the target you are using. That way we can prioritize
  35 porting that particular intrinsic.
  36
  37 If you've got a C compiler available for your target then while we implement
  38 this intrinsic you can temporarily enable a fallback to the actual compiler-rt
  39 implementation as well for unimplemented intrinsics:
  40
  41 ```toml
  42 [dependencies.compiler_builtins]
  43 git = "https://github.com/rust-lang/compiler-builtins"
  44 features = ["c"]
  45 ```
  46
  47 [an issue]: https://github.com/rust-lang/compiler-builtins/issues
  48
  49 ## Contributing
  50
  51 1. Pick one or more intrinsics from the [pending list](#progress).
  52 2. Fork this repository.
  53 3. Port the intrinsic(s) and their corresponding [unit tests][1] from their
  54    [C implementation][2] to Rust.
  55 4. Implement a [test generator][3] to compare the behavior of the ported intrinsic(s)
  56    with their implementation on the testing host. Note that randomized compiler-builtin tests
  57    should be run using `cargo test --features gen-tests`.
  58 4. Send a Pull Request (PR).
  59 5. Once the PR passes our extensive [testing infrastructure][4], we'll merge it!
  60 6. Celebrate :tada:
  61
  62 [1]: https://github.com/rust-lang/compiler-rt/tree/8598065bd965d9713bfafb6c1e766d63a7b17b89/test/builtins/Unit
  63 [2]: https://github.com/rust-lang/compiler-rt/tree/8598065bd965d9713bfafb6c1e766d63a7b17b89/lib/builtins
  64 [3]: https://github.com/rust-lang/compiler-builtins/blob/0ba07e49264a54cb5bbd4856fcea083bb3fbec15/build.rs#L180-L265
  65 [4]: https://travis-ci.org/rust-lang/compiler-builtins
  66
  67 ### Porting Reminders
  68
  69 1. [Rust][5a] and [C][5b] have slightly different operator precedence. C evaluates comparisons (`== !=`) before bitwise operations (`& | ^`), while Rust evaluates the other way.
  70 2. C assumes wrapping operations everywhere. Rust panics on overflow when in debug mode. Consider using the [Wrapping][6] type or the explicit [wrapping_*][7] functions where applicable.
  71 3. Note [C implicit casts][8], especially integer promotion. Rust is much more explicit about casting, so be sure that any cast which affects the output is ported to the Rust implementation.
  72 4. Rust has [many functions][9] for integer or floating point manipulation in the standard library. Consider using one of these functions rather than porting a new one.
  73
  74 [5a]: https://doc.rust-lang.org/reference/expressions.html#expression-precedence
  75 [5b]: http://en.cppreference.com/w/c/language/operator_precedence
  76 [6]: https://doc.rust-lang.org/core/num/struct.Wrapping.html
  77 [7]: https://doc.rust-lang.org/std/primitive.i32.html#method.wrapping_add
  78 [8]: http://en.cppreference.com/w/cpp/language/implicit_conversion
  79 [9]: https://doc.rust-lang.org/std/primitive.i32.html
  80
  81 ## Progress
  82
  83 - [x] adddf3.c
  84 - [x] addsf3.c
  85 - [x] arm/adddf3vfp.S
  86 - [x] arm/addsf3vfp.S
  87 - [x] arm/aeabi_dcmp.S
  88 - [x] arm/aeabi_fcmp.S
  89 - [x] arm/aeabi_idivmod.S
  90 - [x] arm/aeabi_ldivmod.S
  91 - [x] arm/aeabi_memcpy.S
  92 - [x] arm/aeabi_memmove.S
  93 - [x] arm/aeabi_memset.S
  94 - [x] arm/aeabi_uidivmod.S
  95 - [x] arm/aeabi_uldivmod.S
  96 - [x] arm/divdf3vfp.S
  97 - [ ] arm/divmodsi4.S (generic version is done)
  98 - [x] arm/divsf3vfp.S
  99 - [ ] arm/divsi3.S (generic version is done)
 100 - [x] arm/eqdf2vfp.S
 101 - [x] arm/eqsf2vfp.S
 102 - [x] arm/extendsfdf2vfp.S
 103 - [ ] arm/fixdfsivfp.S
 104 - [ ] arm/fixsfsivfp.S
 105 - [ ] arm/fixunsdfsivfp.S
 106 - [ ] arm/fixunssfsivfp.S
 107 - [ ] arm/floatsidfvfp.S
 108 - [ ] arm/floatsisfvfp.S
 109 - [ ] arm/floatunssidfvfp.S
 110 - [ ] arm/floatunssisfvfp.S
 111 - [x] arm/gedf2vfp.S
 112 - [x] arm/gesf2vfp.S
 113 - [x] arm/gtdf2vfp.S
 114 - [x] arm/gtsf2vfp.S
 115 - [x] arm/ledf2vfp.S
 116 - [x] arm/lesf2vfp.S
 117 - [x] arm/ltdf2vfp.S
 118 - [x] arm/ltsf2vfp.S
 119 - [ ] arm/modsi3.S (generic version is done)
 120 - [x] arm/muldf3vfp.S
 121 - [x] arm/mulsf3vfp.S
 122 - [x] arm/nedf2vfp.S
 123 - [ ] arm/negdf2vfp.S
 124 - [ ] arm/negsf2vfp.S
 125 - [x] arm/nesf2vfp.S
 126 - [x] arm/softfloat-alias.list
 127 - [x] arm/subdf3vfp.S
 128 - [x] arm/subsf3vfp.S
 129 - [ ] arm/truncdfsf2vfp.S
 130 - [ ] arm/udivmodsi4.S (generic version is done)
 131 - [ ] arm/udivsi3.S (generic version is done)
 132 - [ ] arm/umodsi3.S (generic version is done)
 133 - [ ] arm/unorddf2vfp.S
 134 - [ ] arm/unordsf2vfp.S
 135 - [x] ashldi3.c
 136 - [x] ashrdi3.c
 137 - [x] comparedf2.c
 138 - [x] comparesf2.c
 139 - [x] divdf3.c
 140 - [x] divdi3.c
 141 - [x] divmoddi4.c
 142 - [x] divmodsi4.c
 143 - [x] divsf3.c
 144 - [x] divsi3.c
 145 - [ ] extendhfsf2.c
 146 - [x] extendsfdf2.c
 147 - [x] fixdfdi.c
 148 - [x] fixdfsi.c
 149 - [x] fixsfdi.c
 150 - [x] fixsfsi.c
 151 - [x] fixunsdfdi.c
 152 - [x] fixunsdfsi.c
 153 - [x] fixunssfdi.c
 154 - [x] fixunssfsi.c
 155 - [x] floatdidf.c
 156 - [x] floatdisf.c
 157 - [x] floatsidf.c
 158 - [x] floatsisf.c
 159 - [x] floatundidf.c
 160 - [x] floatundisf.c
 161 - [x] floatunsidf.c
 162 - [x] floatunsisf.c
 163 - [ ] i386/ashldi3.S
 164 - [ ] i386/ashrdi3.S
 165 - [x] i386/chkstk.S
 166 - [x] i386/chkstk2.S
 167 - [ ] i386/divdi3.S
 168 - [ ] i386/lshrdi3.S
 169 - [ ] i386/moddi3.S
 170 - [ ] i386/muldi3.S
 171 - [ ] i386/udivdi3.S
 172 - [ ] i386/umoddi3.S
 173 - [x] lshrdi3.c
 174 - [x] moddi3.c
 175 - [x] modsi3.c
 176 - [x] muldf3.c
 177 - [x] muldi3.c
 178 - [x] mulodi4.c
 179 - [x] mulosi4.c
 180 - [x] mulsf3.c
 181 - [x] powidf2.c
 182 - [x] powisf2.c
 183 - [x] subdf3.c
 184 - [x] subsf3.c
 185 - [ ] truncdfhf2.c
 186 - [ ] truncdfsf2.c
 187 - [ ] truncsfhf2.c
 188 - [x] udivdi3.c
 189 - [x] udivmoddi4.c
 190 - [x] udivmodsi4.c
 191 - [x] udivsi3.c
 192 - [x] umoddi3.c
 193 - [x] umodsi3.c
 194 - [x] x86_64/chkstk.S
 195 - [x] x86_64/chkstk2.S
 196
 197 These builtins are needed to support 128-bit integers, which are in the process of being added to Rust.
 198
 199 - [x] ashlti3.c
 200 - [x] ashrti3.c
 201 - [x] divti3.c
 202 - [x] fixdfti.c
 203 - [x] fixsfti.c
 204 - [x] fixunsdfti.c
 205 - [x] fixunssfti.c
 206 - [x] floattidf.c
 207 - [x] floattisf.c
 208 - [x] floatuntidf.c
 209 - [x] floatuntisf.c
 210 - [x] lshrti3.c
 211 - [x] modti3.c
 212 - [x] muloti4.c
 213 - [x] multi3.c
 214 - [x] udivmodti4.c
 215 - [x] udivti3.c
 216 - [x] umodti3.c
 217
 218 ## Unimplemented functions
 219
 220 These builtins involve floating-point types ("`f128`", "`f80`" and complex numbers) that are not supported by Rust.
 221
 222 - ~~addtf3.c~~
 223 - ~~comparetf2.c~~
 224 - ~~divdc3.c~~
 225 - ~~divsc3.c~~
 226 - ~~divtc3.c~~
 227 - ~~divtf3.c~~
 228 - ~~divxc3.c~~
 229 - ~~extenddftf2.c~~
 230 - ~~extendsftf2.c~~
 231 - ~~fixtfdi.c~~
 232 - ~~fixtfsi.c~~
 233 - ~~fixtfti.c~~
 234 - ~~fixunstfdi.c~~
 235 - ~~fixunstfsi.c~~
 236 - ~~fixunstfti.c~~
 237 - ~~fixunsxfdi.c~~
 238 - ~~fixunsxfsi.c~~
 239 - ~~fixunsxfti.c~~
 240 - ~~fixxfdi.c~~
 241 - ~~fixxfti.c~~
 242 - ~~floatditf.c~~
 243 - ~~floatdixf.c~~
 244 - ~~floatsitf.c~~
 245 - ~~floattixf.c~~
 246 - ~~floatunditf.c~~
 247 - ~~floatundixf.c~~
 248 - ~~floatunsitf.c~~
 249 - ~~floatuntixf.c~~
 250 - ~~i386/floatdixf.S~~
 251 - ~~i386/floatundixf.S~~
 252 - ~~muldc3.c~~
 253 - ~~mulsc3.c~~
 254 - ~~multc3.c~~
 255 - ~~multf3.c~~
 256 - ~~mulxc3.c~~
 257 - ~~powitf2.c~~
 258 - ~~powixf2.c~~
 259 - ~~ppc/divtc3.c~~
 260 - ~~ppc/fixtfdi.c~~
 261 - ~~ppc/fixunstfdi.c~~
 262 - ~~ppc/floatditf.c~~
 263 - ~~ppc/floatunditf.c~~
 264 - ~~ppc/gcc_qadd.c~~
 265 - ~~ppc/gcc_qdiv.c~~
 266 - ~~ppc/gcc_qmul.c~~
 267 - ~~ppc/gcc_qsub.c~~
 268 - ~~ppc/multc3.c~~
 269 - ~~subtf3.c~~
 270 - ~~trunctfdf2.c~~
 271 - ~~trunctfsf2.c~~
 272 - ~~x86_64/floatdixf.c~~
 273 - ~~x86_64/floatundixf.S~~
 274
 275 These builtins are never called by LLVM.
 276
 277 - ~~absvdi2.c~~
 278 - ~~absvsi2.c~~
 279 - ~~absvti2.c~~
 280 - ~~addvdi3.c~~
 281 - ~~addvsi3.c~~
 282 - ~~addvti3.c~~
 283 - ~~arm/aeabi_cdcmp.S~~
 284 - ~~arm/aeabi_cdcmpeq_check_nan.c~~
 285 - ~~arm/aeabi_cfcmp.S~~
 286 - ~~arm/aeabi_cfcmpeq_check_nan.c~~
 287 - ~~arm/aeabi_div0.c~~
 288 - ~~arm/aeabi_drsub.c~~
 289 - ~~arm/aeabi_frsub.c~~
 290 - ~~arm/aeabi_memcmp.S~~
 291 - ~~arm/bswapdi2.S~~
 292 - ~~arm/bswapsi2.S~~
 293 - ~~arm/clzdi2.S~~
 294 - ~~arm/clzsi2.S~~
 295 - ~~arm/comparesf2.S~~
 296 - ~~arm/restore_vfp_d8_d15_regs.S~~
 297 - ~~arm/save_vfp_d8_d15_regs.S~~
 298 - ~~arm/switch16.S~~
 299 - ~~arm/switch32.S~~
 300 - ~~arm/switch8.S~~
 301 - ~~arm/switchu8.S~~
 302 - ~~clzdi2.c~~
 303 - ~~clzsi2.c~~
 304 - ~~clzti2.c~~
 305 - ~~cmpdi2.c~~
 306 - ~~cmpti2.c~~
 307 - ~~ctzdi2.c~~
 308 - ~~ctzsi2.c~~
 309 - ~~ctzti2.c~~
 310 - ~~ffsdi2.c~~ - this is [called by gcc][jemalloc-fail] though!
 311 - ~~ffsti2.c~~
 312 - ~~mulvdi3.c~~
 313 - ~~mulvsi3.c~~
 314 - ~~mulvti3.c~~
 315 - ~~negdf2.c~~
 316 - ~~negdi2.c~~
 317 - ~~negsf2.c~~
 318 - ~~negti2.c~~
 319 - ~~negvdi2.c~~
 320 - ~~negvsi2.c~~
 321 - ~~negvti2.c~~
 322 - ~~paritydi2.c~~
 323 - ~~paritysi2.c~~
 324 - ~~parityti2.c~~
 325 - ~~popcountdi2.c~~
 326 - ~~popcountsi2.c~~
 327 - ~~popcountti2.c~~
 328 - ~~ppc/restFP.S~~
 329 - ~~ppc/saveFP.S~~
 330 - ~~subvdi3.c~~
 331 - ~~subvsi3.c~~
 332 - ~~subvti3.c~~
 333 - ~~ucmpdi2.c~~
 334 - ~~ucmpti2.c~~
 335 - ~~udivmodti4.c~~
 336
 337 [jemalloc-fail]: https://travis-ci.org/rust-lang/rust/jobs/249772758
 338
 339 Rust only exposes atomic types on platforms that support them, and therefore does not need to fall back to software implementations.
 340
 341 - ~~arm/sync_fetch_and_add_4.S~~
 342 - ~~arm/sync_fetch_and_add_8.S~~
 343 - ~~arm/sync_fetch_and_and_4.S~~
 344 - ~~arm/sync_fetch_and_and_8.S~~
 345 - ~~arm/sync_fetch_and_max_4.S~~
 346 - ~~arm/sync_fetch_and_max_8.S~~
 347 - ~~arm/sync_fetch_and_min_4.S~~
 348 - ~~arm/sync_fetch_and_min_8.S~~
 349 - ~~arm/sync_fetch_and_nand_4.S~~
 350 - ~~arm/sync_fetch_and_nand_8.S~~
 351 - ~~arm/sync_fetch_and_or_4.S~~
 352 - ~~arm/sync_fetch_and_or_8.S~~
 353 - ~~arm/sync_fetch_and_sub_4.S~~
 354 - ~~arm/sync_fetch_and_sub_8.S~~
 355 - ~~arm/sync_fetch_and_umax_4.S~~
 356 - ~~arm/sync_fetch_and_umax_8.S~~
 357 - ~~arm/sync_fetch_and_umin_4.S~~
 358 - ~~arm/sync_fetch_and_umin_8.S~~
 359 - ~~arm/sync_fetch_and_xor_4.S~~
 360 - ~~arm/sync_fetch_and_xor_8.S~~
 361 - ~~arm/sync_synchronize.S~~
 362 - ~~atomic.c~~
 363 - ~~atomic_flag_clear.c~~
 364 - ~~atomic_flag_clear_explicit.c~~
 365 - ~~atomic_flag_test_and_set.c~~
 366 - ~~atomic_flag_test_and_set_explicit.c~~
 367 - ~~atomic_signal_fence.c~~
 368 - ~~atomic_thread_fence.c~~
 369
 370 Miscellaneous functionality that is not used by Rust.
 371
 372 - ~~apple_versioning.c~~
 373 - ~~clear_cache.c~~
 374 - ~~emutls.c~~
 375 - ~~enable_execute_stack.c~~
 376 - ~~eprintf.c~~
 377 - ~~gcc_personality_v0.c~~
 378 - ~~trampoline_setup.c~~
 379
 380 Floating-point implementations of builtins that are only called from soft-float code. It would be better to simply use the generic soft-float versions in this case.
 381
 382 - ~~i386/floatdidf.S~~
 383 - ~~i386/floatdisf.S~~
 384 - ~~i386/floatundidf.S~~
 385 - ~~i386/floatundisf.S~~
 386 - ~~x86_64/floatundidf.S~~
 387 - ~~x86_64/floatundisf.S~~
 388 - ~~x86_64/floatdidf.c~~
 389 - ~~x86_64/floatdisf.c~~
 390
 391 ## License
 392
 393 The compiler-builtins crate is dual licensed under both the University of
 394 Illinois "BSD-Like" license and the MIT license.  As a user of this code you may
 395 choose to use it under either license.  As a contributor, you agree to allow
 396 your code to be used under both.
 397
 398 Full text of the relevant licenses is in LICENSE.TXT.