1 : /*
2 : * Copyright 2010 The Native Client Authors. All rights reserved.
3 : * Use of this source code is governed by a BSD-style license that can
4 : * be found in the LICENSE file.
5 : */
6 :
7 :
8 : // This module provides interfaces for writing to and reading from a
9 : // GDB RSP packet. A packet represents a single data transfer from one
10 : // RSP endpoint to another excluding all additional encapsulating data
11 : // generated by the session layer. See:
12 : // http://ftp.gnu.org/old-gnu/Manuals/gdb-5.1.1/html_node/gdb_129.html#SEC134
13 : //
14 : // The packet object stores the data in a character vector in a cooked format,
15 : // tracking both a read and write position within the stream. An empty
16 : // packet still contains a valid pointer to NULL, so it is always safe to
17 : // get the Payload and use it as a string. In addition packets may be
18 : // sequenced by setting an 8 bit sequence number which helps both sides
19 : // detect when packets have been lost. By default the sequence number is not
20 : // set which is represented as a -1.
21 : //
22 : // This API is not expected to throw unless the underlying vector attempts
23 : // to resize when the system is out of memory, in which case it will throw
24 : // a std::bad_alloc.
25 : #ifndef NATIVE_CLIENT_GDB_RSP_PACKET_H_
26 : #define NATIVE_CLIENT_GDB_RSP_PACKET_H_ 1
27 :
28 : #include <string>
29 : #include <vector>
30 :
31 : #include "native_client/src/trusted/port/std_types.h"
32 :
33 : namespace gdb_rsp {
34 :
35 32 : class Packet {
36 : typedef void (*StrFunc_t)(void *ctx, const char *str);
37 :
38 : public:
39 : Packet();
40 :
41 : // Empty the vector and reset the read/write pointers.
42 : void Clear();
43 :
44 : // Reset the read pointer, allowing the packet to be re-read.
45 : void Rewind();
46 :
47 : // Return true of the read pointer has reached the write pointer.
48 : bool EndOfPacket() const;
49 :
50 : // Store a single raw 8 bit value
51 : void AddRawChar(char ch);
52 :
53 : // Store a block of data as hex pairs per byte
54 : void AddBlock(const void *ptr, uint32_t len);
55 :
56 : // Store an 8, 16, 32, or 64 bit word as a block without removing preceeding
57 : // zeros. This is used for fixed sized fields.
58 : void AddWord8(uint8_t val);
59 : void AddWord16(uint16_t val);
60 : void AddWord32(uint32_t val);
61 : void AddWord64(uint64_t val);
62 :
63 : // Store a number up to 64 bits, with preceeding zeros removed. Since
64 : // zeros can be removed, the width of this number is unknown, and always
65 : // followed by NUL or a seperator (non hex digit).
66 : void AddNumberSep(uint64_t val, char sep);
67 :
68 : // Add a raw string. This is dangerous since the other side may incorrectly
69 : // interpret certain special characters such as: ":,#$"
70 : void AddString(const char *str);
71 :
72 : // Add a string stored as a stream of ASCII hex digit pairs. It is safe
73 : // to use any character in this stream. If this does not terminate the
74 : // packet, there should be a sperator (non hex digit) immediately following.
75 : void AddHexString(const char *str);
76 :
77 : // Retrieve a single character if available
78 : bool GetRawChar(char *ch);
79 :
80 : // Retreive "len" ASCII character pairs.
81 : bool GetBlock(void *ptr, uint32_t len);
82 :
83 : // Retreive a 8, 16, 32, or 64 bit word as pairs of hex digits. These
84 : // functions will always consume bits/4 characters from the stream.
85 : bool GetWord8(uint8_t *val);
86 : bool GetWord16(uint16_t *val);
87 : bool GetWord32(uint32_t *val);
88 : bool GetWord64(uint64_t *val);
89 :
90 : // Retreive a number and the seperator. If SEP is null, the seperator is
91 : // consumed but thrown away.
92 : bool GetNumberSep(uint64_t *val, char *sep);
93 :
94 : // Get a string from the stream
95 : bool GetString(std::string *str);
96 : bool GetHexString(std::string *str);
97 :
98 : // Callback with the passed in context, and a NUL terminated string.
99 : // These methods provide a means to avoid an extra memcpy.
100 : bool GetStringCB(void *ctx, StrFunc_t cb);
101 : bool GetHexStringCB(void *ctx, StrFunc_t cb);
102 :
103 : // Return a pointer to the entire packet payload
104 : const char *GetPayload() const;
105 :
106 : // Returns true and the sequence number, or false if it is unset.
107 : bool GetSequence(int32_t *seq) const;
108 :
109 : // Set the sequence number.
110 : void SetSequence(int32_t seq);
111 :
112 : private:
113 : int32_t seq_;
114 : std::vector<char> data_;
115 : size_t read_index_;
116 : size_t write_index_;
117 : };
118 :
119 : } // namespace gdb_rsp
120 :
121 : #endif // NATIVE_CLIENT_GDB_RSP_PACKET_H_
122 :
|
