From patchwork Wed Apr 24 14:46:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pedro Alves X-Patchwork-Id: 88958 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id BF3D33849AE8 for ; Wed, 24 Apr 2024 14:47:19 +0000 (GMT) X-Original-To: gdb-patches@sourceware.org Delivered-To: gdb-patches@sourceware.org Received: from mail-wr1-f41.google.com (mail-wr1-f41.google.com [209.85.221.41]) by sourceware.org (Postfix) with ESMTPS id 17C93385840D for ; Wed, 24 Apr 2024 14:46:55 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 17C93385840D Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=palves.net Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 17C93385840D Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=209.85.221.41 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713970017; cv=none; b=MotAXdkqp9r+K7siUT8OLvFiaxHQnX7w887gLHewY/XJmtgjWzhgM0w42WOOMdLvgYwGKSiypFpcRETdxz9TRIHjSkXu88TQHe4apJcfhssqjyOxP3MmE7dnlnjJzKA4wsH/Ny/SkWBF363LxPGz5bCYlYlKXkADI5jErYuIjPE= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713970017; c=relaxed/simple; bh=XkgENEsQzSbgf6Ga1Yz2DZks0m1ry0HoU/XJQS6gPN4=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=Fr6EiM5bq6KcNxqVIoJqQkDTftlp+p7Kv//V7ylFiaqnyCajQm7xOgVyz8+Mvf1K7ZxyOi23GF4gA2ysVEl7AzJD2/igMVgjX/cNcHzevBCqqqNyAVjgNY3XucZuUT7exkhIt8FYT+hW/PQcC4edTWCY+ihbcbaA8KI3sMbsOww= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by mail-wr1-f41.google.com with SMTP id ffacd0b85a97d-34a3e0b31e6so5112342f8f.1 for ; Wed, 24 Apr 2024 07:46:55 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713970014; x=1714574814; h=content-transfer-encoding:mime-version:message-id:date:subject:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=F2hxNi2oI+8bHw8HCxpL5HZopzl28N4Cg2NE3Jt9HhU=; b=Oym1sqJq8cCHXrTbWfdZAm9tYs67X+k9PzuuslBxtPj1LbM5q9ZEKbIWrMFEGRWjvJ pFQ9F+O+Jg8Ftw4Cvm+VcE3BHyleZzCe8KdK2uK1WvLecwHRuhehPycvkrk6hdIhJbtU t0K3UwJ/lBkqc2WPaSlJ81te/D+2lYcaOfIUFS5M6sRDiIvm/B7NXyK0c3RRliYtja3W g1VbOxUrfku8+L400q9Kk45GZPxXZycQ0IJvGXjsFVNR53RIl1aHpb2jDrUKGN+kQ4im aBbssOa1odOUzziUI88NSni3Yjr93qLxZbKbPEjoyagBsH1dlbqIwHNkprvM3R5Zt4yq e3ng== X-Gm-Message-State: AOJu0Yw75TqY9b3zkJGx2Xt0DDwC6XOJvI/17rwy6eZVKOECR1CeTJyx SF2ZhePxyKJUtWGlDnLBIAAXExxMZotqidfQ8izBxCUoky2WKfHNuPkslQ== X-Google-Smtp-Source: AGHT+IFd4ZiG6FEq9w3V0fASlC1sC+6wATi/Eaw9gs/8JJ/PRfTuSWbQpE6hva3aKbkV94HFiGHewQ== X-Received: by 2002:a5d:42d2:0:b0:34b:4d4e:c680 with SMTP id t18-20020a5d42d2000000b0034b4d4ec680mr1954589wrr.36.1713970013524; Wed, 24 Apr 2024 07:46:53 -0700 (PDT) Received: from localhost ([2001:8a0:f93d:b900:e6fb:f181:abd6:74dc]) by smtp.gmail.com with UTF8SMTPSA id a12-20020adfed0c000000b0034635bd6ba5sm17332558wro.92.2024.04.24.07.46.52 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 24 Apr 2024 07:46:53 -0700 (PDT) From: Pedro Alves To: gdb-patches@sourceware.org Subject: [PATCH] Improve target.h & target_ops & xfer_partial descriptions Date: Wed, 24 Apr 2024 15:46:47 +0100 Message-ID: <20240424144647.2849085-1-pedro@palves.net> X-Mailer: git-send-email 2.43.2 MIME-Version: 1.0 X-Spam-Status: No, score=-10.8 required=5.0 tests=BAYES_00, FREEMAIL_FORGED_FROMDOMAIN, FREEMAIL_FROM, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, KAM_SHORT, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_PASS, 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: gdb-patches@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gdb-patches-bounces+patchwork=sourceware.org@sourceware.org Working backwards in terms of motivation for the patch: - When accessing memory via the xfer_partial interface, the process that we're accessing is indicated by inferior_ptid. This can be either the same process as current inferior, or a fork child which does not exist in the inferior list. This is not documented currently. This commit fixes that. - For target deletation to work, we must always make the inferior we want to call the target method on, the current inferior. This wasn't documented, AFAICT, so this commit fixes that too. I put that in the intro comment to target_ops. - I actually started writing a larger intro comment to target_ops, as there was seemingly none, which I did find odd. However, I then noticed the description closer to the top of the file. I missed it the first time, because for some reason, that intro comment is no longer at the top of the file, as #includes etc. have been added above it over the years. This commit fixes that too, by moving that intro comment to the top. Change-Id: Id21f5462947f2a0f6f3ac0c42532df62ba355914 --- gdb/target.h | 75 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 24 deletions(-) base-commit: 3b3e2090118966e3b885ae578440e380dc90e648 diff --git a/gdb/target.h b/gdb/target.h index 486a0a687b0..394e377d034 100644 --- a/gdb/target.h +++ b/gdb/target.h @@ -19,6 +19,28 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . */ +/* This include file defines the interface between the main part of + the debugger, and the part which is target-specific, or specific to + the communications interface between us and the target. + + A TARGET is an interface between the debugger and a particular + kind of file or process. Targets can be STACKED in STRATA, + so that more than one target can potentially respond to a request. + In particular, memory accesses will walk down the stack of targets + until they find a target that is interested in handling that particular + address. STRATA are artificial boundaries on the stack, within + which particular kinds of targets live. Strata exist so that + people don't get confused by pushing e.g. a process target and then + a file target, and wondering why they can't see the current values + of variables any more (the file target is handling them and they + never get to the process target). So when you push a file target, + it goes into the file stratum, which is always below the process + stratum. + + Note that rather than allow an empty stack, we always have the + dummy target at the bottom stratum, so we can call the target + methods without checking them. */ + #if !defined (TARGET_H) #define TARGET_H @@ -48,30 +70,6 @@ typedef const gdb_byte const_gdb_byte; #include "gdbsupport/scoped_restore.h" #include "gdbsupport/refcounted-object.h" #include "target-section.h" - -/* This include file defines the interface between the main part - of the debugger, and the part which is target-specific, or - specific to the communications interface between us and the - target. - - A TARGET is an interface between the debugger and a particular - kind of file or process. Targets can be STACKED in STRATA, - so that more than one target can potentially respond to a request. - In particular, memory accesses will walk down the stack of targets - until they find a target that is interested in handling that particular - address. STRATA are artificial boundaries on the stack, within - which particular kinds of targets live. Strata exist so that - people don't get confused by pushing e.g. a process target and then - a file target, and wondering why they can't see the current values - of variables any more (the file target is handling them and they - never get to the process target). So when you push a file target, - it goes into the file stratum, which is always below the process - stratum. - - Note that rather than allow an empty stack, we always have the - dummy target at the bottom stratum, so we can call the target - methods without checking them. */ - #include "target/target.h" #include "target/resume.h" #include "target/wait.h" @@ -433,6 +431,24 @@ struct target_info const char *doc; }; +/* A GDB target. + + Each inferior has a stack of these. See overall description at the + top. + + Most target methods traverse the current inferior's target stack; + you call the method on the top target (normally via one of the + target_foo wrapper free functions), and the implementation of said + method does its work and returns, or defers to the same method on + the target beneath on the current inferior's target stack. Thus, + the inferior you want to call the target method on must be made the + current inferior before calling a target method, so that the stack + traversal works correctly. + + Methods that traverse the stack have a TARGET_DEFAULT_XXX marker in + their declaration below. See the macros' description above, where + they're defined. */ + struct target_ops : public refcounted_object { @@ -784,6 +800,17 @@ struct target_ops starting point. The ANNEX can be used to provide additional data-specific information to the target. + When accessing memory, inferior_ptid indicates which process's + memory is to be accessed. This is usually the same process as + the current inferior, however it may also be a process that is + a fork child of the current inferior, at a moment that the + child does not exist in GDB's inferior lists. This happens + when we remove software breakpoints from the address space of a + fork child process that we're not going to stay attached to. + Because the fork child is a clone of the fork parent, we can + use the fork parent inferior's stack for target method + delegation. + Return the transferred status, error or OK (an 'enum target_xfer_status' value). Save the number of addressable units actually transferred in *XFERED_LEN if transfer is successful