1 This import module uses a largely text-based protocol, except for
   2 certain bulk data transfer operations. All text is in single-byte
   3 US-ASCII.
   4 
   5 Commands understood:
   6 
   7 address_size                  ::= <int result>
   8 
   9     Returns 32 if attached to 32-bit process, 64 if 64-bit.
  10 
  11 peek_fail_fast <bool arg>     ::=
  12 
  13     Indicates whether "peek" requests should "fail fast"; that is, if
  14     any of the addresses in the requested range are unmapped, report
  15     the entire range as unmapped. This is substantially faster than
  16     the alternative, which is to read the entire range byte-by-byte.
  17     However, it should only be used when it is guaranteed by the
  18     client application that peeks come from at most one page. The
  19     default is that peek_fast_fail is not enabled.
  20 
  21 peek <address addr> <unsigned int numBytes> ::=
  22     B<binary char success>
  23        [<binary unsigned int len> <binary char isMapped> [<binary char data>]...]...
  24 
  25     NOTE that the binary portion of this message is prefixed by the
  26     uppercase US-ASCII letter 'B', allowing easier synchronization by
  27     clients. There is no data between the 'B' and the rest of the
  28     message.
  29 
  30     May only be called once attached. Reads the address space of the
  31     target process starting at the given address (see below for format
  32     specifications) and extending the given number of bytes. Whether
  33     the read succeeded is indicated by a single byte containing a 1 or
  34     0 (success or failure). If successful, the return result is given
  35     in a sequence of ranges. _len_, the length of each range, is
  36     indicated by a 32-bit unsigned integer transmitted with big-endian
  37     byte ordering (i.e., most significant byte first).  _isMapped_
  38     indicates whether the range is mapped or unmapped in the target
  39     process's address space, and will contain the value 1 or 0 for
  40     mapped or unmapped, respectively. If the range is mapped,
  41     _isMapped_ is followed by _data_, containing the raw binary data
  42     for the range. The sum of all ranges' lengths is guaranteed to be
  43     equivalent to the number of bytes requested.
  44 
  45 poke <address addr> <int numBytes> B[<binary char data>]... ::= <bool result>
  46 
  47     NOTE that the binary portion of this message is prefixed by the
  48     uppercase US-ASCII letter 'B', allowing easier synchronization by
  49     clients. There is no data between the 'B' and the rest of the
  50     message.
  51 
  52     Writes the given data to the target process starting at the given
  53     address. Returns 1 on success, 0 on failure (i.e., one or more of
  54     target addresses were unmapped).
  55 
  56 mapped <address addr> <int numBytes> ::= <bool result>
  57 
  58     Returns 1 if entire address range [address...address + int arg) is
  59     mapped in target process's address space, 0 if not
  60 
  61 lookup <symbol objName> <symbol sym> ::= <address addr>
  62 
  63     First symbol is object name; second is symbol to be looked up.
  64     Looks up symbol in target process's symbol table and returns
  65     address. Returns NULL (0x0) if symbol is not found.
  66 
  67 thr_gregs <int tid>                  ::= <int numAddresses> <address...>
  68 
  69     Fetch the "general" (integer) register set for the given thread.
  70     Returned as a series of hexidecimal values. NOTE: the meaning of
  71     the return value is architecture-dependent. In general it is the
  72     contents of the prgregset_t.
  73 
  74 exit                                 ::=
  75 
  76     Exits the serviceability agent dbx module, returning control to
  77     the dbx prompt.
  78 
  79 // Data formats and example values:
  80 <address>      ::=   0x12345678[9ABCDEF0] /* up to 64-bit hex value */
  81 <unsigned int> ::=   5                    /* up to 32-bit integer number; no leading sign */
  82 <bool>         ::=   1                    /* ASCII '0' or '1' */