From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from NAM12-BN8-obe.outbound.protection.outlook.com (mail-bn8nam12on2057.outbound.protection.outlook.com [40.107.237.57]) by sourceware.org (Postfix) with ESMTPS id ABEEF385802F for ; Mon, 17 Jan 2022 12:45:06 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org ABEEF385802F ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=ZZP4+qnxophKGpJCgVnV0YV/e8/TBpeFXaYJVUDkMSr4YwFut1wF4hY1HCV1n8CV+cqtoXNklgeeZZyczpEUOLiBKzVWEaqmQGHJa8MfrEkJAoEY6oYdb8o96D/gv1+J3pdSiBINfs9yWqZF8M6quSOSLI+7TF5Von2CDevoIklvhXE85PX/46nq+CWuokrSw2VW8WAHbbuvDmu+NbGoHyYCtZsr1AM2M3Qk0g0A8TdQw2qRougn7Z20Jr83VwUhfM2ye3B3cE0jAyI6a1YRgL5Y42FwnLsbbhsQ6GEKzkAf0h9h0ymlL+UgWodbjPeE+qFzDuXaRkz2ze0wlkPAkQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=/LStk2nXQIwI89q1dZ4hhHHtlVuHUwIOLAHN0eVkdDo=; b=c79NYYdH/WHPiZSOj+zaRacpmEVCfhCqUFIUjPa9BDScZZotOVUMNbfmcRNkkYlBRwXz6KfUllhMyhABjB2+0lJcoQ8XvBVIl3d0khdQ9RxieSYFTcsq9l/OuahdpjHgTZH74gwbAZgQYjMMS0AAydoBFkZ//C76KPmAWja9SiS56PVCg2tf+XvVLQ+gJVc19jmWat84D48aFIsn4qPwEcppXJd5uLOvW/FwuNGO+GwNHTFBufRTx1TLTD+o1MyRsoy4p6PMFPtsnJr8eQ8x0b6I4N8Wu+v0yVG1hZhDw+HUdqgtCQn2Hez/OTvKc9Rcql31m3l2S4yV7lSOPQ8MBA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=labware.com; dmarc=pass action=none header.from=labware.com; dkim=pass header.d=labware.com; arc=none Received: from DM6PR17MB3113.namprd17.prod.outlook.com (2603:10b6:5:6::10) by SJ0PR17MB5494.namprd17.prod.outlook.com (2603:10b6:a03:38e::10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4888.9; Mon, 17 Jan 2022 12:45:03 +0000 Received: from DM6PR17MB3113.namprd17.prod.outlook.com ([fe80::7839:31f:2416:6ba5]) by DM6PR17MB3113.namprd17.prod.outlook.com ([fe80::7839:31f:2416:6ba5%7]) with mapi id 15.20.4888.014; Mon, 17 Jan 2022 12:45:03 +0000 From: Jan Vrany To: gdb-patches@sourceware.org Cc: Jan Vrany Subject: [PATCH 5/5] gdb/python: document GDB/MI commands in Python Date: Mon, 17 Jan 2022 12:44:25 +0000 Message-Id: <20220117124425.2658516-6-jan.vrany@labware.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220117124425.2658516-1-jan.vrany@labware.com> References: <20220117124425.2658516-1-jan.vrany@labware.com> Content-Transfer-Encoding: 8bit Content-Type: text/plain X-ClientProxiedBy: LO4P123CA0505.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:272::15) To DM6PR17MB3113.namprd17.prod.outlook.com (2603:10b6:5:6::10) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 45c1569c-5e3b-4ba5-e0f6-08d9d9b72e69 X-MS-TrafficTypeDiagnostic: SJ0PR17MB5494:EE_ X-Microsoft-Antispam-PRVS: X-MS-Oob-TLC-OOBClassifiers: OLM:8273; X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: uWPpa39k06ErQOxeleCjgjGx15Cmr4AUncP4z/pAJp1Qol5YN293clmkCOq7ONYDZ3U/jCqmTtJlie0mCYYbUAG6lZ9fH8uNsM4v+B8gMVoWbocsGOmm7ojZfQol0WtsqXkP5QYkDr6c6W+S9mzH493VIOabPiTSj8oqtOX9eCUQwCBGkAjCf9K5QTwPVhiZTwhxwdCJ2O/oj8vjMUpD/JjwD4GrtDsZ6483uWrHeUTw4n3R4kxjhzEKmmdZbZ7KkuU+5M/dZh4LK+5DiFs4NGVU94U3RTgU/XXyd7nMyAqYpPFnWz1gySqTFAhnLX1NpUnp40wqHmm1/B0omXs4Eo29dl1ydB8GI2vsngY3v4rK6k91xKIpnullcS3M96sCiBkO6WZNFlXMtxw2FJudWUJ8Bs0iu+p/tT3b9FH4eG7jF3ccDn+WC1KVBY9XT+8rpD4x+h7tN28rXK5sNYD5NgO6/R90yubo1ydZB11VwkVKyTmPEUF5M0UKWEFN503duVIipcrWaqSoL6mUnDl4fYciSMZdttkhaKbQIMJ4vpxT+7Bg4btijr+JMO+QTQjeRCkRIpreW5qq0yLPYXXxevJuJWv2ux26C7YE9Ue3UaPeuzUTOFu5ClAgPj0w0AuH7jd4nrceiPj0zVWhvMVY7SxaMVcqKYfPEccC6cNrhv59ahv9sqlcwrCBoMI6qr3BWPcMurzcneCaVTZ/CFYIbQ== X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DM6PR17MB3113.namprd17.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(366004)(6506007)(86362001)(5660300002)(44832011)(2616005)(6666004)(4326008)(6512007)(38350700002)(38100700002)(186003)(66556008)(66476007)(66946007)(83380400001)(26005)(52116002)(107886003)(8936002)(6916009)(6486002)(316002)(8676002)(1076003)(2906002)(36756003)(508600001); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?b0J3EilIXj+n8AY+uSvYtn7bW+zjIN4WsKUUjGXDaXAdDDOYsaYJog20XVeU?= =?us-ascii?Q?YnZD4sLzr4jK/IAg/KVyURxfXRvPAF94wKivwPdvZDL1MKs01v8MQFhBeCcI?= =?us-ascii?Q?f22OLS2J/JX3agFg1gIWY+rXuFnopqliBANHX3sGZbTIAS9F2oWBpqzKPdm4?= =?us-ascii?Q?lRFLD3cn1a6M7ejhhuHS0e9G7aeKPCbrAlE9n6CC7qHE5I8+lRYQu49zWieA?= =?us-ascii?Q?uIOFWmZP3UbCdavlpCtTS7gCXkOxL/xZahJ9fgdDr+n3s+wxvbVPOjgAbSUC?= =?us-ascii?Q?wbzPL1XJWwlTrW/VYuAzvMxxMbn03JSrYSd3e4Gc+nvcoiTbJimg+0gssIW1?= =?us-ascii?Q?6H3UMc5M5cy9IK5YdbYWhb12EpXkJX7ajZzR1TaLrWsjd1iIS3EbV0TlmGI+?= =?us-ascii?Q?fSiFFUsybpwiyeJRA05aEq8HWJir2r3x35pSpAHBz/JC8J3FBp4Dj7xybP1C?= =?us-ascii?Q?Uv96ma1c+Bwr8z0nZq5+xU6JLbB1DvkxfeFCPM148XMO0VHArNlNY/8Mnatp?= =?us-ascii?Q?aJNWNmuTWmNw1B0VLXodS3jLHtyGnm8662Giuftxs3mMIMbvev17UO1dMDZE?= =?us-ascii?Q?lekF5AbBRIB5eBHU9WCcQsJalATqPilMZhdjCjxSVxYVZ7dzAz9PjPMSsCJU?= =?us-ascii?Q?IQz636AzqNHSSQjt7HxcF9o6HRMamlWtf/MJYPMYBNP9uIq8ZHwHWREg1XwC?= =?us-ascii?Q?q7W1kIaRM/RVJtkFujbde/dc926xxxoEgZJExXDXNhj9NBqCW9rmqebxGIeh?= =?us-ascii?Q?jAm2eUIYKe6+UQEdOfIdUydA0IBlJ9x5h+KxzCUm+aRnv4aUTjVsQlez6gjl?= =?us-ascii?Q?4n3N1UWo9d4MBh3vdGL1TWef0O3pL3VMWGqXTU+A59Ul0LI3D13Ih/B6kxEh?= =?us-ascii?Q?+b+Lq0HwBqdy1Dkcj2w095ZBS9yOjk12qbH7g9s5XIUMVa5tS/+u358mjyLW?= =?us-ascii?Q?eqvuXk8ew9WC8vPvJF/0RkDSHLGNkX9jRuDdTU5PINNueFfsRi0COyGzJbrk?= =?us-ascii?Q?PIM+DifSHLei129xgrEtFNpb54ONbMd+gopj9w5U98BgdcOmhrvFg71ADmXD?= =?us-ascii?Q?YIfoE05SEFTXcBCze1b8CmjmQybomsbnBpwGMXzm597btxngkk24qPdRytsU?= =?us-ascii?Q?NY9+bmp8VrCzVc+Ybt7tWwpd52Jh1dP8FQvga0CQPH2U3gUW1DxJcmpw3ycs?= =?us-ascii?Q?lDsFzjhKZc0fWURIhiQdriFObLUrnejbYFvSwH6ydNoEW9eqm+hQXyUcQkyZ?= =?us-ascii?Q?w3kVl4KnFnRn18LMq813EY1MGVA1ZRuUP3zoRn0Ai/1oIkplBlxz4ijsZtnr?= =?us-ascii?Q?IR1vBxxnisTuVzJC1nzX7+2EeevTNHdborFYAnZEwIirqx48klzbP4idh0/y?= =?us-ascii?Q?Iv3TgPCWvl8dPLHWtwy2ArVMESOuRy4ES14hCD2XWZL0sNdX72nzLWRGYkkh?= =?us-ascii?Q?04g92UGPI7gGEUFiUt6pq+Zu8Ss5ufXSfYcYhCm4G8JNSmy+4RS4eDJM6Riy?= =?us-ascii?Q?UMBhLfiSly2vtgcwogYF4S3bj56zJeFkK+/0NFqX83IeUVZ8Nkh+Fvulj3qe?= =?us-ascii?Q?4SWY6Z/IouwiVzaLkDJbOjTTVYvQUSiwduyQl9v/prhf+pBr0Kz64tqbHUX6?= =?us-ascii?Q?xBxHxG6E1y+r4hdm2F7cHBM=3D?= X-OriginatorOrg: labware.com X-MS-Exchange-CrossTenant-Network-Message-Id: 45c1569c-5e3b-4ba5-e0f6-08d9d9b72e69 X-MS-Exchange-CrossTenant-AuthSource: DM6PR17MB3113.namprd17.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 17 Jan 2022 12:45:03.1194 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: b5db0322-1aa0-4c0a-859c-ad0f96966f4c X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: PWrvJBtvZUXkxiVUeedshkAqcZJTcrKiwpihco+yMgXZ6vZ81yNkEQP1C9nWbfcWPowisVUkEPAeHwuKhx2V8A== X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ0PR17MB5494 X-Spam-Status: No, score=-12.9 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 17 Jan 2022 12:45:13 -0000 --- gdb/NEWS | 2 ++ gdb/doc/python.texi | 80 +++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 76 insertions(+), 6 deletions(-) diff --git a/gdb/NEWS b/gdb/NEWS index 8c13cefb22f..60f157b9c82 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -146,6 +146,8 @@ show debug lin-lwp ** New function gdb.host_charset(), returns a string, which is the name of the current host charset. + ** New GDB/MI commands can now be written in Python. + * New features in the GDB remote stub, GDBserver ** GDBserver is now supported on OpenRISC GNU/Linux. diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 38fce5b38e3..1c17fc1fe2d 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -204,7 +204,8 @@ optional arguments while skipping others. Example: * Events In Python:: Listening for events from @value{GDBN}. * Threads In Python:: Accessing inferior threads from Python. * Recordings In Python:: Accessing recordings from Python. -* Commands In Python:: Implementing new commands in Python. +* CLI Commands In Python:: Implementing new CLI commands in Python. +* GDB/MI Commands In Python:: Implementing new @sc{GDB/MI} commands in Python. * Parameters In Python:: Adding new @value{GDBN} parameters. * Functions In Python:: Writing new convenience functions. * Progspaces In Python:: Program spaces. @@ -388,7 +389,8 @@ the current language, evaluate it, and return the result as a @code{gdb.Value}. This function can be useful when implementing a new command -(@pxref{Commands In Python}), as it provides a way to parse the +(@pxref{CLI Commands In Python}, @pxref{GDB/MI Commands In Python}), +as it provides a way to parse the command's argument as an expression. It is also useful simply to compute values. @end defun @@ -2105,7 +2107,7 @@ must contain the frames that are being elided wrapped in a suitable frame decorator. If no frames are being elided this function may return an empty iterable, or @code{None}. Elided frames are indented from normal frames in a @code{CLI} backtrace, or in the case of -@code{GDB/MI}, are placed in the @code{children} field of the eliding +@sc{GDB/MI}, are placed in the @code{children} field of the eliding frame. It is the frame filter's task to also filter out the elided frames from @@ -3809,9 +3811,10 @@ def countrange (filename, linerange): return count @end smallexample -@node Commands In Python -@subsubsection Commands In Python +@node CLI Commands In Python +@subsubsection CLI Commands In Python +@cindex CLI commands in python @cindex commands in python @cindex python commands You can implement new @value{GDBN} CLI commands in Python. A CLI @@ -4092,6 +4095,71 @@ registration of the command with @value{GDBN}. Depending on how the Python code is read into @value{GDBN}, you may need to import the @code{gdb} module explicitly. +@node GDB/MI Commands In Python +@subsubsection @sc{GDB/MI} Commands In Python + +@cindex MI commands in python +@cindex commands in python +@cindex python commands +You can implement new @sc{GDB/MI} (@pxref{GDB/MI}) commands in Python. A @sc{GDB/MI} +command is implemented using an instance of the @code{gdb.MICommand} +class, most commonly using a subclass. + +@defun Command.__init__ (name) +The object initializer for @code{MICommand} registers the new command +with @value{GDBN}. This initializer is normally invoked from the +subclass' own @code{__init__} method. + +@var{name} is the name of the command. It must be a valid @sc{GDB/MI} +command and must start with hyphen (-). +@end defun + +@defun Command.invoke (arguments) +This method is called by @value{GDBN} when this command is invoked. + +@var{arguments} is a list of strings. Note, that @code{--thread} +and @code{--frame} arguments are handled by @value{GDBN} itself therefore +they do not show up in @code{arguments}. + +If this method throws an exception, it is turned into a @sc{GDB/MI} +@code{^error} response. Otherwise, the return value is converted +to @sc{GDB/MI} value (@pxref{GDB/MI Output Syntax}) as follows: + +@itemize +@item If the value is Python sequence or iterator, it is converted to +@sc{GDB/MI} @emph{list} with elements converted recursively. + +@item If the value is Python dictionary, it is converted to +@sc{GDB/MI} @emph{tuple}. Keys in that dictionary must be strings. +Values are converted recursively. + +@item Otherwise, value is first converted to Python string using +@code{str ()} and then converted to @sc{GDB/MI} @emph{const}. +@end itemize + +@end defun + +The following code snippet shows how a trivial MI command can be +implemented in Python: + +@smallexample +class MIEcho(gdb.MICommand): + """Echo parameters""" + + def __init__ (self): + super (MIEcho, self).__init__ ("-echo") + + def invoke (self, argv): + return @{'argv' : argv @} + +MIEcho () +@end smallexample + +The last line instantiates the class, and is necessary to trigger the +registration of the command with @value{GDBN}. Depending on how the +Python code is read into @value{GDBN}, you may need to import the +@code{gdb} module explicitly. + @node Parameters In Python @subsubsection Parameters In Python @@ -4129,7 +4197,7 @@ If @var{name} consists of multiple words, and no prefix parameter group can be found, an exception is raised. @var{command-class} should be one of the @samp{COMMAND_} constants -(@pxref{Commands In Python}). This argument tells @value{GDBN} how to +(@pxref{CLI Commands In Python}). This argument tells @value{GDBN} how to categorize the new parameter in the help system. @var{parameter-class} should be one of the @samp{PARAM_} constants -- 2.30.2