• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# JerryScript debugger transport interface
2
3The transport interface support allows dynamic selection of transportation
4layers which can encode/decode or send/receive messages transmitted between
5the debugger client and server.
6
7# Types
8
9## jerry_debugger_transport_receive_context_t
10
11**Summary**
12
13This context represents the current status of processing received data.
14The final state is returned by
15[jerry_debugger_transport_receive](#jerry_debugger_transport_receive)
16and must be passed to
17[jerry_debugger_transport_receive_completed](#jerry_debugger_transport_receive_completed)
18after the message is processed.
19
20**Prototype**
21
22```c
23typedef struct
24{
25  uint8_t *buffer_p; /**< buffer for storing the received data */
26  size_t received_length; /**< number of currently received bytes */
27  uint8_t *message_p; /**< start of the received message */
28  size_t message_length; /**< length of the received message */
29  size_t message_total_length; /**< total length for datagram protocols,
30                                *   0 for stream protocols */
31} jerry_debugger_transport_receive_context_t;
32```
33
34## jerry_debugger_transport_header_t
35
36**Summary**
37
38Shared header for each transport interface. It mostly contains callback functions
39used by the JerryScript debugger server.
40
41**Prototype**
42
43```c
44typedef struct jerry_debugger_transport_layer_t
45{
46  /* The following fields must be filled before calling jerry_debugger_transport_add(). */
47  jerry_debugger_transport_close_t close; /**< close connection callback */
48  jerry_debugger_transport_send_t send;  /**< send data callback */
49  jerry_debugger_transport_receive_t receive; /**< receive data callback */
50
51  /* The following fields are filled by jerry_debugger_transport_add(). */
52  struct jerry_debugger_transport_layer_t *next_p; /**< next transport layer */
53} jerry_debugger_transport_header_t;
54```
55
56## jerry_debugger_transport_close_t
57
58**Summary**
59
60Called when the connection is closed. Must release all resources (including the
61memory area for the transport interface) allocated for the transport interface.
62
63**Prototype**
64
65```c
66typedef void (*jerry_debugger_transport_close_t) (struct jerry_debugger_transport_interface_t *header_p);
67```
68
69## jerry_debugger_transport_send_t
70
71**Summary**
72
73Called when a message needs to be sent. Must either transmit the message or call
74the `header_p->next_p->send()` method.
75
76**Prototype**
77
78```c
79typedef bool (*jerry_debugger_transport_send_t) (struct jerry_debugger_transport_interface_t *header_p,
80                                                 uint8_t *message_p, size_t message_length);
81```
82
83## jerry_debugger_transport_receive_t
84
85**Summary**
86
87Called during message processing. If messages are available it must return with
88the next message.
89
90**Prototype**
91
92```c
93typedef bool (*jerry_debugger_transport_receive_t) (struct jerry_debugger_transport_interface_t *header_p,
94                                                    jerry_debugger_transport_receive_context_t *context_p);
95```
96
97# Transport interface API functions
98
99## jerry_debugger_transport_add
100
101**Summary**
102
103Add a new interface to the transporation interface chain. The interface
104will be the first item of the interface chain.
105
106**Prototype**
107
108```c
109void jerry_debugger_transport_add (jerry_debugger_transport_header_t *header_p,
110                                   size_t send_message_header_size, size_t max_send_message_size,
111                                   size_t receive_message_header_size, size_t max_receive_message_size);
112```
113
114- `header_p`: header of a transporation interface.
115- `send_message_header_size`: size of the outgoing message header, can be 0.
116- `max_send_message_size`: maximum outgoing message size supported by the interface.
117- `receive_message_header_size`: size of the incoming message header, can be 0.
118- `max_receive_message_size`: maximum incoming message size supported by the interface.
119
120## jerry_debugger_transport_start
121
122**Summary**
123
124Starts the communication to the debugger client. Must be called after the
125connection is successfully established.
126
127**Prototype**
128
129```c
130void jerry_debugger_transport_start (void);
131```
132
133## jerry_debugger_transport_is_connected
134
135**Summary**
136
137Tells whether a debugger client is connected to the debugger server.
138
139**Prototype**
140
141```c
142bool jerry_debugger_transport_is_connected (void);
143```
144
145- return value: `true`, if a client is connected, `false` otherwise.
146
147## jerry_debugger_transport_close
148
149**Summary**
150
151Disconnect from the current debugger client. It does nothing if a client is
152not connected.
153
154**Prototype**
155
156```c
157void jerry_debugger_transport_close (void);
158```
159
160## jerry_debugger_transport_send
161
162**Summary**
163
164Send message to the client.
165
166**Prototype**
167
168```c
169bool jerry_debugger_transport_send (const uint8_t *message_p, size_t message_length);
170```
171
172- `message_p`: message to be sent.
173- `message_length`: message length in bytes.
174- return value: `true`, if a client is still connected, `false` otherwise.
175
176## jerry_debugger_transport_receive
177
178**Summary**
179
180Receive message from the client.
181
182**Prototype**
183
184```c
185bool jerry_debugger_transport_receive (jerry_debugger_transport_receive_context_t *context_p);
186```
187
188- `context_p`: an unused [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t).
189- return value: `true`, if a client is still connected, `false` otherwise.
190
191## jerry_debugger_transport_receive_completed
192
193**Summary**
194
195Must be called after [jerry_debugger_transport_receive](#jerry_debugger_transport_receive)
196returns with a valid message. Must not be called otherwise.
197
198**Prototype**
199
200```c
201void jerry_debugger_transport_receive_completed (jerry_debugger_transport_receive_context_t *context_p);
202```
203
204- `context_p`: a [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t)
205               passed to [jerry_debugger_transport_receive](#jerry_debugger_transport_receive).
206
207## jerry_debugger_transport_sleep
208
209**Summary**
210
211Can be used to wait for incoming messages. Currently the delay is 100ms.
212
213**Prototype**
214
215```c
216void jerry_debugger_transport_sleep (void);
217```
218