EHLS.Target behaviour (Elixir HLS v0.1.0)

Copy Markdown View Source

A board an application runs on, as the Mix tasks see it (mix ehls.build, mix ehls.run, mix ehls.flash, mix ehls.console, mix ehls.doctor, mix ehls.setup): the tasks are elixir-hls', the work is the target's.

A target package (atomvm-tang25k-hls for the Sipeed Tang Primer 25K) has a module with @behaviour EHLS.Target; the tasks find it among the application's dependencies. With several, config :elixir_hls, target: :tang25k picks one by its name/0 (or a module name).

For those writing a target: the callbacks below; the steps of a build are EHLS.Build.step/0, the machine's settings EHLS.Machine.setting/0.

Summary

Types

What a flash part writes: :vm, :lib, :bitstream, :app, ...

Callbacks

The board's parts for EHLS.GPIO (a JSON file), or nil.

The target's checks for mix ehls.doctor: a label and a function giving :ok or {:error, why}.

Shows the board's console until interrupted.

Writes the given parts to the board's flash.

The files each flash part writes, for the record of what the board holds.

The target's name, as config :elixir_hls, target: gives it (e.g. :tang25k).

Sends the application to the board, starts it and shows its console (options: seconds:).

The flash parts a run needs in the board (e.g. [:vm, :lib]); mix ehls.run writes those that changed.

The machine's settings the target needs besides elixir-hls' own (EHLS.Machine).

Sets up once what the target's builds need on this machine and is not in the dependencies as Mix fetched them (on the Tang Primer 25K the base's LiteX, AtomVM and host tools), for mix ehls.setup (options: force: true to do it again). Kept outside the application (EHLS.Machine.cache_dir/0), so the applications of the machine share it.

The steps of a build, in order (EHLS.Build).

Functions

The target if one is found, else nil (for the compile on the host, which needs none).

The target of the current Mix project: config :elixir_hls, target: (a name or a module), else the only target among the dependencies. Raises when there is none, or several and no choice.

Types

part()

@type part() :: atom()

What a flash part writes: :vm, :lib, :bitstream, :app, ...

Callbacks

board_gpio()

(optional)
@callback board_gpio() :: Path.t() | nil

The board's parts for EHLS.GPIO (a JSON file), or nil.

checks(t)

(optional)
@callback checks(EHLS.Project.t()) :: [{String.t(), (-> :ok | {:error, String.t()})}]

The target's checks for mix ehls.doctor: a label and a function giving :ok or {:error, why}.

console(t)

(optional)
@callback console(EHLS.Project.t()) :: :ok

Shows the board's console until interrupted.

flash(t, list, keyword)

@callback flash(EHLS.Project.t(), [part()], keyword()) :: :ok

Writes the given parts to the board's flash.

flash_images(t)

@callback flash_images(EHLS.Project.t()) :: %{required(part()) => Path.t()}

The files each flash part writes, for the record of what the board holds.

name()

@callback name() :: atom()

The target's name, as config :elixir_hls, target: gives it (e.g. :tang25k).

run(t, keyword)

@callback run(EHLS.Project.t(), keyword()) :: :ok

Sends the application to the board, starts it and shows its console (options: seconds:).

run_needs()

@callback run_needs() :: [part()]

The flash parts a run needs in the board (e.g. [:vm, :lib]); mix ehls.run writes those that changed.

settings()

@callback settings() :: [EHLS.Machine.setting()]

The machine's settings the target needs besides elixir-hls' own (EHLS.Machine).

setup t, keyword

(optional)
@callback setup(EHLS.Project.t(), keyword()) :: :ok

Sets up once what the target's builds need on this machine and is not in the dependencies as Mix fetched them (on the Tang Primer 25K the base's LiteX, AtomVM and host tools), for mix ehls.setup (options: force: true to do it again). Kept outside the application (EHLS.Machine.cache_dir/0), so the applications of the machine share it.

steps(t)

@callback steps(EHLS.Project.t()) :: [EHLS.Build.step()]

The steps of a build, in order (EHLS.Build).

Functions

find()

The target if one is found, else nil (for the compile on the host, which needs none).

find!(choice \\ Application.get_env(:elixir_hls, :target))

The target of the current Mix project: config :elixir_hls, target: (a name or a module), else the only target among the dependencies. Raises when there is none, or several and no choice.