# `EHLS.Blocks`
[🔗](https://github.com/elixir-hls/elixir-hls/blob/v0.1.0/lib/ehls/blocks.ex#L1)

A package of blocks for `definstance` (sources, sinks, fixed stream functions in
the FPGA) and of SoC peripherals, e.g. a board's I/O, for one SoC backend (`soc/0`). A
module of the package implements this behaviour; an application names it in
`use EHLS, blocks: [...]` (the SoC backend's built-in ones, `c:EHLS.SoC.blocks/0`, come
along):

    defmodule MyApp do
      use EHLS, blocks: [EHLS.USBHost, {EHLS.I2S, pins: [dout: "j5:7"]}, EHLS.RPiDisplay35],
        peripherals: [:lcd]

      definstance radio do
        usb_bulk_in() |> ... |> i2s_out()
      end
    end

The FPGA side of a package (`gateware/0`) is what its SoC backend builds, in the form that
backend documents (e.g. `EHLS.SoC.LiteX`); the application's options to the package
(`use EHLS, blocks: [{Pkg, pins: [...]}]`) go to it. A package used with another SoC
backend than its own stops the compile.

# `block`

```elixir
@type block() :: {:source | :block | :sink | :level, arity :: non_neg_integer()}
```

kind: :source (first stage, gives a stream), :block (stream in and out), :sink (last stage, takes
a stream) or :level (last stage, takes a stream and keeps a level, e.g. `hold`)

# `blocks`

```elixir
@callback blocks() :: %{required(atom()) =&gt; block()}
```

The blocks: name => {kind, number of integer arguments}.

# `check_sources`
*optional* 

```elixir
@callback check_sources(files :: [Path.t()], table :: map()) :: [
  {Path.t(), integer(), String.t()}
]
```

Problems in the application's sources that the compile cannot see, e.g. calls that cannot
work: `[{file, line, message}]`. `table` is the package's table as in packages.json. They stop
`mix ehls.compile`.

# `check_stage`
*optional* 

```elixir
@callback check_stage(name :: atom(), args :: list(), table :: map()) :: any()
```

Checks a stage using one of the package's blocks, `name` and its literal arguments, given the
package's table; raises `ArgumentError` on what cannot be built.

# `gateware`

```elixir
@callback gateware() :: String.t()
```

The package's gateware, as its SoC backend names it.

# `options`
*optional* 

```elixir
@callback options(keyword()) :: term()
```

The application's options to the package checked and put in the form its gateware gets;
raises on what cannot be built. Without it they go as they are.

# `peripherals`

```elixir
@callback peripherals() :: [atom()]
```

The SoC peripherals an application can ask for with `use EHLS, peripherals: [...]`.

# `registers`
*optional* 

```elixir
@callback registers() :: %{required(atom()) =&gt; :r | :w}
```

The package's registers the CPU reads and writes: name => `:r` or `:w`. The runtime reaches
them by number (`:hw_kernels.reg(gateware, name)`, the runtime's `reg_read/1`, `reg_write/2`),
so that a simple block needs no code of its own in the VM. The SoC backend says what a name
is in its circuit (LiteX: the CSR `<gateware>_<name>`).

# `soc`

```elixir
@callback soc() :: atom()
```

The SoC backend the package is for (`c:EHLS.SoC.name/0`, e.g. `:litex`).

# `stage_table`
*optional* 

```elixir
@callback stage_table(name :: atom(), args :: list(), table :: map()) :: map()
```

What a stage using one of the package's blocks changes in the package's table: key => value.
They go into packages.json, so `:hw_kernels.data/2` and `check_sources/2` see them.

# `table`
*optional* 

```elixir
@callback table(term()) :: map()
```

From those options, what the package looks up on the CPU: key => value, a tuple of integers
and atoms or one of them (`:hw_kernels.data(gateware, key)`; `:undefined` for another key).

# `types`
*optional* 

```elixir
@callback types() :: %{required(atom()) =&gt; {term(), term()}}
```

What the package's blocks take and give: name => `{in, out}`, each a type (`:u8`, `{:s16, :s16}`), `:any` (takes every type) or
`nil` (nothing). A block not named here works on `:u32`.

# `waits`
*optional* 

```elixir
@callback waits() :: [atom()]
```

The package's sources that can wait: a word stays until it is taken. A stream to the CPU from any
other source needs `overflow: :drop`.

# `defaults`

The packages every module gets besides its own: the SoC backend's built-in blocks (none
without a SoC backend).

---

*Consult [api-reference.md](api-reference.md) for complete listing*
