diff options
Diffstat (limited to 'gdb/target.h')
| -rw-r--r-- | gdb/target.h | 98 |
1 files changed, 54 insertions, 44 deletions
diff --git a/gdb/target.h b/gdb/target.h index 7018c52ce82..2bb47fb2389 100644 --- a/gdb/target.h +++ b/gdb/target.h @@ -180,38 +180,8 @@ extern char *target_signal_to_name (enum target_signal); /* Given a name (SIGHUP, etc.), return its signal. */ enum target_signal target_signal_from_name (char *); -/* Request the transfer of up to LEN 8-bit bytes of the target's - OBJECT. The OFFSET, for a seekable object, specifies the starting - point. The ANNEX can be used to provide additional data-specific - information to the target. - - Return the number of bytes actually transfered, zero when no - further transfer is possible, and -1 when the transfer is not - supported. - - NOTE: cagney/2003-10-17: The current interface does not support a - "retry" mechanism. Instead it assumes that at least one byte will - be transfered on each call. - - NOTE: cagney/2003-10-17: The current interface can lead to - fragmented transfers. Lower target levels should not implement - hacks, such as enlarging the transfer, in an attempt to compensate - for this. Instead, the target stack should be extended so that it - implements supply/collect methods and a look-aside object cache. - With that available, the lowest target can safely and freely "push" - data up the stack. - - NOTE: cagney/2003-10-17: Unlike the old query and the memory - transfer mechanisms, these methods are explicitly parameterized by - the target that it should be applied to. - - NOTE: cagney/2003-10-17: Just like the old query and memory xfer - methods, these new methods perform partial transfers. The only - difference is that these new methods thought to include "partial" - in the name. The old code's failure to do this lead to much - confusion and duplication of effort as each target object attempted - to locally take responsibility for something it didn't have to - worry about. */ +/* Target objects which can be transfered using target_read, + target_write, et cetera. */ enum target_object { @@ -229,17 +199,17 @@ enum target_object /* Possible future objects: TARGET_OBJECT_FILE, TARGET_OBJECT_PROC, ... */ }; -extern LONGEST target_read_partial (struct target_ops *ops, - enum target_object object, - const char *annex, gdb_byte *buf, - ULONGEST offset, LONGEST len); +/* Request that OPS transfer up to LEN 8-bit bytes of the target's + OBJECT. The OFFSET, for a seekable object, specifies the + starting point. The ANNEX can be used to provide additional + data-specific information to the target. -extern LONGEST target_write_partial (struct target_ops *ops, - enum target_object object, - const char *annex, const gdb_byte *buf, - ULONGEST offset, LONGEST len); + Return the number of bytes actually transfered, or -1 if the + transfer is not supported or otherwise fails. Return of a positive + value less than LEN indicates that no further transfer is possible. + Unlike the raw to_xfer_partial interface, callers of these + functions do not need to retry partial transfers. */ -/* Wrappers to perform the full transfer. */ extern LONGEST target_read (struct target_ops *ops, enum target_object object, const char *annex, gdb_byte *buf, @@ -250,6 +220,22 @@ extern LONGEST target_write (struct target_ops *ops, const char *annex, const gdb_byte *buf, ULONGEST offset, LONGEST len); +/* Wrapper to perform a full read of unknown size. OBJECT/ANNEX will + be read using OPS. The return value will be -1 if the transfer + fails or is not supported; 0 if the object is empty; or the length + of the object otherwise. If a positive value is returned, a + sufficiently large buffer will be allocated using xmalloc and + returned in *BUF_P containing the contents of the object. + + This method should be used for objects sufficiently small to store + in a single xmalloc'd buffer, when no fixed bound on the object's + size is known in advance. Don't try to read TARGET_OBJECT_MEMORY + through this function. */ + +extern LONGEST target_read_alloc (struct target_ops *ops, + enum target_object object, + const char *annex, gdb_byte **buf_p); + /* Wrappers to target read/write that perform memory transfers. They throw an error if the memory transfer fails. @@ -409,9 +395,33 @@ struct target_ops CORE_ADDR load_module_addr, CORE_ADDR offset); - /* Perform partial transfers on OBJECT. See target_read_partial - and target_write_partial for details of each variant. One, and - only one, of readbuf or writebuf must be non-NULL. */ + /* Request that OPS transfer up to LEN 8-bit bytes of the target's + OBJECT. The OFFSET, for a seekable object, specifies the + starting point. The ANNEX can be used to provide additional + data-specific information to the target. + + Return the number of bytes actually transfered, zero when no + further transfer is possible, and -1 when the transfer is not + supported. Return of a positive value smaller than LEN does + not indicate the end of the object, only the end of the + transfer; higher level code should continue transferring if + desired. This is handled in target.c. + + The interface does not support a "retry" mechanism. Instead it + assumes that at least one byte will be transfered on each + successful call. + + NOTE: cagney/2003-10-17: The current interface can lead to + fragmented transfers. Lower target levels should not implement + hacks, such as enlarging the transfer, in an attempt to + compensate for this. Instead, the target stack should be + extended so that it implements supply/collect methods and a + look-aside object cache. With that available, the lowest + target can safely and freely "push" data up the stack. + + See target_read and target_write for more information. One, + and only one, of readbuf or writebuf must be non-NULL. */ + LONGEST (*to_xfer_partial) (struct target_ops *ops, enum target_object object, const char *annex, gdb_byte *readbuf, const gdb_byte *writebuf, |