1 : /*
2 : * Copyright (c) 2010 The Native Client Authors. All rights reserved.
3 : * Use of this source code is governed by a BSD-style license that can be
4 : * 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/include/portability.h"
32 :
33 : namespace gdb_rsp {
34 :
35 472 : class Packet {
36 : public:
37 : Packet();
38 :
39 : // Empty the vector and reset the read/write pointers.
40 : void Clear();
41 :
42 : // Reset the read pointer, allowing the packet to be re-read.
43 : void Rewind();
44 :
45 : // Return true of the read pointer has reached the write pointer.
46 : bool EndOfPacket() const;
47 :
48 : // Store a single raw 8 bit value
49 : void AddRawChar(char ch);
50 :
51 : // Store a block of data as hex pairs per byte
52 : void AddBlock(const void *ptr, uint32_t len);
53 :
54 : // Store an 8, 16, 32, or 64 bit word as a block without removing preceeding
55 : // zeros. This is used for fixed sized fields.
56 : void AddWord8(uint8_t val);
57 : void AddWord16(uint16_t val);
58 : void AddWord32(uint32_t val);
59 : void AddWord64(uint64_t val);
60 :
61 : // Store a number up to 64 bits, with preceeding zeros removed. Since
62 : // zeros can be removed, the width of this number is unknown, and always
63 : // followed by NUL or a separator (non hex digit).
64 : void AddNumberSep(uint64_t val, char sep);
65 :
66 : // Add a raw string. This is dangerous since the other side may incorrectly
67 : // interpret certain special characters such as: ":,#$"
68 : void AddString(const char *str);
69 :
70 : // Add escaped data according to the GDB protocol for binary data.
71 : void AddEscapedData(const char *data, size_t length);
72 :
73 : // Add a string stored as a stream of ASCII hex digit pairs. It is safe
74 : // to use any character in this stream. If this does not terminate the
75 : // packet, there should be a sperator (non hex digit) immediately following.
76 : void AddHexString(const char *str);
77 :
78 : // Retrieve a single character if available
79 : bool GetRawChar(char *ch);
80 :
81 : // Retrieve "len" ASCII character pairs.
82 : bool GetBlock(void *ptr, uint32_t len);
83 :
84 : // Retrieve a 8, 16, 32, or 64 bit word as pairs of hex digits. These
85 : // functions will always consume bits/4 characters from the stream.
86 : bool GetWord8(uint8_t *val);
87 : bool GetWord16(uint16_t *val);
88 : bool GetWord32(uint32_t *val);
89 : bool GetWord64(uint64_t *val);
90 :
91 : // Retrieve a number and the separator. If SEP is null, the separator is
92 : // consumed but thrown away.
93 : bool GetNumberSep(uint64_t *val, char *sep);
94 :
95 : // Get a string from the stream
96 : bool GetString(std::string *str);
97 : bool GetHexString(std::string *str);
98 : bool GetStringSep(std::string *str, char sep);
99 :
100 : // Return a pointer to the entire packet payload
101 : const char *GetPayload() const;
102 : size_t GetPayloadSize() const;
103 :
104 : // Returns true and the sequence number, or false if it is unset.
105 : bool GetSequence(int32_t *seq) const;
106 :
107 : // Parses sequence number in package data and moves read pointer past it.
108 : void ParseSequence();
109 :
110 : // Set the sequence number.
111 : void SetSequence(int32_t seq);
112 :
113 : private:
114 : int32_t seq_;
115 : std::vector<char> data_;
116 : size_t read_index_;
117 : size_t write_index_;
118 : };
119 :
120 : } // namespace gdb_rsp
121 :
122 : #endif // NATIVE_CLIENT_GDB_RSP_PACKET_H_
123 :
|
