diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CMakeLists.txt | 41 | ||||
| -rw-r--r-- | docs/building-with-debug-llvm.txt | 50 | ||||
| -rw-r--r-- | docs/code-signing.txt | 61 | ||||
| -rw-r--r-- | docs/doxygen.cfg.in | 1631 | ||||
| -rw-r--r-- | docs/doxygen.footer | 13 | ||||
| -rw-r--r-- | docs/doxygen.header | 9 | ||||
| -rw-r--r-- | docs/doxygen.intro | 19 | ||||
| -rw-r--r-- | docs/lldb-for-gdb-users.txt | 488 | ||||
| -rw-r--r-- | docs/lldb-gdb-remote.txt | 1675 | ||||
| -rw-r--r-- | docs/testsuite/2010-10-19-14_10_49.059609/TestSettings.SettingsCommandTestCase.test_set_output_path.log | 43 | ||||
| -rw-r--r-- | docs/testsuite/a-detailed-walkthrough.txt | 309 | ||||
| -rw-r--r-- | docs/testsuite/best-practices.txt | 93 |
12 files changed, 4432 insertions, 0 deletions
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 000000000000..045e816b727c --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,41 @@ + +include(FindDoxygen) + +if(DOXYGEN_FOUND) + set(abs_top_srcdir ${CMAKE_CURRENT_SOURCE_DIR}/..) + set(DOT dot) + set(PACKAGE_VERSION mainline) + set(abs_top_builddir ..) + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in + ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY) + + add_custom_target(lldb-cpp-doc + ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "Generating LLDB C++ API reference with Doxygen" VERBATIM + ) +endif(DOXYGEN_FOUND) + +find_package(PythonInterp REQUIRED) +find_program(EPYDOC_EXECUTABLE NAMES epydoc epydoc.py) +if(EPYDOC_EXECUTABLE) + find_program(DOT_EXECUTABLE dot) + if(DOT_EXECUTABLE) + set(EPYDOC_OPTIONS ${EPYDOC_OPTIONS} --graph all --dotpath ${DOT_EXECUTABLE}) + endif() + set(DOC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc") + file(MAKE_DIRECTORY "${DOC_DIR}") + #set(ENV{PYTHONPATH} ${CMAKE_CURRENT_BINARY_DIR}/../../../lib/python2.7/site-packages) + add_custom_target(lldb-python-doc + ${EPYDOC_EXECUTABLE} + --html + lldb + -o ${CMAKE_CURRENT_BINARY_DIR}/python_reference + --name "LLDB python API" + --url "http://lldb.llvm.org" + ${EPYDOC_OPTIONS} + DEPENDS swig_wrapper liblldb + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/../../../lib${LLVM_LIBDIR_SUFFIX}/python2.7/site-packages + COMMENT "Generating LLDB Python API reference with epydoc" VERBATIM + ) +endif(EPYDOC_EXECUTABLE) diff --git a/docs/building-with-debug-llvm.txt b/docs/building-with-debug-llvm.txt new file mode 100644 index 000000000000..f59ca410edb0 --- /dev/null +++ b/docs/building-with-debug-llvm.txt @@ -0,0 +1,50 @@ +This document describes how to build a debug version of LLVM for use with +LLDB, and how to make LLDB use it. + +It assumes that you are using the Xcode 3 series (I used 3.2.4) to build +LLDB. It also assumes that your shell is /bin/bash, and that you are +currently at a shell prompt in a checked-out LLDB repository. + +1. Check out LLVM and Clang from their repositories. To determine + the revision to use, consult scripts/build-llvm.pl (this is done + in the first command line below). !!! WARNING Do not use the + name "llvm" for your checkout, for reasons described in part 3 + below. + + $ export CLANG_REVISION=`cat scripts/build-llvm.pl | grep ^our.*llvm_revision | cut -d \' -f 2,2` + $ svn co -r $CLANG_REVISION http://llvm.org/svn/llvm-project/llvm/trunk llvm.checkout + $ svn co -r $CLANG_REVISION http://llvm.org/svn/llvm-project/cfe/trunk llvm.checkout/tools/clang + +2. Configure LLVM/Clang with the proper options and compilers. I use: + + $ cd llvm.checkout + $ CC="cc -g -O0" CXX="c++ -g -O0" ./configure --disable-optimized --enable-assertions --enable-targets=x86_64,arm + $ CC="cc -g -O0" CXX="c++ -g -O0" make -j 2 + $ cd .. + +3. Create a link to the built LLVM. !!! WARNING: Do not rename the + directory! The LLVM builder script that runs as part of the Xcode + build keys off the fact that llvm/ is a symlink to recognize that + we are building with a custom debug build. + + $ ln -sf llvm.checkout llvm + +4. Make sure that your Xcode project is set up correctly. Open + lldb.xcodeproj and do the following: + + Under "Targets" in the Groups & Files navigator, double-click + lldb-tool. In the resulting window, select "Debug" from the + "Configuration:" drop-down. Then, make sure that the setting + "Build Active Architecture Only" is enabled. Close the window. + + Under "Targets" in the Groups & Files navigator, double-click + LLDB. In the resulting window, select "Debug" from the + "Configuration:" drop-down. Then, make sure that the setting + "Build Active Architecture Only" is enabled. Close the window. + +5. Ensure that Xcode is building the lldb-tool target in Debug + configuration for your architecture (typically x86_64). You + can usually pick these options from the Overview drop-down at + the top left of the Xcode window. + +6. Build lldb.xcodeproj. diff --git a/docs/code-signing.txt b/docs/code-signing.txt new file mode 100644 index 000000000000..5407fd4bb42e --- /dev/null +++ b/docs/code-signing.txt @@ -0,0 +1,61 @@ +On MacOSX lldb needs to be code signed. The Debug, DebugClang and Release +builds are set to code sign using a code signing certificate named +"lldb_codesign". + +If you have re-installed a new OS, please delete all old lldb_codesign items +from your keychain. There will be a code signing certification and a public +and private key. Reboot after deleting them. You will also need to delete and +build folders that contained old signed items. The darwin kernel will cache +code signing using the executable's file system node, so you will need to +delete the file so the kernel clears its cache. + +If you don't have one yet you will need to: +- Launch /Applications/Utilities/Keychain Access.app + +- In Keychain Access select the "login" keychain in the "Keychains" + list in the upper left hand corner of the window. + +- Select the following menu item: + + Keychain Access->Certificate Assistant->Create a Certificate... + +- Set the following settings + + Name = lldb_codesign + Identity Type = Self Signed Root + Certificate Type = Code Signing + +- Click Create +- Click Continue +- Click Done +- Click on the "My Certificates" +- Double click on your new lldb_codesign certificate +- Turn down the "Trust" disclosure triangle, scroll to the "Code Signing" trust + pulldown menu and select "Always Trust" and authenticate as needed using your + username and password. +- Drag the new "lldb_codesign" code signing certificate (not the public or private + keys of the same name) from the "login" keychain to the "System" keychain in the + Keychains pane on the left hand side of the main Keychain Access window. This will + move this certificate to the "System" keychain. You'll have to authorize a few + more times, set it to be "Always trusted" when asked. +- Remove "~/Desktop/lldb_codesign.cer" file on your desktop if there is one. +- In the Keychain Access GUI, click and drag "lldb_codesign" in the "System" keychain + onto the desktop. The drag will create a "~/Desktop/lldb_codesign.cer" file used in + the next step. +- Switch to Terminal, and run the following: + +sudo security add-trust -d -r trustRoot -p basic -p codeSign -k /Library/Keychains/System.keychain ~/Desktop/lldb_codesign.cer +rm -f ~/Desktop/lldb_codesign.cer + +- Drag the "lldb_codesign" certificate from the "System" keychain back into the + "login" keychain +- Quit Keychain Access +- Reboot +- Clean by removing all previously creating code signed binaries and rebuild + lldb and you should be able to debug. + +When you build your LLDB for the first time, the Xcode GUI will prompt you for permission +to use the "lldb_codesign" keychain. Be sure to click "Always Allow" on your first +build. From here on out, the "lldb_codesign" will be trusted and you can build from the +command line without having to authorize. Also the first time you debug using a LLDB that +was built with this code signing certificate, you will need to authenticate once. diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in new file mode 100644 index 000000000000..725a26f2a03c --- /dev/null +++ b/docs/doxygen.cfg.in @@ -0,0 +1,1631 @@ +# Doxyfile 1.7.1 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# http://www.gnu.org/software/libiconv for the list of possible encodings. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = LLVM + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = @PACKAGE_VERSION@ + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = @abs_top_builddir@/docs/cpp_reference + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, +# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English +# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, +# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, +# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = NO + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = ../.. + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments +# (thus requiring an explicit @brief command for a brief description.) + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring +# an explicit \brief command for a brief description.) + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 2 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified +# scopes will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for +# Fortran. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for +# VHDL. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given extension. +# Doxygen has a built-in mapping, but you can override or extend it using this +# tag. The format is ext=language, where ext is a file extension, and language +# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, +# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make +# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C +# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions +# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public +# instead of private inheritance when no explicit protection keyword is present. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate getter +# and setter methods for a property. Setting this option to YES (the default) +# will make doxygen to replace the get and set methods by a property in the +# documentation. This will only work if the methods are indeed getting or +# setting a simple type. If this is not the case, or you want to show the +# methods anyway, you should set this option to NO. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. + +TYPEDEF_HIDES_STRUCT = NO + +# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to +# determine which symbols to keep in memory and which to flush to disk. +# When the cache is full, less often used symbols will be written to disk. +# For small to medium size projects (<1000 input files) the default value is +# probably good enough. For larger projects a too small cache size can cause +# doxygen to be busy swapping symbols to and from disk most of the time +# causing a significant performance penality. +# If the system has enough physical memory increasing the cache will improve the +# performance by keeping more symbols in memory. Note that the value works on +# a logarithmic scale so increasing the size by one will rougly double the +# memory usage. The cache size is given by this formula: +# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols + +SYMBOL_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default +# anonymous namespace are hidden. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen +# will list include files with double quotes in the documentation +# rather than with sharp brackets. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen +# will sort the (brief and detailed) documentation of class members so that +# constructors and destructors are listed first. If set to NO (the default) +# the constructors will appear in the respective orders defined by +# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. +# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO +# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) +# the group names will appear in their defined order. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. +# This will remove the Files entry from the Quick Index and from the +# Folder Tree View (if specified). The default is YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. +# This will remove the Namespaces entry from the Quick Index +# and from the Folder Tree View (if specified). The default is YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command <command> <input-file>, where <command> is the value of +# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. The create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. +# You can optionally specify a file name after the option, if omitted +# DoxygenLayout.xml will be used as the name of the layout file. + +LAYOUT_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = NO + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = NO + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = @abs_top_srcdir@/include/lldb/API \ + @abs_top_srcdir@/docs/doxygen.intro + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# the list of possible encodings. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 + +FILE_PATTERNS = + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = @abs_top_srcdir@/examples + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = YES + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = @abs_top_srcdir@/docs/img + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command <filter> <input-file>, where <filter> +# is the value of the INPUT_FILTER tag, and <input-file> is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. +# If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. +# Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. +# The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = NO + +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. +# Otherwise they will link to the documentation. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = YES + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 4 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = llvm:: + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = @abs_top_srcdir@/docs/doxygen.header + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = @abs_top_srcdir@/docs/doxygen.footer + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = @abs_top_srcdir@/../../docs/doxygen.css + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. +# Doxygen will adjust the colors in the stylesheet and background images +# according to this color. Hue is specified as an angle on a colorwheel, +# see http://en.wikipedia.org/wiki/Hue for more information. +# For instance the value 0 represents red, 60 is yellow, 120 is green, +# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. +# The allowed range is 0 to 359. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of +# the colors in the HTML output. For a value of 0 the output will use +# grayscales only. A value of 255 will produce the most vivid colors. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to +# the luminance component of the colors in the HTML output. Values below +# 100 gradually make the output lighter, whereas values above 100 make +# the output darker. The value divided by 100 is the actual gamma applied, +# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, +# and 100 does not change the gamma. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting +# this to NO can help when comparing the output of multiple runs. + +HTML_TIMESTAMP = YES + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. For this to work a browser that supports +# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox +# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). + +HTML_DYNAMIC_SECTIONS = NO + +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# it at startup. +# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. + +GENERATE_DOCSET = NO + +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) +# can be grouped. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# will append .docset to the name. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING +# is used to encode HtmlHelp index (hhk), content (hhc) and project file +# content. + +CHM_INDEX_ENCODING = + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated +# that can be used as input for Qt's qhelpgenerator to generate a +# Qt Compressed Help (.qch) of the generated HTML documentation. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can +# be used to specify the file name of the resulting .qch file. +# The path specified is relative to the HTML output folder. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#namespace + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#virtual-folders + +QHP_VIRTUAL_FOLDER = doc + +# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to +# add. For more information please see +# http://doc.trolltech.com/qthelpproject.html#custom-filters + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see +# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters"> +# Qt Help Project / Custom Filters</a>. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's +# filter section matches. +# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes"> +# Qt Help Project / Filter Attributes</a>. + +QHP_SECT_FILTER_ATTRS = + +# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can +# be used to specify the location of Qt's qhelpgenerator. +# If non-empty doxygen will try to run qhelpgenerator on the generated +# .qhp file. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files +# will be generated, which together with the HTML files, form an Eclipse help +# plugin. To install this plugin and make it available under the help contents +# menu in Eclipse, the contents of the directory containing the HTML and XML +# files needs to be copied into the plugins directory of eclipse. The name of +# the directory within the plugins directory should be the same as +# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before +# the help appears. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have +# this name. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. +# If the tag value is set to YES, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). +# Windows users are probably better off using the HTML help feature. + +GENERATE_TREEVIEW = NO + +# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, +# and Class Hierarchy pages using a tree view instead of an ordered list. + +USE_INLINE_TREES = NO + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open +# links to external symbols imported via tag files in a separate window. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory +# to force them to be regenerated. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are +# not supported properly for IE 6.0, but are supported on all modern browsers. +# Note that when changing this option you need to delete any form_*.png files +# in the HTML output before the changes have effect. + +FORMULA_TRANSPARENT = YES + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box +# for the HTML output. The underlying search engine uses javascript +# and DHTML and should work on any modern browser. Note that when using +# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets +# (GENERATE_DOCSET) there is already a search function so this one should +# typically be disabled. For large projects the javascript based search engine +# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. + +SEARCHENGINE = NO + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a PHP enabled web server instead of at the web client +# using Javascript. Doxygen will generate the search PHP script and index +# file to put on the web server. The advantage of the server +# based approach is that it scales better to large projects and allows +# full text search. The disadvances is that it is more difficult to setup +# and does not have live searching capabilities. + +SERVER_BASED_SEARCH = NO + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. +# Note that when enabling USE_PDFLATEX this option is only used for +# generating bitmaps for formulas in the HTML output, but not in the +# Makefile that is written to the output directory. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = letter + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = NO + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = NO + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +# If LATEX_SOURCE_CODE is set to YES then doxygen will include +# source code with syntax highlighting in the LaTeX output. +# Note that which sources are shown also depends on other settings +# such as SOURCE_BROWSER. + +LATEX_SOURCE_CODE = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. +# This is useful +# if you want to understand what is going on. +# On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = ../scripts/interface + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = YES + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more +# powerful graphs. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = NO + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = YES + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is +# allowed to run in parallel. When set to 0 (the default) doxygen will +# base this on the number of processors available in the system. You can set it +# explicitly to a value larger than 0 to get control over the balance +# between CPU load and processing speed. + +DOT_NUM_THREADS = 0 + +# By default doxygen will write a font called FreeSans.ttf to the output +# directory and reference it in all dot files that doxygen generates. This +# font does not include all possible unicode characters however, so when you need +# these (or just want a differently looking font) you can specify the font name +# using DOT_FONTNAME. You need need to make sure dot is able to find the font, +# which can be done by putting it in a standard location or by setting the +# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory +# containing the font. + +DOT_FONTNAME = FreeSans + +# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. +# The default size is 10pt. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the output directory to look for the +# FreeSans.ttf font (which doxygen will put there itself). If you specify a +# different font using DOT_FONTNAME you can set the path where dot +# can find it using this tag. + +DOT_FONTPATH = + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller +# graphs for selected functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = @DOT@ + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not +# seem to support this out of the box. Warning: Depending on the platform used, +# enabling this option may lead to badly anti-aliased labels on the edges of +# a graph (i.e. they become hard to read). + +DOT_TRANSPARENT = YES + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES diff --git a/docs/doxygen.footer b/docs/doxygen.footer new file mode 100644 index 000000000000..c14814b4a7a5 --- /dev/null +++ b/docs/doxygen.footer @@ -0,0 +1,13 @@ +<hr> +<p class="footer"> +Generated on $datetime for <a href="http://lldb.llvm.org/">$projectname</a> by +<a href="http://www.doxygen.org"><img src="doxygen.png" alt="Doxygen" +align="middle" border="0"/>$doxygenversion</a><br> +Copyright © 2003-2013 University of Illinois at Urbana-Champaign. +All Rights Reserved.</p> + +<hr> +<!--#include virtual="/attrib.incl" --> + +</body> +</html> diff --git a/docs/doxygen.header b/docs/doxygen.header new file mode 100644 index 000000000000..e6e0331cb858 --- /dev/null +++ b/docs/doxygen.header @@ -0,0 +1,9 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html><head> +<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/> +<meta name="keywords" content="LLDB,C++,doxygen,API,documentation"/> +<meta name="description" content="C++ source code API documentation for LLDB."/> +<title>LLVM: $title</title> +<link href="doxygen.css" rel="stylesheet" type="text/css"/> +</head><body> +<p class="title">LLDB API Documentation</p> diff --git a/docs/doxygen.intro b/docs/doxygen.intro new file mode 100644 index 000000000000..1e5cd2787ff1 --- /dev/null +++ b/docs/doxygen.intro @@ -0,0 +1,19 @@ +/// @mainpage LLDB +/// +/// @section main_intro Introduction +/// Welcome to LLDB. +/// +/// This documentation describes the @b interface that can drive LLDB. +/// There are no instructions here on how to use LLDB, only the APIs +/// that make up the software. For usage instructions, please see +/// the help command. +/// +/// @section main_caveat Caveat +/// This documentation is generated directly from the source code with doxygen. +/// Since LLDB is constantly under active development, what you're about to +/// read is out of date! However, it may still be useful since certain portions +/// of LLDB are very stable. +/// +/// @section main_changelog Change Log +/// - Adapted for LLDB 05/25/2013 by Daniel Malea +/// - Original content written 12/30/2003 by Reid Spencer diff --git a/docs/lldb-for-gdb-users.txt b/docs/lldb-for-gdb-users.txt new file mode 100644 index 000000000000..216903a55db5 --- /dev/null +++ b/docs/lldb-for-gdb-users.txt @@ -0,0 +1,488 @@ +Here's a short precis of how to run lldb if you are familiar with the +gdb command set: + + +1) LLDB Command Structure: + +First some details on lldb command structure to help orient you... + +Unlike gdb's command set, which is rather free-form, we tried to make +the lldb command syntax fairly structured. The commands are all of the +form + +<noun> <verb> [-options [option-value]] [argument [argument...]] + +The command line parsing is done before command execution, so it is +uniform across all the commands. The command syntax is very simple, +basically arguments, options and option values are all white-space +separated. If you need to put a backslash or double-quote character +in an argument you back-slash it in the argument. That makes the +command syntax more regular, but it also means you may have to +quote some arguments in lldb that you wouldn't in gdb. + +Options can be placed anywhere on the command line, but if the arguments +begin with a "-" then you have to tell lldb that you're done with options +using the "--" option. So for instance, the "process launch" command takes +the "-s" option to mean "stop the process at the first instruction". It's +arguments are the arguments you are passing to the program. So if you wanted +to pass an argument that contained a "-" you would have to do: + +(lldb) process launch -- -program_arg value + +We also tried to reduce the number of special purpose argument +parsers, which sometimes forces the user to be a little more explicit +about stating their intentions. The first instance you'll note of +this is the breakpoint command. In gdb, to set a breakpoint, you +would just say: + +(gdb) break foo.c:12 + +or + +(gdb) break foo + +if foo is a function. As time went on, the parser that tells foo.c:12 +from foo from foo.c::foo (which means the function foo in the file +foo.c) got more and more complex and bizarre, and especially in C++ +there are times where there's really no way to specify the function +you want to break on. The lldb commands are more verbose but also precise. +So you say: + +(lldb) breakpoint set -f foo.c -l 12 + +to set a file & line breakpoint. To set a breakpoint on a function +by name, you do: + +(lldb) breakpoint set -n foo + +This can allow us to be more expressive, so you can say: + +(lldb) breakpoint set -M foo + +to break on all C++ methods named foo, or: + +(lldb) breakpoint set -S alignLeftEdges: + +to set a breakpoint on all ObjC selectors called alignLeftEdges:. It +also makes it easy to compose specifications, like: + +(lldb) breakpoint set -s foo.dylib -n foo + +for all functions called foo in the shared library foo.dylib. Suggestions +on more interesting primitives of this sort are also very welcome. + +So for instance: + +(lldb) breakpoint set -n "-[SKTGraphicView alignLeftEdges:]" + +Just like gdb, the lldb command interpreter does a shortest unique +string match on command names, so the previous command can also be +typed: + +(lldb) b s -n "-[SKTGraphicView alignLeftEdges:]" + +lldb also supports command completion for source file names, symbol +names, file names, etc. Completion is initiated by a hitting a <TAB>. +Individual options in a command can have different completers, so for +instance the -f option in "breakpoint" completes to source files, the +-s option to currently loaded shared libraries, etc... We can even do +things like if you specify -s, and are completing on -f, we will only +list source files in the shared library specified by -s... + +The individual commands are pretty extensively documented, using +the "help" command. And there is an "apropos" command that will +search the help for a particular word and dump a summary help string +for each matching command. + +Finally, there is a mechanism to construct aliases for commonly used +commands. So for instance if you get annoyed typing + +(lldb) b s -f foo.c -l 12 + +you can do: + +(lldb) command alias bfl breakpoint set -f %1 -l %2 +(lldb) bfl foo.c 12 + +We have added a few aliases for commonly used commands (e.g. "step", +"next" and "continue") but we haven't tried to be exhaustive because +in our experience it is more convenient to make the basic commands +unique down to a letter or two, and then learn these sequences than +fill the namespace with lots of aliases, and then have to type them +all the way out. + +However, users are free to customize lldb's command set however they +like, and since lldb reads the file ~/.lldbinit at startup, you can +store all your aliases there and they will be generally available to +you. Your aliases are also documented in the help command so you can +remind yourself of what you've set up. + +lldb also has a built-in Python interpreter, which is accessible by +the "script" command. All the functionality of the debugger is +available as classes in the Python interpreter, so the more complex +commands that in gdb you would introduce with the "define" command can +be done by writing Python functions using the lldb-Python library, +then loading the scripts into your running session and accessing them +with the "script" command. + + + +2) A typical session: + + +a) Setting the program to debug: + + +As with gdb, you can start lldb and specify the file you wish to debug +on the command line: + +$ lldb /Projects/Sketch/build/Debug/Sketch.app +Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). + +or you can specify it after the fact with the "file" command: + +(lldb) file /Projects/Sketch/build/Debug/Sketch.app +Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64). + + +b) Setting breakpoints: + + +We've discussed how to set breakpoints above. You can use "help break set" +to see all the options for breakpoint setting. For instance, we might do: + +(lldb) b s -S alignLeftEdges: +Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1 + +You can find out about the breakpoints you've set with: + +(lldb) break list +Current breakpoints: +1: name = 'alignLeftEdges:', locations = 1, resolved = 1 + 1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x0000000100010d5b, resolved, hit count = 0 + +Note that each "logical" breakpoint can have multiple "locations". +The logical breakpoint has an integer id, and it's locations have an +id within their parent breakpoint (the two are joined by a ".", +e.g. 1.1 in the example above.) + +Also the breakpoints remain "live" so that if another shared library +were to be loaded that had another implementation of the +"alignLeftEdges:" selector, the new location would be added to +breakpoint 1 (e.g. a "1.2" breakpoint would be set on the newly loaded +selector). + +The other piece of information in the breakpoint listing is whether the +breakpoint location was "resolved" or not. A location gets resolved when +the file address it corresponds to gets loaded into the program you are +debugging. For instance if you set a breakpoint in a shared library that +then gets unloaded, that breakpoint location will remain, but it will no +longer be "resolved". + +One other thing to note for gdb users is that lldb acts like gdb with: + +(gdb) set breakpoint pending on + +That is, lldb should always make a breakpoint from your specification, even +if it couldn't find any locations that match the specification. You can tell +whether the expression was resolved or not by checking the locations field +in "breakpoint list", and we report the breakpoint as "pending" when you +set it so you can tell you've made a typo more easily, if that was indeed +the reason no locations were found: + +(lldb) b s -f no_such_file.c -l 10000000 +Breakpoint created: 1: file ='no_such_file.c', line = 10000000, locations = 0 (pending) + +You can delete, disable, set conditions and ignore counts either on all the +locations generated by your logical breakpoint, or on particular locations +your specification resolved to. For instance if we wanted to add a command +to print a backtrace when we hit this breakpoint we could do: + +(lldb) b command add -c 1.1 +Enter your debugger command(s). Type 'DONE' to end. +> bt +> DONE + +The "-c" option specifies that the breakpoint command is a set of lldb +command interpreter commands. Use "-s" if you want to implement your +breakpoint command using the Python interface instead. + + +c) Running the program: + +Then you can either launch the process with the command: + +(lldb) process launch + +or its alias: + +(lldb) r + +Or you can attach to a process by name with: + +(lldb) process attach -n Sketch + +the "attach by name" also supports the "-w" option which waits for the +next process of that name to show up, and attaches to that. You can also +attach by PID: + +(lldb) process attach -p 12345 +Process 46915 Attaching +(lldb) Process 46915 Stopped +1 of 3 threads stopped with reasons: +* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread + +Note that we tell you that "1 of 3 threads stopped with reasons" and +then list those threads. In a multi-threaded environment it is very +common for more than one thread to hit your breakpoint(s) before the +kernel actually returns control to the debugger. In that case, you +will see all the threads that stopped for some interesting reason +listed in the stop message. + + +d) Controlling execution: + + +After launching, we can continue until we hit our breakpoint. The primitive +commands for process control all exist under the "thread" command: + +(lldb) thread continue +Resuming thread 0x2c03 in process 46915 +Resuming process 46915 +(lldb) + +At present you can only operate on one thread at a time, but the +design will ultimately support saying "step over the function in +Thread 1, and step into the function in Thread 2, and continue Thread +3" etc. When we eventually support keeping some threads running while +others are stopped this will be particularly important. For +convenience, however, all the stepping commands have easy aliases. +So "thread continue" is just "c", etc. + +The other program stepping commands are pretty much the same as in gdb. +You've got: + + 1. (lldb) thread step-in + The same as gdb's "step" -- there is also the alias "s" in lldb + + 2. (lldb) thread step-over + The same as gdb's "next" -- there is also the alias "n" in lldb + + 3. (lldb) thread step-out + The same as gdb's "finish" -- there is also the alias "f" in lldb + +And the "by instruction" versions: + +(lldb) thread step-inst +(lldb) thread step-over-inst + +Finally, there's: + +(lldb) thread until 100 + +Which runs the thread in the current frame till it reaches line 100 in +this frame or stops if it leaves the current frame. This is a pretty +close equivalent to gdb's "until" command. + + +One thing here that might be a little disconcerting to gdb users here is that +when you resume process execution, you immediately get a prompt back. That's +because the lldb interpreter remains live when you are running the target. +This allows you to set a breakpoint, etc without having to explicitly interrupt +the program you are debugging. We're still working out all the operations +that it is safe to do while running. But this way of operation will set us +up for "no stop" debugging when we get to implementing that. + +If you want to interrupt a running program do: + +(lldb) process interrupt + +To find out the state of the program, use: + +(lldb) process status +Process 47958 is running. + +This is very convenient, but it does have the down-side that debugging +programs that use stdin is no longer as straightforward. For now, you +have to specify another tty to use as the program stdout & stdin using +the appropriate options to "process launch", or start your program in +another terminal and catch it with "process attach -w". We will come +up with some more convenient way to juggle the terminal back & forth +over time. + + +e) Examining program state: + +Once you've stopped, lldb will choose a current thread, usually the +one that stopped "for a reason", and a current frame in that thread. +Many the commands for inspecting state work on this current +thread/frame. + +To inspect the current state of your process, you can start with the +threads: + +(lldb) thread list +Process 46915 state is Stopped +* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread + thread #2: tid = 0x2e03, 0x00007fff85cbb08a, where = libSystem.B.dylib`kevent + 10, queue = com.apple.libdispatch-manager + thread #3: tid = 0x2f03, 0x00007fff85cbbeaa, where = libSystem.B.dylib`__workq_kernreturn + 10 + +The * indicates that Thread 1 is the current thread. To get a +backtrace for that thread, do: + +(lldb) thread backtrace +thread #1: tid = 0x2c03, stop reason = breakpoint 1.1, queue = com.apple.main-thread + frame #0: 0x0000000100010d5b, where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405 + frame #1: 0x00007fff8602d152, where = AppKit`-[NSApplication sendAction:to:from:] + 95 + frame #2: 0x00007fff860516be, where = AppKit`-[NSMenuItem _corePerformAction] + 365 + frame #3: 0x00007fff86051428, where = AppKit`-[NSCarbonMenuImpl performActionWithHighlightingForItemAtIndex:] + 121 + frame #4: 0x00007fff860370c1, where = AppKit`-[NSMenu performKeyEquivalent:] + 272 + frame #5: 0x00007fff86035e69, where = AppKit`-[NSApplication _handleKeyEquivalent:] + 559 + frame #6: 0x00007fff85f06aa1, where = AppKit`-[NSApplication sendEvent:] + 3630 + frame #7: 0x00007fff85e9d922, where = AppKit`-[NSApplication run] + 474 + frame #8: 0x00007fff85e965f8, where = AppKit`NSApplicationMain + 364 + frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11 + frame #10: 0x0000000100000f20, where = Sketch`start + 52 + +You can also provide a list of threads to backtrace, or the keyword +"all" to see all threads: + +(lldb) thread backtrace all + +Next task is inspecting data: + +The most convenient way to inspect a frame's arguments and local variables is: + +(lldb) frame variable +self = (SKTGraphicView *) 0x0000000100208b40 +_cmd = (struct objc_selector *) 0x000000010001bae1 +sender = (id) 0x00000001001264e0 +selection = (NSArray *) 0x00000001001264e0 +i = (NSUInteger) 0x00000001001264e0 +c = (NSUInteger) 0x00000001001253b0 + +You can also choose particular variables to view: + +(lldb) frame variable self +(SKTGraphicView *) self = 0x0000000100208b40 + +The frame variable command is not a full expression parser but it +does support some common operations like dereferencing: + +(lldb) fr v *self +(SKTGraphicView *) self = 0x0000000100208b40 + (NSView) NSView = { + (NSResponder) NSResponder = { +... + +and structure element references: + +(lldb) frame variable self.isa +(struct objc_class *) self.isa = 0x0000000100023730 + +The frame variable command will also perform "object printing" operations on +variables (currently we only support NSPrintForDebugger) with: + +(lldb) fr v -o self +(SKTGraphicView *) self = 0x0000000100208b40 +<SKTGraphicView: 0x100208b40> + +You can select another frame to view with: + +(lldb) frame select 9 +frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11 + 8 + 9 + 10 int main(int argc, const char *argv[]) { + 11 -> return NSApplicationMain(argc, argv); + 12 } + 13 + 14 + +Another neat trick that the variable list does is array references, so: + +(lldb) fr v argv[0] +(char const *) argv[0] = 0x00007fff5fbffaf8 "/Projects/Sketch/build/Debug/Sketch.app/Contents/MacOS/Sketch" + +If you need to view more complex data or change program data, you can +use the general "expression" command. It takes an expression and +evaluates it in the scope of the currently selected frame. For instance: + +(lldb) expr self +$0 = (SKTGraphicView *) 0x0000000100135430 +(lldb) expr self = 0x00 +$1 = (SKTGraphicView *) 0x0000000000000000 +(lldb) frame var self +(SKTGraphicView *) self = 0x0000000000000000 + +You can also call functions: + +(lldb) expr (int) printf ("I have a pointer 0x%llx.\n", self) +$2 = (int) 22 +I have a pointer 0x0. + +One thing to note from this example is that lldb commands can be defined to +take "raw" input. "expression" is one of these. So in the expression command, +you don't have to quote your whole expression, nor backslash protect quotes, +etc... + +Finally, the results of the expressions are stored in persistent variables +(of the form $[0-9]+) that you can use in further expressions, like: + +(lldb) expr self = $0 +$4 = (SKTGraphicView *) 0x0000000100135430 + +f) Customization: + +You can use the embedded Python interpreter to add the following 'pwd' and 'cd' commands +for your lldb session: + +(lldb) script import os +(lldb) command alias pwd script print os.getcwd() +(lldb) command regex cd "s/^(.*)$/script os.chdir(os.path.expanduser('%1'))/" + +... + +(lldb) cd /tmp +script os.chdir(os.path.expanduser('/tmp')) +(lldb) pwd +/private/tmp +(lldb) + +Or for a more capable 'cd' command, create ~/utils.py like this: + +import os + +def chdir(debugger, args, result, dict): + """Change the working directory, or cd to ${HOME}.""" + dir = args.strip() + if dir: + os.chdir(args) + else: + os.chdir(os.path.expanduser('~')) + print "Current working directory: %s" % os.getcwd() + +and, have the following in your ~/.lldbinit file: + +script import os, sys +script sys.path.append(os.path.expanduser('~')) +script import utils +command alias pwd script print os.getcwd() +command script add -f utils.chdir cd + +and, then in your lldb session, you can have: + +(lldb) help cd + +Change the working directory, or cd to ${HOME}. +Syntax: cd +(lldb) cd +Current working directory: /Volumes/data/Users/johnny +(lldb) cd /tmp +Current working directory: /private/tmp +(lldb) pwd +/private/tmp +(lldb) + +For more examples of customization, look under the ToT/examples/customization +directory. diff --git a/docs/lldb-gdb-remote.txt b/docs/lldb-gdb-remote.txt new file mode 100644 index 000000000000..5c4a10c82b49 --- /dev/null +++ b/docs/lldb-gdb-remote.txt @@ -0,0 +1,1675 @@ +LLDB has added new GDB server packets to better support multi-threaded and +remote debugging. Why? Normally you need to start the correct GDB and the +correct GDB server when debugging. If you have mismatch, then things go wrong +very quickly. LLDB makes extensive use of the GDB remote protocol and we +wanted to make sure that the experience was a bit more dynamic where we can +discover information about a remote target with having to know anything up +front. We also ran into performance issues with the existing GDB remote +protocol that can be overcome when using a reliable communications layer. +Some packets improve performance, others allow for remote process launching +(if you have an OS), and others allow us to dynamically figure out what +registers a thread might have. Again with GDB, both sides pre-agree on how the +registers will look (how many, their register number,name and offsets). We +prefer to be able to dynamically determine what kind of architecture, OS and +vendor we are debugging, as well as how things are laid out when it comes to +the thread register contexts. Below are the details on the new packets we have +added above and beyond the standard GDB remote protocol packets. + +//---------------------------------------------------------------------- +// "QStartNoAckMode" +// +// BRIEF +// Try to enable no ACK mode to skip sending ACKs and NACKs. +// +// PRIORITY TO IMPLEMENT +// High. Any GDB remote server that can implement this should if the +// connection is reliable. This improves packet throughput and increases +// the performance of the connection. +//---------------------------------------------------------------------- +Having to send an ACK/NACK after every packet slows things down a bit, so we +have a way to disable ACK packets to minimize the traffic for reliable +communication interfaces (like sockets). Below GDB or LLDB will send this +packet to try and disable ACKs. All lines that start with "send packet: " are +from GDB/LLDB, and all lines that start with "read packet: " are from the GDB +remote server: + +send packet: $QStartNoAckMode#b0 +read packet: + +read packet: $OK#9a +send packet: + + + + +//---------------------------------------------------------------------- +// "A" - launch args packet +// +// BRIEF +// Launch a program using the supplied arguments +// +// PRIORITY TO IMPLEMENT +// Low. Only needed if the remote target wants to launch a target after +// making a connection to a GDB server that isn't already connected to +// an inferior process. +//---------------------------------------------------------------------- + +We have added support for the "set program arguments" packet where we can +start a connection to a remote server and then later supply the path to the +executable and the arguments to use when executing: + +GDB remote docs for this: + +set program arguments(reserved) Aarglen,argnum,arg,... + +Where A is followed by the length in bytes of the hex encoded argument, +followed by an argument integer, and followed by the ASCII characters +converted into hex bytes foreach arg + +send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00 +read packet: $OK#00 + +The above packet helps when you have remote debugging abilities where you +could launch a process on a remote host, this isn't needed for bare board +debugging. + +//---------------------------------------------------------------------- +// "QEnvironment:NAME=VALUE" +// +// BRIEF +// Setup the environment up for a new child process that will soon be +// launched using the "A" packet. +// +// NB: key/value pairs are sent as-is so gdb-remote protocol meta characters +// (e.g. '#' or '$') are not acceptable. If any non-printable or +// metacharacters are present in the strings, QEnvironmentHexEncoded +// should be used instead if it is available. If you don't want to +// scan the environment strings before sending, prefer +// the QEnvironmentHexEncoded packet over QEnvironment, if it is +// available. +// +// PRIORITY TO IMPLEMENT +// Low. Only needed if the remote target wants to launch a target after +// making a connection to a GDB server that isn't already connected to +// an inferior process. +//---------------------------------------------------------------------- + +Both GDB and LLDB support passing down environment variables. Is it ok to +respond with a "$#00" (unimplemented): + +send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00 +read packet: $OK#00 + +This packet can be sent one or more times _prior_ to sending a "A" packet. + +//---------------------------------------------------------------------- +// "QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)" +// +// BRIEF +// Setup the environment up for a new child process that will soon be +// launched using the "A" packet. +// +// The only difference between this packet and QEnvironment is that the +// environment key-value pair is ascii hex encoded for transmission. +// This allows values with gdb-remote metacharacters like '#' to be sent. +// +// PRIORITY TO IMPLEMENT +// Low. Only needed if the remote target wants to launch a target after +// making a connection to a GDB server that isn't already connected to +// an inferior process. +//---------------------------------------------------------------------- + +Both GDB and LLDB support passing down environment variables. Is it ok to +respond with a "$#00" (unimplemented): + +send packet: $QEnvironment:41434b5f434f4c4f525f46494c454e414d453d626f6c642379656c6c6f77#00 +read packet: $OK#00 + +This packet can be sent one or more times _prior_ to sending a "A" packet. + +//---------------------------------------------------------------------- +// "QSetSTDIN:<ascii-hex-path>" +// "QSetSTDOUT:<ascii-hex-path>" +// "QSetSTDERR:<ascii-hex-path>" +// +// BRIEF +// Setup where STDIN, STDOUT, and STDERR go prior to sending an "A" +// packet. +// +// PRIORITY TO IMPLEMENT +// Low. Only needed if the remote target wants to launch a target after +// making a connection to a GDB server that isn't already connected to +// an inferior process. +//---------------------------------------------------------------------- + +When launching a program through the GDB remote protocol with the "A" packet, +you might also want to specify where stdin/out/err go: + +QSetSTDIN:<ascii-hex-path> +QSetSTDOUT:<ascii-hex-path> +QSetSTDERR:<ascii-hex-path> + +These packets must be sent _prior_ to sending a "A" packet. + +//---------------------------------------------------------------------- +// "QSetWorkingDir:<ascii-hex-path>" +// +// BRIEF +// Set the working directory prior to sending an "A" packet. +// +// PRIORITY TO IMPLEMENT +// Low. Only needed if the remote target wants to launch a target after +// making a connection to a GDB server that isn't already connected to +// an inferior process. +//---------------------------------------------------------------------- + +Or specify the working directory: + +QSetWorkingDir:<ascii-hex-path> + +This packet must be sent _prior_ to sending a "A" packet. + +//---------------------------------------------------------------------- +// "QSetDisableASLR:<bool>" +// +// BRIEF +// Enable or disable ASLR on the next "A" packet. +// +// PRIORITY TO IMPLEMENT +// Low. Only needed if the remote target wants to launch a target after +// making a connection to a GDB server that isn't already connected to +// an inferior process and if the target supports disabling ASLR +// (Address space layout randomization). +//---------------------------------------------------------------------- + +Or control if ASLR is enabled/disabled: + +send packet: QSetDisableASLR:1 +read packet: OK + +send packet: QSetDisableASLR:0 +read packet: OK + +This packet must be sent _prior_ to sending a "A" packet. + +//---------------------------------------------------------------------- +// QListThreadsInStopReply +// +// BRIEF +// Enable the threads: and thread-pcs: data in the question-mark packet +// ("T packet") responses when the stub reports that a program has +// stopped executing. +// +// PRIORITY TO IMPLEMENT +// Performance. This is a performance benefit to lldb if the thread id's +// and thread pc values are provided to lldb in the T stop packet -- if +// they are not provided to lldb, lldb will likely need to send one to +// two packets per thread to fetch the data at every private stop. +//---------------------------------------------------------------------- + +send packet: QListThreadsInStopReply +read packet: OK + +//---------------------------------------------------------------------- +// "qRegisterInfo<hex-reg-id>" +// +// BRIEF +// Discover register information from the remote GDB server. +// +// PRIORITY TO IMPLEMENT +// High. Any target that can self describe its registers, should do so. +// This means if new registers are ever added to a remote target, they +// will get picked up automatically, and allows registers to change +// depending on the actual CPU type that is used. +// +// NB: As of summer 2015, lldb can get register information from the +// "qXfer:features:read:target.xml" FSF gdb standard register packet +// where the stub provides register definitions in an XML file. +// If qXfer:features:read:target.xml is supported, qRegisterInfo does +// not need to be implemented. +//---------------------------------------------------------------------- + +With LLDB, for register information, remote GDB servers can add +support for the "qRegisterInfoN" packet where "N" is a zero based +base16 register number that must start at zero and increase by one +for each register that is supported. The response is done in typical +GDB remote fashion where a series of "KEY:VALUE;" pairs are returned. +An example for the x86_64 registers is included below: + +send packet: $qRegisterInfo0#00 +read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00 +send packet: $qRegisterInfo1#00 +read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00 +send packet: $qRegisterInfo2#00 +read packet: $name:rcx;bitsize:64;offset:16;encoding:uint;format:hex;set:General Purpose Registers;gcc:2;dwarf:2;#00 +send packet: $qRegisterInfo3#00 +read packet: $name:rdx;bitsize:64;offset:24;encoding:uint;format:hex;set:General Purpose Registers;gcc:1;dwarf:1;#00 +send packet: $qRegisterInfo4#00 +read packet: $name:rdi;bitsize:64;offset:32;encoding:uint;format:hex;set:General Purpose Registers;gcc:5;dwarf:5;#00 +send packet: $qRegisterInfo5#00 +read packet: $name:rsi;bitsize:64;offset:40;encoding:uint;format:hex;set:General Purpose Registers;gcc:4;dwarf:4;#00 +send packet: $qRegisterInfo6#00 +read packet: $name:rbp;alt-name:fp;bitsize:64;offset:48;encoding:uint;format:hex;set:General Purpose Registers;gcc:6;dwarf:6;generic:fp;#00 +send packet: $qRegisterInfo7#00 +read packet: $name:rsp;alt-name:sp;bitsize:64;offset:56;encoding:uint;format:hex;set:General Purpose Registers;gcc:7;dwarf:7;generic:sp;#00 +send packet: $qRegisterInfo8#00 +read packet: $name:r8;bitsize:64;offset:64;encoding:uint;format:hex;set:General Purpose Registers;gcc:8;dwarf:8;#00 +send packet: $qRegisterInfo9#00 +read packet: $name:r9;bitsize:64;offset:72;encoding:uint;format:hex;set:General Purpose Registers;gcc:9;dwarf:9;#00 +send packet: $qRegisterInfoa#00 +read packet: $name:r10;bitsize:64;offset:80;encoding:uint;format:hex;set:General Purpose Registers;gcc:10;dwarf:10;#00 +send packet: $qRegisterInfob#00 +read packet: $name:r11;bitsize:64;offset:88;encoding:uint;format:hex;set:General Purpose Registers;gcc:11;dwarf:11;#00 +send packet: $qRegisterInfoc#00 +read packet: $name:r12;bitsize:64;offset:96;encoding:uint;format:hex;set:General Purpose Registers;gcc:12;dwarf:12;#00 +send packet: $qRegisterInfod#00 +read packet: $name:r13;bitsize:64;offset:104;encoding:uint;format:hex;set:General Purpose Registers;gcc:13;dwarf:13;#00 +send packet: $qRegisterInfoe#00 +read packet: $name:r14;bitsize:64;offset:112;encoding:uint;format:hex;set:General Purpose Registers;gcc:14;dwarf:14;#00 +send packet: $qRegisterInfof#00 +read packet: $name:r15;bitsize:64;offset:120;encoding:uint;format:hex;set:General Purpose Registers;gcc:15;dwarf:15;#00 +send packet: $qRegisterInfo10#00 +read packet: $name:rip;alt-name:pc;bitsize:64;offset:128;encoding:uint;format:hex;set:General Purpose Registers;gcc:16;dwarf:16;generic:pc;#00 +send packet: $qRegisterInfo11#00 +read packet: $name:rflags;alt-name:flags;bitsize:64;offset:136;encoding:uint;format:hex;set:General Purpose Registers;#00 +send packet: $qRegisterInfo12#00 +read packet: $name:cs;bitsize:64;offset:144;encoding:uint;format:hex;set:General Purpose Registers;#00 +send packet: $qRegisterInfo13#00 +read packet: $name:fs;bitsize:64;offset:152;encoding:uint;format:hex;set:General Purpose Registers;#00 +send packet: $qRegisterInfo14#00 +read packet: $name:gs;bitsize:64;offset:160;encoding:uint;format:hex;set:General Purpose Registers;#00 +send packet: $qRegisterInfo15#00 +read packet: $name:fctrl;bitsize:16;offset:176;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo16#00 +read packet: $name:fstat;bitsize:16;offset:178;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo17#00 +read packet: $name:ftag;bitsize:8;offset:180;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo18#00 +read packet: $name:fop;bitsize:16;offset:182;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo19#00 +read packet: $name:fioff;bitsize:32;offset:184;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo1a#00 +read packet: $name:fiseg;bitsize:16;offset:188;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo1b#00 +read packet: $name:fooff;bitsize:32;offset:192;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo1c#00 +read packet: $name:foseg;bitsize:16;offset:196;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo1d#00 +read packet: $name:mxcsr;bitsize:32;offset:200;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo1e#00 +read packet: $name:mxcsrmask;bitsize:32;offset:204;encoding:uint;format:hex;set:Floating Point Registers;#00 +send packet: $qRegisterInfo1f#00 +read packet: $name:stmm0;bitsize:80;offset:208;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:33;dwarf:33;#00 +send packet: $qRegisterInfo20#00 +read packet: $name:stmm1;bitsize:80;offset:224;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:34;dwarf:34;#00 +send packet: $qRegisterInfo21#00 +read packet: $name:stmm2;bitsize:80;offset:240;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:35;dwarf:35;#00 +send packet: $qRegisterInfo22#00 +read packet: $name:stmm3;bitsize:80;offset:256;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:36;dwarf:36;#00 +send packet: $qRegisterInfo23#00 +read packet: $name:stmm4;bitsize:80;offset:272;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:37;dwarf:37;#00 +send packet: $qRegisterInfo24#00 +read packet: $name:stmm5;bitsize:80;offset:288;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:38;dwarf:38;#00 +send packet: $qRegisterInfo25#00 +read packet: $name:stmm6;bitsize:80;offset:304;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:39;dwarf:39;#00 +send packet: $qRegisterInfo26#00 +read packet: $name:stmm7;bitsize:80;offset:320;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:40;dwarf:40;#00 +send packet: $qRegisterInfo27#00 +read packet: $name:xmm0;bitsize:128;offset:336;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:17;dwarf:17;#00 +send packet: $qRegisterInfo28#00 +read packet: $name:xmm1;bitsize:128;offset:352;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:18;dwarf:18;#00 +send packet: $qRegisterInfo29#00 +read packet: $name:xmm2;bitsize:128;offset:368;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:19;dwarf:19;#00 +send packet: $qRegisterInfo2a#00 +read packet: $name:xmm3;bitsize:128;offset:384;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:20;dwarf:20;#00 +send packet: $qRegisterInfo2b#00 +read packet: $name:xmm4;bitsize:128;offset:400;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:21;dwarf:21;#00 +send packet: $qRegisterInfo2c#00 +read packet: $name:xmm5;bitsize:128;offset:416;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:22;dwarf:22;#00 +send packet: $qRegisterInfo2d#00 +read packet: $name:xmm6;bitsize:128;offset:432;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:23;dwarf:23;#00 +send packet: $qRegisterInfo2e#00 +read packet: $name:xmm7;bitsize:128;offset:448;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:24;dwarf:24;#00 +send packet: $qRegisterInfo2f#00 +read packet: $name:xmm8;bitsize:128;offset:464;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:25;dwarf:25;#00 +send packet: $qRegisterInfo30#00 +read packet: $name:xmm9;bitsize:128;offset:480;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:26;dwarf:26;#00 +send packet: $qRegisterInfo31#00 +read packet: $name:xmm10;bitsize:128;offset:496;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:27;dwarf:27;#00 +send packet: $qRegisterInfo32#00 +read packet: $name:xmm11;bitsize:128;offset:512;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:28;dwarf:28;#00 +send packet: $qRegisterInfo33#00 +read packet: $name:xmm12;bitsize:128;offset:528;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:29;dwarf:29;#00 +send packet: $qRegisterInfo34#00 +read packet: $name:xmm13;bitsize:128;offset:544;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:30;dwarf:30;#00 +send packet: $qRegisterInfo35#00 +read packet: $name:xmm14;bitsize:128;offset:560;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:31;dwarf:31;#00 +send packet: $qRegisterInfo36#00 +read packet: $name:xmm15;bitsize:128;offset:576;encoding:vector;format:vector-uint8;set:Floating Point Registers;gcc:32;dwarf:32;#00 +send packet: $qRegisterInfo37#00 +read packet: $name:trapno;bitsize:32;offset:696;encoding:uint;format:hex;set:Exception State Registers;#00 +send packet: $qRegisterInfo38#00 +read packet: $name:err;bitsize:32;offset:700;encoding:uint;format:hex;set:Exception State Registers;#00 +send packet: $qRegisterInfo39#00 +read packet: $name:faultvaddr;bitsize:64;offset:704;encoding:uint;format:hex;set:Exception State Registers;#00 +send packet: $qRegisterInfo3a#00 +read packet: $E45#00 + +As we see above we keep making subsequent calls to the remote server to +discover all registers by increasing the number appended to qRegisterInfo and +we get a response back that is a series of "key=value;" strings. + +The offset: fields should not leave a gap anywhere in the g/G packet -- the +register values should be appended one after another. For instance, if the +register context for a thread looks like + +struct rctx { + uint32_t gpr1; // offset 0 + uint32_t gpr2; // offset 4 + uint32_t gpr3; // offset 8 + uint64_t fp1; // offset 16 +}; + +You may end up with a 4-byte gap between gpr3 and fp1 on architectures +that align values like this. The correct offset: value for fp1 is 12 - +in the g/G packet fp1 will immediately follow gpr3, even though the +in-memory thread structure has an empty 4 bytes for alignment between +these two registers. + +The keys and values are detailed below: + +Key Value +========== ================================================================ +name The primary register name as a string ("rbp" for example) + +alt-name An alternate name for a register as a string ("fp" for example for + the above "rbp") + +bitsize Size in bits of a register (32, 64, etc). Base 10. + +offset The offset within the "g" and "G" packet of the register data for + this register. This is the byte offset once the data has been + transformed into binary, not the character offset into the g/G + packet. Base 10. + +encoding The encoding type of the register which must be one of: + + uint (unsigned integer) + sint (signed integer) + ieee754 (IEEE 754 float) + vector (vector register) + +format The preferred format for display of this register. The value must + be one of: + + binary + decimal + hex + float + vector-sint8 + vector-uint8 + vector-sint16 + vector-uint16 + vector-sint32 + vector-uint32 + vector-float32 + vector-uint128 + +set The register set name as a string that this register belongs to. + +gcc The GCC compiler registers number for this register (used for + EH frame and other compiler information that is encoded in the + executable files). The supplied number will be decoded like a + string passed to strtoul() with a base of zero, so the number + can be decimal, or hex if it is prefixed with "0x". + + NOTE: If the compiler doesn't have a register number for this + register, this key/value pair should be omitted. + +dwarf The DWARF register number for this register that is used for this + register in the debug information. The supplied number will be decoded + like a string passed to strtoul() with a base of zero, so the number + can be decimal, or hex if it is prefixed with "0x". + + NOTE: If the compiler doesn't have a register number for this + register, this key/value pair should be omitted. + +generic If the register is a generic register that most CPUs have, classify + it correctly so the debugger knows. Valid values are one of: + pc (a program counter register. for example "name=eip;" (i386), + "name=rip;" (x86_64), "name=r15;" (32 bit arm) would + include a "generic=pc;" key value pair) + sp (a stack pointer register. for example "name=esp;" (i386), + "name=rsp;" (x86_64), "name=r13;" (32 bit arm) would + include a "generic=sp;" key value pair) + fp (a frame pointer register. for example "name=ebp;" (i386), + "name=rbp;" (x86_64), "name=r7;" (32 bit arm with macosx + ABI) would include a "generic=fp;" key value pair) + ra (a return address register. for example "name=lr;" (32 bit ARM) + would include a "generic=ra;" key value pair) + fp (a CPU flags register. for example "name=eflags;" (i386), + "name=rflags;" (x86_64), "name=cpsr;" (32 bit ARM) + would include a "generic=flags;" key value pair) + arg1 - arg8 (specified for registers that contain function + arguments when the argument fits into a register) + +container-regs + The value for this key is a comma separated list of raw hex (optional + leading "0x") register numbers. + + This specifies that this register is contained in other concrete + register values. For example "eax" is in the lower 32 bits of the + "rax" register value for x86_64, so "eax" could specify that it is + contained in "rax" by specifying the register number for "rax" (whose + register number is 0x00) + + "container-regs:00;" + + If a register is comprised of one or more registers, like "d0" is ARM + which is a 64 bit register, it might be made up of "s0" and "s1". If + the register number for "s0" is 0x20, and the register number of "s1" + is "0x21", the "container-regs" key/value pair would be: + + "container-regs:20,21;" + + This is handy for defining what GDB used to call "pseudo" registers. + These registers are never requested by LLDB via the register read + or write packets, the container registers will be requested on behalf + of this register. + +invalidate-regs + The value for this key is a comma separated list of raw hex (optional + leading "0x") register numbers. + + This specifies which register values should be invalidated when this + register is modified. For example if modifying "eax" would cause "rax", + "eax", "ax", "ah", and "al" to be modified where rax is 0x0, eax is 0x15, + ax is 0x25, ah is 0x35, and al is 0x39, the "invalidate-regs" key/value + pair would be: + + "invalidate-regs:0,15,25,35,39;" + + If there is a single register that gets invalidated, then omit the comma + and just list a single register: + + "invalidate-regs:0;" + + This is handy when modifying a specific register can cause other + register values to change. For example, when debugging an ARM target, + modifying the CPSR register can cause the r8 - r14 and cpsr value to + change depending on if the mode has changed. + +//---------------------------------------------------------------------- +// "qPlatform_shell" +// +// BRIEF +// Run a command in a shell on the connected remote machine. +// +// PRIORITY TO IMPLEMENT +// High. This command allows LLDB clients to run arbitrary shell +// commands on a remote host. +// +/---------------------------------------------------------------------- + +The request consists of the command to be executed encoded in ASCII characters +converted into hex bytes. + +The response to this packet consists of the letter F followed by the return code, +followed by the signal number (or 0 if no signal was delivered), and escaped bytes +of captured program output. + +Below is an example communication from a client sending an "ls -la" command: + +send packet: $qPlatform_shell:6c73202d6c61,00000002#ec +read packet: $F,00000000,00000000,total 4736 +drwxrwxr-x 16 username groupname 4096 Aug 15 21:36 . +drwxr-xr-x 17 username groupname 4096 Aug 10 16:39 .. +-rw-rw-r-- 1 username groupname 73875 Aug 12 16:46 notes.txt +drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp +-rw-r--r-- 1 username groupname 2792 Aug 12 16:46 a.out +-rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile + +//---------------------------------------------------------------------- +// "qPlatform_mkdir" +// +// BRIEF +// Creates a new directory on the connected remote machine. +// +// PRIORITY TO IMPLEMENT +// Low. This command allows LLDB clients to create new directories on +// a remote host. +// +/---------------------------------------------------------------------- + +Request: + qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path> + +Reply: + F<mkdir-return-code> + mkdir called successfully and returned with the given return code + Exx + An error occurred + +//---------------------------------------------------------------------- +// "qPlatform_chmod" +// +// BRIEF +// Change the permissions of a file on the connected remote machine. +// +// PRIORITY TO IMPLEMENT +// Low. This command allows LLDB clients to change the permissions of +// a file on the remote host. +// +/---------------------------------------------------------------------- + +Request: + qPlatform_chmod:<hex-file-mode>,<ascii-hex-path> + +Reply: + F<chmod-return-code> + chmod called successfully and returned with the given return code + Exx + An error occurred + +//---------------------------------------------------------------------- +// "qHostInfo" +// +// BRIEF +// Get information about the host we are remotely connected to. +// +// PRIORITY TO IMPLEMENT +// High. This packet is usually very easy to implement and can help +// LLDB select the correct plug-ins for the job based on the target +// triple information that is supplied. +//---------------------------------------------------------------------- + +LLDB supports a host info call that gets all sorts of details of the system +that is being debugged: + +send packet: $qHostInfo#00 +read packet: $cputype:16777223;cpusubtype:3;ostype:darwin;vendor:apple;endian:little;ptrsize:8;#00 + +Key value pairs are one of: + +cputype: is a number that is the mach-o CPU type that is being debugged (base 10) +cpusubtype: is a number that is the mach-o CPU subtype type that is being debugged (base 10) +triple: a string for the target triple (x86_64-apple-macosx) that can be used to specify arch + vendor + os in one entry +vendor: a string for the vendor (apple), not needed if "triple" is specified +ostype: a string for the OS being debugged (macosx, linux, freebsd, ios, watchos), not needed if "triple" is specified +endian: is one of "little", "big", or "pdp" +ptrsize: an unsigned number that represents how big pointers are in bytes on the debug target +hostname: the hostname of the host that is running the GDB server if available +os_build: a string for the OS build for the remote host as a string value +os_kernel: a string describing the kernel version +os_version: a version string that represents the current OS version (10.8.2) +watchpoint_exceptions_received: one of "before" or "after" to specify if a watchpoint is triggered before or after the pc when it stops +default_packet_timeout: an unsigned number that specifies the default timeout in seconds +distribution_id: optional. For linux, specifies distribution id (e.g. ubuntu, fedora, etc.) +osmajor: optional, specifies the major version number of the OS (e.g. for Mac OS X 10.11.2, it would be 10) +osminor: optional, specifies the minor version number of the OS (e.g. for Mac OS X 10.11.2, it would be 11) +ospatch: optional, specifies the patch level number of the OS (e.g. for Mac OS X 10.11.2, it would be 2) + +//---------------------------------------------------------------------- +// "qGDBServerVersion" +// +// BRIEF +// Get version information about this implementation of the gdb-remote +// protocol. +// +// PRIORITY TO IMPLEMENT +// High. This packet is usually very easy to implement and can help +// LLDB to work around bugs in a server's implementation when they +// are found. +//---------------------------------------------------------------------- + +The goal of this packet is to provide enough information about an +implementation of the gdb-remote-protocol server that lldb can +work around implementation problems that are discovered after the +version has been released/deployed. The name and version number +should be sufficiently unique that lldb can unambiguously identify +the origin of the program (for instance, debugserver from lldb) and +the version/submission number/patch level of the program - whatever +is appropriate for your server implementation. + +The packet follows the key-value pair model, semicolon separated. + +send packet: $qGDBServerVersion#00 +read packet: $name:debugserver;version:310.2;#00 + +Other clients may find other key-value pairs to be useful for identifying +a gdb stub. Patch level, release name, build number may all be keys that +better describe your implementation's version. +Suggested key names: + + name : the name of your remote server - "debugserver" is the lldb standard + implementation + + version : identifies the version number of this server + + patch_level : the patch level of this server + + release_name : the name of this release, if your project uses names + + build_number : if you use a build system with increasing build numbers, + this may be the right key name for your server + + major_version : major version number + minor_version : minor version number + +//---------------------------------------------------------------------- +// "qProcessInfo" +// +// BRIEF +// Get information about the process we are currently debugging. +// +// PRIORITY TO IMPLEMENT +// Medium. On systems which can launch multiple different architecture processes, +// the qHostInfo may not disambiguate sufficiently to know what kind of +// process is being debugged. +// e.g. on a 64-bit x86 Mac system both 32-bit and 64-bit user processes are possible, +// and with Mach-O universal files, the executable file may contain both 32- and +// 64-bit slices so it may be impossible to know until you're attached to a real +// process to know what you're working with. +// +// All numeric fields return base-16 numbers without any "0x" prefix. +//---------------------------------------------------------------------- + +An i386 process: + +send packet: $qProcessInfo#00 +read packet: $pid:42a8;parent-pid:42bf;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:7;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:4;#00 + +An x86_64 process: + +send packet: $qProcessInfo#00 +read packet: $pid:d22c;parent-pid:d34d;real-uid:ecf;real-gid:b;effective-uid:ecf;effective-gid:b;cputype:1000007;cpusubtype:3;ostype:macosx;vendor:apple;endian:little;ptrsize:8;#00 + +Key value pairs include: + +pid: the process id +parent-pid: the process of the parent process (often debugserver will become the parent when attaching) +real-uid: the real user id of the process +real-gid: the real group id of the process +effective-uid: the effective user id of the process +effective-gid: the effective group id of the process +cputype: the Mach-O CPU type of the process (base 16) +cpusubtype: the Mach-O CPU subtype of the process (base 16) +ostype: is a string the represents the OS being debugged (darwin, linux, freebsd) +vendor: is a string that represents the vendor (apple) +endian: is one of "little", "big", or "pdp" +ptrsize: is a number that represents how big pointers are in bytes + + +//---------------------------------------------------------------------- +// "qShlibInfoAddr" +// +// BRIEF +// Get an address where the dynamic linker stores information about +// where shared libraries are loaded. +// +// PRIORITY TO IMPLEMENT +// High if you have a dynamic loader plug-in in LLDB for your target +// triple (see the "qHostInfo" packet) that can use this information. +// Many times address load randomization can make it hard to detect +// where the dynamic loader binary and data structures are located and +// some platforms know, or can find out where this information is. +// +// Low if you have a debug target where all object and symbol files +// contain static load addresses. +//---------------------------------------------------------------------- + +LLDB and GDB both support the "qShlibInfoAddr" packet which is a hint to each +debugger as to where to find the dynamic loader information. For darwin +binaries that run in user land this is the address of the "all_image_infos" +structure in the "/usr/lib/dyld" executable, or the result of a TASK_DYLD_INFO +call. The result is returned as big endian hex bytes that are the address +value: + +send packet: $qShlibInfoAddr#00 +read packet: $7fff5fc40040#00 + + + +//---------------------------------------------------------------------- +// "qThreadStopInfo<tid>" +// +// BRIEF +// Get information about why a thread, whose ID is "<tid>", is stopped. +// +// PRIORITY TO IMPLEMENT +// High if you need to support multi-threaded or multi-core debugging. +// Many times one thread will hit a breakpoint and while the debugger +// is in the process of suspending the other threads, other threads +// will also hit a breakpoint. This packet allows LLDB to know why all +// threads (live system debug) / cores (JTAG) in your program have +// stopped and allows LLDB to display and control your program +// correctly. +//---------------------------------------------------------------------- + +LLDB tries to use the "qThreadStopInfo" packet which is formatted as +"qThreadStopInfo%x" where %x is the hex thread ID. This requests information +about why a thread is stopped. The response is the same as the stop reply +packets and tells us what happened to the other threads. The standard GDB +remote packets love to think that there is only _one_ reason that _one_ thread +stops at a time. This allows us to see why all threads stopped and allows us +to implement better multi-threaded debugging support. + +//---------------------------------------------------------------------- +// "QThreadSuffixSupported" +// +// BRIEF +// Try to enable thread suffix support for the 'g', 'G', 'p', and 'P' +// packets. +// +// PRIORITY TO IMPLEMENT +// High. Adding a thread suffix allows us to read and write registers +// more efficiently and stops us from having to select a thread with +// one packet and then read registers with a second packet. It also +// makes sure that no errors can occur where the debugger thinks it +// already has a thread selected (see the "Hg" packet from the standard +// GDB remote protocol documentation) yet the remote GDB server actually +// has another thread selected. +//---------------------------------------------------------------------- + +When reading thread registers, you currently need to set the current +thread, then read the registers. This is kind of cumbersome, so we added the +ability to query if the remote GDB server supports adding a "thread:<tid>;" +suffix to all packets that request information for a thread. To test if the +remote GDB server supports this feature: + +send packet: $QThreadSuffixSupported#00 +read packet: OK + +If "OK" is returned, then the 'g', 'G', 'p' and 'P' packets can accept a +thread suffix. So to send a 'g' packet (read all register values): + +send packet: $g;thread:<tid>;#00 +read packet: .... + +send packet: $G;thread:<tid>;#00 +read packet: .... + +send packet: $p1a;thread:<tid>;#00 +read packet: .... + +send packet: $P1a=1234abcd;thread:<tid>;#00 +read packet: .... + + +otherwise, without this you would need to always send two packets: + +send packet: $Hg<tid>#00 +read packet: .... +send packet: $g#00 +read packet: .... + +We also added support for allocating and deallocating memory. We use this to +allocate memory so we can run JITed code. + +//---------------------------------------------------------------------- +// "_M<size>,<permissions>" +// +// BRIEF +// Allocate memory on the remote target with the specified size and +// permissions. +// +// PRIORITY TO IMPLEMENT +// High if you want LLDB to be able to JIT code and run that code. JIT +// code also needs data which is also allocated and tracked. +// +// Low if you don't support running JIT'ed code. +//---------------------------------------------------------------------- + +The allocate memory packet starts with "_M<size>,<permissions>". It returns a +raw big endian address value, or "" for unimplemented, or "EXX" for an error +code. The packet is formatted as: + +char packet[256]; +int packet_len; +packet_len = ::snprintf ( + packet, + sizeof(packet), + "_M%zx,%s%s%s", + (size_t)size, + permissions & lldb::ePermissionsReadable ? "r" : "", + permissions & lldb::ePermissionsWritable ? "w" : "", + permissions & lldb::ePermissionsExecutable ? "x" : ""); + +You request a size and give the permissions. This packet does NOT need to be +implemented if you don't want to support running JITed code. The return value +is just the address of the newly allocated memory as raw big endian hex bytes. + +//---------------------------------------------------------------------- +// "_m<addr>" +// +// BRIEF +// Deallocate memory that was previously allocated using an allocate +// memory pack. +// +// PRIORITY TO IMPLEMENT +// High if you want LLDB to be able to JIT code and run that code. JIT +// code also needs data which is also allocated and tracked. +// +// Low if you don't support running JIT'ed code. +//---------------------------------------------------------------------- + +The deallocate memory packet is "_m<addr>" where you pass in the address you +got back from a previous call to the allocate memory packet. It returns "OK" +if the memory was successfully deallocated, or "EXX" for an error, or "" if +not supported. + +//---------------------------------------------------------------------- +// "qMemoryRegionInfo:<addr>" +// +// BRIEF +// Get information about the address range that contains "<addr>" +// +// PRIORITY TO IMPLEMENT +// Medium. This is nice to have, but it isn't necessary. It helps LLDB +// do stack unwinding when we branch into memory that isn't executable. +// If we can detect that the code we are stopped in isn't executable, +// then we can recover registers for stack frames above the current +// frame. Otherwise we must assume we are in some JIT'ed code (not JIT +// code that LLDB has made) and assume that no registers are available +// in higher stack frames. +//---------------------------------------------------------------------- + +We added a way to get information for a memory region. The packet is: + + qMemoryRegionInfo:<addr> + +Where <addr> is a big endian hex address. The response is returned in a series +of tuples like the data returned in a stop reply packet. The currently valid +tuples to return are: + + start:<start-addr>; // <start-addr> is a big endian hex address that is + // the start address of the range that contains <addr> + + size:<size>; // <size> is a big endian hex byte size of the address + // of the range that contains <addr> + + permissions:<permissions>; // <permissions> is a string that contains one + // or more of the characters from "rwx" + + error:<ascii-byte-error-string>; // where <ascii-byte-error-string> is + // a hex encoded string value that + // contains an error string + +If the address requested is not in a mapped region (e.g. we've jumped through +a NULL pointer and are at 0x0) currently lldb expects to get back the size +of the unmapped region -- that is, the distance to the next valid region. +For instance, with a Mac OS X process which has nothing mapped in the first +4GB of its address space, if we're asking about address 0x2, + + qMemoryRegionInfo:2 + start:2;size:fffffffe; + +The lack of 'permissions:' indicates that none of read/write/execute are valid +for this region. + +//---------------------------------------------------------------------- +// "x" - Binary memory read +// +// Like the 'm' (read) and 'M' (write) packets, this is a partner to the +// 'X' (write binary data) packet, 'x'. +// +// It is called like +// +// xADDRESS,LENGTH +// +// where both ADDRESS and LENGTH are big-endian base 16 values. +// +// To test if this packet is available, send a addr/len of 0: +// +// x0,0 +// +// and you will get an "OK" response. +// +// The reply will be the data requested in 8-bit binary data format. +// The standard quoting is applied to the payload -- characters +// } # $ * +// will all be escaped with '}' (0x7d) character and then XOR'ed with 0x20. +// +// A typical use to read 512 bytes at 0x1000 would look like +// +// x0x1000,0x200 +// +// The "0x" prefixes are optional - like most of the gdb-remote packets, +// omitting them will work fine; these numbers are always base 16. +// +// The length of the payload is not provided. A reliable, 8-bit clean, +// transport layer is assumed. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// Detach and stay stopped: +// +// We extended the "D" packet to specify that the monitor should keep the +// target suspended on detach. The normal behavior is to resume execution +// on detach. We will send: +// +// qSupportsDetachAndStayStopped: +// +// to query whether the monitor supports the extended detach, and if it does, +// when we want the monitor to detach but not resume the target, we will +// send: +// +// D1 +// +// In any case, if we want the normal detach behavior we will just send: +// +// D +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// QSaveRegisterState +// QSaveRegisterState;thread:XXXX; +// +// BRIEF +// The QSaveRegisterState packet tells the remote debugserver to save +// all registers and return a non-zero unique integer ID that +// represents these save registers. If thread suffixes are enabled the +// second form of this packet is used, otherwise the first form is +// used. This packet is called prior to executing an expression, so +// the remote GDB server should do anything it needs to in order to +// ensure the registers that are saved are correct. On MacOSX this +// involves calling "thread_abort_safely(mach_port_t thread)" to +// ensure we get the correct registers for a thread in case it is +// currently having code run on its behalf in the kernel. +// +// RESPONSE +// unsigned - The save_id result is a non-zero unsigned integer value +// that can be passed back to the GDB server using a +// QRestoreRegisterState packet to restore the registers +// one time. +// "EXX" - or an error code in the form of EXX where XX is a +// hex error code. +// +// PRIORITY TO IMPLEMENT +// Low, this is mostly a convenience packet to avoid having to send all +// registers via a g packet. It should only be implemented if support +// for the QRestoreRegisterState is added. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// QRestoreRegisterState:<save_id> +// QRestoreRegisterState:<save_id>;thread:XXXX; +// +// BRIEF +// The QRestoreRegisterState packet tells the remote debugserver to +// restore all registers using the "save_id" which is an unsigned +// integer that was returned from a previous call to +// QSaveRegisterState. The restoration process can only be done once +// as the data backing the register state will be freed upon the +// completion of the QRestoreRegisterState command. +// +// If thread suffixes are enabled the second form of this packet is +// used, otherwise the first form is used. +// +// RESPONSE +// "OK" - if all registers were successfully restored +// "EXX" - for any errors +// +// PRIORITY TO IMPLEMENT +// Low, this is mostly a convenience packet to avoid having to send all +// registers via a g packet. It should only be implemented if support +// for the QSaveRegisterState is added. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// qFileLoadAddress:<file_path> +// +// BRIEF +// Get the load address of a memory mapped file. +// The load address is defined as the address of the first memory +// region what contains data mapped from the specified file. +// +// RESPONSE +// <unsinged-hex64> - Load address of the file in big endian encoding +// "E01" - the requested file isn't loaded +// "EXX" - for any other errors +// +// PRIORITY TO IMPLEMENT +// Low, required if dynamic linker don't fill in the load address of +// some object file in the rendezvous data structure. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// qModuleInfo:<module_path>;<arch triple> +// +// BRIEF +// Get information for a module by given module path and architecture. +// +// RESPONSE +// "(uuid|md5):...;triple:...;file_offset:...;file_size...;" +// "EXX" - for any errors +// +// PRIORITY TO IMPLEMENT +// Optional, required if dynamic loader cannot fetch module's information like +// UUID directly from inferior's memory. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// Stop reply packet extensions +// +// BRIEF +// This section describes some of the additional information you can +// specify in stop reply packets that help LLDB to know more detailed +// information about your threads. +// +// DESCRIPTION +// Standard GDB remote stop reply packets are reply packets sent in +// response to a packet that made the program run. They come in the +// following forms: +// +// "SAA" +// "S" means signal and "AA" is a hex signal number that describes why +// the thread or stopped. It doesn't specify which thread, so the "T" +// packet is recommended to use instead of the "S" packet. +// +// "TAAkey1:value1;key2:value2;..." +// "T" means a thread stopped due to a unix signal where "AA" is a hex +// signal number that describes why the program stopped. This is +// followed by a series of key/value pairs: +// - If key is a hex number, it is a register number and value is +// the hex value of the register in debuggee endian byte order. +// - If key == "thread", then the value is the big endian hex +// thread-id of the stopped thread. +// - If key == "core", then value is a hex number of the core on +// which the stop was detected. +// - If key == "watch" or key == "rwatch" or key == "awatch", then +// value is the data address in big endian hex +// - If key == "library", then value is ignore and "qXfer:libraries:read" +// packets should be used to detect any newly loaded shared libraries +// +// "WAA" +// "W" means the process exited and "AA" is the exit status. +// +// "XAA" +// "X" means the process exited and "AA" is signal that caused the program +// to exit. +// +// "O<ascii-hex-string>" +// "O" means STDOUT has data that was written to its console and is +// being delivered to the debugger. This packet happens asynchronously +// and the debugger is expected to continue to wait for another stop reply +// packet. +// +// LLDB EXTENSIONS +// +// We have extended the "T" packet to be able to also understand the +// following keys and values: +// +// KEY VALUE DESCRIPTION +// =========== ======== ================================================ +// "metype" unsigned mach exception type (the value of the EXC_XXX enumerations) +// as an unsigned integer. For targets with mach +// kernels only. +// +// "mecount" unsigned mach exception data count as an unsigned integer +// For targets with mach kernels only. +// +// "medata" unsigned There should be "mecount" of these and it is the data +// that goes along with a mach exception (as an unsigned +// integer). For targets with mach kernels only. +// +// "name" string The name of the thread as a plain string. The string +// must not contain an special packet characters or +// contain a ':' or a ';'. Use "hexname" if the thread +// name has special characters. +// +// "hexname" ascii-hex An ASCII hex string that contains the name of the thread +// +// "qaddr" hex Big endian hex value that contains the libdispatch +// queue address for the queue of the thread. +// +// "reason" enum The enumeration must be one of: +// "trace" the program stopped after a single instruction +// was executed on a core. Usually done when single +// stepping past a breakpoint +// "breakpoint" a breakpoint set using a 'z' packet was hit. +// "trap" stopped due to user interruption +// "signal" stopped due to an actual unix signal, not +// just the debugger using a unix signal to keep +// the GDB remote client happy. +// "watchpoint". Should be used in conjunction with +// the "watch"/"rwatch"/"awatch" key value pairs. +// "exception" an exception stop reason. Use with +// the "description" key/value pair to describe the +// exceptional event the user should see as the stop +// reason. +// "description" ascii-hex An ASCII hex string that contains a more descriptive +// reason that the thread stopped. This is only needed +// if none of the key/value pairs are enough to +// describe why something stopped. +// +// "threads" comma-sep-base16 A list of thread ids for all threads (including +// the thread that we're reporting as stopped) that +// are live in the process right now. lldb may +// request that this be included in the T packet via +// the QListThreadsInStopReply packet earlier in +// the debug session. +// +// Example: +// threads:63387,633b2,63424,63462,63486; +// +// "thread-pcs" comma-sep-base16 A list of pc values for all threads that currently +// exist in the process, including the thread that +// this T packet is reporting as stopped. +// This key-value pair will only be emitted when the +// "threads" key is already included in the T packet. +// The pc values correspond to the threads reported +// in the "threads" list. The number of pcs in the +// "thread-pcs" list will be the same as the number of +// threads in the "threads" list. +// lldb may request that this be included in the T +// packet via the QListThreadsInStopReply packet +// earlier in the debug session. +// +// Example: +// thread-pcs:dec14,2cf872b0,2cf8681c,2d02d68c,2cf716a8; +// +// BEST PRACTICES: +// Since register values can be supplied with this packet, it is often useful +// to return the PC, SP, FP, LR (if any), and FLAGS registers so that separate +// packets don't need to be sent to read each of these registers from each +// thread. +// +// If a thread is stopped for no reason (like just because another thread +// stopped, or because when one core stops all cores should stop), use a +// "T" packet with "00" as the signal number and fill in as many key values +// and registers as possible. +// +// LLDB likes to know why a thread stopped since many thread control +// operations like stepping over a source line, actually are implemented +// by running the process multiple times. If a breakpoint is hit while +// trying to step over a source line and LLDB finds out that a breakpoint +// is hit in the "reason", we will know to stop trying to do the step +// over because something happened that should stop us from trying to +// do the step. If we are at a breakpoint and we disable the breakpoint +// at the current PC and do an instruction single step, knowing that +// we stopped due to a "trace" helps us know that we can continue +// running versus stopping due to a "breakpoint" (if we have two +// breakpoint instruction on consecutive instructions). So the more info +// we can get about the reason a thread stops, the better job LLDB can +// do when controlling your process. A typical GDB server behavior is +// to send a SIGTRAP for breakpoints _and_ also when instruction single +// stepping, in this case the debugger doesn't really know why we +// stopped and it can make it hard for the debugger to control your +// program correctly. What if a real SIGTRAP was delivered to a thread +// while we were trying to single step? We wouldn't know the difference +// with a standard GDB remote server and we could do the wrong thing. +// +// PRIORITY TO IMPLEMENT +// High. Having the extra information in your stop reply packets makes +// your debug session more reliable and informative. +//---------------------------------------------------------------------- + + +//---------------------------------------------------------------------- +// PLATFORM EXTENSION - for use as a GDB remote platform +//---------------------------------------------------------------------- +// "qfProcessInfo" +// "qsProcessInfo" +// +// BRIEF +// Get the first process info (qfProcessInfo) or subsequent process +// info (qsProcessInfo) for one or more processes on the remote +// platform. The first call gets the first match and subsequent calls +// to qsProcessInfo gets the subsequent matches. Return an error EXX, +// where XX are two hex digits, when no more matches are available. +// +// PRIORITY TO IMPLEMENT +// Required. The qfProcessInfo packet can be followed by a ':' and +// some key value pairs. The key value pairs in the command are: +// +// KEY VALUE DESCRIPTION +// =========== ======== ================================================ +// "name" ascii-hex An ASCII hex string that contains the name of +// the process that will be matched. +// "name_match" enum One of: "equals", "starts_with", "ends_with", +// "contains" or "regex" +// "pid" integer A string value containing the decimal process ID +// "parent_pid" integer A string value containing the decimal parent +// process ID +// "uid" integer A string value containing the decimal user ID +// "gid" integer A string value containing the decimal group ID +// "euid" integer A string value containing the decimal effective user ID +// "egid" integer A string value containing the decimal effective group ID +// "all_users" bool A boolean value that specifies if processes should +// be listed for all users, not just the user that the +// platform is running as +// "triple" string An ASCII triple string ("x86_64", +// "x86_64-apple-macosx", "armv7-apple-ios") +// +// The response consists of key/value pairs where the key is separated from the +// values with colons and each pair is terminated with a semi colon. For a list +// of the key/value pairs in the response see the "qProcessInfoPID" packet +// documentation. +// +// Sample packet/response: +// send packet: $qfProcessInfo#00 +// read packet: $pid:60001;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00 +// send packet: $qsProcessInfo#00 +// read packet: $pid:59992;ppid:192;uid:7746;gid:11;euid:7746;egid:11;name:6d64776f726b6572;triple:x86_64-apple-macosx;#00 +// send packet: $qsProcessInfo#00 +// read packet: $E04#00 +//---------------------------------------------------------------------- + + +//---------------------------------------------------------------------- +// PLATFORM EXTENSION - for use as a GDB remote platform +//---------------------------------------------------------------------- +// "qLaunchGDBServer" +// +// BRIEF +// Have the remote platform launch a GDB server. +// +// PRIORITY TO IMPLEMENT +// Required. The qLaunchGDBServer packet must be followed by a ':' and +// some key value pairs. The key value pairs in the command are: +// +// KEY VALUE DESCRIPTION +// =========== ======== ================================================ +// "port" integer A string value containing the decimal port ID or +// zero if the port should be bound and returned +// +// "host" integer The host that connections should be limited to +// when the GDB server is connected to. +// +// The response consists of key/value pairs where the key is separated from the +// values with colons and each pair is terminated with a semi colon. +// +// Sample packet/response: +// send packet: $qLaunchGDBServer:port:0;host:lldb.apple.com;#00 +// read packet: $pid:60025;port:50776;#00 +// +// The "pid" key/value pair is only specified if the remote platform launched +// a separate process for the GDB remote server and can be omitted if no +// process was separately launched. +// +// The "port" key/value pair in the response lets clients know what port number +// to attach to in case zero was specified as the "port" in the sent command. +//---------------------------------------------------------------------- + + +//---------------------------------------------------------------------- +// PLATFORM EXTENSION - for use as a GDB remote platform +//---------------------------------------------------------------------- +// "qProcessInfoPID:PID" +// +// BRIEF +// Have the remote platform get detailed information on a process by +// ID. PID is specified as a decimal integer. +// +// PRIORITY TO IMPLEMENT +// Optional. +// +// The response consists of key/value pairs where the key is separated from the +// values with colons and each pair is terminated with a semi colon. +// +// The key value pairs in the response are: +// +// KEY VALUE DESCRIPTION +// =========== ======== ================================================ +// "pid" integer Process ID as a decimal integer string +// "ppid" integer Parent process ID as a decimal integer string +// "uid" integer A string value containing the decimal user ID +// "gid" integer A string value containing the decimal group ID +// "euid" integer A string value containing the decimal effective user ID +// "egid" integer A string value containing the decimal effective group ID +// "name" ascii-hex An ASCII hex string that contains the name of the process +// "triple" string A target triple ("x86_64-apple-macosx", "armv7-apple-ios") +// +// Sample packet/response: +// send packet: $qProcessInfoPID:60050#00 +// read packet: $pid:60050;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00 +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// "vAttachName" +// +// BRIEF +// Same as vAttach, except instead of a "pid" you send a process name. +// +// PRIORITY TO IMPLEMENT +// Low. Only needed for "process attach -n". If the packet isn't supported +// then "process attach -n" will fail gracefully. So you need only to support +// it if attaching to a process by name makes sense for your environment. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// "vAttachWait" +// +// BRIEF +// Same as vAttachName, except that the stub should wait for the next instance +// of a process by that name to be launched and attach to that. +// +// PRIORITY TO IMPLEMENT +// Low. Only needed to support "process attach -w -n" which will fail +// gracefully if the packet is not supported. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// "qAttachOrWaitSupported" +// +// BRIEF +// This is a binary "is it supported" query. Return OK if you support +// vAttachOrWait +// +// PRIORITY TO IMPLEMENT +// Low. This is required if you support vAttachOrWait, otherwise no support +// is needed since the standard "I don't recognize this packet" response +// will do the right thing. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// "vAttachOrWait" +// +// BRIEF +// Same as vAttachWait, except that the stub will attach to a process +// by name if it exists, and if it does not, it will wait for a process +// of that name to appear and attach to it. +// +// PRIORITY TO IMPLEMENT +// Low. Only needed to implement "process attach -w -i false -n". If +// you don't implement it but do implement -n AND lldb can somehow get +// a process list from your device, it will fall back on scanning the +// process list, and sending vAttach or vAttachWait depending on +// whether the requested process exists already. This is racy, +// however, so if you want to support this behavior it is better to +// support this packet. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// "jThreadExtendedInfo" +// +// BRIEF +// This packet, which takes its arguments as JSON and sends its reply as +// JSON, allows the gdb remote stub to provide additional information +// about a given thread. +// +// PRIORITY TO IMPLEMENT +// Low. This packet is only needed if the gdb remote stub wants to +// provide interesting additional information about a thread for the +// user. +// +// This packet takes its arguments in JSON form ( http://www.json.org ). +// At a minimum, a thread must be specified, for example: +// +// jThreadExtendedInfo:{"thread":612910} +// +// Because this is a JSON string, the thread number is provided in base10. +// Additional key-value pairs may be provided by lldb to the gdb remote +// stub. For instance, on some versions of Mac OS X, lldb can read offset +// information out of the system libraries. Using those offsets, debugserver +// is able to find the Thread Specific Address (TSD) for a thread and include +// that in the return information. So lldb will send these additional fields +// like so: +// +// jThreadExtendedInfo:{"plo_pthread_tsd_base_address_offset":0,"plo_pthread_tsd_base_offset":224,"plo_pthread_tsd_entry_size":8,"thread":612910} +// +// There are no requirements for what is included in the response. A simple +// reply on a Mac OS X Yosemite / iOS 8 may include the pthread_t value, the +// Thread Specific Data (TSD) address, the dispatch_queue_t value if the thread +// is associated with a GCD queue, and the requested Quality of Service (QoS) +// information about that thread. For instance, a reply may look like: +// +// {"tsd_address":4371349728,"requested_qos":{"enum_value":33,"constant_name":"QOS_CLASS_USER_INTERACTIVE","printable_name":"User Interactive"},"pthread_t":4371349504,"dispatch_queue_t":140735087127872} +// +// tsd_address, pthread_t, and dispatch_queue_t are all simple key-value pairs. +// The JSON standard requires that numbers be expressed in base 10 - so all of +// these are. requested_qos is a dictionary with three key-value pairs in it - +// so the UI layer may choose the form most appropriate for displaying to the user. +// +// Sending JSON over gdb-remote protocol introduces some problems. We may be +// sending strings with arbitrary contents in them, including the '#', '$', and '*' +// characters that have special meaning in gdb-remote protocol and cannot occur +// in the middle of the string. The standard solution for this would be to require +// ascii-hex encoding of all strings, or ascii-hex encode the entire JSON payload. +// +// Instead, the binary escaping convention is used for JSON data. This convention +// (e.g. used for the X packet) says that if '#', '$', '*', or '}' are to occur in +// the payload, the character '}' (0x7d) is emitted, then the metacharacter is emitted +// xor'ed by 0x20. The '}' character occurs in every JSON payload at least once, and +// '}' ^ 0x20 happens to be ']' so the raw packet characters for a request will look +// like +// +// jThreadExtendedInfo:{"thread":612910}] +// +// on the wire. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// "QEnableCompression" +// +// BRIEF +// This packet enables compression of the packets that the debug stub sends to lldb. +// If the debug stub can support compression, it indictes this in the reply of the +// "qSupported" packet. e.g. +// LLDB SENDS: qSupported:xmlRegisters=i386,arm,mips +// STUB REPLIES: qXfer:features:read+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;DefaultCompressionMinSize=384 +// +// If lldb knows how to use any of these compression algorithms, it can ask that this +// compression mode be enabled. It may optionally change the minimum packet size +// where compression is used. Typically small packets do not benefit from compression, +// as well as compression headers -- compression is most beneficial with larger packets. +// +// QEnableCompression:type:zlib-deflate; +// or +// QEnableCompression:type:zlib-deflate;minsize:512; +// +// The debug stub should reply with an uncompressed "OK" packet to indicate that the +// request was accepted. All further packets the stub sends will use this compression. +// +// Packets are compressed as the last step before they are sent from the stub, and +// decompressed as the first step after they are received. The packet format in compressed +// mode becomes one of two: +// +// $N<uncompressed payload>#00 +// +// $C<size of uncompressed payload in base10>:<compressed payload>#00 +// +// Where "#00" is the actual checksum value if noack mode is not enabled. The checksum +// value is for the "N<uncompressed payload>" or +// "C<size of uncompressed payload in base10>:<compressed payload>" bytes in the packet. +// +// The size of the uncompressed payload in base10 is provided because it will simplify +// decompression if the final buffer size needed is known ahead of time. +// +// Compression on low-latency connections is unlikely to be an improvement. Particularly +// when the debug stub and lldb are running on the same host. It should only be used +// for slow connections, and likely only for larger packets. +// +// Example compression algorithsm that may be used include +// +// zlib-deflate +// The raw DEFLATE format as described in IETF RFC 1951. With the ZLIB library, you +// can compress to this format with an initialization like +// deflateInit2 (&stream, 5, Z_DEFLATED, -15, 8, Z_DEFAULT_STRATEGY) +// and you can decompress with an initialization like +// inflateInit2 (&stream, -15) +// +// lz4 +// https://en.wikipedia.org/wiki/LZ4_(compression_algorithm) +// https://github.com/Cyan4973/lz4 +// The libcompression APIs on darwin systems call this COMPRESSION_LZ4_RAW. +// +// lzfse +// An Apple proprietary compression algorithm implemented in libcompression. +// +// lzma +// libcompression implements "LZMA level 6", the default compression for the +// open source LZMA implementation. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// "jGetLoadedDynamicLibrariesInfos" +// +// BRIEF +// This packet asks the remote debug stub to send the details about libraries +// being added/removed from the process as a performance optimization. +// +// LLDB SENDS: jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128} +// STUB REPLIES: ${"images":[{"load_address":4294967296,"mod_date":0,"pathname":"/tmp/a.out","uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF","mach_header":{"magic":4277009103,"cputype":16777223,"cpusubtype":18446744071562067971,"filetype":2},"segments":{"name":"__PAGEZERO","vmaddr":0,"vmsize":4294967296,"fileoff":0,"filesize":0,"maxprot":0},{"name":"__TEXT","vmaddr":4294967296,"vmsize":4096,"fileoff":0,"filesize":4096,"maxprot":7},{"name":"__LINKEDIT","vmaddr":4294971392,"vmsize":4096,"fileoff":4096,"filesize":152,"maxprot":7}}]}#00 +// +// Or pretty-printed, +// +// STUB REPLIES: ${"images": +// [ +// {"load_address":4294967296, +// "mod_date":0, +// "pathname":"/tmp/a.out", +// "uuid":"02CF262C-ED6F-3965-9E14-63538B465CFF", +// "mach_header": +// {"magic":4277009103, +// "cputype":16777223, +// "cpusubtype":18446744071562067971, +// "filetype":2 +// }, +// "segments": +// [ +// {"name":"__PAGEZERO", +// "vmaddr":0, +// "vmsize":4294967296, +// "fileoff":0, +// "filesize":0, +// "maxprot":0 +// }, +// {"name":"__TEXT", +// "vmaddr":4294967296, +// "vmsize":4096, +// "fileoff":0, +// "filesize":4096, +// "maxprot":7 +// }, +// {"name":"__LINKEDIT", +// "vmaddr":4294971392, +// "vmsize":4096, +// "fileoff":4096, +// "filesize":152, +// "maxprot":7 +// } +// ] +// } +// ] +// } +// +// +// This is similar to the qXfer:libraries:read packet, and it could +// be argued that it should be merged into that packet. A separate +// packet was created primarily because lldb needs to specify the +// number of images to be read and the address from which the initial +// information is read. Also the XML DTD would need to be extended +// quite a bit to provide all the information that the DynamicLoaderMacOSX +// would need to work correctly on this platform. +// +// On Mac OS X / iOS, when libraries are added or removed, a stub +// function is called which lldb puts a breakpoint on. The arguments +// to the stub function include the number of libraries being added +// or removed and the address where the list of libraries can be +// found. The information at this address is the load address of the +// library, the filename, and the mod date of the library if available. +// DynamicLoaderMacOSX then parses the load commands in the Mach-O header +// at the load address before it can decide what action to take. +// +// The purpose of this packet is to eliminate all of the memory reads needed +// to read the Mach-O header and load commands for these libraries. +// On a typical GUI app, there can be a couple hundred shared libraries +// which results in megabytes of read packets. That same information can +// be returned in a couple hundred kilobytes in JSON format from the remote +// debugserver. +// +// +// PRIORITY TO IMPLEMENT +// Low. If this packet is absent, lldb will read the Mach-O headers/load +// commands out of memory. +//---------------------------------------------------------------------- + +//---------------------------------------------------------------------- +// "jThreadsInfo" +// +// BRIEF +// Ask for the server for thread stop information of all threads. +// +// PRIORITY TO IMPLEMENT +// Low. This is a performance optimization, which speeds up debugging by avoiding +// multiple round-trips for retrieving thread information. The information from this +// packet can be retrieved using a combination of qThreadStopInfo and m packets. +//---------------------------------------------------------------------- + +The data in this packet is very similar to the stop reply packets, but is packaged in +JSON and uses JSON arrays where applicable. The JSON output looks like: + [ + { "tid":1580681, + "metype":6, + "medata":[2,0], + "reason":"exception", + "qaddr":140735118423168, + "registers": { + "0":"8000000000000000", + "1":"0000000000000000", + "2":"20fabf5fff7f0000", + "3":"e8f8bf5fff7f0000", + "4":"0100000000000000", + "5":"d8f8bf5fff7f0000", + "6":"b0f8bf5fff7f0000", + "7":"20f4bf5fff7f0000", + "8":"8000000000000000", + "9":"61a8db78a61500db", + "10":"3200000000000000", + "11":"4602000000000000", + "12":"0000000000000000", + "13":"0000000000000000", + "14":"0000000000000000", + "15":"0000000000000000", + "16":"960b000001000000", + "17":"0202000000000000", + "18":"2b00000000000000", + "19":"0000000000000000", + "20":"0000000000000000" + }, + "memory":[ + {"address":140734799804592,"bytes":"c8f8bf5fff7f0000c9a59e8cff7f0000"}, + {"address":140734799804616,"bytes":"00000000000000000100000000000000"} + ] + } + ] + +It contains an array of dictionaries with all of the key value pairs that are +normally in the stop reply packet, including the expedited registers. The registers are +passed as hex-encoded JSON string in debuggee-endian byte order. Note that the register +numbers are decimal numbers, unlike the stop-reply packet, where they are written in +hex. The packet also contains expedited memory in the "memory" key. This allows the +server to expedite memory that the client is likely to use (e.g., areas around the +stack pointer, which are needed for computing backtraces) and it reduces the packet +count. + +On MacOSX with debugserver, we expedite the frame pointer backchain for a thread +(up to 256 entries) by reading 2 pointers worth of bytes at the frame pointer (for +the previous FP and PC), and follow the backchain. Most backtraces on MacOSX and +iOS now don't require us to read any memory! + +//---------------------------------------------------------------------- +// "qQueryGDBServer" +// +// BRIEF +// Ask the platform for the list of gdbservers we have to connect +// +// PRIORITY TO IMPLEMENT +// Low. The packet is required to support connecting to gdbserver started +// by the platform instance automatically. +//---------------------------------------------------------------------- + +If the remote platform automatically started one or more gdbserver instance (without +lldb asking it) then it have to return the list of port number or socket name for +each of them what can be used by lldb to connect to those instances. + +The data in this packet is a JSON array of JSON objects with the following keys: +"port": <the port number to connect> (optional) +"socket_name": <the name of the socket to connect> (optional) + +Example packet: +[ + { "port": 1234 }, + { "port": 5432 }, + { "socket_name": "foo" } +] diff --git a/docs/testsuite/2010-10-19-14_10_49.059609/TestSettings.SettingsCommandTestCase.test_set_output_path.log b/docs/testsuite/2010-10-19-14_10_49.059609/TestSettings.SettingsCommandTestCase.test_set_output_path.log new file mode 100644 index 000000000000..e18199537e6f --- /dev/null +++ b/docs/testsuite/2010-10-19-14_10_49.059609/TestSettings.SettingsCommandTestCase.test_set_output_path.log @@ -0,0 +1,43 @@ + +os command: [['/bin/sh', '-c', 'make clean; make']] +stdout: rm -rf "a.out" "a.out.dSYM" main.o main.d +g++ -arch x86_64 -gdwarf-2 -O0 -c -o main.o main.cpp +g++ -arch x86_64 -gdwarf-2 -O0 main.o -o "a.out" +/usr/bin/dsymutil -o "a.out.dSYM" "a.out" + +stderr: None +retcode: 0 + + +runCmd: file /Volumes/data/lldb/svn/trunk/test/settings/a.out +output: Current executable set to '/Volumes/data/lldb/svn/trunk/test/settings/a.out' (x86_64). + + +runCmd: settings set target.process.output-path 'stdout.txt' +output: + +runCmd: settings show target.process.output-path +output: target.process.output-path (string) = 'stdout.txt' + + +Expecting start string: target.process.output-path (string) = 'stdout.txt' +Matched + +runCmd: run +output: Process 43533 launched: '/Volumes/data/lldb/svn/trunk/test/settings/a.out' (x86_64) + + +FAIL + +runCmd: process kill +check of return status not required +runCmd failed! +error: Process must be launched. + + +Traceback (most recent call last): + File "/Volumes/data/lldb/svn/trunk/test/settings/TestSettings.py", line 125, in test_set_output_path + "'stdout.txt' exists due to target.process.output-path.") +AssertionError: False is not True : 'stdout.txt' exists due to target.process.output-path. + + diff --git a/docs/testsuite/a-detailed-walkthrough.txt b/docs/testsuite/a-detailed-walkthrough.txt new file mode 100644 index 000000000000..6b5267f414ce --- /dev/null +++ b/docs/testsuite/a-detailed-walkthrough.txt @@ -0,0 +1,309 @@ +Let's pick test/settings/TestSettings.py as our example. First, notice the file +name "TestSettings.py", the Test*.py pattern is the default mechanism that the +test driver uses for discovery of tests. As to TestSettings.py, it defines a +class: + +class SettingsCommandTestCase(TestBase): + +derived from TestBase, which is defined in test/lldbtest.py and is itself +derived from Python's unittest framework's TestCase class. See also +http://docs.python.org/library/unittest.html for more details. + +To just run the TestSettings.py test, chdir to the lldb test directory, and then +type the following command: + +/Volumes/data/lldb/svn/trunk/test $ ./dotest.py settings +---------------------------------------------------------------------- +Collected 6 tests + +---------------------------------------------------------------------- +Ran 6 tests in 8.699s + +OK (expected failures=1) +/Volumes/data/lldb/svn/trunk/test $ + +Pass '-v' option to the test driver to also output verbose descriptions of the +individual test cases and their test status: + +/Volumes/data/lldb/svn/trunk/test $ ./dotest.py -v settings +---------------------------------------------------------------------- +Collected 6 tests + +test_set_auto_confirm (TestSettings.SettingsCommandTestCase) +Test that after 'set auto-confirm true', manual confirmation should not kick in. ... ok +test_set_output_path (TestSettings.SettingsCommandTestCase) +Test that setting target.process.output-path for the launched process works. ... expected failure +test_set_prompt (TestSettings.SettingsCommandTestCase) +Test that 'set prompt' actually changes the prompt. ... ok +test_set_term_width (TestSettings.SettingsCommandTestCase) +Test that 'set term-width' actually changes the term-width. ... ok +test_with_dsym (TestSettings.SettingsCommandTestCase) +Test that run-args and env-vars are passed to the launched process. ... ok +test_with_dwarf (TestSettings.SettingsCommandTestCase) +Test that run-args and env-vars are passed to the launched process. ... ok + +---------------------------------------------------------------------- +Ran 6 tests in 5.735s + +OK (expected failures=1) +/Volumes/data/lldb/svn/trunk/test $ + +Underneath, the '-v' option passes keyword argument verbosity=2 to the +Python's unittest.TextTestRunner (see also +http://docs.python.org/library/unittest.html#unittest.TextTestRunner). For very +detailed descriptions about what's going on during the test, pass '-t' to the +test driver, which asks the test driver to trace the commands executed and to +display their output. For brevity, the '-t' output is not included here. + +Notice the 'expected failures=1' message at the end of the run. This is because +of a bug currently in lldb such that setting target.process.output-path to +'stdout.txt' does not have any effect on the redirection of the standard output +of the subsequent launched process. We are using unittest2 (a backport of new +unittest features for Python 2.4-2.6) to decorate (mark) the particular test +method as such: + + @unittest2.expectedFailure + # rdar://problem/8435794 + # settings set target.process.output-path does not seem to work + def test_set_output_path(self): + +See http://pypi.python.org/pypi/unittest2 for more details. + +Now let's look inside the test method: + + def test_set_output_path(self): + """Test that setting target.process.output-path for the launched process works.""" + self.buildDefault() + + exe = os.path.join(os.getcwd(), "a.out") + self.runCmd("file " + exe, CURRENT_EXECUTABLE_SET) + + # Set the output-path and verify it is set. + self.runCmd("settings set target.process.output-path 'stdout.txt'") + self.expect("settings show target.process.output-path", + startstr = "target.process.output-path (string) = 'stdout.txt'") + + self.runCmd("run", RUN_SUCCEEDED) + + # The 'stdout.txt' file should now exist. + self.assertTrue(os.path.isfile("stdout.txt"), + "'stdout.txt' exists due to target.process.output-path.") + + # Read the output file produced by running the program. + with open('stdout.txt', 'r') as f: + output = f.read() + + self.expect(output, exe=False, + startstr = "This message should go to standard out.") + +The self.buildDefault() statement is used to build a default binary for this +test instance. For this particular test case, since we don't really care what +debugging format is used, we instruct the build subsystem to build the default +binary for us. The base class TestBase has defined three instance methods: + + def buildDefault(self, architecture=None, compiler=None, dictionary=None): + """Platform specific way to build the default binaries.""" + module = __import__(sys.platform) + if not module.buildDefault(self, architecture, compiler, dictionary): + raise Exception("Don't know how to build default binary") + + def buildDsym(self, architecture=None, compiler=None, dictionary=None): + """Platform specific way to build binaries with dsym info.""" + module = __import__(sys.platform) + if not module.buildDsym(self, architecture, compiler, dictionary): + raise Exception("Don't know how to build binary with dsym") + + def buildDwarf(self, architecture=None, compiler=None, dictionary=None): + """Platform specific way to build binaries with dwarf maps.""" + module = __import__(sys.platform) + if not module.buildDwarf(self, architecture, compiler, dictionary): + raise Exception("Don't know how to build binary with dwarf") + +And the test/plugins/darwin.py provides the implementation for all three build +methods using the makefile mechanism. We envision that linux plugin can use a +similar approach to accomplish the task of building the binaries. + +Mac OS X provides an additional way to manipulate archived DWARF debug symbol +files and produces dSYM files. The buildDsym() instance method is used by the +test method to build the binary with dsym info. For an example of this, +see test/array_types/TestArrayTypes.py: + + @unittest2.skipUnless(sys.platform.startswith("darwin"), "requires Darwin") + def test_with_dsym_and_run_command(self): + """Test 'frame variable var_name' on some variables with array types.""" + self.buildDsym() + self.array_types() + +This method is decorated with a skipUnless decorator so that it will only gets +included into the test suite if the platform it is running on is 'darwin', aka +Mac OS X. + +Type 'man dsymutil' for more details. + +After the binary is built, it is time to specify the file to be used as the main +executable by lldb: + + exe = os.path.join(os.getcwd(), "a.out") + self.runCmd("file " + exe, CURRENT_EXECUTABLE_SET) + +This is where the attribute assignment: + +class SettingsCommandTestCase(TestBase): + + mydir = "settings" + +which happens right after the SettingsCommandTestCase class declaration comes +into place. It specifies the relative directory to the top level 'test' so that +the test harness can change its working directory in order to find the +executable as well as the source code files. The runCmd() method is defined in +the TestBase base class (within test/lldbtest.py) and its purpose is to pass the +specified command to the lldb command interpreter. It's like you're typing the +command within an interactive lldb session. + +The CURRENT_EXECUTABLE_SET is an assert message defined in the lldbtest module +so that it can be reused from other test modules. + +By default, the runCmd() is going to check the return status of the command +execution and fails the test if it is not a success. The assert message, in our +case CURRENT_EXECUTABLE_SET, is used in the exception printout if this happens. + +There are cases when we don't care about the return status from the command +execution. This can be accomplished by passing the keyword argument pair +'check=False' to the method. + +After the current executable is set, we'll then execute two more commands: + + # Set the output-path and verify it is set. + self.runCmd("settings set target.process.output-path 'stdout.txt'") + self.expect("settings show target.process.output-path", + SETTING_MSG("target.process.output-path"), + startstr = "target.process.output-path (string) = 'stdout.txt'") + +The first uses the 'settings set' command to set the static setting +target.process.output-path to be 'stdout.txt', instead of the default +'/dev/stdout'. We then immediately issue a 'settings show' command to check +that, indeed, the setting did take place. Notice that we use a new method +expect() to accomplish the task, which in effect issues a runCmd() behind the +door and grabs the output from the command execution and expects to match the +start string of the output against what we pass in as the value of the keyword +argument pair: + + startstr = "target.process.output-path (string) = 'stdout.txt'" + +Take a look at TestBase.expect() within lldbtest.py for more details. Among +other things, it can also match against a list of regexp patterns as well as a +list of sub strings. And it can also perform negative matching, i.e., instead +of expecting something from the output of command execution, it can perform the +action of 'not expecting' something. + +This will launch/run the program: + + self.runCmd("run", RUN_SUCCEEDED) + +And this asserts that the file 'stdout.txt' should be present after running the +program. + + # The 'stdout.txt' file should now exist. + self.assertTrue(os.path.isfile("stdout.txt"), + "'stdout.txt' exists due to target.process.output-path.") + +Also take a look at main.cpp which emits some message to the stdout. Now, if we +pass this assertion, it's time to examine the contents of the file to make sure +it contains the same message as programmed in main.cpp: + + # Read the output file produced by running the program. + with open('stdout.txt', 'r') as f: + output = f.read() + + self.expect(output, exe=False, + startstr = "This message should go to standard out.") + +We open the file and read its contents into output, then issue an expect() +method. The 'exe=False' keyword argument pair tells expect() that don't try to +execute the first arg as a command at all. Instead, treat it as a string to +match against whatever is thrown in as keyword argument pairs! + +There are also other test methods present in the TestSettings.py mode: +test_set_prompt(), test_set_term_width(), test_set_auto_confirm(), +test_with_dsym(), and test_with_dwarf(). We are using the default test loader +from unittest framework, which uses the 'test' method name prefix to identify +test methods automatically. + +This finishes the walkthrough of the test method test_set_output_path(self). +Before we say goodbye, notice the little method definition at the top of the +file: + + @classmethod + def classCleanup(cls): + system(["/bin/sh", "-c", "rm -f output.txt"]) + system(["/bin/sh", "-c", "rm -f stdout.txt"]) + +This is a classmethod (as shown by the @classmethod decorator) which allows the +individual test class to perform cleanup actions after the test harness finishes +with the particular test class. This is part of the so-called test fixture in +the unittest framework. From http://docs.python.org/library/unittest.html: + +A test fixture represents the preparation needed to perform one or more tests, +and any associate cleanup actions. This may involve, for example, creating +temporary or proxy databases, directories, or starting a server process. + +The TestBase class uses such fixture with setUp(self), tearDown(self), +setUpClass(cls), and tearDownClass(cls). And within teraDownClass(cls), it +checks whether the current class has an attribute named 'classCleanup', and +executes as a method if present. In this particular case, the classCleanup() +calls a utility function system() defined in lldbtest.py in order to remove the +files created by running the program as the tests are executed. + +This system() function uses the Python subprocess module to spawn the process +and to retrieve its results. If the test instance passes the keyword argument +pair 'sender=self', the detailed command execution through the operating system +also gets recorded in a session object. If the test instance fails or errors, +the session info automatically gets dumped to a file grouped under a directory +named after the timestamp of the particular test suite run. + +For simple cases, look for the timestamp directory in the same directory of the +test driver program dotest.py. For example, if we comment out the +@expectedFailure decorator for TestSettings.py, and then run the test module: + +/Volumes/data/lldb/svn/trunk/test $ ./dotest.py -v settings +---------------------------------------------------------------------- +Collected 6 tests + +test_set_auto_confirm (TestSettings.SettingsCommandTestCase) +Test that after 'set auto-confirm true', manual confirmation should not kick in. ... ok +test_set_output_path (TestSettings.SettingsCommandTestCase) +Test that setting target.process.output-path for the launched process works. ... FAIL +test_set_prompt (TestSettings.SettingsCommandTestCase) +Test that 'set prompt' actually changes the prompt. ... ok +test_set_term_width (TestSettings.SettingsCommandTestCase) +Test that 'set term-width' actually changes the term-width. ... ok +test_with_dsym (TestSettings.SettingsCommandTestCase) +Test that run-args and env-vars are passed to the launched process. ... ok +test_with_dwarf (TestSettings.SettingsCommandTestCase) +Test that run-args and env-vars are passed to the launched process. ... ok + +====================================================================== +FAIL: test_set_output_path (TestSettings.SettingsCommandTestCase) +Test that setting target.process.output-path for the launched process works. +---------------------------------------------------------------------- +Traceback (most recent call last): + File "/Volumes/data/lldb/svn/trunk/test/settings/TestSettings.py", line 125, in test_set_output_path + "'stdout.txt' exists due to target.process.output-path.") +AssertionError: False is not True : 'stdout.txt' exists due to target.process.output-path. + +---------------------------------------------------------------------- +Ran 6 tests in 8.219s + +FAILED (failures=1) +/Volumes/data/lldb/svn/trunk/test $ ls 2010-10-19-14:10:49.059609 + +NOTE: This directory name has been changed to not contain the ':' character + which is not allowed in windows platforms. We'll change the ':' to '_' + and get rid of the microsecond resolution by modifying the test driver. + +TestSettings.SettingsCommandTestCase.test_set_output_path.log +/Volumes/data/lldb/svn/trunk/test $ + +We get one failure and a timestamp directory 2010-10-19-14:10:49.059609. +For education purposes, the directory and its contents are reproduced here in +the same directory as the current file. diff --git a/docs/testsuite/best-practices.txt b/docs/testsuite/best-practices.txt new file mode 100644 index 000000000000..b5a9156fd521 --- /dev/null +++ b/docs/testsuite/best-practices.txt @@ -0,0 +1,93 @@ +This document attempts to point out some best practices that prove to be helpful +when building new test cases in the tot/test directory. Everyone is welcomed to +add/modify contents into this file. + +o Do not use hard-coded line numbers in your test case. Instead, try to tag the + line with some distinguishing pattern, and use the function line_number() + defined in lldbtest.py which takes filename and string_to_match as arguments + and returns the line number. + +As an example, take a look at test/breakpoint_conditions/main.c which has these +two lines: + + return c(val); // Find the line number of c's parent call here. + +and + + return val + 3; // Find the line number of function "c" here. + +The Python test case TestBreakpointConditions.py uses the comment strings to +find the line numbers during setUp(self) and use them later on to verify that +the correct breakpoint is being stopped on and that its parent frame also has +the correct line number as intended through the breakpoint condition. + +o Take advantage of the unittest framework's decorator features to properly + mark your test class or method for platform-specific tests. + +As an example, take a look at test/forward/TestForwardDeclaration.py which has +these lines: + + @unittest2.skipUnless(sys.platform.startswith("darwin"), "requires Darwin") + def test_with_dsym_and_run_command(self): + """Display *bar_ptr when stopped on a function with forward declaration of struct bar.""" + self.buildDsym() + self.forward_declaration() + +This tells the test harness that unless we are running "darwin", the test should +be skipped. This is because we are asking to build the binaries with dsym debug +info, which is only available on the darwin platforms. + +o Cleanup after yourself. A classic example of this can be found in test/types/ + TestFloatTypes.py: + + def test_float_types_with_dsym(self): + """Test that float-type variables are displayed correctly.""" + d = {'CXX_SOURCES': 'float.cpp'} + self.buildDsym(dictionary=d) + self.setTearDownCleanup(dictionary=d) + self.float_type() + + ... + + def test_double_type_with_dsym(self): + """Test that double-type variables are displayed correctly.""" + d = {'CXX_SOURCES': 'double.cpp'} + self.buildDsym(dictionary=d) + self.setTearDownCleanup(dictionary=d) + self.double_type() + +This tests different data structures composed of float types to verify that what +the debugger prints out matches what the compiler does for different variables +of these types. We're using a dictionary to pass the build parameters to the +build system. After a particular test instance is done, it is a good idea to +clean up the files built. This eliminates the chance that some leftover files +can interfere with the build phase for the next test instance and render it +invalid. + +TestBase.setTearDownCleanup(self, dictionary) defined in lldbtest.py is created +to cope with this use case by taking the same build parameters in order to do +the cleanup when we are finished with a test instance, during +TestBase.tearDown(self). + +o Class-wise cleanup after yourself. + +TestBase.tearDownClass(cls) provides a mechanism to invoke the platform-specific +cleanup after finishing with a test class. A test class can have more than one +test methods, so the tearDownClass(cls) method gets run after all the test +methods have been executed by the test harness. + +The default cleanup action performed by the plugins/darwin.py module invokes the +"make clean" os command. + +If this default cleanup is not enough, individual class can provide an extra +cleanup hook with a class method named classCleanup , for example, +in test/breakpoint_command/TestBreakpointCommand.py: + + @classmethod + def classCleanup(cls): + system(["/bin/sh", "-c", "rm -f output.txt"]) + +The 'output.txt' file gets generated during the test run, so it makes sense to +explicitly spell out the action in the same TestBreakpointCommand.py file to do +the cleanup instead of artificially adding it as part of the default cleanup +action which serves to cleanup those intermediate and a.out files. |