| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="content-type" content="text/html; |
| charset=windows-1252"> |
| <title>Target Communication Framework Services - PortForward</title> |
| </head> |
| <body lang="EN-US"> |
| <h1>Target Communication Framework Services - PortForward</h1> |
| <ul> |
| <li><a href="#VersionHistory">Version History</a> </li> |
| <li><a href="#Overview">Overview</a> </li> |
| <li><a href="#Cmds">Commands</a> |
| <ul> |
| <li><a href="#CmdGetConfig">getConfig</a> </li> |
| <li><a href="#CmdList">list</a></li> |
| <li><a href="#cmdGetCapabilities">getCapabilities</a><br> |
| </li> |
| <li><a href="#CmdCreate">create</a> </li> |
| <li><a href="#CmdDelete">delete</a></li> |
| </ul> |
| </li> |
| <li><a href="#Events">Events</a> </li> |
| </ul> |
| <h1>PortForward Service</h1> |
| <h2><a name="VersionHistory">Version History</a></h2> |
| <table border="1" cellpadding="8" height="124" width="298"> |
| <tbody> |
| <tr> |
| <th>Version </th> |
| <th>Date </th> |
| <th>Change<br> |
| </th> |
| </tr> |
| <tr> |
| <td>0.1 </td> |
| <td>2016-07-10 </td> |
| <td>Initial contribution </td> |
| </tr> |
| </tbody> |
| </table> |
| <h2><a name="Overview">Overview</a></h2> |
| <p>PortForward service is an interface to provide ability to connect |
| a TCF stream to a device port (TCP port, UDP port, serial line...)<br> |
| </p> |
| <p>The service supports: </p> |
| <ul> |
| <li> Ability to create and delete port configurations<br> |
| </li> |
| <li>Ability to connect to or disconnect from previously created |
| GDB Remote connections.</li> |
| <li>Ability to list created ports configuration and display |
| details of those ports configuration<br> |
| </li> |
| </ul> |
| <p>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 <b>"Streams"</b> 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.<br> |
| </p> |
| <p>Command are encoded as zero terminated <a |
| href='TCF JSON.html'>JSON</a> strings.</p> |
| <p>The service uses standard format for error reports, see <a |
| href='TCF Error Report Format.html'>Error Report Format</a>.</p> |
| <h2><a name="Cmds">Commands</a></h2> |
| <h3><a name="CmdGetConfig">getConfig</a></h3> |
| <pre><b><font color="#333399" face="Courier New" size="2"> |
| C <i><token></i> PortForward getConfig </font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i><string: Port Forward ID></i></font></b></font></b><b><font color="#333399" face="Courier New" size="2"> |
| </font></b></pre> |
| <p>The command retrieves information for given Port Forward |
| configuration ID.</p> |
| <p>Reply:</p> |
| <b><font color="#333399" face="Courier New" size="2"> R <i><token></i> |
| <i><error report></i> <i><Port Forward |
| properties></i> <i><</i></font></b><b><font><i><b><font |
| color="#333399" face="Courier New" size="2"><i>port |
| forward properties</i></font></b></i></font></b><b><font |
| color="#333399" face="Courier New" size="2"><i>></i> </font></b> |
| <p>Port Forward properties consists of a list of status properties.</p> |
| <p>Predefined properties are:<br> |
| </p> |
| <ul> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"ID" |
| |
| |
| |
| |
| |
| |
| : <i><string></i></font></b><font color="#333399" |
| face="Courier New" size="2"> - </font></code><code><font |
| color="#333399" face="Courier New" size="2">Gdb Remote |
| connection </font></code><code><font color="#333399" |
| face="Courier New" size="2">ID</font></code> </li> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"InputStream" |
| |
| |
| |
| |
| |
| : <i><string></i></font></b><font color="#333399" |
| face="Courier New" size="2"> - TCF stream used for port |
| input (reading from port)</font></code> </li> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"OutputStream" |
| |
| |
| |
| |
| |
| : <i><string></i></font></b><font color="#333399" |
| face="Courier New" size="2"> - </font></code><code><font |
| color="#333399" face="Courier New" size="2">TCF stream used |
| for port input (writing to port)</font></code></li> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"Verbose" |
| |
| |
| |
| |
| |
| : <i><boolean></i></font></b><font color="#333399" |
| face="Courier New" size="2"> - Indicate if messages should |
| be printed on console</font></code></li> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"ClientData" |
| |
| |
| |
| |
| |
| : <i><string></i></font></b><font color="#333399" |
| face="Courier New" size="2"> - Port client data string as |
| specified when port was created</font></code></li> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"Port" |
| |
| |
| |
| |
| |
| : <i><string></i></font></b><font color="#333399" |
| face="Courier New" size="2"> - Port configuration string</font></code></li> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"Params" |
| |
| |
| |
| |
| |
| : <i><string></i></font></b><font color="#333399" |
| face="Courier New" size="2"> - Port configuration parameters |
| string</font></code></li> |
| </ul> |
| <h3><a name="CmdList">list</a></h3> |
| <b><font color="#333399" face="Courier New" size="2"> C <i><token></i> |
| PortForward list </font></b> |
| <p>The command list available Port Forward configurations<br> |
| </p> |
| <p>Reply:</p> |
| <pre><b><font><b><font color="#333399" face="Courier New" size="2"> |
| <i><array of Port Forward</i></font></b></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i> </i></font></b></font></b></i></font></b></font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i>IDs></i> |
| ⇒ null |
| ⇒ [ ] |
| ⇒ [ <i><Port Forwards ID list></i> ] |
| |
| <i><</i></font></b></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i>Port Forwards </i></font></b></font></b></i></font></b></font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i>ID list></i> |
| ⇒ <i><string: </i></font></b></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i>Port Forward ID</i></font></b></font></b></i></font></b></font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i>></i> |
| ⇒ </font></b></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i>Port Forward ID</i></font></b></font></b></i></font></b></font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i> list></i> , <i><string: </i></font></b></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i>Port Forward</i></font></b></font></b></i></font></b></font></b> </i></font></b></font></b></i></font></b></font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i>ID></i></font></b></font></b><b><font color="#333399" face="Courier New" size="2"> |
| </font></b></pre> |
| <h3><a name="CmdCreate">create</a></h3> |
| <pre><b><font color="#333399" face="Courier New" size="2"> |
| C <i><token></i> PortForward create</font></b><b><font color="#333399" face="Courier New" size="2"> </font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i><Port Forward configuration></i> </font></b></font></b><b><font color="#333399" face="Courier New" size="2"><br></font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i><br><</i></font></b></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i><b><font><b><font color="#333399" face="Courier New" size="2"><i>Port Forward</i></font></b></font></b> configuration</i></font></b></font></b></i></font></b></font></b><b><font><b><font color="#333399" face="Courier New" size="2"><i>></i> |
| ⇒ <i><object></i></font></b></font></b><b><font color="#333399" face="Courier New" size="2"> <br></font></b></pre> |
| <p>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 <br> |
| </p> |
| <p>Predefined properties are:</p> |
| <ul> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"ID" |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| : <i><string></i></font></b><font color="#333399" face="Courier New" size="2"> - Port Forward ID (this parameter is mandatory)</font></code> </li> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"Port" |
| : <i><string></i></font></b><font color="#333399" face="Courier New" size="2"> - device port to access. This configuration is device specified and described below</font></code><code><font color="#333399" face="Courier New" size="2"> (this parameter is mandatory)</font></code> </li> |
| <li><code><b><font color="#333399" face="Courier New" size="2">"Verbose" |
| : <i><boolean> </i></font></b><font color="#333399" face="Courier New" size="2">- Indicate if Port Forward server must display message in the console when port is accessed (opened, closed...). Default to false.</font></code> </li><li><code><b><font color="#333399" face="Courier New" size="2">"ClientData" |
| |
| |
| : <i><string></i></font></b><font color="#333399" face="Courier New" size="2"> - 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.<br></font></code></li><li><font color="#333399" face="Courier New" size="2"><code><code><b><font color="#333399" face="Courier New" size="2">"Params" |
| : <i><string></i></font></b><font color="#333399" face="Courier New" size="2"> - Port configuration parameters (used only for serial line).<br></font></code></code></font></li></ul><br>The following syntax is supported for the port forward "<font color="#333399"><b>Config</b></font>" string:<br><ul><li><font color="#333399"><b>"tcp:<host name or IP>:<port number>"</b> - <code>Establish a connection to TCP port </code><code><port number> on host <host name or IP>. If <host name or IP> is not specified, then </code><code>loop back</code><code> address will be used. <port number> is mandatory.</code></font> <br></li><li><font color="#333399"><b>"udp:<host name or IP>:<port number>"</b> - <code>Establish a connection to UDP port </code><code><port number> on host <host name or IP>. If <host name or IP> is not specified, then </code><code>loop back</code><code> address will be used. <port number> is mandatory.</code></font></li><li><font color="#333399"><b>"serial:<serial device>"</b> - <code>Establish a connect to specified serial device (e.g. COM1, /dev/ttyS0).</code></font></li></ul><br>The following syntax is supported for the port forward "<font color="#333399"><b>Params</b></font>" string when specified device is a serial line (unused in other cases):<br><br><b><font color="#333399">"<baud rate>:<data bits>:<parity>:<stop bits>:<flow control>"</font></b><br><ul><li><b><font color="#333399"><baud rate></font></b>: serial line baud rate (default to 115200 if not specified)</li><li><b><font color="#333399"><data bits></font></b>: number of data bits (default to 8 if not specified)</li><li><b><font color="#333399"><parity></font></b>: can be one of <b><font color="#333399">"O"</font></b> or <b><font color="#333399">"o"</font></b> for odd parity, <b><font color="#333399">"E"</font></b> or <b><font color="#333399">"e"</font></b> for even parity, <b><font color="#333399">"N"</font></b> or <b><font color="#333399">"n" </font></b>for no parity, <b><font color="#333399">"M"</font></b> or <b><font color="#333399">"m"</font></b> for mark parity, <b><font color="#333399">"S"</font></b> or <b><font color="#333399">"s"</font></b> for space parity. Default to no parity if not specified.</li><li><b><font color="#333399"><stop bits></font></b>: number of stop bits (default to 1 if not specified)</li><li><b><font color="#333399"><flow control></font></b>: can be one of <b><font color="#333399">"N"</font></b> or <b><font color="#333399">"n"</font></b> for no flow control, <b><font color="#333399">"S"</font></b> or <b><font color="#333399">"s"</font></b> for XON/XOFF, <b><font color="#333399">"R"</font></b> or <b><font color="#333399">"r" </font></b>for RTS/CTS, <b><font color="#333399">"D"</font></b> or <b><font color="#333399">"d"</font></b> for DTR/DSR. Default to no flow control if not specified.</li></ul> "<font color="#333399"><b>Params</b></font>" string can be of the form: <br><blockquote><code><b>"9600"</b> - Only specify baud rate, keep default for everything else<br></code><code><b>":7"</b> - Only specify number of data bits</code><code>, keep default for everything else<br></code><code><b>"::::S"</b> - Set flow control to XON/XOFF,</code><code> keep default for everything else<br></code><code><code><b>"9600:8:N:1:S"</b> - set barud rate to 9600, 8 data bits, no parity, 1 stop bit and space parity<br></code></code><br></blockquote><div align="left"><p>Reply:</p> |
| <b><font color="#333399" face="Courier New" size="2"> R <i><token></i> |
| <i><error report></i> </font></b><b><font color="#333399" face="Courier New" size="2"><i><</i></font></b><b><font><i><b><font color="#333399" face="Courier New" size="2"><i>port |
| properties</i></font></b></i></font></b><b><font color="#333399" face="Courier New" size="2"><i>></i></font></b><b><font color="#333399" face="Courier New" size="2"> </font></b><br><pre><b><font color="#333399" face="Courier New" size="2"><i><port properties></i> |
| ⇒ null |
| ⇒ <i><object><br></i></font></b></pre><p>Port properties are the same as returned by the <a href="#CmdGetConfig">getConfig</a> command. |
| </p></div><h3><a name="CmdDelete">delete</a></h3> |
| <pre><b><font color="#333399" face="Courier New" size="2"> |
| C <i><token></i> PortForward </font></b><b><font color="#333399" face="Courier New" size="2"> delete <i><string: PortForward</i></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i> </i></font></b></font></b></i></font></b></font></b><b><font color="#333399" face="Courier New" size="2"><i>ID></i> </font></b><b><font color="#333399" face="Courier New" size="2"><br><br></font></b></pre> |
| <p>The command deletes a previously created Port Foward connection.<b><font color="#333399" face="Courier New" size="2"><br> |
| </font></b></p> |
| <p> </p> |
| <p>Reply:</p> |
| <pre><b><font color="#333399" face="Courier New" size="2"> |
| R <i><token></i> <i><error report></i> <br><br></font></b></pre> |
| <h3><a name="cmdGetCapabilities"></a>getCapabilities</h3> |
| <pre><b><font color="#333399" face="Courier New" size="2"> |
| C <i><token></i> </font></b><b><font color="#333399" face="Courier New" size="2">PortForward </font></b><b><font color="#333399" face="Courier New" size="2"> getCapabilities <i><string: PortForward ID></i> |
| </font></b> |
| </pre> |
| <p>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.<br></p> |
| <p>Reply:</p> |
| <b><font color="#333399" face="Courier New" size="2"> R <i><token></i> |
| <i><error report></i> <i><service |
| capabilities></i> <i><br> |
| <br> |
| <service capabilities></i> <br> |
| ⇒ <i><object></i> </font></b> |
| <p>Service capabilities consist of a list of properties. All |
| properties are optional. Tools and targets can define additional |
| properties. Predefined properties are:</p> |
| <ul> |
| |
| <li><code><b><font color="#333399" face="Courier New" size="2">"TCP" |
| |
| |
| : <i><boolean></i></font></b></code> - if true, TCP Port Forward connections are supported</li><li><code><b><font color="#333399" face="Courier New" size="2">"UDP" |
| |
| |
| : <i><boolean></i></font></b></code> - if true, UDPPort Forward connections are supported</li><li><code><b><font color="#333399" face="Courier New" size="2">"Serial" |
| |
| |
| : <i><boolean></i></font></b></code> - if true, serial Port Forward connections are supported</li> |
| </ul><b><font color="#333399" face="Courier New" size="2"> |
| |
| </font></b> |
| <h2><a name="Events">Events</a></h2> |
| <p>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.</p> |
| <pre><b><font color="#333399" face="Courier New" size="2"> |
| E </font></b><b><font><b><font color="#333399" face="Courier New" size="2">PortForward </font></b></font></b><b><font color="#333399" face="Courier New" size="2"> configAdded <i><</i></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i>PortForward connection properties</i></font></b></font></b></i></font></b></font></b><b><font color="#333399" face="Courier New" size="2"><i>></i> <br></font></b><b><font color="#333399" face="Courier New" size="2">E </font></b><b><font><b><font color="#333399" face="Courier New" size="2">PortForward </font></b></font></b><b><font color="#333399" face="Courier New" size="2"> configRemoved <i><PortForward</i></font></b><b><font><b><font><i><b><font><b><font color="#333399" face="Courier New" size="2"><i> connection ID</i></font></b></font></b></i></font></b></font></b><b><font color="#333399" face="Courier New" size="2"><i>></i> </font></b><b><font color="#333399" face="Courier New" size="2"> |
| </font></b></pre> |
| <dl> |
| </dl><dl><dt><b>configAdded</b></dt><dd>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.</dd><dt><b>configRemoved</b></dt><dd>Is sent when a PortForward connection is removed.</dd> |
| </dl><br> |
| <dl> |
| </dl> |
| |
| |
| </body></html> |