Gergo Csizi
718a439db1
There was some style issues in debugger documentation. This patch fixes these issues. JerryScript-DCO-1.0-Signed-off-by: Gergo Csizi gergocs@inf.u-szeged.hu
221 lines
6.0 KiB
Markdown
221 lines
6.0 KiB
Markdown
# JerryScript debugger transport interface
|
|
|
|
The transport interface support allows dynamic selection of transportation
|
|
layers which can encode/decode or send/receive messages transmitted between
|
|
the debugger client and server.
|
|
|
|
# Types
|
|
|
|
## jerry_debugger_transport_receive_context_t
|
|
|
|
**Summary**
|
|
|
|
This context represents the current status of processing received data.
|
|
The final state is returned by
|
|
[jerry_debugger_transport_receive](#jerry_debugger_transport_receive)
|
|
and must be passed to
|
|
[jerry_debugger_transport_receive_completed](#jerry_debugger_transport_receive_completed)
|
|
after the message is processed.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
typedef struct
|
|
{
|
|
uint8_t *buffer_p; /**< buffer for storing the received data */
|
|
size_t received_length; /**< number of currently received bytes */
|
|
uint8_t *message_p; /**< start of the received message */
|
|
size_t message_length; /**< length of the received message */
|
|
size_t message_total_length; /**< total length for datagram protocols,
|
|
* 0 for stream protocols */
|
|
} jerry_debugger_transport_receive_context_t;
|
|
```
|
|
|
|
## jerry_debugger_transport_header_t
|
|
|
|
**Summary**
|
|
|
|
Shared header for each transport interface. It mostly contains callback functions
|
|
used by the JerryScript debugger server.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
typedef struct jerry_debugger_transport_layer_t
|
|
{
|
|
/* The following fields must be filled before calling jerry_debugger_transport_add(). */
|
|
jerry_debugger_transport_close_t close; /**< close connection callback */
|
|
jerry_debugger_transport_send_t send; /**< send data callback */
|
|
jerry_debugger_transport_receive_t receive; /**< receive data callback */
|
|
|
|
/* The following fields are filled by jerry_debugger_transport_add(). */
|
|
struct jerry_debugger_transport_layer_t *next_p; /**< next transport layer */
|
|
} jerry_debugger_transport_header_t;
|
|
```
|
|
|
|
## jerry_debugger_transport_close_t
|
|
|
|
**Summary**
|
|
|
|
Called when the connection is closed. Must release all resources (including the
|
|
memory area for the transport interface) allocated for the transport interface.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
typedef void (*jerry_debugger_transport_close_t) (struct jerry_debugger_transport_interface_t *header_p);
|
|
```
|
|
|
|
## jerry_debugger_transport_send_t
|
|
|
|
**Summary**
|
|
|
|
Called when a message needs to be sent. Must either transmit the message or call
|
|
the `header_p->next_p->send()` method.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
typedef bool (*jerry_debugger_transport_send_t) (struct jerry_debugger_transport_interface_t *header_p,
|
|
uint8_t *message_p,
|
|
size_t message_length);
|
|
```
|
|
|
|
## jerry_debugger_transport_receive_t
|
|
|
|
**Summary**
|
|
|
|
Called during message processing. If messages are available it must return with
|
|
the next message.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
typedef bool (*jerry_debugger_transport_receive_t) (struct jerry_debugger_transport_interface_t *header_p,
|
|
jerry_debugger_transport_receive_context_t *context_p);
|
|
```
|
|
|
|
# Transport interface API functions
|
|
|
|
## jerry_debugger_transport_add
|
|
|
|
**Summary**
|
|
|
|
Add a new interface to the transportation interface chain. The interface
|
|
will be the first item of the interface chain.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
void jerry_debugger_transport_add (jerry_debugger_transport_header_t *header_p,
|
|
size_t send_message_header_size,
|
|
size_t max_send_message_size,
|
|
size_t receive_message_header_size,
|
|
size_t max_receive_message_size);
|
|
```
|
|
|
|
- `header_p`: header of a transportation interface.
|
|
- `send_message_header_size`: size of the outgoing message header, can be 0.
|
|
- `max_send_message_size`: maximum outgoing message size supported by the interface.
|
|
- `receive_message_header_size`: size of the incoming message header, can be 0.
|
|
- `max_receive_message_size`: maximum incoming message size supported by the interface.
|
|
|
|
## jerry_debugger_transport_start
|
|
|
|
**Summary**
|
|
|
|
Starts the communication to the debugger client. Must be called after the
|
|
connection is successfully established.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
void jerry_debugger_transport_start (void);
|
|
```
|
|
|
|
## jerry_debugger_transport_is_connected
|
|
|
|
**Summary**
|
|
|
|
Tells whether a debugger client is connected to the debugger server.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
bool jerry_debugger_transport_is_connected (void);
|
|
```
|
|
|
|
- return value: `true`, if a client is connected, `false` otherwise.
|
|
|
|
## jerry_debugger_transport_close
|
|
|
|
**Summary**
|
|
|
|
Disconnect from the current debugger client. It does nothing if a client is
|
|
not connected.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
void jerry_debugger_transport_close (void);
|
|
```
|
|
|
|
## jerry_debugger_transport_send
|
|
|
|
**Summary**
|
|
|
|
Send message to the client.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
bool jerry_debugger_transport_send (const uint8_t *message_p, size_t message_length);
|
|
```
|
|
|
|
- `message_p`: message to be sent.
|
|
- `message_length`: message length in bytes.
|
|
- return value: `true`, if a client is still connected, `false` otherwise.
|
|
|
|
## jerry_debugger_transport_receive
|
|
|
|
**Summary**
|
|
|
|
Receive message from the client.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
bool jerry_debugger_transport_receive (jerry_debugger_transport_receive_context_t *context_p);
|
|
```
|
|
|
|
- `context_p`: an unused [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t).
|
|
- return value: `true`, if a client is still connected, `false` otherwise.
|
|
|
|
## jerry_debugger_transport_receive_completed
|
|
|
|
**Summary**
|
|
|
|
Must be called after [jerry_debugger_transport_receive](#jerry_debugger_transport_receive)
|
|
returns with a valid message. Must not be called otherwise.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
void jerry_debugger_transport_receive_completed (jerry_debugger_transport_receive_context_t *context_p);
|
|
```
|
|
|
|
- `context_p`: a [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t)
|
|
passed to [jerry_debugger_transport_receive](#jerry_debugger_transport_receive).
|
|
|
|
## jerry_debugger_transport_sleep
|
|
|
|
**Summary**
|
|
|
|
Can be used to wait for incoming messages. Currently the delay is 100ms.
|
|
|
|
**Prototype**
|
|
|
|
```c
|
|
void jerry_debugger_transport_sleep (void);
|
|
```
|