diff --git a/README.md b/README.md index 107a8ba..2623803 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,20 @@ Once you have the SVD file, specify the location of it in your `launch.json` usi } ``` +### Extending SVD Viewer + +It is possible to extend the SVD Viewer and register new file extension providers with your VSCode extension. This method will provide reading non-svd formats and load the peripherals information in SVD Viewer. + +```json +{ + ... + "svdPath": "${workspaceFolder}/STM32F103.customFileExtension" + ... +} +``` + +For more details about the implementation, please check the [Extending SVD Viewer](./docs/extending-svd-viewer.md) document. + ## Settings All variable key names used to extract data from debug launch configurations can be modified. This allows variable name clashes to be avoided as well as the need to duplicate configuration entries. diff --git a/docs/appendix-types.md b/docs/appendix-types.md new file mode 100644 index 0000000..870d652 --- /dev/null +++ b/docs/appendix-types.md @@ -0,0 +1,91 @@ +# Appendix: Types of `svd-viewer` + +Types could be imported from `svd-viewer` like the code below: + +```js +import { + AccessType, + PeripheralOptions, + PeripheralRegisterOptions, + ClusterOptions, + FieldOptions +} from "svd-viewer"; +``` + +## Enum: AccessType + +AccessType enum defines the type of the access to the related peripheral item. + +```js +enum AccessType { + ReadOnly = 1, + ReadWrite, + WriteOnly +} +``` + +## Interface: PeripheralOptions + +The definition of the PeripheralOptions interface is shown below: + +```js +interface PeripheralOptions { + name: string; + baseAddress: number; + totalLength: number; + description: string; + groupName?: string; + accessType?: AccessType; + size?: number; + resetValue?: number; + registers?: PeripheralRegisterOptions[]; + clusters?: ClusterOptions[]; +} +``` +## Interface: PeripheralRegisterOptions + +The definition of the PeripheralRegisterOptions interface is shown below: + +```js +interface PeripheralRegisterOptions { + name: string; + description?: string; + addressOffset: number; + accessType?: AccessType; + size?: number; + resetValue?: number; + fields?: FieldOptions[]; +} +``` + +## Interface: ClusterOptions Interface + +The definition of the ClusterOptions interface is shown below: + +```js +interface ClusterOptions { + name: string; + description?: string; + addressOffset: number; + accessType?: AccessType; + size?: number; + resetValue?: number; + registers?: PeripheralRegisterOptions[]; + clusters?: ClusterOptions[]; +} +``` + +## Interface: FieldOptions Interface + +The definition of the FieldOptions interface is shown below: + +```js +interface FieldOptions { + name: string; + description: string; + offset: number; + width: number; + enumeration?: EnumerationMap; + accessType?: AccessType; +} +``` diff --git a/docs/extending-svd-viewer.md b/docs/extending-svd-viewer.md new file mode 100644 index 0000000..6715733 --- /dev/null +++ b/docs/extending-svd-viewer.md @@ -0,0 +1,77 @@ +# Extending SVD Viewer + +It is possible to extend the SVD Viewer and register new file extension providers with your VSCode extension. This method will provide reading non-svd formats and load the peripherals information in SVD Viewer. + +## Building your VSCode Extension to extend SVD Viewer + +This is a guide about how you can register new peripheral providers to SVD Viewer in your VSCode extension. Please refer to [VSCode Extension API](https://code.visualstudio.com/api) for more information about developing VSCode extensions. + +### Adding peripheral-viewer to your VSCode extension + +You need to install eclipse-cdt-cloud/vscode-svd-viewer to access the types information. You can use `npm` or `yarn` with the following arguments described below: + +Using with npm: +```bash +npm install github:eclipse-cdt-cloud/vscode-svd-viewer +``` +Using with yarn: +```bash +yarn add github:eclipse-cdt-cloud/vscode-svd-viewer +``` + +### Developing your extension + +To provide the peripherals information to SVD Viewer on debug session time, you need register your command which is going 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: + +```js +import { ExtensionContext } from 'vscode'; +import { + PeripheralOptions, + PeripheralRegisterOptions, + ClusterOptions, + FieldOptions, + AccessType, + IGetPeripheralsArguments, + IPeripheralsProvider +} from "svd-viewer"; + + +class MyExtensionProvider implements IPeripheralsProvider { + public async getPeripherals (data: string, options: IGetPeripheralsArguments): Promise { + // Load your peripherals data + const peripherals: PeripheralOptions[] = ... + return peripherals; + } +} + +export async function activate(context: ExtensionContext) { + ... + // Get the eclipse-cdt.svd-viewer extension + const svdViewerExtension = extensions.getExtension('eclipse-cdt.svd-viewer'); + + // Invoke registerPeripheralsProvider method in eclipse-cdt.svd-viewer extension api + // Register 'MyExtensionProvider' for files *.myext + svdViewerExtension?.exports?.registerPeripheralsProvider('myext', new MyExtensionProvider()); + ... +} +``` + +You can check the type definitions (`PeripheralOptions`, `PeripheralRegisterOptions`, `ClusterOptions`, `FieldOptions`, `AccessType`) from [this document](./appendix-types.md). + +### Modifying your package.json + +In `package.json` of your VSCode extension project, you need to define the dependency between svd-viewer and your extension. + +You need to define SVD Viewer in the `extensionDependencies` as shown below: + +```json +{ + ... + "extensionDependencies": [ + "eclipse-cdt.svd-viewer" + ], + ... +} +```