llvm-project/lldb/tools/lldb-mi/MIReadMe.txt

========================================================================
    The MI Driver - LLDB Machine Interface V2 (MI)  Project Overview  
	28/01/2014
========================================================================

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 (CMIDriver) is a driver in its own right to work alongside
the LLDB driver (driver .h/.cpp). Only one is operated at a time depending
on the options entered on the command line. The MI driver inputs and
outputs MI (GDB instruction) to be interpreted by a client i.e. Eclipse. 
Should MI not understand an instruction it can be passed to the LLDB driver for 
interpretation (the MI stub is on top of LLDB driver not GDB)(build
configuration dependant). Should the LLDB driver be chosen then it the 
MI driver will behave as a normal LLDB driver code MI.

Type --help for instruction on using the MI driver. MI produces a MILog.txt file
which records the actions of the MI driver (only) found in the directory
of the lldbMI executable.

Note any command or text sent to the MI Driver 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 debugging the MI Driver. 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.

=========================================================================
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.
	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.

=========================================================================
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.

=========================================================================
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 command implemented 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
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.

=========================================================================
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)