aboutsummaryrefslogtreecommitdiff
path: root/tools/lldb-mi/MIReadMe.txt
diff options
context:
space:
mode:
Diffstat (limited to 'tools/lldb-mi/MIReadMe.txt')
-rw-r--r--tools/lldb-mi/MIReadMe.txt261
1 files changed, 261 insertions, 0 deletions
diff --git a/tools/lldb-mi/MIReadMe.txt b/tools/lldb-mi/MIReadMe.txt
new file mode 100644
index 000000000000..fbd3b2d364f6
--- /dev/null
+++ b/tools/lldb-mi/MIReadMe.txt
@@ -0,0 +1,261 @@
+========================================================================
+ The MI Driver - LLDB Machine Interface V2 (MI) Project Overview
+ 24/07/2014
+========================================================================
+
+The MI Driver is a stand alone executable that either be used via a
+client i.e. Eclipse or directly from the command line.
+
+All the files in this directory are required to build the MI executable.
+The executable is intended to compile and work on the following platforms:
+
+ Windows (Vista or newer) (Compiler: Visual C++ 12)
+ LINUX (Compiler: gcc (Ubuntu/Linaro 4.8.1-10ubuntu9) 4.8.1)
+ OSX (Not tested)
+
+THe MI Driver has two modes of operation; LLDB and MI. The MI Driver (CMIDriver)
+which operates the MI mode is a driver in its own right to work alongside
+the LLDB driver (driver .h/.cpp). Only one is operatational at a time depending
+on the options entered on the command line. The MI Driver reads MI inputs and
+outputs MI responses to be interpreted by a client i.e. Eclipse.
+Should the MI Driver not understand an instruction it could be passed to the
+LLDB driver for interpretation (MI Driver build configuration dependant). Should
+the LLDB driver mode be chosen then it the MI Driver will behave as the normal
+LLDB driver.
+
+For help information on using the MI driver type at the command line:
+
+ lldb-mi --interpreter --help
+
+A blog about the MI Driver is available on CodePlay's website
+http://www.codeplay.com/portal/.
+
+The MI Driver produces a MILog.txt file which records the actions of the MI
+Driver when in the MI mode only.
+
+Note any command or text sent to the MI Driver in MI mode that is not a command
+registered in the MI Driver's Command Factory will be rejected given an error.
+
+The MILogfile.txt keeps a history of the MI Driver's activity for one session
+only. It is used to aid the debugging of the MI Driver in MI mode only. As well
+as recorded commands that are recognised by the MI Driver it also gives warnings
+about command's which do not support certain argument or options.
+
+All the files prefix with MI are specifically for the MI driver code only.
+Non prefixed code is the original LLDB driver which has been left untouched
+as much as possible. This allows the LLDB driver code to develop
+independently and make future integration more straight forward.
+
+File MIDriverMain.cpp contains the executables main() function and some
+common global functions common to the two drivers.
+
+=========================================================================
+Current limitations:
+1. Commands implemented likely not to have all their arguments supported
+2. The MI Driver has only been tested with Eclipse Juno with an in-house
+ plugin
+3. Local target has been implemented but not tested
+4. The MI Driver has been designed primarily to work in a 'remote-target'
+ mode only. The MI Driver does not currently except arguments beyond
+ those described above.
+5. The MI Driver does not accept as arguments an executable to create a
+ target instance.
+6. Not all MI commands have been implemented. See section MI Driver
+ commands for those that have been fully or partially implemented (not
+ indicated - see command class).
+7. Not necessarily a limitation but the MI Driver is used with Codeplay's
+ own Eclipse plugin (not supplied) which has allowed more control over
+ the interaction with the MI Driver between Eclipse.
+
+=========================================================================
+Versions:
+1.0.0.1 First version from scratch 28/1/2014 to 28/3/2014.
+ MI working alpha. MI framework not complete.
+1.0.0.2 First deliverable to client 7/3/2014.
+ MI working beta. MI framework not complete.
+1.0.0.3 Code refactor tidy. Release to community for evaluation
+ 7/5/2014.
+ MI working beta - code refactored and tidied. MI framework
+ complete. Just missing commands (which may still require
+ changes).
+1.0.0.4 Post release to community for evaluation 7/5/2014.
+ 1. MI command token now optional
+ 2. MI command token is now fixed length
+ 3. New commands added see section "MI commands implemented are:"
+ 4. Able to debug a local target as well as remote target
+ 5. MI Driver now sends to the client "(gdb)" + '\n' on
+ initialising
+ 6. Improve coverage of parsing and fix command argument parsing
+ 7. Fix bug with stdin thinking there was no input when there was which
+ caused communication between the client and the MI Driver to halt
+ due to internal buffering, we now keep track of it ourself.
+ 8. Code comment fixes and additions. Code style fixes.
+ 9. MI Driver now on receiving Ctrl-C (SIGINT) when the client pauses
+ an inferior program does not quit but continues operating.
+ 10.Fix commands "var-update", "var-evaluate-expression" to which did
+ not send back information to correctly update arrays and structures.
+ 11.Commands "Not implemented" are now not registered to the command
+ factory except for GDB command "thread". Commands not registered
+ with the command factory produce MI error message "...not in
+ Command Factory". (Removed from command section in this readme.txt)
+1.0.0.5 Second deliverable to client 16/6/2014.
+1.0.0.6 Post release of second deliverable to client 16/6/2014.
+ Released to the community 24/6/2014.
+ 1. The MI Driver has a new option --noLog. If present the MI Driver
+ does not output progress or status messages to it's log file.
+ 2. Moved OS specific handling of the stdin stream to their own class
+ implementations so any changes to one handler will not affect
+ another OS's handler.
+ 3. The session data/information map for sharing data between commands
+ now uses a variant object which enables objects of different types
+ to be stored instead of previously just text information.
+ 4. Debug session var object create, update and retrieve efficiency
+ improved by using a map type container.
+ 5. Re-enable the MI Driver's command line option --interpreter (see
+ --help). Up until now it was implementented but not enforced, it
+ was always the MI Driver interpreter.
+ 6. Re-enable the compilation of the original LLDB driver code into
+ the MI Driver's code. See MICmnConfig.h for build configuration.
+1.0.0.7 Post release to community. Delivered to client 30/6/2014.
+ 1. Fix MI Driver's output of "(gdb)" appearing when running in LLDB
+ mode (no --interpreter argument)'
+ 2. Fix command "interpret-exec" to allow commands to be entered
+ directly in the IDE console.
+1.0.0.8 Post release to client. Delivered to client 29/07/2014
+ 1. Fix command "break-insert" argument -f not accepting file paths
+ as a string. Looked like the MI Driver was not accepting LINUX
+ style file paths in the Windows version and vice versa.
+ 2. Fix command "stack-list-arguments" handling only the current
+ stack frame. Eclipse now shows variables for all frames.
+ 3. Fix and improve MI response for sending back information on
+ stack local variables, stack arguments and stack frame selection.
+ 4. Fix recursive crash when asking to gather information on link
+ lists.
+ 5. Fix MI Driver's Log date and time field.
+ 6. Fix MI response return from event 'StopReason' and 'Breakpoint-
+ hit'.
+ 7. Fix command "environment-cd" to handle paths with spaces in the
+ path.
+ 8. Fix not displaying backtrace (stack) variable information when
+ choosing frames other than the current frame.
+ 9. Fix command "data-evaluate-expression" to be able to handle
+ valid SBValue objects but have no value object name. Fix same
+ command to handle expressions surround by string format inserted
+ quotes.
+ 10.Fix command "break-insert" to handle file location that is
+ surrounded by quotes.
+ 11.For commands "var-create" and "data-evaluate-expression" improve
+ variable type handling for quoted expressions.
+ 12.Implement command "inferior-tty-set". It just responds with
+ "^Done".
+ 13.Improve the MI Driver's help description.
+ 14.Fix file name paths that contained '.', '-' and '_' in the path
+ as being treated as invalid.
+ 15.Fix trying to interpret escapse character text as an errorous
+ command.
+1.0.0.9 Post release to client.
+
+=========================================================================
+MI Driver Commands
+MI commands below are written to work for Eclipse Juno 7.4. If may be
+one are more commands required by other IDEs are missing or do not
+support all arguments or options. Additionally some commands may handle
+additional arguments or options not documented here
+https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI-Data-Manipulation.html#GDB_002fMI-Data-Manipulation.
+The implemented commands are:
+CMICmdCmdBreakAfter
+CMICmdCmdBreakCondition
+CMICmdCmdBreakDelete
+CMICmdCmdBreakDisable
+CMICmdCmdBreakEnable
+CMICmdCmdBreakInsert
+CMICmdCmdDataEvaluateExpression
+CMICmdCmdDataDisassemble
+CMICmdCmdDataListRegisterChanged
+CMICmdCmdDataListRegisterNames
+CMICmdCmdDataListRegisterValues
+CMICmdCmdDataReadMemory
+CMICmdCmdDataReadMemoryBytes
+CMICmdCmdDataWriteMemory
+CMICmdCmdEnablePrettyPrinting
+CMICmdCmdEnvironmentCd
+CMICmdCmdExecContinue
+CMICmdCmdExecFinish
+CMICmdCmdExecInterrupt
+CMICmdCmdExecNext
+CMICmdCmdExecNextInstruction
+CMICmdCmdExecRun
+CMICmdCmdExecStep
+CMICmdCmdExecStepInstruction
+CMICmdCmdFileExecAndSymbols
+CMICmdCmdGdbExit
+CMICmdCmdGdbInfo
+CMICmdCmdGdbSet
+CMICmdCmdGdbSet - solib-search-path option
+CMICmdCmdInferiorTtySet (not functionally implemented)
+CMICmdCmdInterpreterExec
+CMICmdCmdListThreadGroups
+CMICmdCmdSource
+CMICmdCmdStackInfoDepth
+CMICmdCmdStackListArguments
+CMICmdCmdStackListFrames
+CMICmdCmdStackListLocals
+CMICmdCmdSupportInfoMiCmdQuery
+CMICmdCmdSupportListFeatures
+CMICmdCmdTargetSelect
+CMICmdCmdThread
+CMICmdCmdThreadInfo
+CMICmdCmdTraceStatus (not functionally implemented)
+CMICmdCmdVarAssign
+CMICmdCmdVarCreate
+CMICmdCmdVarDelete
+CMICmdCmdVarEvaluateExpression
+CMICmdCmdVarInfoPathExpression
+CMICmdCmdVarListChildren
+CMICmdCmdVarSetFormat
+CMICmdCmdVarShowAttributes
+CMICmdCmdVarUpdate
+
+=========================================================================
+The MI Driver build configuration:
+MICmnConfig.h defines various preprocessor build options i.e. enable
+LLDB driver fall through (Driver.h/.cpp) should MI Driver not recognise a
+command (option not fully implemented - may be removed in the future).
+
+=========================================================================
+Code standard, documentation and code style scope:
+The coding style and coding documentation scope covers all MI prefixed
+files and where MI code is implemented in the LLDB driver files. Should
+you wish to make improvements or fixes to the MI code (which is encouraged)
+please DO comment your code in the style already applied. The same applies
+to the coding style. Class names should also follow this lead and ideally
+should be one class per file (.h/.cpp). Class interface files (.h) should
+not contain any implementation code unless there is a performance issue or
+templated functions. You get the idea, look around the existing code and
+follow by example :)
+
+Where code comment or documentation is wrong or can be improved to help
+others then it is strongly encouraged you DO improve the documentation.
+
+=========================================================================
+MI Driver license:
+The MI Driver code is under the University of Illinois Open Source License
+agreement. Submitted by Codeplay Ltd UK.
+
+Source code found at: llvm/tools/lldb/tools/lldb-mi.
+
+=========================================================================
+The MI Driver uses the following libraries:
+Standard Template library
+ Thread
+ Containers
+ String
+ File
+ Time
+LLDB public API
+OS specific
+ OS error reporting windows
+ OS error handling OSX (not implemented)
+ OS error handling LINUX (not implemented)
+
+