Adding the ability to configure serial port output to the debug console (eclipse-cdt-cloud#271)

AdhamRagabMCHP · web-flow · commit e39e7bc4f44a · 2023-07-10T13:18:47.000-04:00
This commit introduces a set of parameters that allow us to configure a
serial line in the adapter to print UART output from on-board/emulation
debug to the debug console. These parameters include the TCP port to
hook onto (for emulation programs outputting UART output), or the serial
port on the host-machine to capture UART output from. For the serial
line, we also configure the baud rate, stop bits, handshaking method,
etc.

The source code looks to take this parameters to then configure serial
ports and sockets to read UART data and output it to the debug console.
It will also set up necessary event handlers, and changes the log level
in the non-verbose case to allow for "log" messages to be printed in a
manner such that UART output isn't designated as a "warning".
diff --git a/.github/workflows/build-pr.yml b/.github/workflows/build-pr.yml
@@ -14,7 +14,7 @@ jobs:
           node-version: '14'
       - name: Install GCC & GDB & other build essentials
         run: |
-          sudo apt-get -y install build-essential gcc g++ gdb gdbserver
+          sudo apt-get -y install build-essential gcc g++ gdb gdbserver socat
           gdb --version
           gcc --version
           gdbserver --version
diff --git a/.github/workflows/build-push.yml b/.github/workflows/build-push.yml
@@ -15,7 +15,7 @@ jobs:
           node-version: '14'
       - name: Install GCC & GDB & other build essentials
         run: |
-          sudo apt-get -y install build-essential gcc g++ gdb gdbserver
+          sudo apt-get -y install build-essential gcc g++ gdb gdbserver socat
           gdb --version
           gcc --version
           gdbserver --version
diff --git a/package.json b/package.json
@@ -60,14 +60,16 @@
   "dependencies": {
     "@vscode/debugadapter": "^1.59.0",
     "@vscode/debugprotocol": "^1.59.0",
-    "node-addon-api": "^4.3.0"
+    "node-addon-api": "^4.3.0",
+    "serialport": "11.0.0"
   },
   "devDependencies": {
     "@types/chai": "^4.3.4",
     "@types/chai-string": "^1.4.2",
     "@types/mocha": "^9.1.0",
     "@types/node": "^14.18.17",
     "@types/tmp": "^0.2.3",
+    "@types/serialport": "8.0.2",
     "@typescript-eslint/eslint-plugin": "^5.54.0",
     "@typescript-eslint/parser": "^5.54.0",
     "@vscode/debugadapter-testsupport": "^1.59.0",
diff --git a/src/GDBTargetDebugSession.ts b/src/GDBTargetDebugSession.ts
@@ -18,6 +18,27 @@ import {
 import * as mi from './mi';
 import { DebugProtocol } from '@vscode/debugprotocol';
 import { spawn, ChildProcess } from 'child_process';
+import { SerialPort, ReadlineParser } from 'serialport';
+import { Socket } from 'net';
+
+interface UARTArguments {
+    // Path to the serial port connected to the UART on the board.
+    serialPort?: string;
+    // Target TCP port on the host machine to attach socket to print UART output (defaults to 3456)
+    socketPort?: string;
+    // Baud Rate (in bits/s) of the serial port to be opened (defaults to 115200).
+    baudRate?: number;
+    // The number of bits in each character of data sent across the serial line (defaults to 8).
+    characterSize?: 5 | 6 | 7 | 8;
+    // The type of parity check enabled with the transmitted data (defaults to "none" - no parity bit sent)
+    parity?: 'none' | 'even' | 'odd' | 'mark' | 'space';
+    // The number of stop bits sent to allow the receiver to detect the end of characters and resynchronize with the character stream (defaults to 1).
+    stopBits?: 1 | 1.5 | 2;
+    // The handshaking method used for flow control across the serial line (defaults to "none" - no handshaking)
+    handshakingMethod?: 'none' | 'XON/XOFF' | 'RTS/CTS';
+    // The EOL character used to parse the UART output line-by-line.
+    eolCharacter?: 'LF' | 'CRLF';
+}
 
 export interface TargetAttachArguments {
     // Target type default is "remote"
@@ -31,6 +52,8 @@ export interface TargetAttachArguments {
     port?: string;
     // Target connect commands - if specified used in preference of type, parameters, host, target
     connectCommands?: string[];
+    // Settings related to displaying UART output in the debug console
+    uart?: UARTArguments;
 }
 
 export interface TargetLaunchArguments extends TargetAttachArguments {
@@ -80,6 +103,11 @@ export class GDBTargetDebugSession extends GDBDebugSession {
     protected gdbserver?: ChildProcess;
     protected killGdbServer = true;
 
+    // Serial Port to capture UART output across the serial line
+    protected serialPort?: SerialPort;
+    // Socket to listen on a TCP port to capture UART output
+    protected socket?: Socket;
+
     /**
      * Define the target type here such that we can run the "disconnect"
      * command when servicing the disconnect request if the target type
@@ -271,6 +299,99 @@ export class GDBTargetDebugSession extends GDBDebugSession {
         });
     }
 
+    protected initializeUARTConnection(
+        uart: UARTArguments,
+        host: string | undefined
+    ): void {
+        if (uart.serialPort !== undefined) {
+            // Set the path to the serial port
+            this.serialPort = new SerialPort({
+                path: uart.serialPort,
+                // If the serial port path is defined, then so will the baud rate.
+                baudRate: uart.baudRate ?? 115200,
+                // If the serial port path is deifned, then so will the number of data bits.
+                dataBits: uart.characterSize ?? 8,
+                // If the serial port path is defined, then so will the number of stop bits.
+                stopBits: uart.stopBits ?? 1,
+                // If the serial port path is defined, then so will the parity check type.
+                parity: uart.parity ?? 'none',
+                // If the serial port path is defined, then so will the type of handshaking method.
+                rtscts: uart.handshakingMethod === 'RTS/CTS' ? true : false,
+                xon: uart.handshakingMethod === 'XON/XOFF' ? true : false,
+                xoff: uart.handshakingMethod === 'XON/XOFF' ? true : false,
+                autoOpen: false,
+            });
+
+            this.serialPort.on('open', () => {
+                this.sendEvent(
+                    new OutputEvent(
+                        `listening on serial port ${this.serialPort?.path}`,
+                        'Serial Port'
+                    )
+                );
+            });
+
+            const SerialUartParser = new ReadlineParser({
+                delimiter: uart.eolCharacter === 'LF' ? '\n' : '\r\n',
+                encoding: 'utf8',
+            });
+
+            this.serialPort
+                .pipe(SerialUartParser)
+                .on('data', (line: string) => {
+                    this.sendEvent(new OutputEvent(line, 'Serial Port'));
+                });
+
+            this.serialPort.on('close', () => {
+                this.sendEvent(
+                    new OutputEvent(
+                        'closing serial port connection',
+                        'Serial Port'
+                    )
+                );
+            });
+
+            this.serialPort.open();
+        } else if (uart.socketPort !== undefined) {
+            this.socket = new Socket();
+            this.socket.setEncoding('utf-8');
+
+            const eolChar: string = uart.eolCharacter === 'LF' ? '\n' : '\r\n';
+
+            let tcpUartData = '';
+            this.socket.on('data', (data: string) => {
+                for (const char of data) {
+                    if (char === eolChar) {
+                        this.sendEvent(new OutputEvent(tcpUartData, 'Socket'));
+                        tcpUartData = '';
+                    } else {
+                        tcpUartData += char;
+                    }
+                }
+            });
+            this.socket.on('close', () => {
+                this.sendEvent(new OutputEvent(tcpUartData, 'Socket'));
+                this.sendEvent(
+                    new OutputEvent('closing socket connection', 'Socket')
+                );
+            });
+            this.socket.connect(
+                // Putting a + (unary plus operator) infront of the string converts it to a number.
+                +uart.socketPort,
+                // Default to localhost if target.host is undefined.
+                host ?? 'localhost',
+                () => {
+                    this.sendEvent(
+                        new OutputEvent(
+                            `listening on tcp port ${uart?.socketPort}`,
+                            'Socket'
+                        )
+                    );
+                }
+            );
+        }
+    }
+
     protected async startGDBAndAttachToTarget(
         response: DebugProtocol.AttachResponse | DebugProtocol.LaunchResponse,
         args: TargetAttachRequestArguments
@@ -338,6 +459,10 @@ export class GDBTargetDebugSession extends GDBDebugSession {
 
             await this.gdb.sendCommands(args.initCommands);
 
+            if (target.uart !== undefined) {
+                this.initializeUARTConnection(target.uart, target.host);
+            }
+
             if (args.imageAndSymbols) {
                 if (args.imageAndSymbols.imageFileName) {
                     await this.gdb.sendLoad(
@@ -380,9 +505,13 @@ export class GDBTargetDebugSession extends GDBDebugSession {
         _args: DebugProtocol.DisconnectArguments
     ): Promise<void> {
         try {
+            if (this.serialPort !== undefined && this.serialPort.isOpen)
+                this.serialPort.close();
+
             if (this.targetType === 'remote') {
                 await this.gdb.sendCommand('disconnect');
             }
+
             await this.gdb.sendGDBExit();
             if (this.killGdbServer) {
                 await this.stopGDBServer();
diff --git a/src/integration-tests/debugClient.ts b/src/integration-tests/debugClient.ts
@@ -371,6 +371,23 @@ export class CdtDebugClient extends DebugClient {
         });
         return evalResponse.body.result;
     }
+
+    /**
+     * Obtain the output coming from the debug console..
+     * @param category catgory of output event coming on debug console.
+     * @param output expected output coming on debug console
+     */
+    public async getDebugConsoleOutput(
+        launchArgs: any,
+        category: string,
+        output: string
+    ): Promise<any> {
+        return Promise.all([
+            this.waitForEvent('initialized'),
+            this.launch(launchArgs),
+            this.waitForOutputEvent(category, output),
+        ]);
+    }
 }
 
 /**
diff --git a/src/integration-tests/launchRemote.spec.ts b/src/integration-tests/launchRemote.spec.ts
@@ -8,13 +8,16 @@
  * SPDX-License-Identifier: EPL-2.0
  *********************************************************************/
 
+import * as cp from 'child_process';
 import * as path from 'path';
 import {
     TargetLaunchRequestArguments,
     TargetLaunchArguments,
 } from '../GDBTargetDebugSession';
 import { CdtDebugClient } from './debugClient';
 import { fillDefaults, standardBeforeEach, testProgramsDir } from './utils';
+import { expect } from 'chai';
+import * as os from 'os';
 
 describe('launch remote', function () {
     let dc: CdtDebugClient;
@@ -43,4 +46,77 @@ describe('launch remote', function () {
             }
         );
     });
+
+    it('can print a message to the debug console sent from a socket server', async function () {
+        const socketServer = cp.spawn(
+            'node',
+            [`${path.join(testProgramsDir, 'socketServer.js')}`],
+            {
+                cwd: testProgramsDir,
+            }
+        );
+        // Ensure that the socket port is defined prior to the test.
+        let socketPort = '';
+        socketServer.stdout.on('data', (data) => {
+            socketPort = data.toString();
+            socketPort = socketPort.substring(0, socketPort.indexOf('\n'));
+        });
+
+        // Sleep for 1 second before running test to ensure socketPort is defined.
+        await new Promise((f) => setTimeout(f, 1000));
+        expect(socketPort).not.eq('');
+
+        await dc.getDebugConsoleOutput(
+            fillDefaults(this.test, {
+                program: emptyProgram,
+                openGdbConsole: false,
+                initCommands: ['break _fini'],
+                target: {
+                    uart: {
+                        socketPort: socketPort,
+                        eolCharacter: 'LF',
+                    },
+                } as TargetLaunchArguments,
+            } as TargetLaunchRequestArguments),
+            'Socket',
+            'Hello World!'
+        );
+
+        // Kill the spawned process.
+        socketServer.kill();
+    });
+
+    it('can print a message to the debug console sent from across a serial line', async function () {
+        // Skip this test on Windows - socat utility only available on Linux.
+        if (os.platform() === 'win32') this.skip();
+
+        // Start a virtual serial line. Use /tmp/ttyV0 and /tmp/ttyV1 to refer to the two ends.
+        const virtualSerialLine = cp.spawn('socat', [
+            '-d',
+            '-d',
+            'pty,rawer,echo=0,link=/tmp/ttyV0',
+            'pty,rawer,echo=0,link=/tmp/ttyV1',
+        ]);
+
+        await dc.getDebugConsoleOutput(
+            fillDefaults(this.test, {
+                program: emptyProgram,
+                openGdbConsole: false,
+                initCommands: ['break _fini'],
+                preRunCommands: [`shell echo "Hello World!" > /tmp/ttyV1`],
+                target: {
+                    uart: {
+                        serialPort: '/tmp/ttyV0',
+                        eolCharacter: 'LF',
+                        baudRate: 38400,
+                    },
+                } as TargetLaunchArguments,
+            } as TargetLaunchRequestArguments),
+            'Serial Port',
+            'Hello World!'
+        );
+
+        // Kill the spawned process.
+        virtualSerialLine.kill();
+    });
 });
diff --git a/src/integration-tests/test-programs/socketServer.js b/src/integration-tests/test-programs/socketServer.js
@@ -0,0 +1,33 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const net = require('net');
+
+// Create socket echo server.
+const socketServer = new net.Server();
+
+socketServer.on('connection', (connection) => {
+    console.log('adapter connected');
+
+    connection.on('end', () => {
+        console.log('adapter disconected');
+    });
+
+    // Echo "Hello World!"
+    connection.write('Hello World!\n');
+});
+
+socketServer.on('close', () => {
+    console.log('shutting down');
+});
+
+socketServer.on('error', (error) => {
+    throw error;
+});
+
+function serverListen() {
+    socketServer.listen(0, 'localhost', 1, () => {
+        const port = socketServer.address().port;
+        console.log(`${port}`);
+    });
+}
+
+serverListen();
diff --git a/tsconfig.json b/tsconfig.json
@@ -19,5 +19,8 @@
       }
     ]
   },
-  "include": ["src/**/*.ts"]
+  "include": [
+    "src/**/*.ts",
+    "src/integration-tests/test-programs/socketServer.js"
+  ]
 }
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -19,5 +19,8 @@`
`19`	`19`	`}`
`20`	`20`	`]`
`21`	`21`	`},`
`22`		`- "include": ["src/*/.ts"]`
	`22`	`+ "include": [`
	`23`	`+ "src/*/.ts",`
	`24`	`+ "src/integration-tests/test-programs/socketServer.js"`
	`25`	`+ ]`
`23`	`26`	`}`