From patchwork Fri Mar 24 23:56:35 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Malcolm X-Patchwork-Id: 74788 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp100912vqo; Fri, 24 Mar 2023 16:57:25 -0700 (PDT) X-Google-Smtp-Source: AKy350bDYNe49uyh8K/C9gcKZk0e7HrBYQwSH0HTHIQZZ3/oVpm+6Y1X5AE+w9EuC326YNVZ7K96 X-Received: by 2002:a17:906:fc13:b0:93d:78e:d21d with SMTP id ov19-20020a170906fc1300b0093d078ed21dmr4606002ejb.64.1679702245690; Fri, 24 Mar 2023 16:57:25 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1679702245; cv=none; d=google.com; s=arc-20160816; b=aQAOqO2/hCSx1hNT/pdGxedQmEeFfeScAmillrFve9HJo325uQdjMvGpEfX/8j2QcA pCDsKn7AjOt+bL/fvFO4eR9pjm0Zv0m2DleZLKyOPEYJYuJfe7sivnjLWM6ergcnn2gI Z6j77yxtMz+beqOVVX+UHfPUEIjINccrIXX/MHrLZFyNhHDK7fBXudDbTg2vvmn44bKs f+o3uwdeyyMTK7AXelewpBN7MtGAM8scDwCeiOQMDMDoqM+yOej6CuNXctzFEUk2xmh5 goiAA/3mnr+iMh0ERY1QA8EH2DsNLBTKC4vXQwT+8/NBDpxrlZZHvQbRR70jfGSIdLGH ZrRA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:reply-to:from:list-subscribe:list-help:list-post :list-archive:list-unsubscribe:list-id:precedence :content-transfer-encoding:mime-version:message-id:date:subject:cc :to:dmarc-filter:delivered-to:dkim-signature:dkim-filter; bh=Bp9UoNDrata6TNvJrNl0r/N+M9lwsJlqm8rwmW36vWU=; b=mxzkh0K9woNlTpWRCIZ898ucbt6vYoT5KE+QqjFvKnSXdzV2CDY0Lzbaat0ximGpMD +LjnbIHyRhK3QV4EmydNI/nXMWHNvQ+T7Uo0LQfpjRmI6fYYonph4i+t9bJySZ2P9Wpl PlPV4B4w9qB/K5lW0+bAuStc952dGCvUkeIXLbpCrv+NuGpsd3k2zP7tI02uWQBFHkZ7 yl7jtfWuMC3HHzUhsNVnRBcB8gpNhVYCe6FYJwHLdOS5BHCiBGC1xPDMP9HOToY0Mnp8 Ky+Hwo+KwIAk/qm1a/ZlC1xgrM+mRiMTCzSgj/vN4vGgALBOL3RSy6Zqa+Z4fe/KcX3a hrcg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=Vz8oKw73; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from sourceware.org (server2.sourceware.org. [2620:52:3:1:0:246e:9693:128c]) by mx.google.com with ESMTPS id sg9-20020a170907a40900b0093e3a33d7easi3307226ejc.451.2023.03.24.16.57.25 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 24 Mar 2023 16:57:25 -0700 (PDT) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) client-ip=2620:52:3:1:0:246e:9693:128c; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=Vz8oKw73; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 5AB3A3858422 for ; Fri, 24 Mar 2023 23:57:24 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 5AB3A3858422 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1679702244; bh=Bp9UoNDrata6TNvJrNl0r/N+M9lwsJlqm8rwmW36vWU=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:From:Reply-To:From; b=Vz8oKw73m0V2Pz8Wz5d+OkCCX+4/g7Z4xmyN/1lZH8p82oe7rSlKZSJGR+CvMaz7+ 1Qo4AihYwD4hto8mr+eXypbhVsqkfDMGoYl3fSSneiSBowZtrjAwhV9fCqtzoEKpY9 E176W92YXOruMkZtIdVdVm42Ek6Jul5p+NfX7L4U= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 8670A3858D28 for ; Fri, 24 Mar 2023 23:56:39 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 8670A3858D28 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-605-W15NI0cBOj6eEzHtfJlOSA-1; Fri, 24 Mar 2023 19:56:37 -0400 X-MC-Unique: W15NI0cBOj6eEzHtfJlOSA-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 656E785A588 for ; Fri, 24 Mar 2023 23:56:37 +0000 (UTC) Received: from t14s.localdomain.com (unknown [10.2.17.70]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3689D40CF916; Fri, 24 Mar 2023 23:56:37 +0000 (UTC) To: gcc-patches@gcc.gnu.org Cc: David Malcolm Subject: [pushed] docs, analyzer: improvements to "Debugging the Analyzer" Date: Fri, 24 Mar 2023 19:56:35 -0400 Message-Id: <20230324235635.4137828-1-dmalcolm@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-11.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: David Malcolm via Gcc-patches From: David Malcolm Reply-To: David Malcolm Errors-To: gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org Sender: "Gcc-patches" X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1761295461845399347?= X-GMAIL-MSGID: =?utf-8?q?1761295461845399347?= Successfully bootstrapped on x86_64-pc-linux-gnu. Pushed to trunk as r13-6859-gfdb06fe68253d2 gcc/ChangeLog: * doc/analyzer.texi (Debugging the Analyzer): Add notes on useful debugging options. (Special Functions for Debugging the Analyzer): Convert to a table, and rewrite in places. (Other Debugging Techniques): Add notes on how to compare two different exploded graphs. Signed-off-by: David Malcolm --- gcc/doc/analyzer.texi | 125 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 116 insertions(+), 9 deletions(-) diff --git a/gcc/doc/analyzer.texi b/gcc/doc/analyzer.texi index 0afd1143d4c..2692b0e3ece 100644 --- a/gcc/doc/analyzer.texi +++ b/gcc/doc/analyzer.texi @@ -437,13 +437,97 @@ than printing the underlying variable name. @cindex analyzer, debugging @cindex static analyzer, debugging +When debugging the analyzer I normally use all of these options +together: + +@smallexample +./xgcc -B. \ + -S \ + -fanalyzer \ + OTHER_GCC_ARGS \ + -wrapper gdb,--args \ + -fdump-analyzer-stderr \ + -fanalyzer-fine-grained \ + -fdump-ipa-analyzer=stderr +@end smallexample + +where: + +@itemize @bullet +@item @code{./xgcc -B.} +is the usual way to invoke a self-built GCC from within the @file{BUILDDIR/gcc} +subdirectory. + +@item @code{-S} +so that the driver (@code{./xgcc}) invokes @code{cc1}, but doesn't bother +running the assembler or linker (since the analyzer runs inside @code{cc1}). + +@item @code{-fanalyzer} +enables the analyzer, obviously. + +@item @code{-wrapper gdb,--args} +invokes @code{cc1} under the debugger so that I can debug @code{cc1} and +set breakpoints and step through things. + +@item @code{-fdump-analyzer-stderr} +so that the logging interface is enabled and goes to stderr, which often +gives valuable context into what's happening when stepping through the +analyzer + +@item @code{-fanalyzer-fine-grained} +which splits the effect of every statement into its own +exploded_node, rather than the default (which tries to combine +successive stmts to reduce the size of the exploded_graph). This makes +it easier to see exactly where a particular change happens. + +@item @code{-fdump-ipa-analyzer=stderr} +which dumps the GIMPLE IR seen by the analyzer pass to stderr + +@end itemize + +Other useful options: + +@itemize @bullet +@item @code{-fdump-analyzer-exploded-graph} +which dumps a @file{SRC.eg.dot} GraphViz file that I can look at (with +python-xdot) + +@item @code{-fdump-analyzer-exploded-nodes-2} +which dumps a @file{SRC.eg.txt} file containing the full @code{exploded_graph}. + +@end itemize + +Assuming that you have the +@uref{https://gcc-newbies-guide.readthedocs.io/en/latest/debugging.html,,python support scripts for gdb} +installed, you can use: + +@smallexample +(gdb) break-on-saved-diagnostic +@end smallexample + +to put a breakpoint at the place where a diagnostic is saved during +@code{exploded_graph} exploration, to see where a particular diagnostic +is being saved, and: + +@smallexample +(gdb) break-on-diagnostic +@end smallexample + +to put a breakpoint at the place where diagnostics are actually emitted. + @subsection Special Functions for Debugging the Analyzer The analyzer recognizes various special functions by name, for use -in debugging the analyzer. Declarations can be seen in the testsuite +in debugging the analyzer, and for use in DejaGnu tests. + +The declarations of these functions can be seen in the testsuite in @file{analyzer-decls.h}. None of these functions are actually -implemented. +implemented in terms of code, merely as @code{known_function} subclasses +(in @file{gcc/analyzer/kf-analyzer.cc}). + +@table @code +@item __analyzer_break Add: @smallexample __analyzer_break (); @@ -452,6 +536,7 @@ to the source being analyzed to trigger a breakpoint in the analyzer when that source is reached. By putting a series of these in the source, it's much easier to effectively step through the program state as it's analyzed. +@item __analyzer_describe The analyzer handles: @smallexample @@ -462,6 +547,7 @@ by emitting a warning describing the 2nd argument (which can be of any type), at a verbosity level given by the 1st argument. This is for use when debugging, and may be of use in DejaGnu tests. +@item __analyzer_dump @smallexample __analyzer_dump (); @end smallexample @@ -469,6 +555,7 @@ __analyzer_dump (); will dump the copious information about the analyzer's state each time it reaches the call in its traversal of the source. +@item __analyzer_dump_capacity @smallexample extern void __analyzer_dump_capacity (const void *ptr); @end smallexample @@ -476,6 +563,7 @@ extern void __analyzer_dump_capacity (const void *ptr); will emit a warning describing the capacity of the base region of the region pointed to by the 1st argument. +@item __analyzer_dump_escaped @smallexample extern void __analyzer_dump_escaped (void); @end smallexample @@ -484,16 +572,19 @@ will emit a warning giving the number of decls that have escaped on this analysis path, followed by a comma-separated list of their names, in alphabetical order. +@item __analyzer_dump_path @smallexample __analyzer_dump_path (); @end smallexample will emit a placeholder ``note'' diagnostic with a path to that call site, -if the analyzer finds a feasible path to it. +if the analyzer finds a feasible path to it. This can be useful for +writing DejaGnu tests for constraint-tracking and feasibility checking. -The builtin @code{__analyzer_dump_exploded_nodes} will emit a warning -after analysis containing information on all of the exploded nodes at that -program point: +@item __analyzer_dump_exploded_nodes +For every callsite to @code{__analyzer_dump_exploded_nodes} the analyzer +will emit a warning after it finished the analysis containing information +on all of the exploded nodes at that program point. @smallexample __analyzer_dump_exploded_nodes (0); @@ -514,8 +605,9 @@ With a non-zero argument it will also dump all of the states within the ``processed'' nodes. -The builtin @code{__analyzer_dump_named_constant} will emit a warning -during analysis describing what is known about the value of a given +@item __analyzer_dump_named_constant +When the analyzer sees a call to @code{__analyzer_dump_named_constant} it +will emit a warning describing what is known about the value of a given named constant, for parts of the analyzer that interact with target headers. @@ -525,17 +617,19 @@ For example: __analyzer_dump_named_constant ("O_RDONLY"); @end smallexample -might emit the warning: +might lead to the analyzer emitting the warning: @smallexample warning: named constant 'O_RDONLY' has value '1' @end smallexample +@item __analyzer_dump_region_model @smallexample __analyzer_dump_region_model (); @end smallexample will dump the region_model's state to stderr. +@item __analyzer_dump_state @smallexample __analyzer_dump_state ("malloc", ptr); @end smallexample @@ -545,19 +639,32 @@ will emit a warning describing the state of the 2nd argument a name matching the 1st argument (which must be a string literal). This is for use when debugging, and may be of use in DejaGnu tests. +@item __analyzer_eval @smallexample __analyzer_eval (expr); @end smallexample will emit a warning with text "TRUE", FALSE" or "UNKNOWN" based on the truthfulness of the argument. This is useful for writing DejaGnu tests. +@item __analyzer_get_unknown_ptr @smallexample __analyzer_get_unknown_ptr (); @end smallexample will obtain an unknown @code{void *}. +@end table + @subsection Other Debugging Techniques +To compare two different exploded graphs, try +@code{-fdump-analyzer-exploded-nodes-2 -fdump-noaddr -fanalyzer-fine-grained}. +This will dump a @file{SRC.eg.txt} file containing the full +@code{exploded_graph}. I use @code{diff -u50 -p} to compare two different +such files (e.g. before and after a patch) to find the first place where the +two graphs diverge. The option @option{-fdump-noaddr} will suppress +printing pointers withihn the dumps (which would otherwise hide the real +differences with irrelevent churn). + The option @option{-fdump-analyzer-json} will dump both the supergraph and the exploded graph in compressed JSON form.