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_malloc
 138  * A routine to assert the result of allocations which may fail.
 139  *
 140  * @param desc
 141  * A string describing the object whose allocation was attempted.
 142  *
 143  * @param p
 144  * The result of a call to malloc(3), calloc(3), et al.
 145  *
 146  * @param alloc_size
 147  * The size of the attempted allocation.
 148  *
 149  * @discussion
 150  * If {@link p} is NULL, the routine will abort the caller with a message
 151  * indicating the nature of the failure in the Application Specific Information
 152  * section of the resulting crash log.
 153  */
 154 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 155 OS_ALWAYS_INLINE
 156 static inline void
 157 os_assert_malloc(const char *desc, const void *const p, size_t alloc_size)
 158 {
 159         if (!p) {
 160                 os_crash("allocation failed: obj = %s, size = %lu, error = %s",
 161                                 desc, alloc_size, strerror(errno));
 162         }
 163 }
 164
 165 /*!
 166  * @function os_assert_mach
 167  * A routine to assert the result of a Mach kernel routine.
 168  *
 169  * @param op
 170  * A human-readable description of the operation.
 171  *
 172  * @param kr
 173  * The return code.
 174  *
 175  * @discsussion
 176  * If {@link kr} is non-zero, this routine will abort the caller with a message
 177  * indicating the nature of the failure in the Application Specific Information
 178  * section of the resulting crash log.
 179  */
 180 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 181 OS_EXPORT OS_NONNULL1 OS_COLD
 182 void
 183 os_assert_mach(const char *op, kern_return_t kr);
 184
 185 #define os_assert_mach(op, kr) ({ \
 186                 kern_return_t __kr = (kr); \
 187                 if (os_unlikely(__kr != KERN_SUCCESS)) os_assert_mach(op, kr); \
 188 })
 189
 190 /*!
 191  * @function os_assert_mach_port_status
 192  * A routine to assert the status of a Mach port.
 193  *
 194  * @param desc
 195  * A human-readable description of the port's purpose.
 196  *
 197  * @param p
 198  * The port.
 199  *
 200  * @param expected
 201  * A pointer to a mach_port_status_t describing the expected attributes of the
 202  * port. If no particular value is expected for a given field in the structure,
 203  * a sentinel value may be provided for each expected field to indicate that its
 204  * check should be elided. The sentival values are:
 205  *
 206  * mps_pset => UINT32_MAX
 207  * mps_seqno => UINT32_MAX
 208  * mps_mscount => UINT32_MAX
 209  * mps_qlimit => UINT32_MAX
 210  * mps_msgcount => UINT32_MAX
 211  * mps_sorights => UINT32_MAX
 212  * mps_srights => INT32_MAX
 213  * mps_pdrequest => INT32_MAX
 214  * mps_nsrequest => INT32_MAX
 215  * mps_flags => 0
 216  *
 217  * @discussion
 218  * If there are any mismatches in the expected and actual status of the port,
 219  * the implementation will abort the caller. If status cannot be obtained for
 220  * the given port, the implementation will abort the caller.
 221  */
 222 API_AVAILABLE(macos(10.14), ios(12.0), tvos(12.0), watchos(5.0))
 223 OS_EXPORT
 224 void
 225 os_assert_mach_port_status(const char *desc, mach_port_t p,
 226                 mach_port_status_t *expected);
 227
 228 #else // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 229
 230 #define os_crash(msg) __os_crash_simple(msg)
 231
 232 #endif // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 233
 234 /*
 235  * An executable can register a callback to be made upon a crash using the
 236  * os_set_crash_callback function.  If a crash callback is not set, the symbol
 237  * `os_crash_function` will be called in the main binary, if it exists.
 238  */
 239
 240 typedef void (*os_crash_callback_t) (const char *);
 241
 242 /* private: use accessors below */
 243 extern os_crash_callback_t _os_crash_callback;
 244
 245 static inline os_crash_callback_t
 246 os_get_crash_callback() {
 247         return _os_crash_callback;
 248 }
 249
 250 static inline void
 251 os_set_crash_callback(os_crash_callback_t callback) {
 252         _os_crash_callback = callback;
 253 }
 254
 255 #pragma mark os_assert
 256
 257 #if defined(OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE)
 258
 259 #define _os_assert_crash(value, expression) ({ \
 260                 os_crash("assertion failure: \"" expression "\" -> %lld", value); \
 261 })
 262
 263 #define _os_assert_crash_errno(value, expression) ({ \
 264                 os_crash("assertion failure: \"" expression "\" -> %{errno}d", value); \
 265 })
 266
 267 #else // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 268
 269 #define _os_assert_crash(e, ...) ({ \
 270                 char *_fail_message = _os_assert_log(e); \
 271                 os_crash(_fail_message); \
 272                 free(_fail_message); \
 273 })
 274
 275 #define _os_assert_crash_errno(...) _os_assert_crash(__VA_ARGS__)
 276
 277 #endif // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 278
 279 #define __os_assert(e) __extension__({ \
 280         __typeof__(e) _e = (e); \
 281         if (os_unlikely(!_e)) { \
 282                 if (os_constant(e)) { __OS_COMPILETIME_ASSERT__((e)); } \
 283                 _os_assert_crash((uint64_t)(uintptr_t)_e, #e); \
 284         } \
 285 })
 286
 287 #define __os_assert_zero(e) __extension__({ \
 288         __typeof__(e) _e = (e); \
 289         if (os_unlikely(_e)) { \
 290                 if (os_constant(e)) { __OS_COMPILETIME_ASSERT__(!(e)); } \
 291                 _os_assert_crash((uint64_t)(uintptr_t)_e, #e); \
 292         } \
 293 })
 294
 295 /*
 296  * This variant is for use with old-style POSIX APIs that return -1 on failure
 297  * and set errno. If the return code is -1, the value logged will be as though
 298  * os_assert_zero(errno) was used. It encapsulates the following pattern:
 299  *
 300  * int tubes[2];
 301  * if (pipe(tubes) == -1) {
 302  *     (void)os_assert_zero(errno);
 303  * }
 304  */
 305 #define __posix_assert_zero(e) __extension__({ \
 306         __typeof__(e) _e = (e); \
 307         if (os_unlikely(_e == (__typeof__(e))-1)) { \
 308                 _os_assert_crash_errno(errno, #e); \
 309         } \
 310 })
 311
 312 #if defined(OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE)
 313
 314 #define __os_assert_msg(e, fmt, ...) __extension__({ \
 315         __typeof__(e) _e = (e); \
 316         if (os_unlikely(!_e)) { \
 317                 os_crash("assertion failure: " fmt, ##__VA_ARGS__); \
 318         } \
 319 })
 320
 321 #define __os_assert_zero_msg(e, fmt, ...) __extension__({ \
 322         __typeof__(e) _e = (e); \
 323         if (os_unlikely(_e)) { \
 324                 os_crash("assertion failure (%lld): " fmt, value, ##__VA_ARGS__); \
 325         } \
 326 })
 327
 328 #define __posix_assert_zero_msg(e, fmt, ...) __extension__({ \
 329         __typeof__(e) _e = (e); \
 330         if (os_unlikely(_e == (__typeof__(e))-1)) { \
 331                 os_crash("assertion failure (%{errno}d): " fmt, errno, ##__VA_ARGS__); \
 332         } \
 333 })
 334
 335 #define __os_assert_N(e) __os_assert(e)
 336 #define __os_assert_Y(...) __os_assert_msg(__VA_ARGS__)
 337 #define __os_assert_zero_N(e) __os_assert_zero(e)
 338 #define __os_assert_zero_Y(...) __os_assert_zero_msg(__VA_ARGS__)
 339 #define __posix_assert_zero_N(e) __posix_assert_zero(e)
 340 #define __posix_assert_zero_Y(...) __posix_assert_zero_msg(__VA_ARGS__)
 341
 342 #define __os_assert_invoke(function, variant, ...) \
 343         OS_CONCAT(function, variant)(__VA_ARGS__)
 344
 345 #define os_assert(...) \
 346         __os_assert_invoke(__os_assert_, \
 347                         __has_more_than_one_argument(__VA_ARGS__), __VA_ARGS__)
 348 #define os_assert_zero(...) \
 349         __os_assert_invoke(__os_assert_zero_, \
 350                         __has_more_than_one_argument(__VA_ARGS__), __VA_ARGS__)
 351 #define posix_assert_zero(...) \
 352         __os_assert_invoke(__posix_assert_zero_, \
 353                         __has_more_than_one_argument(__VA_ARGS__), __VA_ARGS__)
 354
 355 #else // OS_CRASH_ENABLE_EXPERIMENTAL_LIBTRACE
 356
 357 #define os_assert(e) __os_assert(e)
 358 #define os_assert_zero(e) __os_assert_zero(e)
 359 #define posix_assert_zero(e) __posix_assert_zero(e)
 360
 361 #endif
 362
 363 #pragma mark os_assumes
 364
 365
 366 #define os_assumes(e) __extension__({ \
 367         __typeof__(e) _e = os_fastpath(e); \
 368         if (!_e) { \
 369                 if (os_constant(e)) { \
 370                         __OS_COMPILETIME_ASSERT__(e); \
 371                 } \
 372                 _os_assumes_log((uint64_t)(uintptr_t)_e); \
 373         } \
 374         _e; \
 375 })
 376
 377 #define os_assumes_zero(e) __extension__({ \
 378         __typeof__(e) _e = os_slowpath(e); \
 379         if (_e) { \
 380                 if (os_constant(e)) { \
 381                         __OS_COMPILETIME_ASSERT__(!(e)); \
 382                 } \
 383                 _os_assumes_log((uint64_t)(uintptr_t)_e); \
 384         } \
 385         _e; \
 386 })
 387
 388 #define posix_assumes_zero(e) __extension__({ \
 389         __typeof__(e) _e = os_slowpath(e); \
 390         if (_e == (__typeof__(e))-1) { \
 391                 _os_assumes_log((uint64_t)(uintptr_t)errno); \
 392         } \
 393         _e; \
 394 })
 395
 396 #pragma mark assumes redirection
 397
 398 /* This is useful for clients who wish for the messages generated by assumes()
 399  * failures to go somewhere other than (or in addition to) the system log. If
 400  * you don't wish for the message to be logged to the system log, then return
 401  * true (to indicate that the message has been handled). If you want the default
 402  * behavior, return false.
 403  */
 404 typedef bool (*os_redirect_t)(const char *);
 405 struct _os_redirect_assumes_s {
 406         os_redirect_t redirect;
 407 };
 408
 409 #define OS_ASSUMES_REDIRECT_SEG "__DATA"
 410 #define OS_ASSUMES_REDIRECT_SECT "__os_assumes_log"
 411
 412 #define os_redirect_assumes(func) \
 413         __attribute__((__used__)) \
 414         __attribute__((__section__(OS_ASSUMES_REDIRECT_SEG "," OS_ASSUMES_REDIRECT_SECT))) \
 415         static struct _os_redirect_assumes_s _os_redirect_##func = { \
 416                 .redirect = &func, \
 417         };
 418
 419 #pragma mark _ctx variants
 420
 421 /*
 422  * These are for defining your own assumes()-like wrapper calls so that you can
 423  * log additional information, such as the about-PID, sender, etc. They're
 424  * generally not useful for direct inclusion in your code.
 425  */
 426
 427 /*
 428  * The asl_message argument is a _SIMPLE_STRING that, when given to _simple_asl_send(), will
 429  * direct the message to the MessageTracer diagnostic messages store rather than
 430  * the default system log store.
 431  */
 432 typedef bool (*os_log_callout_t)(_SIMPLE_STRING asl_message, void *ctx, const char *);
 433
 434
 435 #define os_assumes_ctx(f, ctx, e) __extension__({ \
 436         __typeof__(e) _e = os_fastpath(e); \
 437         if (!_e) { \
 438                 if (os_constant(e)) { \
 439                         __OS_COMPILETIME_ASSERT__(e); \
 440                 } \
 441                 _os_assumes_log_ctx(f, ctx, (uintptr_t)_e); \
 442         } \
 443         _e; \
 444 })
 445
 446 #define os_assumes_zero_ctx(f, ctx, e) __extension__({ \
 447         __typeof__(e) _e = os_slowpath(e); \
 448         if (_e) { \
 449                 if (os_constant(e)) { \
 450                         __OS_COMPILETIME_ASSERT__(!(e)); \
 451                 } \
 452                 _os_assumes_log_ctx((f), (ctx), (uintptr_t)_e); \
 453         } \
 454         _e; \
 455 })
 456
 457 #define posix_assumes_zero_ctx(f, ctx, e) __extension__({ \
 458         __typeof__(e) _e = os_slowpath(e); \
 459         if (_e == (__typeof__(e))-1) { \
 460                 _os_assumes_log_ctx((f), (ctx), (uintptr_t)errno); \
 461         } \
 462         _e; \
 463 })
 464
 465 #define os_assert_ctx(f, ctx, e) __extension__({ \
 466         __typeof__(e) _e = os_fastpath(e); \
 467         if (!_e) { \
 468                 if (os_constant(e)) { \
 469                         __OS_COMPILETIME_ASSERT__(e); \
 470                 } \
 471                                                                         \
 472                 char *_fail_message = _os_assert_log_ctx((f), (ctx), (uint64_t)(uintptr_t)_e); \
 473                 os_crash(_fail_message);             \
 474                 free(_fail_message); \
 475         } \
 476 })
 477
 478 #define os_assert_zero_ctx(f, ctx, e) __extension__({ \
 479         __typeof__(e) _e = os_slowpath(e); \
 480         if (_e) { \
 481                 if (os_constant(e)) { \
 482                         __OS_COMPILETIME_ASSERT__(!(e)); \
 483                 } \
 484 \
 485                 char *_fail_message = _os_assert_log_ctx((f), (ctx), (uint64_t)(uintptr_t)_e); \
 486                 os_crash(_fail_message);             \
 487                 free(_fail_message); \
 488         } \
 489 })
 490
 491 #define posix_assert_zero_ctx(f, ctx, e) __extension__({ \
 492         __typeof__(e) _e = os_slowpath(e); \
 493         if (_e == (__typeof__(e))-1) { \
 494                 char *_fail_message = _os_assert_log_ctx((f), (ctx), (uint64_t)(uintptr_t)errno); \
 495                 os_crash(_fail_message);             \
 496                 free(_fail_message); \
 497         } \
 498 })
 499
 500 #pragma mark internal symbols
 501
 502 __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0)
 503 OS_COLD OS_NOT_TAIL_CALLED
 504 extern void
 505 _os_crash(const char *);
 506
 507 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 508 OS_COLD OS_NOT_TAIL_CALLED
 509 extern void
 510 _os_assumes_log(uint64_t code);
 511
 512 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 513 OS_COLD OS_NOT_TAIL_CALLED
 514 extern char *
 515 _os_assert_log(uint64_t code);
 516
 517 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 518 OS_COLD OS_NOT_TAIL_CALLED
 519 extern void
 520 _os_assumes_log_ctx(os_log_callout_t callout, void *ctx, uint64_t code);
 521
 522 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 523 OS_COLD OS_NOT_TAIL_CALLED
 524 extern char *
 525 _os_assert_log_ctx(os_log_callout_t callout, void *ctx, uint64_t code);
 526
 527 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0)
 528 extern void
 529 _os_avoid_tail_call(void);
 530
 531 __END_DECLS
 532
 533 #endif /* __OS_ASSUMES_H__ */