1 //===-- CommandOptionArgumentTable.cpp ------------------------------------===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #include "lldb/Interpreter/CommandOptionArgumentTable.h" 10 #include "lldb/DataFormatters/FormatManager.h" 11 #include "lldb/Target/Language.h" 12 #include "lldb/Utility/StreamString.h" 13 14 using namespace lldb; 15 using namespace lldb_private; 16 17 namespace lldb_private { 18 llvm::StringRef RegisterNameHelpTextCallback() { 19 return "Register names can be specified using the architecture specific " 20 "names. " 21 "They can also be specified using generic names. Not all generic " 22 "entities have " 23 "registers backing them on all architectures. When they don't the " 24 "generic name " 25 "will return an error.\n" 26 "The generic names defined in lldb are:\n" 27 "\n" 28 "pc - program counter register\n" 29 "ra - return address register\n" 30 "fp - frame pointer register\n" 31 "sp - stack pointer register\n" 32 "flags - the flags register\n" 33 "arg{1-6} - integer argument passing registers.\n"; 34 } 35 36 llvm::StringRef BreakpointIDHelpTextCallback() { 37 return "Breakpoints are identified using major and minor numbers; the major " 38 "number corresponds to the single entity that was created with a " 39 "'breakpoint " 40 "set' command; the minor numbers correspond to all the locations that " 41 "were " 42 "actually found/set based on the major breakpoint. A full breakpoint " 43 "ID might " 44 "look like 3.14, meaning the 14th location set for the 3rd " 45 "breakpoint. You " 46 "can specify all the locations of a breakpoint by just indicating the " 47 "major " 48 "breakpoint number. A valid breakpoint ID consists either of just the " 49 "major " 50 "number, or the major number followed by a dot and the location " 51 "number (e.g. " 52 "3 or 3.2 could both be valid breakpoint IDs.)"; 53 } 54 55 llvm::StringRef BreakpointIDRangeHelpTextCallback() { 56 return "A 'breakpoint ID list' is a manner of specifying multiple " 57 "breakpoints. " 58 "This can be done through several mechanisms. The easiest way is to " 59 "just " 60 "enter a space-separated list of breakpoint IDs. To specify all the " 61 "breakpoint locations under a major breakpoint, you can use the major " 62 "breakpoint number followed by '.*', eg. '5.*' means all the " 63 "locations under " 64 "breakpoint 5. You can also indicate a range of breakpoints by using " 65 "<start-bp-id> - <end-bp-id>. The start-bp-id and end-bp-id for a " 66 "range can " 67 "be any valid breakpoint IDs. It is not legal, however, to specify a " 68 "range " 69 "using specific locations that cross major breakpoint numbers. I.e. " 70 "3.2 - 3.7" 71 " is legal; 2 - 5 is legal; but 3.2 - 4.4 is not legal."; 72 } 73 74 llvm::StringRef BreakpointNameHelpTextCallback() { 75 return "A name that can be added to a breakpoint when it is created, or " 76 "later " 77 "on with the \"breakpoint name add\" command. " 78 "Breakpoint names can be used to specify breakpoints in all the " 79 "places breakpoint IDs " 80 "and breakpoint ID ranges can be used. As such they provide a " 81 "convenient way to group breakpoints, " 82 "and to operate on breakpoints you create without having to track the " 83 "breakpoint number. " 84 "Note, the attributes you set when using a breakpoint name in a " 85 "breakpoint command don't " 86 "adhere to the name, but instead are set individually on all the " 87 "breakpoints currently tagged with that " 88 "name. Future breakpoints " 89 "tagged with that name will not pick up the attributes previously " 90 "given using that name. " 91 "In order to distinguish breakpoint names from breakpoint IDs and " 92 "ranges, " 93 "names must start with a letter from a-z or A-Z and cannot contain " 94 "spaces, \".\" or \"-\". " 95 "Also, breakpoint names can only be applied to breakpoints, not to " 96 "breakpoint locations."; 97 } 98 99 llvm::StringRef GDBFormatHelpTextCallback() { 100 return "A GDB format consists of a repeat count, a format letter and a size " 101 "letter. " 102 "The repeat count is optional and defaults to 1. The format letter is " 103 "optional " 104 "and defaults to the previous format that was used. The size letter " 105 "is optional " 106 "and defaults to the previous size that was used.\n" 107 "\n" 108 "Format letters include:\n" 109 "o - octal\n" 110 "x - hexadecimal\n" 111 "d - decimal\n" 112 "u - unsigned decimal\n" 113 "t - binary\n" 114 "f - float\n" 115 "a - address\n" 116 "i - instruction\n" 117 "c - char\n" 118 "s - string\n" 119 "T - OSType\n" 120 "A - float as hex\n" 121 "\n" 122 "Size letters include:\n" 123 "b - 1 byte (byte)\n" 124 "h - 2 bytes (halfword)\n" 125 "w - 4 bytes (word)\n" 126 "g - 8 bytes (giant)\n" 127 "\n" 128 "Example formats:\n" 129 "32xb - show 32 1 byte hexadecimal integer values\n" 130 "16xh - show 16 2 byte hexadecimal integer values\n" 131 "64 - show 64 2 byte hexadecimal integer values (format and size " 132 "from the last format)\n" 133 "dw - show 1 4 byte decimal integer value\n"; 134 } 135 136 llvm::StringRef FormatHelpTextCallback() { 137 static std::string help_text; 138 139 if (!help_text.empty()) 140 return help_text; 141 142 StreamString sstr; 143 sstr << "One of the format names (or one-character names) that can be used " 144 "to show a variable's value:\n"; 145 for (Format f = eFormatDefault; f < kNumFormats; f = Format(f + 1)) { 146 if (f != eFormatDefault) 147 sstr.PutChar('\n'); 148 149 char format_char = FormatManager::GetFormatAsFormatChar(f); 150 if (format_char) 151 sstr.Printf("'%c' or ", format_char); 152 153 sstr.Printf("\"%s\"", FormatManager::GetFormatAsCString(f)); 154 } 155 156 sstr.Flush(); 157 158 help_text = std::string(sstr.GetString()); 159 160 return help_text; 161 } 162 163 llvm::StringRef LanguageTypeHelpTextCallback() { 164 static std::string help_text; 165 166 if (!help_text.empty()) 167 return help_text; 168 169 StreamString sstr; 170 sstr << "One of the following languages:\n"; 171 172 Language::PrintAllLanguages(sstr, " ", "\n"); 173 174 sstr.Flush(); 175 176 help_text = std::string(sstr.GetString()); 177 178 return help_text; 179 } 180 181 llvm::StringRef SummaryStringHelpTextCallback() { 182 return "A summary string is a way to extract information from variables in " 183 "order to present them using a summary.\n" 184 "Summary strings contain static text, variables, scopes and control " 185 "sequences:\n" 186 " - Static text can be any sequence of non-special characters, i.e. " 187 "anything but '{', '}', '$', or '\\'.\n" 188 " - Variables are sequences of characters beginning with ${, ending " 189 "with } and that contain symbols in the format described below.\n" 190 " - Scopes are any sequence of text between { and }. Anything " 191 "included in a scope will only appear in the output summary if there " 192 "were no errors.\n" 193 " - Control sequences are the usual C/C++ '\\a', '\\n', ..., plus " 194 "'\\$', '\\{' and '\\}'.\n" 195 "A summary string works by copying static text verbatim, turning " 196 "control sequences into their character counterpart, expanding " 197 "variables and trying to expand scopes.\n" 198 "A variable is expanded by giving it a value other than its textual " 199 "representation, and the way this is done depends on what comes after " 200 "the ${ marker.\n" 201 "The most common sequence if ${var followed by an expression path, " 202 "which is the text one would type to access a member of an aggregate " 203 "types, given a variable of that type" 204 " (e.g. if type T has a member named x, which has a member named y, " 205 "and if t is of type T, the expression path would be .x.y and the way " 206 "to fit that into a summary string would be" 207 " ${var.x.y}). You can also use ${*var followed by an expression path " 208 "and in that case the object referred by the path will be " 209 "dereferenced before being displayed." 210 " If the object is not a pointer, doing so will cause an error. For " 211 "additional details on expression paths, you can type 'help " 212 "expr-path'. \n" 213 "By default, summary strings attempt to display the summary for any " 214 "variable they reference, and if that fails the value. If neither can " 215 "be shown, nothing is displayed." 216 "In a summary string, you can also use an array index [n], or a " 217 "slice-like range [n-m]. This can have two different meanings " 218 "depending on what kind of object the expression" 219 " path refers to:\n" 220 " - if it is a scalar type (any basic type like int, float, ...) the " 221 "expression is a bitfield, i.e. the bits indicated by the indexing " 222 "operator are extracted out of the number" 223 " and displayed as an individual variable\n" 224 " - if it is an array or pointer the array items indicated by the " 225 "indexing operator are shown as the result of the variable. if the " 226 "expression is an array, real array items are" 227 " printed; if it is a pointer, the pointer-as-array syntax is used to " 228 "obtain the values (this means, the latter case can have no range " 229 "checking)\n" 230 "If you are trying to display an array for which the size is known, " 231 "you can also use [] instead of giving an exact range. This has the " 232 "effect of showing items 0 thru size - 1.\n" 233 "Additionally, a variable can contain an (optional) format code, as " 234 "in ${var.x.y%code}, where code can be any of the valid formats " 235 "described in 'help format', or one of the" 236 " special symbols only allowed as part of a variable:\n" 237 " %V: show the value of the object by default\n" 238 " %S: show the summary of the object by default\n" 239 " %@: show the runtime-provided object description (for " 240 "Objective-C, it calls NSPrintForDebugger; for C/C++ it does " 241 "nothing)\n" 242 " %L: show the location of the object (memory address or a " 243 "register name)\n" 244 " %#: show the number of children of the object\n" 245 " %T: show the type of the object\n" 246 "Another variable that you can use in summary strings is ${svar . " 247 "This sequence works exactly like ${var, including the fact that " 248 "${*svar is an allowed sequence, but uses" 249 " the object's synthetic children provider instead of the actual " 250 "objects. For instance, if you are using STL synthetic children " 251 "providers, the following summary string would" 252 " count the number of actual elements stored in an std::list:\n" 253 "type summary add -s \"${svar%#}\" -x \"std::list<\""; 254 } 255 256 llvm::StringRef ExprPathHelpTextCallback() { 257 return "An expression path is the sequence of symbols that is used in C/C++ " 258 "to access a member variable of an aggregate object (class).\n" 259 "For instance, given a class:\n" 260 " class foo {\n" 261 " int a;\n" 262 " int b; .\n" 263 " foo* next;\n" 264 " };\n" 265 "the expression to read item b in the item pointed to by next for foo " 266 "aFoo would be aFoo.next->b.\n" 267 "Given that aFoo could just be any object of type foo, the string " 268 "'.next->b' is the expression path, because it can be attached to any " 269 "foo instance to achieve the effect.\n" 270 "Expression paths in LLDB include dot (.) and arrow (->) operators, " 271 "and most commands using expression paths have ways to also accept " 272 "the star (*) operator.\n" 273 "The meaning of these operators is the same as the usual one given to " 274 "them by the C/C++ standards.\n" 275 "LLDB also has support for indexing ([ ]) in expression paths, and " 276 "extends the traditional meaning of the square brackets operator to " 277 "allow bitfield extraction:\n" 278 "for objects of native types (int, float, char, ...) saying '[n-m]' " 279 "as an expression path (where n and m are any positive integers, e.g. " 280 "[3-5]) causes LLDB to extract" 281 " bits n thru m from the value of the variable. If n == m, [n] is " 282 "also allowed as a shortcut syntax. For arrays and pointers, " 283 "expression paths can only contain one index" 284 " and the meaning of the operation is the same as the one defined by " 285 "C/C++ (item extraction). Some commands extend bitfield-like syntax " 286 "for arrays and pointers with the" 287 " meaning of array slicing (taking elements n thru m inside the array " 288 "or pointed-to memory)."; 289 } 290 291 llvm::StringRef arch_helper() { 292 static StreamString g_archs_help; 293 if (g_archs_help.Empty()) { 294 StringList archs; 295 296 ArchSpec::ListSupportedArchNames(archs); 297 g_archs_help.Printf("These are the supported architecture names:\n"); 298 archs.Join("\n", g_archs_help); 299 } 300 return g_archs_help.GetString(); 301 } 302 303 template <int I> struct TableValidator : TableValidator<I + 1> { 304 static_assert( 305 g_argument_table[I].arg_type == I, 306 "g_argument_table order doesn't match CommandArgumentType enumeration"); 307 }; 308 309 template <> struct TableValidator<eArgTypeLastArg> {}; 310 311 TableValidator<0> validator; 312 313 } // namespace lldb_private 314