Parse interrupt tables and expose through extension API (#77)

* Extension API: get interrupt table (types and docs)
* Extends parser and API implementation
* Normalize paths through URI conversion, move pathToUri to central location
* Test command: Requires the following in settings.json of workspace
"peripheral-inspector.testCommandsEnabled": true

Author: jreineckearm

docs/extending-peripheral-inspector.md

@@ -21,7 +21,8 @@ yarn add github:eclipse-cdt-cloud/vscode-peripheral-inspector
 
 ### Developing your extension
 
-To provide the peripherals information to Peripheral Inspector on debug session time, you need register your command which is going to construct the peripherals information. The command will receive `DebugSession` object as an input parameter and expects to return array of type `PeripheralOptions[]`.
+To provide the peripherals information to Peripheral Inspector on debug session time, you need register your command which is going to construct the peripherals information.
+The command will receive `DebugSession` object as an input parameter and expects to return array of type `PeripheralOptions[]`.
 
 You can find the example command implementation below:
 
@@ -41,11 +42,11 @@ class MyExtensionProvider implements api.IPeripheralsProvider {
 export async function activate(context: ExtensionContext) {
     ...
     // Get the eclipse-cdt.peripheral-inspector extension
-    const peripheralInspectorExtention = extensions.getExtension<api.IPeripheralInspectorAPI>('eclipse-cdt.peripheral-inspector');
+    const peripheralInspectorExtension = extensions.getExtension<api.IPeripheralInspectorAPI>('eclipse-cdt.peripheral-inspector');
 
     // Check if the eclipse-cdt.peripheral-inspector extension is installed
-    if (peripheralInspectorExtention) {
-        const peripheralInspectorAPI = await peripheralInspectorExtention.activate();
+    if (peripheralInspectorExtension) {
+        const peripheralInspectorAPI = await peripheralInspectorExtension.activate();
 
         // Invoke registerPeripheralsProvider method in eclipse-cdt.peripheral-inspector extension api
         // Register 'MyExtensionProvider' for files *.myext
@@ -55,6 +56,10 @@ export async function activate(context: ExtensionContext) {
 }
 ```
 
+Alternatively, you also use the extension API to extract information from parsed SVD files:
+- See the implementation of the [Print Interrupt Table (Extension API)](../src/test-commands/print-api-interrupt-table.ts) test command for an example how to get the
+interrupt table for an SVD.
+
 For further information about the api definitions, review the [Peripheral Inspector API Definitions](../src/api-types.ts).
 
 ### Modifying your package.json

package.json

@@ -162,6 +162,12 @@
         "command": "peripheral-inspector.svd.periodicRefreshInterval",
         "title": "Set Periodic Refresh Interval",
         "icon": "$(calendar)"
+      },
+      {
+        "command": "peripheral-inspector.printInterruptTable",
+        "title": "Print Interrupt Table (Extension API)",
+        "category": "Peripherals",
+        "enablement": "inDebugMode && config.peripheral-inspector.testCommandsEnabled"
       }
     ],
     "menus": {
@@ -213,6 +219,10 @@
         {
           "command": "peripheral-inspector.svd.clearIgnoredPeripherals",
           "when": "false"
+        },
+        {
+          "command": "peripheral-inspector.printInterruptTable",
+          "when": "inDebugMode && config.peripheral-inspector.testCommandsEnabled"
         }
       ],
       "touchBar": [

src/api-types.ts

@@ -4,6 +4,14 @@ export interface IPeripheralInspectorAPI {
     getSVDFile: (device: string) => string | undefined;
     getSVDFileFromCortexDebug: (device: string) => Promise<string | undefined>;
     registerPeripheralsProvider: (fileExtension: string, provider: IPeripheralsProvider) => void;
+    /**
+     * Get interrupt table for provided SVD file path.
+     * IMPORTANT: The input path must be absolute and normalized on desktop.
+     *
+     * @param svdPath The SVD file path.
+     * @returns The interrupt table for the SVD file, or undefined if the file was not loaded.
+     */
+    getInterruptTable?: (svdPath: string) => InterruptTable | undefined;
 }
 
 export interface IPeripheralsProvider {
@@ -25,6 +33,7 @@ export interface PeripheralOptions {
     resetValue?: number;
     registers?: PeripheralRegisterOptions[];
     clusters?: ClusterOptions[];
+    interrupt?: InterruptEntry[];
 }
 
 export interface PeripheralRegisterOptions {
@@ -49,6 +58,12 @@ export interface ClusterOptions {
     clusters?: ClusterOptions[];
 }
 
+export interface InterruptEntry {
+    name: string;
+    description?: string;
+    value: number;
+}
+
 export interface FieldOptions {
     name: string;
     description: string;
@@ -60,14 +75,6 @@ export interface FieldOptions {
     readAction?: ReadActionType;
 }
 
-export interface IGetPeripheralsArguments {
-    gapThreshold: number;
-}
-
-export interface IPeripheralsProvider {
-    getPeripherals: (data: string, options: IGetPeripheralsArguments) => Promise<PeripheralOptions[]>;
-}
-
 export interface PeripheralsConfiguration {
     gapThreshold: number;
     peripheralOptions: Record<string, PeripheralOptions>;
@@ -97,3 +104,16 @@ export interface IEnumeratedValue {
     description: string;
     value: number;
 }
+
+/**
+ * Interrupt table structure to represent the interrupts defined in the SVD file's
+ * <peripheral> elements.
+ */
+export interface InterruptTable {
+    /**
+     * Mapping of interrupt numbers to their corresponding interrupt information.
+     * The keys are the interrupt numbers, and the values are objects containing
+     * the name, value, and optional description of each interrupt.
+     */
+    interrupts: Record<number, InterruptEntry>;
+}

src/entry-points/desktop/extension.ts

@@ -15,6 +15,8 @@ import { SvdResolver } from '../../svd-resolver';
 import { PeripheralConfigurationProvider } from '../../model/peripheral/tree/peripheral-configuration-provider';
 import { PeripheralTreeDataProvider } from '../../views/peripheral/peripheral-data-provider';
 import { PeripheralsTreeTableWebView } from '../../views/peripheral/peripheral-view-provider';
+import { CONFIG_ENABLE_TEST_COMMANDS } from '../../manifest';
+import { PrintApiInterruptTable } from '../../test-commands/print-api-interrupt-table';
 export * as api from '../../api-types';
 
 export const activate = async (context: vscode.ExtensionContext): Promise<IPeripheralInspectorAPI> => {
@@ -33,6 +35,12 @@ export const activate = async (context: vscode.ExtensionContext): Promise<IPerip
     await dataProvider.activate(webView);
     await webView.activate(context);
 
+    const enableTestCommands = vscode.workspace.getConfiguration().get<boolean>(CONFIG_ENABLE_TEST_COMMANDS, false);
+    if (enableTestCommands) {
+        const printApiInterruptTable = new PrintApiInterruptTable();
+        await printApiInterruptTable.activate(context);
+    }
+
     return api;
 };
 

src/fileUtils.ts

@@ -14,3 +14,11 @@ export async function getFilePath(): Promise<vscode.Uri | undefined> {
     });
     return fileUri;
 }
+
+export const pathToUri = (path: string): vscode.Uri => {
+    try {
+        return vscode.Uri.file(path);
+    } catch {
+        return vscode.Uri.parse(path);
+    }
+};

src/manifest.ts

@@ -7,6 +7,7 @@
 
 import { CommandDefinition } from '@eclipse-cdt-cloud/vscode-ui-components/lib/vscode/webview-types';
 
+export const PUBLISHER_NAME = 'eclipse-cdt';
 export const PACKAGE_NAME = 'peripheral-inspector';
 export const CONFIG_SVD_PATH = 'definitionPathConfig';
 export const DEFAULT_SVD_PATH = 'definitionPath';
@@ -32,6 +33,9 @@ export const DEFAULT_PERIODIC_REFRESH_MODE: PeriodicRefreshMode = 'always';
 export const CONFIG_PERIODIC_REFRESH_INTERVAL = 'periodicRefreshInterval';
 export const DEFAULT_PERIODIC_REFRESH_INTERVAL = 500;
 
+// Hidden configs, not exposed to users via package.json
+export const CONFIG_ENABLE_TEST_COMMANDS = `${PACKAGE_NAME}.testCommandsEnabled`;
+
 // Commands
 export namespace Commands {
     // Commands used only within VSCode

src/model/peripheral/tree/peripheral-session-tree.ts

@@ -7,30 +7,24 @@
 
 import * as vscode from 'vscode';
 import { AddrRange } from '../../../addrranges';
-import { IPeripheralsProvider, PeripheralOptions, PeripheralsConfiguration } from '../../../api-types';
+import { InterruptTable, IPeripheralsProvider, PeripheralOptions, PeripheralsConfiguration } from '../../../api-types';
 import { NodeSetting, PERIPHERAL_ID_SEP, PeripheralNodeSort, PeripheralSessionNodeDTO } from '../../../common';
 import * as manifest from '../../../manifest';
 import { PeripheralInspectorAPI } from '../../../peripheral-inspector-api';
 import { SVDParser } from '../../../svd-parser';
 import { readFromUrl } from '../../../utils';
+import { pathToUri } from '../../../fileUtils';
 import { MessageNode, PeripheralBaseNode, PeripheralNode, UpdateDataContext } from '../nodes';
 import { PeripheralConfigurationProvider } from './peripheral-configuration-provider';
 import { DebugSessionStatus } from '../../../debug-tracker';
 import { clearTimeout, setTimeout } from 'timers';
 
-const pathToUri = (path: string): vscode.Uri => {
-    try {
-        return vscode.Uri.file(path);
-    } catch {
-        return vscode.Uri.parse(path);
-    }
-};
-
 interface CachedSVDFile {
     svdUri: vscode.Uri;
     mtime: number;
     peripherals: PeripheralNode[],
     configuration: PeripheralsConfiguration;
+    interruptTable?: InterruptTable;
 }
 
 export class PeripheralTreeForSession extends PeripheralBaseNode {
@@ -40,6 +34,7 @@ export class PeripheralTreeForSession extends PeripheralBaseNode {
 
     private peripherals: PeripheralNode[] = [];
     private peripheralsConfiguration?: PeripheralsConfiguration;
+    private interruptTable?: InterruptTable;
 
     private loaded = false;
     private errMessage = 'No SVD file loaded';
@@ -97,21 +92,28 @@ export class PeripheralTreeForSession extends PeripheralBaseNode {
         return state;
     }
 
-    private static async addToCache(uri: vscode.Uri, peripherals: PeripheralNode[], configuration: PeripheralsConfiguration) {
+    private static async addToCache(
+        uri: vscode.Uri,
+        peripherals: PeripheralNode[],
+        configuration: PeripheralsConfiguration,
+        interruptTable?: InterruptTable
+    ): Promise<CachedSVDFile | undefined> {
         try {
             const stat = await vscode.workspace.fs.stat(uri);
             if (stat && stat.mtime) {
                 const tmp: CachedSVDFile = {
                     svdUri: uri,
                     mtime: stat.mtime,
                     peripherals,
-                    configuration
+                    configuration,
+                    interruptTable
                 };
                 PeripheralTreeForSession.svdCache[uri.toString()] = tmp;
+                return tmp;
             }
         } catch {
             delete PeripheralTreeForSession.svdCache[uri.toString()];
-            return;
+            return undefined;
         }
     }
 
@@ -135,6 +137,7 @@ export class PeripheralTreeForSession extends PeripheralBaseNode {
         this.errMessage = `Loading ${svdPath} ...`;
         let parsedConfiguration: PeripheralsConfiguration | undefined;
         let parsedPeripherals: PeripheralNode[] | undefined;
+        const parsedInterruptTable: InterruptTable = { interrupts: {} };
 
         const ignoredPeripherals = this.config.ignorePeripherals();
 
@@ -146,6 +149,9 @@ export class PeripheralTreeForSession extends PeripheralBaseNode {
             } else {
                 this.svdUri = pathToUri(svdPath);
                 const cached = await PeripheralTreeForSession.getFromCache(this.svdUri);
+                if (!cached) {
+                    this.api.updateLoadedSVDInfo(this.svdUri, undefined);
+                }
                 if (cached && manifest.IgnorePeripherals.isEqual(cached.configuration.ignoredPeripherals, ignoredPeripherals)) {
                     this.peripherals = cached.peripherals;
                     this.peripheralsConfiguration = cached.configuration;
@@ -174,6 +180,13 @@ export class PeripheralTreeForSession extends PeripheralBaseNode {
                 parsedConfiguration = await this.parseWithSVDParser(data, gapThreshold, ignoredPeripherals);
             }
 
+            // Ignored peripherals not applied yet, collect interrupt information before filtering out peripherals
+            Object.values(parsedConfiguration.peripheralOptions).forEach((options) => {
+                options.interrupt?.forEach((interrupt) => {
+                    parsedInterruptTable.interrupts[interrupt.value] = { name: interrupt.name, value: interrupt.value, description: interrupt.description };
+                });
+            });
+
             const poptions = Array.from(Object.values(parsedConfiguration.peripheralOptions)).filter(p => !manifest.IgnorePeripherals.includes(ignoredPeripherals, p.name));
             parsedPeripherals = poptions.map((options) => new PeripheralNode(gapThreshold, options, this));
             parsedPeripherals.sort(PeripheralNodeSort.compare);
@@ -195,15 +208,18 @@ export class PeripheralTreeForSession extends PeripheralBaseNode {
         try {
             this.peripherals = parsedPeripherals;
             this.peripheralsConfiguration = parsedConfiguration;
+            this.interruptTable = parsedInterruptTable;
 
             this.loaded = true;
             await this.setSession(this.session);
             if (this.svdUri) {
-                await PeripheralTreeForSession.addToCache(this.svdUri, this.peripherals, this.peripheralsConfiguration);
+                const cachedSvd = await PeripheralTreeForSession.addToCache(this.svdUri, this.peripherals, this.peripheralsConfiguration, this.interruptTable);
+                this.api.updateLoadedSVDInfo(this.svdUri, cachedSvd ? { interruptTable: cachedSvd.interruptTable } : undefined);
             }
         } catch (e) {
             this.peripherals = [];
             this.peripheralsConfiguration = undefined;
+            this.interruptTable = undefined;
             this.loaded = false;
             throw e;
         }
@@ -264,7 +280,8 @@ export class PeripheralTreeForSession extends PeripheralBaseNode {
         this.refresh();
 
         if (this.svdUri) {
-            await PeripheralTreeForSession.addToCache(this.svdUri, this.peripherals, this.peripheralsConfiguration);
+            const cachedSvd = await PeripheralTreeForSession.addToCache(this.svdUri, this.peripherals, this.peripheralsConfiguration, this.interruptTable);
+            this.api.updateLoadedSVDInfo(this.svdUri, cachedSvd ? { interruptTable: cachedSvd.interruptTable } : undefined);
         }
     }
 

src/peripheral-inspector-api.ts

@@ -6,7 +6,12 @@
  ********************************************************************************/
 
 import * as vscode from 'vscode';
-import { IPeripheralsProvider, IPeripheralInspectorAPI } from './api-types';
+import {
+    IPeripheralsProvider,
+    IPeripheralInspectorAPI,
+    InterruptTable
+} from './api-types';
+import { pathToUri } from './fileUtils';
 
 const CORTEX_EXTENSION = 'marus25.cortex-debug';
 
@@ -15,9 +20,16 @@ interface SVDInfo {
     path: string;
 }
 
+interface LoadedSVDInfo {
+    interruptTable?: InterruptTable;
+}
+
 export class PeripheralInspectorAPI implements IPeripheralInspectorAPI {
     private SVDDirectory: SVDInfo[] = [];
     private PeripheralProviders: Record<string, IPeripheralsProvider> = {};
+    private LoadedSVDInfos: Record<string, LoadedSVDInfo> = {};
+
+    /** IPeripheralInspectorAPI implementation */
 
     public registerSVDFile(expression: RegExp | string, path: string): void {
         if (typeof expression === 'string') {
@@ -58,8 +70,26 @@ export class PeripheralInspectorAPI implements IPeripheralInspectorAPI {
         this.PeripheralProviders[fileExtension] = provider;
     }
 
+    public getInterruptTable(svdPath: string): InterruptTable | undefined {
+        const normalizedPath = pathToUri(svdPath).toString();
+        return this.LoadedSVDInfos[normalizedPath]?.interruptTable;
+    }
+
+    /** Locally used methods */
+
     public getPeripheralsProvider(svdPath: string): IPeripheralsProvider | undefined {
         const ext = Object.keys(this.PeripheralProviders).filter((extension) => svdPath.endsWith(`.${extension}`))[0];
         return ext ? this.PeripheralProviders[ext] : undefined;
     }
+
+    public updateLoadedSVDInfo(svdPath: string | vscode.Uri, svdInfo?: LoadedSVDInfo): void {
+        // Normalize path by converting to URI and back to string.
+        const svdUri = typeof svdPath === 'string' ? pathToUri(svdPath) : svdPath;
+        const svdUriString = svdUri.toString();
+        if (svdInfo) {
+            this.LoadedSVDInfos[svdUriString] = svdInfo;
+        } else {
+            delete this.LoadedSVDInfos[svdUriString];
+        }
+    }
 }