toolkit/crashreporter/CrashAnnotations.h.in

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #ifndef CrashAnnotations_h
   6 #define CrashAnnotations_h
   7
   8 #include <cstddef>
   9 #include <cstdint>
  10
  11 namespace CrashReporter {
  12
  13 // Typed enum representing all crash annotations
  14 enum class Annotation : uint32_t {
  15 ${enum}
  16 };
  17
  18 // Stringified crash annotation names
  19 const char* const kAnnotationStrings[] = {
  20 ${strings}
  21 };
  22
  23 // Type of each annotation
  24 enum class AnnotationType : uint8_t {
  25   String = 0,   // Any type of string, const char*, nsCString, etc...
  26   Boolean = 1,  // Stored as a byte
  27   U32 = 2,      // C/C++'s uint32_t or Rust's u32
  28   U64 = 3,      // C/C++'s uint64_t or Rust's u64
  29   USize = 4,    // C/C++'s size_t or Rust's usize
  30 };
  31
  32 // Type of each annotation
  33 const AnnotationType kAnnotationTypes[] = {
  34 ${types}
  35 };
  36
  37 // Allowlist of crash annotations that can be included in a crash ping
  38 const Annotation kCrashPingAllowedList[] = {
  39 ${allowedlist}
  40 };
  41
  42 // Annotations which should be skipped when they have specific values
  43 struct AnnotationSkipValue {
  44   Annotation annotation;
  45   const char* value;
  46 };
  47
  48 const AnnotationSkipValue kSkipIfList[] = {
  49 ${skiplist}
  50 };
  51
  52 /**
  53  * Return the type of a crash annotation.
  54  *
  55  * @param aAnnotation a crash annotation
  56  * @returns The type of this annotation
  57  */
  58 static inline AnnotationType TypeOfAnnotation(Annotation aAnnotation) {
  59   return kAnnotationTypes[static_cast<uint32_t>(aAnnotation)];
  60 }
  61
  62 /**
  63  * Return the string representation of a crash annotation.
  64  *
  65  * @param aAnnotation a crash annotation
  66  * @returns A constant string holding the annotation name
  67  */
  68 static inline const char* AnnotationToString(Annotation aAnnotation) {
  69   return kAnnotationStrings[static_cast<uint32_t>(aAnnotation)];
  70 }
  71
  72 /**
  73  * Converts a string to its corresponding crash annotation.
  74  *
  75  * @param aResult a reference where the annotation will be stored
  76  * @param aValue the string to be converted
  77  * @return true if the string was successfully converted, false if it did not
  78  *         correspond to any known annotation
  79  */
  80 bool AnnotationFromString(Annotation& aResult, const char* aValue);
  81
  82 /**
  83  * Checks if the given crash annotation is allowed for inclusion in the crash
  84  * ping.
  85  *
  86  * @param aAnnotation the crash annotation to be checked
  87  * @return true if the annotation can be included in the crash ping, false
  88  *         otherwise
  89  */
  90 bool IsAnnotationAllowedForPing(Annotation aAnnotation);
  91
  92 /**
  93  * Checks if the annotation should be included. Some annotations are skipped if
  94  * their value matches a specific one (like the value 0).
  95  *
  96  * @param aAnnotation the crash annotation to be checked
  97  * @param aValue the contents of the annotation as a string
  98  * @return true if the annotation should be included, false otherwise
  99  */
 100 bool ShouldIncludeAnnotation(Annotation aAnnotation, const char* aValue);
 101
 102 /**
 103  * Abstract annotation writer, this is needed only for code that writes out
 104  * annotations in the exception handler.
 105  */
 106 class AnnotationWriter {
 107  public:
 108   virtual void Write(Annotation aAnnotation, const char* aValue,
 109                      size_t aLen = 0) = 0;
 110   virtual void Write(Annotation aAnnotation, bool aValue) = 0;
 111   virtual void Write(Annotation aAnnotation, uint64_t aValue) = 0;
 112 };
 113
 114 #ifdef XP_WIN
 115
 116 extern void RecordDllAnnotations(bool* aBlocklistInitFailed,
 117                                  bool* aUser32BeforeBlocklist);
 118
 119 #endif  // XP_WIN
 120
 121 }  // namespace CrashReporter
 122
 123 #endif  // CrashAnnotations_h