diff options
| author | Dimitry Andric <dim@FreeBSD.org> | 2019-08-20 18:01:57 +0000 |
|---|---|---|
| committer | Dimitry Andric <dim@FreeBSD.org> | 2019-08-20 18:01:57 +0000 |
| commit | 88c643b6fec27eec436c8d138fee6346e92337d6 (patch) | |
| tree | 82cd13b2f3cde1c9e5f79689ba4e6ba67694843f /docs | |
| parent | 94994d372d014ce4c8758b9605d63fae651bd8aa (diff) | |
Notes
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CMakeLists.txt | 41 | ||||
| -rw-r--r-- | docs/building-with-debug-llvm.txt | 51 | ||||
| -rw-r--r-- | docs/code-signing.txt | 66 | ||||
| -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 | 1915 | ||||
| -rw-r--r-- | docs/lldb-platform-packets.txt | 404 | ||||
| -rw-r--r-- | docs/structured_data/DarwinLog.md | 160 | ||||
| -rw-r--r-- | docs/structured_data/StructuredDataPlugins.md | 136 | ||||
| -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 | 311 | ||||
| -rw-r--r-- | docs/testsuite/best-practices.txt | 93 |
15 files changed, 0 insertions, 5380 deletions
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt deleted file mode 100644 index 045e816b727c6..0000000000000 --- a/docs/CMakeLists.txt +++ /dev/null @@ -1,41 +0,0 @@ - -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 deleted file mode 100644 index af1bcf8856b2d..0000000000000 --- a/docs/building-with-debug-llvm.txt +++ /dev/null @@ -1,51 +0,0 @@ -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 deleted file mode 100644 index 3da3a8085e661..0000000000000 --- a/docs/code-signing.txt +++ /dev/null @@ -1,66 +0,0 @@ -To use the in-tree debug server on macOS, 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". This document explains how to set up the -signing certificate. - -Note that it's possible to build and use lldb on macOS without setting up code -signing by using the system's debug server. To configure lldb in this way with -cmake, specify -DLLDB_CODESIGN_IDENTITY=''. - -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 deleted file mode 100644 index 0c20660518537..0000000000000 --- a/docs/doxygen.cfg.in +++ /dev/null @@ -1,1631 +0,0 @@ -# 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 = YES - -# 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 = YES - -# 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 deleted file mode 100644 index c14814b4a7a58..0000000000000 --- a/docs/doxygen.footer +++ /dev/null @@ -1,13 +0,0 @@ -<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 deleted file mode 100644 index e6e0331cb858f..0000000000000 --- a/docs/doxygen.header +++ /dev/null @@ -1,9 +0,0 @@ -<!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 deleted file mode 100644 index 1e5cd2787ff12..0000000000000 --- a/docs/doxygen.intro +++ /dev/null @@ -1,19 +0,0 @@ -/// @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 deleted file mode 100644 index d505d639192d3..0000000000000 --- a/docs/lldb-for-gdb-users.txt +++ /dev/null @@ -1,488 +0,0 @@ -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 deleted file mode 100644 index 3b808642eb7c6..0000000000000 --- a/docs/lldb-gdb-remote.txt +++ /dev/null @@ -1,1915 +0,0 @@ -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. - -//---------------------------------------------------------------------- -// "QEnableErrorStrings" -// -// BRIEF -// This packet enables reporting of Error strings in remote packet -// replies from the server to client. If the server supports this -// feature, it should send an OK response. The client can expect the -// following error replies if this feature is enabled in the server -> -// -// EXX;AAAAAAAAA -// -// where AAAAAAAAA will be a hex encoded ASCII string. -// XX is hex encoded byte number. -// -// It must be noted that even if the client has enabled reporting -// strings in error replies, it must not expect error strings to all -// error replies. -// -// PRIORITY TO IMPLEMENT -// Low. Only needed if the remote target wants to provide strings that -// are human readable along with an error code. -//---------------------------------------------------------------------- - -send packet: $QEnableErrorStrings -read packet: $OK#00 - -//---------------------------------------------------------------------- -// "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 - -//---------------------------------------------------------------------- -// jTraceStart: -// -// BRIEF -// Packet for starting trace of type lldb::TraceType. The following -// parameters should be appended to the packet formatted as a JSON -// dictionary, where the schematic for the JSON dictionary in terms of -// the recognized Keys is given below in the table. -// Different tracing types could require different custom parameters. -// Such custom tracing parameters if needed should be collectively -// specified in a JSON dictionary and the dictionary can be appended -// to this packet (as Value corresponding to "params"). Since sending -// JSON data over gdb-remote protocol has certain limitations, binary -// escaping convention should be used. -// -// Following is the list of parameters - -// -// Key Value (Integer) (O)Optional/ -// (except params which should be a (M)Mandatory -// JSON dictionary) -// ========== ==================================================== -// -// type The type of trace to start (see M -// lldb-enumerations for TraceType) -// -// buffersize The size of the buffer to allocate M -// for trace gathering. -// -// threadid The id of the thread to start tracing O -// on. -// -// metabuffersize The size of buffer to hold meta data O -// used for decoding the trace data. -// -// params Any parameters that are specific to O -// certain trace technologies should be -// collectively specified as a JSON -// dictionary -// ========== ==================================================== -// -// Each tracing instance is identified by a trace id which is returned -// as the reply to this packet. In case the tracing failed to begin an -// error code along with a hex encoded ASCII message is returned -// instead. -//---------------------------------------------------------------------- - -send packet: jTraceStart:{"type":<type>,"buffersize":<buffersize>}] -read packet: <trace id>/E<error code>;AAAAAAAAA - -//---------------------------------------------------------------------- -// jTraceStop: -// -// BRIEF -// Stop tracing instance with trace id <trace id>, of course trace -// needs to be started before. The following parameters should be -// formatted as a JSON dictionary to the packet. Since sending -// JSON data over gdb-remote protocol has certain limitations, binary -// escaping convention should be used. -// -// Following is the list of parameters - -// -// Key Value (Integer) (O)Optional/ -// (M)Mandatory -// ========== ==================================================== -// -// traceid The trace id of the tracing instance M -// -// threadid The id of the thread to stop tracing O -// on. Since <trace id> could map to -// multiple trace instances (in case it -// maps to the complete process), the -// threadid of a particular thread could -// be appended as "threadid:<thread id>;" -// to stop tracing on that thread. -// ========== ==================================================== -// -// An OK response is sent in case of success else an error code along -// with a hex encoded ASCII message is returned. -//---------------------------------------------------------------------- - -send packet: jTraceStop:{"traceid":<trace id>}] -read packet: <OK response>/E<error code>;AAAAAAAAA - -//---------------------------------------------------------------------- -// jTraceBufferRead: -// -// BRIEF -// Packet for reading the trace for tracing instance <trace id>, i.e the -// id obtained from StartTrace API. The following parameters should be -// formatted as a JSON dictionary to the packet. Since sending -// JSON data over gdb-remote protocol has certain limitations, binary -// escaping convention should be used. -// -// Following is the list of parameters - -// -// Key Value (Integer) (O)Optional/ -// (M)Mandatory -// ========== ==================================================== -// traceid The trace id of the tracing instance M -// -// offset The offset to start reading the data M -// from. -// -// buffersize The size of the data intended to read. M -// -// threadid The id of the thread to retrieve data O -// from. -// ========== ==================================================== -// -// The trace data is sent as raw binary data if the read was successful -// else an error code along with a hex encoded ASCII message is sent. -//---------------------------------------------------------------------- - -send packet: jTraceBufferRead:{"traceid":<trace id>,"offset":<byteoffset>,"buffersize":<byte_count>}] -read packet: <binary trace data>/E<error code>;AAAAAAAAA - -//---------------------------------------------------------------------- -// jTraceMetaRead: -// -// BRIEF -// Similar Packet as above except it reads meta data. -//---------------------------------------------------------------------- - -/---------------------------------------------------------------------- -// jTraceConfigRead: -// -// BRIEF -// Request the trace configuration for the tracing instance with id -// <trace id>. -// -// Following is the list of parameters - -// -// Key Value (Integer) (O)Optional/ -// (M)Mandatory -// ========== ==================================================== -// traceid The trace id of the tracing instance M -// -// threadid The id of the thread to obtain trace O -// configuration from. Since <trace id> -// could map to multiple trace instances -// (in case it maps to the complete -// process), the threadid of a particular -// thread could be appended as -// "threadid:<thread id>;" to obtain the -// trace configuration of that thread. -// ========== ==================================================== -// -// In the response packet the trace configuration is sent as text, -// formatted as a JSON dictionary. Since sending JSON data over -// gdb-remote protocol has certain limitations, binary escaping -// convention is used. -// In case the trace instance with the <trace id> was not found, an -// error code along with a hex encoded ASCII message is returned. -//---------------------------------------------------------------------- - -send packet: jTraceConfigRead:{"traceid":<trace id>} -read packet: {"conf1":<conf1>,"conf2":<conf2>,"params":{"paramName":paramValue}]}];/E<error code>;AAAAAAAAA - -//---------------------------------------------------------------------- -// "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" - - name:<name>; // <name> is a hex encoded string that contains the name of - // the memory region mapped at the given address. In case of - // regions backed by a file it have to be the absolute path of - // the file while for anonymous regions it have to be the name - // associated to the region if that is available. - - 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 -// <unsigned-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. -//---------------------------------------------------------------------- - -//---------------------------------------------------------------------- -// jModulesInfo:[{"file":"...",triple:"..."}, ...] -// -// BRIEF -// Get information for a list of modules by given module path and -// architecture. -// -// RESPONSE -// A JSON array of dictionaries containing the following keys: uuid, -// triple, file_path, file_offset, file_size. The meaning of the fields -// is the same as in the qModuleInfo packet. The server signals the -// failure to retrieve the module info for a file by ommiting the -// corresponding array entry from the response. The server may also -// include entries the client did not ask for, if it has reason to -// the modules will be interesting to the client. -// -// PRIORITY TO IMPLEMENT -// Optional. If not implemented, qModuleInfo packet will be used, which -// may be slower if the target contains a large number of modules and -// the communication link has a non-negligible latency. -//---------------------------------------------------------------------- - -//---------------------------------------------------------------------- -// 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. -// -// There are three ways this packet can be used. All three return a dictionary of -// binary images formatted the same way. -// -// On MacOS X 10.11, iOS 9, tvOS 9, watchOS 2 and earlier, the packet is used like -// jGetLoadedDynamicLibrariesInfos:{"image_count":1,"image_list_address":140734800075128} -// where the image_list_address is an array of {void* load_addr, void* mod_date, void* pathname} -// in the inferior process memory (and image_count is the number of elements in this array). -// lldb is using information from the dyld_all_image_infos structure to make these requests to -// debugserver. This use is not supported on macOS 10.12, iOS 10, tvOS 10, watchOS 3 or newer. -// -// On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer, there are two calls. One requests information -// on all shared libraries: -// jGetLoadedDynamicLibrariesInfos:{"fetch_all_solibs":true} -// And the second requests information about a list of shared libraries, given their load addresses: -// jGetLoadedDynamicLibrariesInfos:{"solib_addresses":[8382824135,3258302053,830202858503]} -// -// The second call is both a performance optimization (instead of having lldb read the mach-o header/load commands -// out of memory with generic read packets) but also adds additional information in the form of the -// filename of the shared libraries (which is not available in the mach-o header/load commands.) -// -// An example using the Mac OS X 10.11 style call: -// -// 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. -// -// PRIORITY TO IMPLEMENT -// On Mac OS X 10.11, iOS 9, tvOS 9, watchOS 2 and older: Low. If this packet is absent, -// lldb will read the Mach-O headers/load commands out of memory. -// On macOS 10.12, iOS 10, tvOS 10, watchOS 3 and newer: High. If this packet is absent, -// lldb will not know anything about shared libraries in the inferior, or where the main -// executable loaded. -//---------------------------------------------------------------------- - -//---------------------------------------------------------------------- -// "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! - -//---------------------------------------------------------------------- -// "jGetSharedCacheInfo" -// -// BRIEF -// This packet asks the remote debug stub to send the details about the inferior's -// shared cache. The shared cache is a collection of common libraries/frameworks that -// are mapped into every process at the same address on Darwin systems, and can be -// identified by a load address and UUID. -// -// -// LLDB SENDS: jGetSharedCacheInfo:{} -// STUB REPLIES: ${"shared_cache_base_address":140735683125248,"shared_cache_uuid":"DDB8D70C-C9A2-3561-B2C8-BE48A4F33F96","no_shared_cache":false,"shared_cache_private_cache":false]}#00 -// -// PRIORITY TO IMPLEMENT -// Low. When both lldb and the inferior process are running on the same computer, and lldb -// and the inferior process have the same shared cache, lldb may (as an optimization) read -// the shared cache out of its own memory instead of using gdb-remote read packets to read -// them from the inferior process. -//---------------------------------------------------------------------- - -//---------------------------------------------------------------------- -// "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/lldb-platform-packets.txt b/docs/lldb-platform-packets.txt deleted file mode 100644 index 3258e4c0dd882..0000000000000 --- a/docs/lldb-platform-packets.txt +++ /dev/null @@ -1,404 +0,0 @@ -Here is a brief overview of the packets that an lldb platform server -needs to implement for the lldb testsuite to be run on a remote -target device/system. - -These are almost all lldb extensions to the gdb-remote serial -protocol. Many of the vFile: packets are described to the "Host -I/O Packets" detailed in the gdb-remote protocol documentation, -although the lldb platform extensions include packets that are not -defined there (vFile:size:, vFile:mode:, vFile:symlink, vFile:chmod:). -Most importantly, the flags that lldb passes to vFile:open: are -incompatible with the flags that gdb specifies. - - -//---------------------------------------------------------------------- -// QStartNoAckMode -// -// BRIEF -// A request to stop sending ACK packets for each properly formatted packet. -// -// EXAMPLE -// A platform session will typically start like this: -// -// receive: +$QStartNoAckMode#b0 -// send: + <-- ACKing the properly formatted QStartNoAckMode packet -// send: $OK#9a -// receive: + <-- Our OK packet getting ACKed -// -// ACK mode is now disabled. - -//---------------------------------------------------------------------- -// qHostInfo -// -// BRIEF -// Describe the hardware and OS of the target system -// -// EXAMPLE -// -// receive: qHostInfo -// send: cputype:16777228;cpusubtype:1;ostype:ios;watchpoint_exceptions_received:before;os_version:12.1;vendor:apple;default_packet_timeout:5; -// -// All numbers are base 10, os_version is a string that will be parsed as major.minor.patch. - -//---------------------------------------------------------------------- -// qModuleInfo -// -// BRIEF -// Report information about a binary on the target system -// -// EXAMPLE -// receive: qModuleInfo:2f62696e2f6c73; -// -// FIXME finish this packet description, v. GDBRemoteCommunicationServerCommon::Handle_qModuleInfo - - -//---------------------------------------------------------------------- -// qGetWorkingDir -// -// BRIEF -// Get the current working directory of the platform stub in -// ASCII hex encoding. -// -// EXAMPLE -// -// receive: qGetWorkingDir -// send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773 - - - -//---------------------------------------------------------------------- -// QSetWorkingDir: -// -// BRIEF -// Set the current working directory of the platform stub in -// ASCII hex encoding. -// -// EXAMPLE -// -// receive: QSetWorkingDir:2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f5465737453657474696e67732e746573745f646973617373656d626c65725f73657474696e6773 -// send: OK - -//---------------------------------------------------------------------- -// qPlatform_mkdir: -// -// BRIEF -// Create a directory on the target system. -// -// EXAMPLE -// -// receive: qPlatform_mkdir:000001fd,2f746d702f6131 -// send: F0 -// -// request packet has the fields: -// 1. mode bits in base 16 -// 2. file path in ascii-hex encoding -// -// response is F followed by the return value of the mkdir() call, -// base 10 encoded. - -//---------------------------------------------------------------------- -// qPlatform_shell: -// -// BRIEF -// Run a shell command on the target system, return the output. -// -// EXAMPLE -// -// receive: qPlatform_shell:6c73202f746d702f,0000000a -// send: F,0,0,<OUTPUT> -// -// request packet has the fields: -// 1. shell command ascii-hex encoded -// 2. timeout -// 3. {optional} working directory ascii-hex encoded -// -// Response is F followed by the return value of the command (base 16), -// followed by a another number, followed by the output of the command -/ in binary-escaped-data encoding. - -//---------------------------------------------------------------------- -// qLaunchGDBServer -// -// BRIEF -// Start a gdbserver process (gdbserver, debugserver, lldb-server) -// on the target system. -// -// EXAMPLE -// -// receive: qLaunchGDBServer;host:<HOSTNAME_LLDB_IS_ON>; -// send: pid:1337;port:43001; -// -// request packet hostname field is not ascii-hex encoded. Hostnames -// don't have $ or # characters in them. -// -// response to the packet is the pid of the newly launched gdbserver, -// and the port it is listening for a connection on. -// -// When the testsuite is running, lldb may use the pid to kill off a -// debugserver that doesn't seem to be responding, etc. - -//---------------------------------------------------------------------- -// qKillSpawnedProcess: -// -// BRIEF -// Kill a process running on the target system. -// -// EXAMPLE -// -// receive: qKillSpawnedProcess:1337 -// send: OK -// -// The request packet has the process ID in base 10. - -//---------------------------------------------------------------------- -// qProcessInfoPID: -// -// BRIEF -// Gather information about a process running on the target -// -// EXAMPLE -// -// receive: qProcessInfoPID:71964 -// send: pid:71964;name:612e6f7574; -// -// The request packet has the pid encoded in base 10. -// -// The reply has semicolon-separated name:value fields, two are -// shown here. pid is base 10 encoded. name is ascii hex encoded. -// lldb-server can reply with many additional fields, but I think -// this is enough for the testsuite. - -//---------------------------------------------------------------------- -// qfProcessInfo: -// -// BRIEF -// Search the process table for processes matching criteria, -// respond with them in multiple packets. -// -// EXAMPLE -// -// receive: qfProcessInfo:name_match:equals;name:6e6f70726f6365737365786973747377697468746869736e616d65; -// send: pid:3500;name:612e6f7574; -// -// The request packet has a criteria to search for, followed by -// a specific name. Other name_match: values include -// starts_with, ends_with, contains, regex. You can specify a pid -// to search for, a uid, all_users, triple, etc etc. The testsuite -// only ever searches for name_match:equals. -// -// The response should include any information about the process that -// can be retrieved in semicolon-separated name:value fields. -// In this example, pid is base 10, name is ascii-hex encoded. -// The testsuite seems to only require these two. -// -// This packet only responds with one process. To get further matches to -// the search, qsProcessInfo should be sent. -// -// If no process match is found, Exx should be returned. - -//---------------------------------------------------------------------- -// qsProcessInfo -// -// BRIEF -// Return the next process info found by the most recent qfProcessInfo: -// packet. -// -// EXAMPLE -// -// Continues to return the results of the qfProcessInfo. Once all matches -// have been sent, Exx is returned to indicate end of matches. - -//---------------------------------------------------------------------- -// vFile:size: -// -// BRIEF -// Get the size of a file on the target system, filename in ASCII hex. -// -// EXAMPLE -// -// receive: vFile:size:2f746d702f61 -// send: Fc008 -// -// response is "F" followed by the file size in base 16. -// "F-1,errno" with the errno if an error occurs. - - -//---------------------------------------------------------------------- -// vFile:mode: -// -// BRIEF -// Get the mode bits of a file on the target system, filename in ASCII hex. -// -// EXAMPLE -// -// receive: vFile:mode:2f746d702f61 -// send: F1ed -// -// response is "F" followed by the mode bits in base 16, this 0x1ed would -// correspond to 0755 in octal. -// "F-1,errno" with the errno if an error occurs. - -//---------------------------------------------------------------------- -// vFile:unlink: -// -// BRIEF -// Remove a file on the target system. -// -// EXAMPLE -// -// receive: vFile:unlink:2f746d702f61 -// send: F0 -// -// Argument is a file path in ascii-hex encoding. -// Response is "F" plus the return value of unlink(), base 10 encoding. - -//---------------------------------------------------------------------- -// vFile:symlink: -// -// BRIEF -// Create a symbolic link (symlink, soft-link) on the target system. -// -// EXAMPLE -// -// receive: vFile:symlink:<SRC-FILE>,<DST-NAME> -// send: F0,0 -// -// Argument file paths are in ascii-hex encoding. -// Response is "F" plus the return value of symlink(), base 10 encoding, twice. - -//---------------------------------------------------------------------- -// vFile:chmod: -// qPlatform_chmod: -// -// BRIEF -// Change the permission mode bits on a file on the target -// -// EXAMPLE -// -// receive: vFile:chmod:180,2f746d702f61 -// send: F0 -// -// Arguments are the mode bits to set, base 16, and a file path in -// ascii-hex encoding. -// Response is "F" plus the return value of chmod(), base 10 encoding. -// -// I don't know why there are two packets for the same thing, v. -// vFile:chmod:. - -//---------------------------------------------------------------------- -// vFile:chmod: -// -// BRIEF -// Change the permission mode bits on a file on the target -// -// EXAMPLE -// -// receive: vFile:chmod:180,2f746d702f61 -// send: F0 -// -// Arguments are the mode bits to set, base 16, and a file path in -// ascii-hex encoding. -// Response is "F" plus the return value of chmod(), base 10 encoding. - - -//---------------------------------------------------------------------- -// vFile:open: -// -// BRIEF -// Open a file on the remote system and return the file descriptor of it. -// -// EXAMPLE -// -// receive: vFile:open:2f746d702f61,00000001,00000180 -// send: F8 -// -// request packet has the fields: -// 1. ASCII hex encoded filename -// 2. flags passed to the open call, base 16. -// Note that these are not the oflags that open(2) takes, but -// are the constant values in enum OpenOptions from lldb's File.h -// 3. mode bits, base 16 -// -// response is F followed by the opened file descriptor in base 10. -// "F-1,errno" with the errno if an error occurs. -// -// COMPATABILITY -// The gdb-remote serial protocol documentatio defines a vFile:open: -// packet which uses incompatible flag values, e.g. 1 means O_WRONLY -// in gdb's vFile:open:, but it means eOpenOptionRead to lldb's -// implementation. - -//---------------------------------------------------------------------- -// vFile:close: -// -// BRIEF -// Close a previously opened file descriptor. -// -// EXAMPLE -// -// receive: vFile:close:7 -// send: F0 -// -// File descriptor is in base 10. -// "F-1,errno" with the errno if an error occurs. - - -//---------------------------------------------------------------------- -// vFile:pread: -// -// BRIEF -// Read data from an opened file descriptor. -// -// EXAMPLE -// -// receive: vFile:pread:7,1024,0 -// send: F4;a'b\00 -// -// request packet has the fields: -// 1. file descriptor, base 10 -// 2. number of bytes to be read, base 10 -// 3. offset into file to start from, base 10 -// -// Response is F, followed by the number of bytes read (base 10), a -// semicolon, followed by the data in the binary-escaped-data encoding. - - -//---------------------------------------------------------------------- -// vFile:pwrite: -// -// BRIEF -// Write data to a previously opened file descriptor. -// -// EXAMPLE -// -// receive: vFile:pwrite:8,0,\cf\fa\ed\fe\0c\00\00 -// send: F1024 -// -// request packet has the fields: -// 1. file descriptor, base 10 -// 2. offset into file to start from, base 10 -// 3. binary-escaped-data to be written -// -// Response is F, followed by the number of bytes written (base 10) - - - - - - -Finally, the platform must be able to launch processes so that debugserver -can attach to them. To do this, the following packets should be handled: - -QSetDisableASLR -QSetDetachOnError -QSetSTDOUT -QSetSTDERR -QSetSTDIN -QEnvironment -QEnvironmentHexEncoded -A -qLaunchSuccess -qProcessInfo - -Most of these are documented in the standard gdb-remote protocol -and/or the lldb-gdb-remote.txt documentation. diff --git a/docs/structured_data/DarwinLog.md b/docs/structured_data/DarwinLog.md deleted file mode 100644 index c9905829e5ebe..0000000000000 --- a/docs/structured_data/DarwinLog.md +++ /dev/null @@ -1,160 +0,0 @@ -# Change Notes - -## Summary - -This document describes the DarwinLog logging feature. - -## StructuredDataDarwinLog feature - -The DarwinLog feature supports logging `os_log`*() and `NSLog`() messages -to the command-line lldb console, as well as making those messages -available to LLDB clients via the event system. Starting with fall -2016 OSes, Apple platforms introduce a new fire-hose, stream-style -logging system where the bulk of the log processing happens on the log -consumer side. This reduces logging impact on the system when there -are no consumers, making it cheaper to include logging at all times. -However, it also increases the work needed on the consumer end when -log messages are desired. - -The debugserver binary has been modified to support collection of -`os_log`*()/`NSLog`() messages, selection of which messages appear in the -stream, and fine-grained filtering of what gets passed on to the LLDB -client. DarwinLog also tracks the activity chain (i.e. `os_activity`() -hierarchy) in effect at the time the log messages were issued. The -user is able to configure a number of aspects related to the -formatting of the log message header fields. - -The DarwinLog support is written in a way which should support the -lldb client side on non-Apple clients talking to an Apple device or -macOS system; hence, the plugin support is built into all LLDB -clients, not just those built on an Apple platform. - -StructuredDataDarwinLog implements the 'DarwinLog' feature type, and -the plugin name for it shows up as `darwin-log`. - -The user interface to the darwin-log support is via the following: - -* `plugin structured-data darwin-log enable` command - - This is the main entry point for enabling the command. It can be - set before launching a process or while the process is running. - If the user wants to squelch seeing info-level or debug-level - messages, which is the default behavior, then the enable command - must be made prior to launching the process; otherwise, the - info-level and debug-level messages will always show up. Also, - there is a similar "echo os_log()/NSLog() messages to target - process stderr" mechanism which is properly disabled when enabling - the DarwinLog support prior to launch. This cannot be squelched - if enabling DarwinLog after launch. - - See the help for this command. There are a number of options - to shrink or expand the number of messages that are processed - on the remote side and sent over to the client, and other - options to control the formatting of messages displayed. - - This command is sticky. Once enabled, it will stay enabled for - future process launches. - -* `plugin structured-data darwin-log disable` command - - Executing this command disables os_log() capture in the currently - running process and signals LLDB to stop attempting to launch - new processes with DarwinLog support enabled. - -* `settings set - plugin.structured-data.darwin-log.enable-on-startup true` - - and - - `settings set - plugin.structured-data.darwin-log.auto-enable-options -- `{options} - - When `enable-on-startup` is set to `true`, then LLDB will automatically - enable DarwinLog on startup of relevant processes. It will use the - content provided in the auto-enable-options settings as the - options to pass to the enable command. - - Note the `--` required after auto-enable-command. That is necessary - for raw commands like settings set. The `--` will not become part - of the options for the enable command. - -### Message flow and related performance considerations - -`os_log`()-style collection is not free. The more data that must be -processed, the slower it will be. There are several knobs available -to the developer to limit how much data goes through the pipe, and how -much data ultimately goes over the wire to the LLDB client. The -user's goal should be to ensure he or she only collects as many log -messages are needed, but no more. - -The flow of data looks like the following: - -1. Data comes into debugserver from the low-level OS facility that - receives log messages. The data that comes through this pipe can - be limited or expanded by the `--debug`, `--info` and - `--all-processes` options of the `plugin structured-data darwin-log - enable` command options. Exclude as many categories as possible - here (also the default). The knobs here are very coarse - for - example, whether to include `os_log_info()`-level or - `os_log_debug()`-level info, or to include callstacks in the log - message event data. - -2. The debugserver process filters the messages that arrive through a - message log filter that may be fully customized by the user. It - works similar to a rules-based packet filter: a set of rules are - matched against the log message, each rule tried in sequential - order. The first rule that matches then either accepts or rejects - the message. If the log message does not match any rule, then the - message gets the no-match (i.e. fall-through) action. The no-match - action defaults to accepting but may be set to reject. - - Filters can be added via the enable command's '`--filter` - {filter-spec}' option. Filters are added in order, and multiple - `--filter` entries can be provided to the enable command. - - Filters take the following form: -``` - {action} {attribute} {op} - - {action} := - accept | - reject - - {attribute} := - category | // The log message category - subsystem | // The log message subsystem - activity | // The child-most activity in force - // at the time the message was logged. - activity-chain | // The complete activity chain, specified - // as {parent-activity}:{child-activity}: - // {grandchild-activity} - message | // The fully expanded message contents. - // Note this one is expensive because it - // requires expanding the message. Avoid - // this if possible, or add it further - // down the filter chain. - - {op} := - match {exact-match-text} | - regex {search-regex} // uses C++ std::regex - // ECMAScript variant. -``` - e.g. - `--filter "accept subsystem match com.example.mycompany.myproduct"` - `--filter "accept subsystem regex com.example.+"` - `--filter "reject category regex spammy-system-[[:digit:]]+"` - -3. Messages that are accepted by the log message filter get sent to - the lldb client, where they are mapped to the - StructuredDataDarwinLog plugin. By default, command-line lldb will - issue a Process-level event containing the log message content, and - will request the plugin to print the message if the plugin is - enabled to do so. - -### Log message display - -Several settings control aspects of displaying log messages in -command-line LLDB. See the `enable` command's help for a description -of these. - - diff --git a/docs/structured_data/StructuredDataPlugins.md b/docs/structured_data/StructuredDataPlugins.md deleted file mode 100644 index 2a536c7871b7d..0000000000000 --- a/docs/structured_data/StructuredDataPlugins.md +++ /dev/null @@ -1,136 +0,0 @@ -# Change Notes - -## Overview - -This document describes an infrastructural feature called Structured -Data plugins. See the `DarwinLog.md` doc for a description of one -such plugin that makes use of this feature. - -## StructuredDataPlugin - -StructuredDataPlugin instances have the following characteristics: - -* Each plugin instance is bound to a single Process instance. - -* Each StructuredData feature has a type name that identifies the - feature. For instance, the type name for the DarwinLog feature is - "DarwinLog". This feature type name is used in various places. - -* The process monitor reports the list of supported StructuredData - features advertised by the process monitor. Process goes through the - list of supported feature type names, and asks each known - StructuredDataPlugin if it can handle the feature. The first plugin - that supports the feature is mapped to that Process instance for - that feature. Plugins are only mapped when the process monitor - advertises that a feature is supported. - -* The feature may send asynchronous messages in StructuredData format - to the Process instance. Process instances route the asynchronous - structured data messages to the plugin mapped to that feature type, - if one exists. - -* Plugins can request that the Process instance forward on - configuration data to the process monitor if the plugin needs/wants - to configure the feature. Plugins may call the new Process method - - ```C++ - virtual Error - ConfigureStructuredData(const ConstString &type_name, - const StructuredData::ObjectSP &config_sp) - ``` - - where `type_name` is the feature name and `config_sp` points to the - configuration structured data, which may be nullptr. - -* Plugins for features present in a process are notified when modules - are loaded into the Process instance via this StructuredDataPlugin - method: - - ```C++ - virtual void - ModulesDidLoad(Process &process, ModuleList &module_list); - ``` - -* Plugins may optionally broadcast their received structured data as - an LLDB process-level event via the following new Process call: - - ```C++ - void - BroadcastStructuredData(const StructuredData::ObjectSP &object_sp, - const lldb::StructuredDataPluginSP &plugin_sp); - ``` - - IDE clients might use this feature to receive information about the - process as it is running to monitor memory usage, CPU usage, and - logging. - - Internally, the event type created is an instance of - EventDataStructuredData. - -* In the case where a plugin chooses to broadcast a received - StructuredData event, the command-line LLDB Debugger instance - listens for them. The Debugger instance then gives the plugin an - opportunity to display info to either the debugger output or error - stream at a time that is safe to write to them. The plugin can - choose to display something appropriate regarding the structured - data that time. - -* Plugins can provide a ProcessLaunchInfo filter method when the - plugin is registered. If such a filter method is provided, then - when a process is about to be launched for debugging, the filter - callback is invoked, given both the launch info and the target. The - plugin may then alter the launch info if needed to better support - the feature of the plugin. - -* The plugin is entirely independent of the type of Process-derived - class that it is working with. The only requirements from the - process monitor are the following feature-agnostic elements: - - * Provide a way to discover features supported by the process - monitor for the current process. - - * Specify the list of supported feature type names to Process. - The process monitor does this by calling the following new - method on Process: - - ```C++ - void - MapSupportedStructuredDataPlugins(const StructuredData::Array - &supported_type_names) - ``` - - The `supported_type_names` specifies an array of string entries, - where each entry specifies the name of a StructuredData feature. - - * Provide a way to forward on configuration data for a feature type - to the process monitor. This is the manner by which LLDB can - configure a feature, perhaps based on settings or commands from - the user. The following virtual method on Process (described - earlier) does the job: - - ```C++ - virtual Error - ConfigureStructuredData(const ConstString &type_name, - const StructuredData::ObjectSP &config_sp) - ``` - - * Listen for asynchronous structured data packets from the process - monitor, and forward them on to Process via this new Process - member method: - - ```C++ - bool - RouteAsyncStructuredData(const StructuredData::ObjectSP object_sp) - ``` - -* StructuredData producers must send their top-level data as a - Dictionary type, with a key called 'type' specifying a string value, - where the value is equal to the StructuredData feature/type name - previously advertised. Everything else about the content of the - dictionary is entirely up to the feature. - -* StructuredDataPlugin commands show up under `plugin structured-data - plugin-name`. - -* StructuredDataPlugin settings show up under - `plugin.structured-data.{plugin-name}`. 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 deleted file mode 100644 index e18199537e6fe..0000000000000 --- a/docs/testsuite/2010-10-19-14_10_49.059609/TestSettings.SettingsCommandTestCase.test_set_output_path.log +++ /dev/null @@ -1,43 +0,0 @@ - -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 deleted file mode 100644 index be679ef353de8..0000000000000 --- a/docs/testsuite/a-detailed-walkthrough.txt +++ /dev/null @@ -1,311 +0,0 @@ -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', a.k.a. -macOS. - -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: - - # Construct the path to a file "a.out" inside the test's build folder. - exe = self.getBuildArtifact("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. - stdout = self.getBuildArtifact('stdout.txt') - self.runCmd("settings set target.process.output-path '%s'" %stdout) - 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) = '%s'" %stdout - -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), - "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, '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 "+self.getBuildArtifact("output.txt")]) - system(["/bin/sh", "-c", "rm -f "+self.getBuildArtifact("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 deleted file mode 100644 index b5a9156fd521c..0000000000000 --- a/docs/testsuite/best-practices.txt +++ /dev/null @@ -1,93 +0,0 @@ -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. |
