os/assumes.h

   1 /* Copyright (c) 2012, 2012 Apple Inc. All rights reserved.
   2  *
   3  * @APPLE_LICENSE_HEADER_START@
   4  *
   5  * This file contains Original Code and/or Modifications of Original Code
   6  * as defined in and that are subject to the Apple Public Source License
   7  * Version 2.0 (the 'License'). You may not use this file except in
   8  * compliance with the License. Please obtain a copy of the License at
   9  * http://www.opensource.apple.com/apsl/ and read it before using this
  10  * file.
  11  *
  12  * The Original Code and all software distributed under the License are
  13  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  17  * Please see the License for the specific language governing rights and
  18  * limitations under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22
  23 #ifndef __OS_ASSUMES_H__
  24 #define __OS_ASSUMES_H__
  25
  26 #include <sys/cdefs.h>
  27 #include <stdalign.h>
  28
  29 __BEGIN_DECLS
  30
  31 #include <Availability.h>
  32 #include <TargetConditionals.h>
  33 #include <stdlib.h>
  34 #include <stdint.h>
  35 #include <stdarg.h>
  36 #include <stdbool.h>
  37 #include <_simple.h>
  38 #include <errno.h>
  39 #include <os/base_private.h>
  40 #include <stdint.h>
  41
  42 #if __GNUC__
  43 #define os_constant(x) __builtin_constant_p((x))
  44 #define os_hardware_trap() __asm__ __volatile__ (""); __builtin_trap()
  45 #define __OS_COMPILETIME_ASSERT__(e) __extension__({ \
  46         char __compile_time_assert__[(e) ? 1 : -1];     \
  47         (void)__compile_time_assert__; \
  48 })
  49 #else /* __GNUC__ */
  50 #define os_constant(x) ((long)0)
  51 #define os_hardware_trap() abort()
  52 #define __OS_COMPILETIME_ASSERT__(e) (e)
  53 #endif /* __GNUC__ */
  54
  55 #pragma mark os_crash
  56
  57 /*
  58  * os_crash() is like os_hardware_trap(), except you get to pass in a crash
  59  * message, and it can be redirected to a callback function using
  60  * os_set_crash_callback()
  61  */
  62
  63 #define __os_crash_simple(msg) \
  64         ({               \
  65                 _os_crash(msg);                 \
  66                 os_hardware_trap();             \
  67         })
  68
  69 #if defined(OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE)
  70 #include <os/log_private.h>
  71
  72 #define __os_crash_fmt(...) \
  73         ({ \
  74                 const size_t size = os_log_pack_size(__VA_ARGS__); \
  75                 uint8_t buf[size] __attribute__((aligned(alignof(os_log_pack_s)))); \
  76                 os_log_pack_t pack = (os_log_pack_t)&buf; \
  77                 os_log_pack_fill(pack, size, errno, __VA_ARGS__); \
  78                 _os_crash_fmt(pack, size); \
  79                 os_hardware_trap(); \
  80         })
  81
  82 #define __os_crash_N(msg) __os_crash_simple(msg)
  83 #define __os_crash_Y(...) __os_crash_fmt(__VA_ARGS__)
  84
  85 // Returns Y if >1 argument, N if just one argument.
  86 #define __thirty_second_argument(_1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, \
  87                 _12, _13, _14, _15, _16, _17, _18, _19, _20, _21, _22, _23, _24, _25, \
  88                 _26, _27, _28, _29, _30, _31, _32, ...) _32
  89 #define __has_more_than_one_argument(...) __thirty_second_argument(__VA_ARGS__, \
  90                 Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, Y, \
  91                 Y, Y, Y, Y, Y, Y, Y, N, EXTRA)
  92
  93 #define __os_crash_invoke(variant, ...) \
  94         OS_CONCAT(__os_crash_, variant)(__VA_ARGS__)
  95
  96 #define os_crash(...) \
  97         __os_crash_invoke(__has_more_than_one_argument(__VA_ARGS__), __VA_ARGS__)
  98
  99 OS_COLD
 100 extern void
 101 _os_crash_fmt(os_log_pack_t, size_t);
 102
 103 /*!
 104  * @function os_assert_sprintf
 105  * A routine to assert the result of a call to snprintf(3) or vsnprintf(3).
 106  *
 107  * @param ret
 108  * The return value from {v}snprintf(3).
 109  *
 110  * @param buff_size
 111  * The size of the buffer given to {v}snprintf(3).
 112  *
 113  * @discussion
 114  * If ret is less than zero or greater than size, the routine will abort the
 115  * caller with a message indicating the nature of the failure in the Application
 116  * Specific Information section of the resulting crash log.
 117  *
 118  * This routine is useful for printing paths that are expected to succeed with a
 119  * statically-sized buffer.
 120  */
 121 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 122 OS_ALWAYS_INLINE OS_COLD
 123 static inline void
 124 os_assert_sprintf(int ret, size_t buff_size)
 125 {
 126         if (ret < 0) {
 127                 os_crash("error printing buffer: %s", strerror(errno));
 128         }
 129
 130         if ((size_t)ret > buff_size) {
 131                 os_crash("buffer too small: needed = %d, actual = %lu",
 132                                 ret, buff_size);
 133         }
 134 }
 135
 136 /*!
 137  * @function os_assert_asprintf
 138  * A routine to assert the result of a call to {v}asprintf(3).
 139  *
 140  * @param ret
 141  * The return value from {v}asnprintf(3).
 142  *
 143  * @discussion
 144  * If ret is less than zero, the routine will abort the caller with a message
 145  * indicating the nature of the failure in the Application Specific Information
 146  * section of the resulting crash log.
 147  */
 148 API_AVAILABLE(macos(10.15.2), ios(13.3), tvos(13.3), watchos(6.1.1))
 149 OS_ALWAYS_INLINE OS_COLD
 150 static inline void
 151 os_assert_asprintf(int ret)
 152 {
 153         if (ret < 0) {
 154                 os_crash("error printing buffer: %s", strerror(errno));
 155         }
 156 }
 157
 158 /*!
 159  * @function os_assert_malloc
 160  * A routine to assert the result of allocations which may fail.
 161  *
 162  * @param desc
 163  * A string describing the object whose allocation was attempted.
 164  *
 165  * @param p
 166  * The result of a call to malloc(3), calloc(3), et al.
 167  *
 168  * @param alloc_size
 169  * The size of the attempted allocation.
 170  *
 171  * @discussion
 172  * If {@link p} is NULL, the routine will abort the caller with a message
 173  * indicating the nature of the failure in the Application Specific Information
 174  * section of the resulting crash log.
 175  */
 176 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 177 OS_ALWAYS_INLINE
 178 static inline void
 179 os_assert_malloc(const char *desc, const void *const p, size_t alloc_size)
 180 {
 181         if (!p) {
 182                 os_crash("allocation failed: obj = %s, size = %lu, error = %s",
 183                                 desc, alloc_size, strerror(errno));
 184         }
 185 }
 186
 187 /*!
 188  * @function os_assert_mach
 189  * A routine to assert the result of a Mach kernel routine.
 190  *
 191  * @param op
 192  * A human-readable description of the operation.
 193  *
 194  * @param kr
 195  * The return code.
 196  *
 197  * @discsussion
 198  * If {@link kr} is non-zero, this routine will abort the caller with a message
 199  * indicating the nature of the failure in the Application Specific Information
 200  * section of the resulting crash log.
 201  */
 202 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 203 OS_EXPORT OS_NONNULL1 OS_COLD
 204 void
 205 os_assert_mach(const char *op, kern_return_t kr);
 206
 207 #define os_assert_mach(op, kr) ({ \
 208                 kern_return_t __kr = (kr); \
 209                 if (os_unlikely(__kr != KERN_SUCCESS)) os_assert_mach(op, kr); \
 210 })
 211
 212 /*!
 213  * @function os_assert_mach_port_status
 214  * A routine to assert the status of a Mach port.
 215  *
 216  * @param desc
 217  * A human-readable description of the port's purpose.
 218  *
 219  * @param p
 220  * The port.
 221  *
 222  * @param expected
 223  * A pointer to a mach_port_status_t describing the expected attributes of the
 224  * port. If no particular value is expected for a given field in the structure,
 225  * a sentinel value may be provided for each expected field to indicate that its
 226  * check should be elided. The sentival values are:
 227  *
 228  * mps_pset => UINT32_MAX
 229  * mps_seqno => UINT32_MAX
 230  * mps_mscount => UINT32_MAX
 231  * mps_qlimit => UINT32_MAX
 232  * mps_msgcount => UINT32_MAX
 233  * mps_sorights => UINT32_MAX
 234  * mps_srights => INT32_MAX
 235  * mps_pdrequest => INT32_MAX
 236  * mps_nsrequest => INT32_MAX
 237  * mps_flags => 0
 238  *
 239  * @discussion
 240  * If there are any mismatches in the expected and actual status of the port,
 241  * the implementation will abort the caller. If status cannot be obtained for
 242  * the given port, the implementation will abort the caller.
 243  */
 244 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 245 OS_EXPORT
 246 void
 247 os_assert_mach_port_status(const char *desc, mach_port_t p,
 248                 mach_port_status_t *expected);
 249
 250 #else // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 251
 252 #define os_crash(msg) __os_crash_simple(msg)
 253
 254 #endif // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 255
 256 /*
 257  * An executable can register a callback to be made upon a crash using the
 258  * os_set_crash_callback function.  If a crash callback is not set, the symbol
 259  * `os_crash_function` will be called in the main binary, if it exists.
 260  */
 261
 262 typedef void (*os_crash_callback_t) (const char *);
 263
 264 /* private: use accessors below */
 265 extern os_crash_callback_t _os_crash_callback;
 266
 267 static inline os_crash_callback_t
 268 os_get_crash_callback() {
 269         return _os_crash_callback;
 270 }
 271
 272 static inline void
 273 os_set_crash_callback(os_crash_callback_t callback) {
 274         _os_crash_callback = callback;
 275 }
 276
 277 #pragma mark os_assert
 278
 279 #if defined(OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE)
 280
 281 #define _os_assert_crash(value, expression) ({ \
 282                 os_crash("assertion failure: \"" expression "\" -> %lld", value); \
 283 })
 284
 285 #define _os_assert_crash_errno(value, expression) ({ \
 286                 os_crash("assertion failure: \"" expression "\" -> %{errno}d", value); \
 287 })
 288
 289 #else // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 290
 291 #define _os_assert_crash(e, ...) ({ \
 292                 char *_fail_message = _os_assert_log(e); \
 293                 os_crash(_fail_message); \
 294                 free(_fail_message); \
 295 })
 296
 297 #define _os_assert_crash_errno(...) _os_assert_crash(__VA_ARGS__)
 298
 299 #endif // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 300
 301 #define __os_assert(e) __extension__({ \
 302         __typeof__(e) _e = (e); \
 303         if (os_unlikely(!_e)) { \
 304                 if (os_constant(e)) { __OS_COMPILETIME_ASSERT__((e)); } \
 305                 _os_assert_crash((uint64_t)(uintptr_t)_e, #e); \
 306         } \
 307 })
 308
 309 #define __os_assert_zero(e) __extension__({ \
 310         __typeof__(e) _e = (e); \
 311         if (os_unlikely(_e)) { \
 312                 if (os_constant(e)) { __OS_COMPILETIME_ASSERT__(!(e)); } \
 313                 _os_assert_crash((uint64_t)(uintptr_t)_e, #e); \
 314         } \
 315 })
 316
 317 /*
 318  * This variant is for use with old-style POSIX APIs that return -1 on failure
 319  * and set errno. If the return code is -1, the value logged will be as though
 320  * os_assert_zero(errno) was used. It encapsulates the following pattern:
 321  *
 322  * int tubes[2];
 323  * if (pipe(tubes) == -1) {
 324  *     (void)os_assert_zero(errno);
 325  * }
 326  */
 327 #define __posix_assert_zero(e) __extension__({ \
 328         __typeof__(e) _e = (e); \
 329         if (os_unlikely(_e == (__typeof__(e))-1)) { \
 330                 _os_assert_crash_errno(errno, #e); \
 331         } \
 332 })
 333
 334 #if defined(OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE)
 335
 336 #define __os_assert_msg(e, fmt, ...) __extension__({ \
 337         __typeof__(e) _e = (e); \
 338         if (os_unlikely(!_e)) { \
 339                 os_crash("assertion failure: " fmt, ##__VA_ARGS__); \
 340         } \
 341 })
 342
 343 #define __os_assert_zero_msg(e, fmt, ...) __extension__({ \
 344         __typeof__(e) _e = (e); \
 345         if (os_unlikely(_e)) { \
 346                 os_crash("assertion failure (%lld): " fmt, value, ##__VA_ARGS__); \
 347         } \
 348 })
 349
 350 #define __posix_assert_zero_msg(e, fmt, ...) __extension__({ \
 351         __typeof__(e) _e = (e); \
 352         if (os_unlikely(_e == (__typeof__(e))-1)) { \
 353                 os_crash("assertion failure (%{errno}d): " fmt, errno, ##__VA_ARGS__); \
 354         } \
 355 })
 356
 357 #define __os_assert_N(e) __os_assert(e)
 358 #define __os_assert_Y(...) __os_assert_msg(__VA_ARGS__)
 359 #define __os_assert_zero_N(e) __os_assert_zero(e)
 360 #define __os_assert_zero_Y(...) __os_assert_zero_msg(__VA_ARGS__)
 361 #define __posix_assert_zero_N(e) __posix_assert_zero(e)
 362 #define __posix_assert_zero_Y(...) __posix_assert_zero_msg(__VA_ARGS__)
 363
 364 #define __os_assert_invoke(function, variant, ...) \
 365         OS_CONCAT(function, variant)(__VA_ARGS__)
 366
 367 #define os_assert(...) \
 368         __os_assert_invoke(__os_assert_, \
 369                         __has_more_than_one_argument(__VA_ARGS__), __VA_ARGS__)
 370 #define os_assert_zero(...) \
 371         __os_assert_invoke(__os_assert_zero_, \
 372                         __has_more_than_one_argument(__VA_ARGS__), __VA_ARGS__)
 373 #define posix_assert_zero(...) \
 374         __os_assert_invoke(__posix_assert_zero_, \
 375                         __has_more_than_one_argument(__VA_ARGS__), __VA_ARGS__)
 376
 377 #else // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 378
 379 #define os_assert(e) __os_assert(e)
 380 #define os_assert_zero(e) __os_assert_zero(e)
 381 #define posix_assert_zero(e) __posix_assert_zero(e)
 382
 383 #endif
 384
 385 #pragma mark os_assumes
 386
 387
 388 #define os_assumes(e) __extension__({ \
 389         __typeof__(e) _e = os_fastpath(e); \
 390         if (!_e) { \
 391                 if (os_constant(e)) { \
 392                         __OS_COMPILETIME_ASSERT__(e); \
 393                 } \
 394                 _os_assumes_log((uint64_t)(uintptr_t)_e); \
 395         } \
 396         _e; \
 397 })
 398
 399 #define os_assumes_zero(e) __extension__({ \
 400         __typeof__(e) _e = os_slowpath(e); \
 401         if (_e) { \
 402                 if (os_constant(e)) { \
 403                         __OS_COMPILETIME_ASSERT__(!(e)); \
 404                 } \
 405                 _os_assumes_log((uint64_t)(uintptr_t)_e); \
 406         } \
 407         _e; \
 408 })
 409
 410 #define posix_assumes_zero(e) __extension__({ \
 411         __typeof__(e) _e = os_slowpath(e); \
 412         if (_e == (__typeof__(e))-1) { \
 413                 _os_assumes_log((uint64_t)(uintptr_t)errno); \
 414         } \
 415         _e; \
 416 })
 417
 418 #pragma mark assumes redirection
 419
 420 /* This is useful for clients who wish for the messages generated by assumes()
 421  * failures to go somewhere other than (or in addition to) the system log. If
 422  * you don't wish for the message to be logged to the system log, then return
 423  * true (to indicate that the message has been handled). If you want the default
 424  * behavior, return false.
 425  */
 426 typedef bool (*os_redirect_t)(const char *);
 427 struct _os_redirect_assumes_s {
 428         os_redirect_t redirect;
 429 };
 430
 431 #define OS_ASSUMES_REDIRECT_SEG "__DATA"
 432 #define OS_ASSUMES_REDIRECT_SECT "__os_assumes_log"
 433
 434 #define os_redirect_assumes(func) \
 435         __attribute__((__used__)) \
 436         __attribute__((__section__(OS_ASSUMES_REDIRECT_SEG "," OS_ASSUMES_REDIRECT_SECT))) \
 437         static struct _os_redirect_assumes_s _os_redirect_##func = { \
 438                 .redirect = &func, \
 439         };
 440
 441 #pragma mark _ctx variants
 442
 443 /*
 444  * These are for defining your own assumes()-like wrapper calls so that you can
 445  * log additional information, such as the about-PID, sender, etc. They're
 446  * generally not useful for direct inclusion in your code.
 447  */
 448
 449 /*
 450  * The asl_message argument is a _SIMPLE_STRING that, when given to _simple_asl_send(), will
 451  * direct the message to the MessageTracer diagnostic messages store rather than
 452  * the default system log store.
 453  */
 454 typedef bool (*os_log_callout_t)(_SIMPLE_STRING asl_message, void *ctx, const char *);
 455
 456
 457 #define os_assumes_ctx(f, ctx, e) __extension__({ \
 458         __typeof__(e) _e = os_fastpath(e); \
 459         if (!_e) { \
 460                 if (os_constant(e)) { \
 461                         __OS_COMPILETIME_ASSERT__(e); \
 462                 } \
 463                 _os_assumes_log_ctx(f, ctx, (uintptr_t)_e); \
 464         } \
 465         _e; \
 466 })
 467
 468 #define os_assumes_zero_ctx(f, ctx, e) __extension__({ \
 469         __typeof__(e) _e = os_slowpath(e); \
 470         if (_e) { \
 471                 if (os_constant(e)) { \
 472                         __OS_COMPILETIME_ASSERT__(!(e)); \
 473                 } \
 474                 _os_assumes_log_ctx((f), (ctx), (uintptr_t)_e); \
 475         } \
 476         _e; \
 477 })
 478
 479 #define posix_assumes_zero_ctx(f, ctx, e) __extension__({ \
 480         __typeof__(e) _e = os_slowpath(e); \
 481         if (_e == (__typeof__(e))-1) { \
 482                 _os_assumes_log_ctx((f), (ctx), (uintptr_t)errno); \
 483         } \
 484         _e; \
 485 })
 486
 487 #define os_assert_ctx(f, ctx, e) __extension__({ \
 488         __typeof__(e) _e = os_fastpath(e); \
 489         if (!_e) { \
 490                 if (os_constant(e)) { \
 491                         __OS_COMPILETIME_ASSERT__(e); \
 492                 } \
 493                                                                         \
 494                 char *_fail_message = _os_assert_log_ctx((f), (ctx), (uint64_t)(uintptr_t)_e); \
 495                 os_crash(_fail_message);             \
 496                 free(_fail_message); \
 497         } \
 498 })
 499
 500 #define os_assert_zero_ctx(f, ctx, e) __extension__({ \
 501         __typeof__(e) _e = os_slowpath(e); \
 502         if (_e) { \
 503                 if (os_constant(e)) { \
 504                         __OS_COMPILETIME_ASSERT__(!(e)); \
 505                 } \
 506 \
 507                 char *_fail_message = _os_assert_log_ctx((f), (ctx), (uint64_t)(uintptr_t)_e); \
 508                 os_crash(_fail_message);             \
 509                 free(_fail_message); \
 510         } \
 511 })
 512
 513 #define posix_assert_zero_ctx(f, ctx, e) __extension__({ \
 514         __typeof__(e) _e = os_slowpath(e); \
 515         if (_e == (__typeof__(e))-1) { \
 516                 char *_fail_message = _os_assert_log_ctx((f), (ctx), (uint64_t)(uintptr_t)errno); \
 517                 os_crash(_fail_message);             \
 518                 free(_fail_message); \
 519         } \
 520 })
 521
 522 #pragma mark internal symbols
 523
 524 __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0)
 525 OS_COLD OS_NOT_TAIL_CALLED
 526 extern void
 527 _os_crash(const char *);
 528
 529 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 530 OS_COLD OS_NOT_TAIL_CALLED
 531 extern void
 532 _os_assumes_log(uint64_t code);
 533
 534 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 535 OS_COLD OS_NOT_TAIL_CALLED
 536 extern char *
 537 _os_assert_log(uint64_t code);
 538
 539 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 540 OS_COLD OS_NOT_TAIL_CALLED
 541 extern void
 542 _os_assumes_log_ctx(os_log_callout_t callout, void *ctx, uint64_t code);
 543
 544 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 545 OS_COLD OS_NOT_TAIL_CALLED
 546 extern char *
 547 _os_assert_log_ctx(os_log_callout_t callout, void *ctx, uint64_t code);
 548
 549 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 550 extern void
 551 _os_avoid_tail_call(void);
 552
 553 __END_DECLS
 554
 555 #endif /* __OS_ASSUMES_H__ */