This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[patch] Improve comments in dcache.c, target.c.
- From: dje at google dot com (Doug Evans)
- To: gdb-patches at sourceware dot org, msnyder at vmware dot com
- Date: Fri, 23 Oct 2009 11:50:56 -0700 (PDT)
- Subject: [patch] Improve comments in dcache.c, target.c.
Hi.
ref: http://sourceware.org/ml/gdb-patches/2009-10/msg00511.html
This patch tweaks/adds a few comments to dcache.c, target.c.
I'll check it in on Monday if there are no objections.
2009-10-23 Doug Evans <dje@google.com>
* dcache.c (dcache_hit, dcache_read_line): Tweak comments.
(dcache_peek_byte, dcache_init, dcache_xfer_memory): Ditto.
* target.c (memory_xfer_partial): Tweak comments.
(target_xfer_partial, target_write_memory): Add comment.
(target_read_partial): Remove note from 2003-10-21.
(target_read, target_write): Add comments.
Index: dcache.c
===================================================================
RCS file: /cvs/src/src/gdb/dcache.c,v
retrieving revision 1.36
diff -u -p -r1.36 dcache.c
--- dcache.c 31 Aug 2009 20:18:45 -0000 1.36
+++ dcache.c 23 Oct 2009 18:38:31 -0000
@@ -175,7 +175,7 @@ dcache_invalidate_line (DCACHE *dcache,
}
/* If addr is present in the dcache, return the address of the block
- containing it. */
+ containing it. Otherwise return NULL. */
static struct dcache_block *
dcache_hit (DCACHE *dcache, CORE_ADDR addr)
@@ -193,7 +193,9 @@ dcache_hit (DCACHE *dcache, CORE_ADDR ad
return db;
}
-/* Fill a cache line from target memory. */
+/* Fill a cache line from target memory.
+ The result is 1 for success, 0 if the (entire) cache line
+ wasn't readable. */
static int
dcache_read_line (DCACHE *dcache, struct dcache_block *db)
@@ -286,7 +288,7 @@ dcache_alloc (DCACHE *dcache, CORE_ADDR
return db;
}
-/* Using the data cache DCACHE return the contents of the byte at
+/* Using the data cache DCACHE, store in *PTR the contents of the byte at
address ADDR in the remote machine.
Returns 1 for success, 0 for error. */
@@ -341,7 +343,7 @@ dcache_splay_tree_compare (splay_tree_ke
return -1;
}
-/* Initialize the data cache. */
+/* Allocate and initialize a data cache. */
DCACHE *
dcache_init (void)
@@ -388,7 +390,11 @@ dcache_free (DCACHE *dcache)
to or from debugger address MYADDR. Write to inferior if SHOULD_WRITE is
nonzero.
- The meaning of the result is the same as for target_write. */
+ Return the number of bytes actually transfered, or -1 if the
+ transfer is not supported or otherwise fails. Return of a non-negative
+ value less than LEN indicates that no further transfer is possible.
+ NOTE: This is different than the to_xfer_partial interface, in which
+ positive values less than LEN mean further transfers may be possible. */
int
dcache_xfer_memory (struct target_ops *ops, DCACHE *dcache,
Index: target.c
===================================================================
RCS file: /cvs/src/src/gdb/target.c,v
retrieving revision 1.229
diff -u -p -r1.229 target.c
--- target.c 20 Oct 2009 11:09:01 -0000 1.229
+++ target.c 23 Oct 2009 18:38:31 -0000
@@ -1181,8 +1181,8 @@ target_section_by_addr (struct target_op
return NULL;
}
-/* Perform a partial memory transfer. The arguments and return
- value are just as for target_xfer_partial. */
+/* Perform a partial memory transfer.
+ For docs see target.h, to_xfer_partial. */
static LONGEST
memory_xfer_partial (struct target_ops *ops, enum target_object object,
@@ -1360,6 +1360,8 @@ make_show_memory_breakpoints_cleanup (in
(void *) (uintptr_t) current);
}
+/* For docs see target.h, to_xfer_partial. */
+
static LONGEST
target_xfer_partial (struct target_ops *ops,
enum target_object object, const char *annex,
@@ -1474,6 +1476,11 @@ target_read_stack (CORE_ADDR memaddr, gd
return EIO;
}
+/* Write LEN bytes from MYADDR to target memory at address MEMADDR.
+ Returns either 0 for success or an errno value if any error occurs.
+ If an error occurs, no guarantee is made about how much data got written.
+ Callers that can deal with partial writes should call target_write. */
+
int
target_write_memory (CORE_ADDR memaddr, const gdb_byte *myaddr, int len)
{
@@ -1637,11 +1644,7 @@ current_xfer_partial (struct target_ops
return -1;
}
-/* Target vector read/write partial wrapper functions.
-
- NOTE: cagney/2003-10-21: I wonder if having "to_xfer_partial
- (inbuf, outbuf)", instead of separate read/write methods, make life
- easier. */
+/* Target vector read/write partial wrapper functions. */
static LONGEST
target_read_partial (struct target_ops *ops,
@@ -1662,6 +1665,9 @@ target_write_partial (struct target_ops
}
/* Wrappers to perform the full transfer. */
+
+/* For docs on target_write see target.h. */
+
LONGEST
target_read (struct target_ops *ops,
enum target_object object,
@@ -1750,7 +1756,6 @@ target_read_until_error (struct target_o
return len;
}
-
/* An alternative to target_write with progress callbacks. */
LONGEST
@@ -1786,6 +1791,8 @@ target_write_with_progress (struct targe
return len;
}
+/* For docs on target_write see target.h. */
+
LONGEST
target_write (struct target_ops *ops,
enum target_object object,