From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 62351 invoked by alias); 8 Sep 2018 20:22:57 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 62337 invoked by uid 89); 8 Sep 2018 20:22:57 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-25.5 required=5.0 tests=AWL,BAYES_00,GIT_PATCH_0,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,RCVD_IN_DNSWL_NONE,SPF_HELO_PASS autolearn=ham version=3.3.2 spammy=Inside, unwinding, crashes X-HELO: gateway23.websitewelcome.com Received: from gateway23.websitewelcome.com (HELO gateway23.websitewelcome.com) (192.185.50.119) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 08 Sep 2018 20:22:55 +0000 Received: from cm15.websitewelcome.com (cm15.websitewelcome.com [100.42.49.9]) by gateway23.websitewelcome.com (Postfix) with ESMTP id 121632AFD4 for ; Sat, 8 Sep 2018 15:14:49 -0500 (CDT) Received: from box5379.bluehost.com ([162.241.216.53]) by cmsmtp with SMTP id yjcff2f2pbXuJyjctfMGmz; Sat, 08 Sep 2018 15:14:48 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tromey.com; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=oa9MlIUq46Zg5jh38SSPMBj0ewEChoJdF90Is3rjL2k=; b=QI8A+4i6fXAApQh3SLOqpQBE4u PeM4HoZ10AT8CBb77bv6mcd9pibufNtMvJfuHthGYw1VvFHjTVwtzRIphO06QzC65+q/uZ7GlO1F7 Gmc1n0tOuTsnbUeb8M0qn0a+p; Received: from 75-166-85-72.hlrn.qwest.net ([75.166.85.72]:47090 helo=bapiya.Home) by box5379.bluehost.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.91) (envelope-from ) id 1fyjcf-002ImX-4n; Sat, 08 Sep 2018 15:14:25 -0500 From: Tom Tromey To: gdb-patches@sourceware.org Cc: Tom Tromey Subject: [PATCH 09/14] Update Python unwinder documentation Date: Sat, 08 Sep 2018 20:22:00 -0000 Message-Id: <20180908201417.13444-10-tom@tromey.com> In-Reply-To: <20180908201417.13444-1-tom@tromey.com> References: <20180908201417.13444-1-tom@tromey.com> X-SW-Source: 2018-09/txt/msg00181.txt.bz2 PR python/19808 points out a few issues in the Python unwinder documentation. This patch update the documentation for create_unwind_info and read_register to address the issues noted, and adds a cautionary note about writing an unwinder. gdb/doc/ChangeLog 2018-09-08 Tom Tromey PR python/19808: * python.texi (Unwinding Frames in Python): Rewrite create_unwind_info documentation. Update read_register documentation and add a note about unwinder caution. --- gdb/doc/ChangeLog | 7 +++++++ gdb/doc/python.texi | 55 ++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 53 insertions(+), 9 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index 47691c448d2..ccad593e247 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -2290,17 +2290,40 @@ return @code{None}. The code in @value{GDBN} that enables writing unwinders in Python uses this object to return frame's ID and previous frame registers when @value{GDBN} core asks for them. +An unwinder should do as little work as possible. Some otherwise +innocuous operations can cause problems (even crashes, as this code is +not not well-hardened yet). For example, making an inferior call from +an unwinder is unadvisable, as an inferior call will reset +@value{GDBN}'s stack unwinding process, potentially causing re-entrant +unwinding. + @subheading Unwinder Input An object passed to an unwinder (a @code{gdb.PendingFrame} instance) provides a method to read frame's registers: @defun PendingFrame.read_register (reg) -This method returns the contents of the register @var{regn} in the +This method returns the contents of the register @var{reg} in the frame as a @code{gdb.Value} object. @var{reg} can be either a register number or a register name; the values are platform-specific. They are usually found in the corresponding -@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree. +@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree. If +@var{reg} does not name a register for the current architecture, this +method will throw an exception. + +Note that this method will always return a @code{gdb.Value} for a +valid register name. This does not mean that the value will be valid. +For example, you may request a register that an earlier unwinder could +not unwind---the value will be unavailable. Instead, the +@code{gdb.Value} returned from this method will be lazy; that is, its +underlying bits will not be fetched until it is first used. So, +attempting to use such a value will cause an exception at the point of +use. + +The type of the returned @code{gdb.Value} depends on the register and +the architecture. It is common for registers to have a scalar type, +like @code{long long}; but many other types are possible, such as +pointer, pointer-to-function, floating point or vector types. @end defun It also provides a factory method to create a @code{gdb.UnwindInfo} @@ -2313,18 +2336,32 @@ using one of functions provided by @value{GDBN}. @var{frame_id}'s attributes determine which function will be used, as follows: @table @code -@item sp, pc, special -@code{frame_id_build_special (@var{frame_id}.sp, @var{frame_id}.pc, @var{frame_id}.special)} - @item sp, pc -@code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)} +The frame is identified by the given stack address and PC. The stack +address must be chosen so that it is constant throughout the lifetime +of the frame, so a typical choice is the value of the stack pointer at +the start of the function---in the DWARF standard, this would be the +``Call Frame Address''. + +This is the most common case by far. The other cases are documented +for completeness but are only useful in specialized situations. -This is the most common case. +@item sp, pc, special +The frame is identified by the stack address, the PC, and a +``special'' address. The special address is used on architectures +that can have frames that do not change the stack, but which are still +distinct, for example the IA-64, which has a second stack for +registers. Both @var{sp} and @var{special} must be constant +throughout the lifetime of the frame. @item sp -@code{frame_id_build_wild (@var{frame_id}.sp)} +The frame is identified by the stack address only. Any other stack +frame with a matching @var{sp} will be considered to match this frame. +Inside gdb, this is called a ``wild frame''. You will never need +this. @end table -The attribute values should be @code{gdb.Value} + +Each attribute value should be an instance of @code{gdb.Value}. @end defun -- 2.13.6