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