Target Communication Framework Services - PortForward

• Version History
• Overview
• Commands
  • getConfig
  • list
  • getCapabilities
    
  • create
  • delete
• Events

PortForward Service

Version History

Overview

PortForward service is an interface to provide ability to connect a TCF stream to a device port (TCP port, UDP port, serial line...)

The service supports:

• Ability to create and delete port configurations
  
• Ability to connect to or disconnect from previously created GDB Remote connections.
• Ability to list created ports configuration and display details of those ports configuration
  

When a PortForward creation command is receive, the connection is established to the specified device port and when the connection is established two TCF streams are created and allow to read and write to the port. Any data written by the client to the "OuptutStream" is automatically written to the device port and any data read from the device port is automatically sent to the "InputStream". Reading and writing to/from TCF streams is done using the TCF "Streams" service. The PortFoward configuration is not persistent, when the connection to the device port is lost or if the channel is closed, the PortForward configuration is automatically removed and has to be created again if you want to re-instantiate the connection.

Command are encoded as zero terminated JSON strings.

The service uses standard format for error reports, see Error Report Format.

Commands

getConfig

C • <token> • PortForward • getConfig • <string: Port Forward ID> •

The command retrieves information for given Port Forward configuration ID.

Reply:

Port Forward properties consists of a list of status properties.

Predefined properties are:

• "ID" : <string> - Gdb Remote connection ID
• "InputStream" : <string> - TCF stream used for port input (reading from port)
• "OutputStream" : <string> - TCF stream used for port input (writing to port)
• "Verbose" : <boolean> - Indicate if messages should be printed on console
• "ClientData" : <string> - Port client data string as specified when port was created
• "Port" : <string> - Port configuration string
• "Params" : <string> - Port configuration parameters string

list

The command list available Port Forward configurations

Reply:

<array of Port Forward IDs>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <Port Forwards ID list> ]

<Port Forwards ID list>
    ⇒ <string: Port Forward ID>
    ⇒ Port Forward ID list> , <string: Port Forward ID>

create

C • <token> • PortForward • create • <Port Forward configuration> •

<Port Forward configuration>
    ⇒ <object> 

The command adds a Port Forward connection with specified properties. The connection to the device port is done automatically when the "create" command is issued; reply is sent only when the connection to the port is established or when an error was detected. If

Predefined properties are:

• "ID" : <string> - Port Forward ID (this parameter is mandatory)
• "Port" : <string> - device port to access. This configuration is device specified and described below (this parameter is mandatory)
• "Verbose" : <boolean> - Indicate if Port Forward server must display message in the console when port is accessed (opened, closed...). Default to false.
• "ClientData" : <string> - Port client data string; this can be specified to any value by the client and will be returned when asking information about the port. It is not interpreted by the service.

• "Params" : <string> - Port configuration parameters (used only for serial line).


• "tcp:<host name or IP>:<port number>" - Establish a connection to TCP port <port number> on host <host name or IP>. If <host name or IP> is not specified, then loop back address will be used. <port number> is mandatory.
  
• "udp:<host name or IP>:<port number>" - Establish a connection to UDP port <port number> on host <host name or IP>. If <host name or IP> is not specified, then loop back address will be used. <port number> is mandatory.
• "serial:<serial device>" - Establish a connect to specified serial device (e.g. COM1, /dev/ttyS0).

• <baud rate>: serial line baud rate (default to 115200 if not specified)
• <data bits>: number of data bits (default to 8 if not specified)
• <parity>: can be one of "O" or "o" for odd parity, "E" or "e" for even parity, "N" or "n" for no parity, "M" or "m" for mark parity, "S" or "s" for space parity. Default to no parity if not specified.
• <stop bits>: number of stop bits (default to 1 if not specified)
• <flow control>: can be one of "N" or "n" for no flow control, "S" or "s" for XON/XOFF, "R" or "r" for RTS/CTS, "D" or "d" for DTR/DSR. Default to no flow control if not specified.

"9600" - Only specify baud rate, keep default for everything else
":7" - Only specify number of data bits, keep default for everything else
"::::S" - Set flow control to XON/XOFF, keep default for everything else
"9600:8:N:1:S" - set barud rate to 9600, 8 data bits, no parity, 1 stop bit and space parity


<port properties>
    ⇒ null
    ⇒ <object>

delete

C • <token> • PortForward • delete • <string: PortForward ID> •

The command deletes a previously created Port Foward connection.

Reply:

R • <token> • <error report> •

getCapabilities

C • <token> • PortForward • getCapabilities • <string: PortForward ID> •

This command retrieves PortForward service capabilities to clients so they can adjust to different implementations of the service. Currently, only a null ("") PortForward ID is supported.

Reply:

Service capabilities consist of a list of properties. All properties are optional. Tools and targets can define additional properties. Predefined properties are:

• "TCP" : <boolean> - if true, TCP Port Forward connections are supported
• "UDP" : <boolean> - if true, UDPPort Forward connections are supported
• "Serial" : <boolean> - if true, serial Port Forward connections are supported

Events

PortForward service events are sent to notify clients about PortFoward configurations created ordeleted. The purpose of these events is to let all clients know about PortForward connections that were created by other clients.

E • PortForward • configAdded • <PortForward connection properties> •
E • PortForward • configRemoved • <PortForward connection ID> •

configAdded

Is sent when a new PortForward connection is created and established.The configAdded event contains the same information as returned by the getConfig command. Note that the event is sent only when the connection to the device port has been established.

configRemoved

Is sent when a PortForward connection is removed.