Add code generation documentation

docs/README.md

@@ -41,3 +41,11 @@ Tool for inspecting, updating and interfacing with Harp devices.
     ```cmd
     dotnet tool restore
     ```
+
+## Contributing
+
+Bug reports and contributions are welcome at [the GitHub repository](https://github.com/harp-tech/toolkit).
+
+## License
+
+`Harp.Toolkit` is released as open-source under the [MIT license](https://licenses.nuget.org/MIT).

docs/articles/generate.md

@@ -0,0 +1,91 @@
+# Code Generation
+
+`harp.toolkit` can be used to automatically generate firmware and interface code from device and IO pin configuration metadata files.
+
+## Editing device metadata
+
+1. Install [Visual Studio Code](https://code.visualstudio.com/)
+2. Install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
+
+The device interface can be described using a `device.yml` file. A complete specification of all device registers, including bit masks, group masks, and payload formats needs to be provided.
+
+```yaml
+%YAML 1.1
+---
+# yaml-language-server: $schema=https://harp-tech.org/draft-02/schema/device.json
+device: DeviceName
+whoAmI: 0000
+firmwareVersion: "0.1"
+hardwareTargets: "0.0"
+registers:
+  DigitalInputs:
+    address: 32
+    type: U8
+    access: Event
+```
+
+## Generating device interface code
+
+A complete reactive interface to communicate with the device can be generated from the `device.yml` metadata file.
+
+```ps1
+dotnet harp.toolkit generate interface
+```
+
+The following options are available to configure the generated output.
+
+#### Namespace
+```ps1
+-ns, --namespace <ns>
+```
+
+Specifies the namespace for the generated code. The default namespace is `Harp.DeviceName` where `DeviceName` is the name of the device specified in the `device.yml` file.
+
+#### Output location
+```ps1
+-o, --output <o>
+```
+
+Specifies the location where to place the generated output. The default is the current directory. Usually this will point to the folder of your `.csproj` interface project.
+
+## Generating device firmware code
+
+Device firmware interface stubs can be generated by providing an additional metadata file, `ios.yml`, describing IO pin configuration. Currently only the [Harp Core ATxmega](https://harp-tech.org/core.atxmega/) is supported.
+
+```ps1
+dotnet harp.toolkit generate firmware
+```
+
+The following options are available to configure the generated output.
+
+#### Generate implementation stubs
+```ps1
+--implementation
+```
+
+Specifies whether to generate implementation stubs. In general this should be run only when starting development of a new device, to provide templates for all required functions. It should also be run when significantly changing the device metadata file, to ensure alignment between firmware and device interface naming conventions.
+
+#### Output location
+```ps1
+-o, --output <o>
+```
+
+Specifies the location where to place the generated output. The default is the current directory. Usually this will point to the folder of your `.cproj` firmware project.
+
+## Generating device metadata
+
+The device metadata and IO pin configuration files can be generated from legacy XLS worksheet files describing the device. Both the `device.yml` and `ios.yml` will be generated from a single `registers.xls` file.
+
+```ps1
+dotnet harp.toolkit generate metadata <registers.xls>
+```
+
+#### Output location
+```ps1
+-o, --output <o>
+```
+
+Specifies the location where to place the generated output. The default is the current directory.
+
+> [!Warning]
+> The `registers.xls` file format is deprecated and is no longer recommended for editing device metadata as it lacks important features of the new YAML format, including complex payload spec formats and mixed access registers.

docs/articles/toc.yml

@@ -1,2 +1,3 @@
 - name: Introduction
-  href: ../index.md
+  href: ../index.md
+- href: generate.md