コグノスケ

Zephyr OSで遊ぼう その8 - 独自のシリアルドライバの実装

目次: Zephyr

前回はシリアルドライバの枠組み、というか、何も実装されていないドライバを追加しました。今回はシリアルドライバを実装します。

Zephyrのドライバについてはドキュメント（Device Driver Model - Zephyr Project Documentation）があります。ドライバの定義や初期化を司るAPIがDriver APIの節に書いてあります。

今回作成するUARTドライバでは初期化は要りませんが、ドライバのAPIをいくつか実装したいのでDEVICE_AND_API_INIT() を使います。

UARTのドライバで実装できるAPIの一覧はドキュメント（UART - Zephyr Project Documentation）に書いてあります。APIはたくさんありますが、poll_in, poll_outがあれば動作するようなので、この2つを作ります。

コードは下記のようにしました。

/*
 * SPDX-License-Identifier: Apache-2.0
 */

/**
 * @brief UART driver for the Spike Simulator
 */

#include <kernel.h>
#include <arch/cpu.h>
#include <drivers/uart.h>

volatile u64_t tohost;
volatile u64_t fromhost;

void uart_spike_poll_out(struct device *dev, unsigned char c)
{
        u64_t cmd;

        // QEMU spike mode
        u8_t dev_no = 1;
        u8_t cmd_no = 1;
        u64_t payload = c;

        cmd = ((u64_t)dev_no << 56) |
                ((u64_t)cmd_no << 48) |
                (payload & 0xffffffffffffULL);

        tohost = cmd;

        while (fromhost == 0)
                ;
        fromhost = 0;
}

static int uart_spike_poll_in(struct device *dev, unsigned char *c)
{
        return -1;
}

static int uart_spike_init(struct device *dev)
{
        return 0;
}

static const struct uart_driver_api uart_spike_driver_api = {
        .poll_in          = uart_spike_poll_in,
        .poll_out         = uart_spike_poll_out,
};

DEVICE_AND_API_INIT(uart_spike_0, DT_INST_0_SPIKE_UART_SPIKE_LABEL,
                    uart_spike_init, NULL, NULL,
                    PRE_KERNEL_1, CONFIG_KERNEL_INIT_PRIORITY_DEVICE,
                    (void *)&uart_spike_driver_api);

このままビルドするとDEVICE_AND_API_INIT() に渡しているラベルDT_INST_0_SPIKE_UART_SPIKE_LABELが未定義だと怒られます。これについては後ほど作り方を説明します。

zephyr/drivers/serial/uart_spike.c:73:35: error: 'DT_INST_0_SPIKE_UART_SPIKE_LABEL' undeclared here (not in a function); did you mean 'DT_COMPAT_SPIKE_UART_SPIKE'?
 DEVICE_AND_API_INIT(uart_spike_0, DT_INST_0_SPIKE_UART_SPIKE_LABEL,
                                   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
../include/device.h:106:11: note: in definition of macro 'DEVICE_AND_API_INIT'
   .name = drv_name, .init = (init_fn),     \
           ^~~~~~~~
[89/97] Linking C static library zephyr/libzephyr.a
ninja: build stopped: subcommand failed.

初期化はDEVICE_AND_API_INIT() で指定します。引数の意味は DEVICE_AND_API_INIT() のドキュメントを見たほうが良いでしょう。

引っかかりそうなところはdev_nameにダブルクォートを「付けない」こと、一番に初期化されるようにPRE_KERNEL_1にすることくらいでしょうか。

QEMU Spikeモードの文字出力

文字出力poll_outの実装は、グローバル変数に謎の数字を書くだけの不思議実装になっていますが、これはQEMU SpikeモードのHost, Guest間インタフェースの仕様に従っているためです。

ちなみにQEMU側はこんなコードになっています。

// https://github.com/qemu/qemu/blob/master/hw/riscv/riscv_htif.c

...

static void htif_handle_tohost_write(HTIFState *htifstate, uint64_t val_written)
{
    uint8_t device = val_written >> 56;
    uint8_t cmd = val_written >> 48;
    uint64_t payload = val_written & 0xFFFFFFFFFFFFULL;
    int resp = 0;

...

    } else if (likely(device == 0x1)) {
        /* HTIF Console */
        if (cmd == 0x0) {
            /* this should be a queue, but not yet implemented as such */
            htifstate->pending_read = val_written;
            htifstate->env->mtohost = 0; /* clear to indicate we read */
            return;
        } else if (cmd == 0x1) {
            qemu_chr_fe_write(&htifstate->chr, (uint8_t *)&payload, 1);
            resp = 0x100 | (uint8_t)payload;
        } else {
            qemu_log("HTIF device %d: unknown command\n", device);
        }
    } else {

...

    htifstate->env->mfromhost = (val_written >> 48 << 48) | (resp << 16 >> 16);
    htifstate->env->mtohost = 0; /* clear to indicate we read */
}

途中のif文を見るとわかるように、device=1, cmd=1にすると文字が出力できます。またQEMUが文字出力を終えたときにfromhostが0以外の値に書き換わります（なので、Zephyrのシリアルドライバ側ではfromhostをポーリングで監視する実装にしています）。

シリアルドライバのラベル定義とbindings

DT_INST_0_SPIKE_UART_SPIKE_LABELのようなラベルはユーザが定義するのではなく、zephyr/dts/bindings以下のファイルに存在するcompatibleと、デバイスツリーを突き合わせて自動生成するみたいです。命名規則については、以前Zephyr OSで遊ぼう その3（2020年2月4日の日記参照）で紹介したとおりです。

# SPDX-License-Identifier: Apache-2.0

description: UART for Spike Simulator

compatible: "spike,uart-spike"

include: uart-controller.yaml

デバイスツリーのcompatibleの突き合わせとラベルの自動生成は、zephyr/scripts/dts/gen_defines.pyとedtlib.py辺りでやっていることは間違いなさそうなのですが、詳細な仕組みはまだ追えていません。

若干もやっとしますがYAMLファイルを作成して、compatibleをデバイスツリーで使用したものと合わせると、目的のラベルDT_INST_0_SPIKE_UART_SPIKE_LABELが定義され、ビルドが通ります。

Hello world

ビルドが通ったら実行します。

$ /usr/bin/qemu-system-riscv32 -nographic -machine spike -net none -chardev stdio,id=con,mux=on -serial chardev:con -mon chardev=con,mode=readline -kernel zephyr/build/zephyr/zephyr.elf

qemu-system-riscv32: clint: time_hi write not implemented
qemu-system-riscv32: clint: time_lo write not implemented
qemu-system-riscv32: clint: time_hi write not implemented
*** Booting Zephyr OS build zephyr-v2.1.0-1699-gbb40304f2531  ***
Hello World! hoge

やっとHello worldが拝めました。長かった。 （2/19追記: qemu-system-riscv32: clint: time_hi write not implementedのエラーメッセージはmtimeとmtimecmpのアドレスが逆だったために発生していたエラーです。アドレス修正後は表示されません）

パッチ

今まで説明してきた変更をパッチとしてまとめておきます。

•  Hogeボード（SiFive SoC使用版）追加のパッチ
•  QEMU Spikeモード用シリアルドライバ追加のパッチ
•  QEMU Spikeモード用SoC追加のパッチ
•  Hogeボード（Spike SoC使用版）変更のパッチ