Fuchsia

Get started with driver development

This guide provides step-by-step instructions on setting up the Fuchsia driver development environment on your host machine using a terminal or Visual Studio Code (VS Code). Then the guide walks through the basic workflows of building, running, debugging, and updating drivers in a Fuchsia system using the Fuchsia SDK.

Important: This guide is the driver equivalent of the Get started with the Fuchsia SDK guide. If you haven‘t already, it’s strongly recommended that you complete Get started with the Fuchsia SDK first to become familiar with the comprehensive set of Fuchsia SDK workflows.

Which development environment are you using for this guide?

{% dynamic if request.query_string.env == “terminal” %}

Complete the following sections:

  1. Prerequisites.
  2. Clone the SDK driver samples repository.
  3. Start the emulator.
  4. Build and load the sample driver.
  5. Build and run a tool.
  6. Debug the sample driver.
  7. Modify and reload the sample driver.

{% dynamic elif request.query_string.env == “vscode” %}

Complete the following sections:

  1. Prerequisites.
  2. Clone the SDK driver samples repository.
  3. Configure a VS Code workspace
  4. Start the emulator.
  5. Build and load the sample driver.
  6. Build and run a tool.
  7. Debug the sample driver.
  8. Modify and reload the sample driver.

{% dynamic endif %}

Found an issue? Please let us know{:.external}.

Prerequisites {:#prerequisites .numbered}

This guide requires that your host machine meets the following criteria:

  • An x64-based machine running Linux or macOS.
  • Has at least 15 GB of storage space.
  • Supports KVM{:.external} (Kernel Virtual Machine) for running a QEMU{:.external}-based emulator.
  • IPv6 is enabled.
  • Git{:.external} is installed. {% dynamic if request.query_string.env == “vscode” %}
  • Visual Studio Code{:.external} is installed. {% dynamic endif %}

Clone the SDK driver samples repository {:#clone-the-sdk-driver-samples-repository .numbered}

{% dynamic if request.query_string.env == “terminal” %} <<_common/drivers/_get-started-driver-clone-repo-terminal.md>> {% dynamic elif request.query_string.env == “vscode” %} <<_common/drivers/_get-started-driver-clone-repo-vs-code.md>> {% dynamic endif %}

{% dynamic if request.query_string.env == “vscode” %}

Configure a VS Code workspace {:#configure-a-vs-code-workspace .numbered}

<<_common/drivers/_get-started-driver-configure-vs-code.md>> {% dynamic endif %}

Start the emulator {:#start-the-emulator .numbered}

{% dynamic if request.query_string.env == “terminal” %} <<_common/drivers/_get-started-driver-start-emulator-terminal.md>> {% dynamic elif request.query_string.env == “vscode” %} <<_common/drivers/_get-started-driver-start-emulator-vs-code.md>> {% dynamic endif %}

Build and load the sample driver {:#build-and-load-the-sample-driver .numbered}

{% dynamic if request.query_string.env == “terminal” %} <<_common/drivers/_get-started-driver-build-and-load-terminal.md>> {% dynamic elif request.query_string.env == “vscode” %} <<_common/drivers/_get-started-driver-build-and-load-vs-code.md>> {% dynamic endif %}

Build and run a tool {:#build-and-run-a-tool .numbered}

{% dynamic if request.query_string.env == “terminal” %} <<_common/drivers/_get-started-driver-build-and-run-tool-terminal.md>> {% dynamic elif request.query_string.env == “vscode” %} <<_common/drivers/_get-started-driver-build-and-run-tool-vs-code.md>> {% dynamic endif %}

Debug the sample driver {:#debug-the-sample-driver .numbered}

{% dynamic if request.query_string.env == “terminal” %} <<_common/drivers/_get-started-driver-debug-driver-terminal.md>> {% dynamic elif request.query_string.env == “vscode” %} <<_common/drivers/_get-started-driver-debug-driver-vs-code.md>> {% dynamic endif %}

Modify and reload the sample driver {:#modify-and-reload-the-sample-driver .numbered}

{% dynamic if request.query_string.env == “terminal” %} <<_common/drivers/_get-started-driver-modify-driver-terminal.md>> {% dynamic elif request.query_string.env == “vscode” %} <<_common/drivers/_get-started-driver-modify-driver-vs-code.md>> {% dynamic endif %}

Congratulations! You’re now all set with the Fuchsia driver development!

Next steps {:#next-steps}

Learn more about how the qemu_edu driver works in Codelab: QEMU edu driver.

Appendices

Update the environment to the latest SDK {:#update-the-environment-to-the-latest-sdk}

To update your development environment to use the latest version of the Fuchsia SDK, do the following:

  1. In a terminal, go to your fuchsia-drivers directory:

    cd $HOME/fuchsia-drivers

  2. Update the project repository and its submodules to the latest version:

    git pull --rebase --recurse-submodules

  3. Update the Fuchsia SDK toolchain and dependencies:

    tools/bazel build @fuchsia_sdk//:fuchsia_toolchain_sdk

  4. Check the new version of the Fuchsia SDK:

    tools/ffx sdk version

    Verify that the SDK version is now the latest release version.

Clean up the environment {:#clean-up-the-environment}

If you run into a problem while following this guide and decide to start over from the beginning, consider running the commands below to clean up your development environment (that is, to clean up directories, build artifacts, downloaded files, symlinks, configuration settings, and more).

Remove the package repositories created in this guide:

tools/ffx repository remove workstation-packages

tools/ffx repository server stop

Remove all existing configurations and data of ffx:

  • {Linux}

    tools/ffx daemon stop

    rm -rf $HOME/.local/share/Fuchsia/ffx

  • {macOS}

    tools/ffx daemon stop

    rm -rf $HOME/Library/Caches/Fuchsia/ffx

    rm -rf $HOME/Library/Fuchsia/ffx

    rm -rf $HOME/Library/Preferences/Fuchsia/ffx

    rm -rf $HOME/Library/Application\ Support/Fuchsia/ffx

When Bazel fails to build, try the commands below:

  • {Linux}

    Note: Running bazel clean or deleting the $HOME/.cache/bazel directory deletes artifacts downloaded by Bazel, which can be around 4 GB. This means Bazel will need to download dependencies again next time you run bazel build.

    tools/bazel clean --expunge

    tools/bazel shutdown && rm -rf $HOME/.cache/bazel

  • {macOS}

    Note: Running bazel clean or deleting the /private/var/tmp/bazel$USER directory deletes artifacts downloaded by Bazel, which can be around 4 GB. This means Bazel will need to download dependencies again next time you run bazel build.

    tools/bazel clean --expunge

    tools/bazel shutdown && rm -rf /private/var/tmp/bazel$USER

Remove the fuchsia-drivers directory and its artifacts:

Caution: If the driver samples repository is cloned to a different location than $HOME/fuchsia-drivers, adjust the directory in the command below. Be extremely careful with the directory path when you run the `rm -rf

rm -rf $HOME/fuchsia-drivers

Other clean up commands:

killall ffx

killall pm