ハードウェア定義

  • [アーティクル]

このセクションでは、ハードウェア定義ファイルと、それらを Azure Sphere ボードとモジュール用に作成する方法について説明します。

ハードウェア定義ファイル

ハードウェア定義は、次の 2 つの独立した関連する目的で機能します。

ボード固有の 定義は、モジュールまたはその他のボードの特定の周辺機器を定義し、関連する意味のある識別子を使用してアプリケーションがそれらを参照できるようにします。 たとえば、アプリでは、GPIO "13" などの不透明な数値の代わりに "Red_LED_1" を使用できます。 Azure Sphere SDK の HardwareDefinitions ディレクトリには、一般的な Azure Sphere ボードと、それらが使用するチップに対してこのような定義が含まれています。 このディレクトリは、 %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions Windows と /opt/azurespheresdk/HardwareDefinitions Linux 上にあります。

アプリケーション固有の 定義は、アプリケーション コードで参照されている周辺機器をボード固有の定義にマップします。 アプリケーション固有の定義は、ボード固有の定義に基づいて構築され、任意のボード上の周辺機器を参照するために使用できる 1 つの識別子セットを定義します。 したがって、複数のボードで実行されるアプリケーションは、ボードの種類ごとにアプリケーション固有の定義を持つ場合がありますが、アプリケーション自体で使用される周辺機器識別子のセットは 1 つだけです。 コード自体は、異なるハードウェアで完全に変更されずに実行できます。開発者は、適切な定義を使用するために参照を変更するだけで済みます。 たとえば、コーヒー メーカーのアプリケーション コードは、BrewingStatus インジケーター LED を参照します。 コーヒー メーカーコントロールボードは、Contoso と Fabrikam の 2 つのサプライヤーによって供給されています。 各ボードのアプリケーション固有の定義を使用することで、BrewingStatus インジケーターは、Contoso が提供するコントロール ボードの LED 2 と Fabrikam が提供するコントロール ボードの LED 4 にマップできます。

アプリケーションで SDK またはハードウェア サプライヤーのハードウェア定義を使用していて、独自のアプリケーション固有の定義を作成していない場合は、このトピックの残りの部分を今のところスキップして、 ハードウェアの依存関係の使用に直接進むことができます。

ハードウェア定義ファイルは JSON 形式で作成します。 次に、JSON ファイルから C ヘッダー ファイルを生成します。

ハードウェア定義ファイルの形式

ハードウェア定義ファイルは、次の形式の JSON ファイルです。

{
    "Metadata":
    {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "<name of board or module>",
        "MainCoreHeaderFileTopContent": [
            "/* Copyright (c) <vendor name> All rights reserved.",
            "   <vendor licensing information, if any> */",
            "",
            "// This header contains the peripheral pinout definitions for the",
            "// <name of board or module>"
        ]
    },
    "Imports" : [ {"Path": "<path to underlying hardware definition file>"} ],
    "Peripherals": [
       {"Name": "", "Type": " ", "Mapping": " ", "Comment": " "},
   ]
}

[ メタデータ] セクションには、ファイル (ファイルの種類、バージョンなど) に関する情報が含まれています。

[ 説明 ] セクションには、ボードまたはモジュールに関する情報が含まれています。 "MainCoreHeaderFileTopContent" フィールドには、生成されたヘッダー ファイルの先頭に配置される情報が含まれています。

[ インポート] セクションでは、基になるハードウェア プラットフォーム (ボードまたはモジュール) のハードウェア定義ファイルのパス名を指定します。

[ 周辺機器] セクションには、このボードがアプリケーションで使用するために公開する周辺機器の一覧が表示されます。 周辺機器の説明の形式は次のとおりです。

{"   Name": "<name-in-code>", "Type": "<type>", "Mapping": "<name-in-imported-definition>", "Comment": "<helpful info>"}

[周辺機器] セクションの要素を次に示します。

名前 - アプリケーション コード内の周辺機器を参照するために使用される識別子。

Type - 周辺機器の種類 (Gpio、Uart、Adc など)。 型情報を取得するには、「 Imports 」セクションに記載されているハードウェア定義ファイルを参照してください。

マッピング - [名前] フィールドの識別子を、インポートされたハードウェア定義ファイルの周辺機器に使用される識別子にマップします。

コメント - 生成されたヘッダー ファイルに表示するのに役立つ情報を提供します。 たとえば、ISU* 周辺機器のピン割り当て、またはオンボード LED を基になる MCU またはモジュールの GPIO ピンにマッピングします。

例: ボード固有の定義

次の例は、MyBoard という架空の MT3620 開発ボードのボード固有の定義を含むハードウェア定義ファイルの一部を示しています。 MyBoard の周辺機器のピン配置定義を指定します。 MT3620 MCU のチップ固有のハードウェア定義ファイル (mt3620.json) からリソース定義をインポートします。 [周辺機器] セクションの情報により、MyBoard によって公開されるリソースが、基になる MT3620 MCU によって提供されるリソースにピン間マッピングされます。

{
    "Metadata":
    {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "MyBoard",
        "MainCoreHeaderFileTopContent": [
            "// This header contains the peripheral pinout definitions for ",
            "// MyBoard"
        ]
    },
    "Imports" : [ {"Path": "... /mt3620/mt3620.json"} ],
    "Peripherals": [
        {"Name": "MY_BOARD_LED_RED", "Type": "Gpio", "Mapping": "MT3620_GPIO8", "Comment": "LED 1 Red channel uses GPIO8."},
        {"Name": "MY_BOARD_LED_GREEN", "Type": "Gpio", "Mapping": "MT3620_GPIO16", "Comment": "LED 2 Green channel uses GPIO16"},
        {"Name": "MY_BOARD_BUTTON_A", "Type": "Gpio", "Mapping": "MT3620_GPIO12", "Comment": "Button A uses GPIO12"},
                              .
                              .
                              .
    ]
}

ボード固有の定義ファイルのその他の例は、Azure Sphere SDK のインストールの一部である HardwareDefinitions ディレクトリで確認できます。

例: アプリケーション固有の定義

次の例は、架空のコーヒー メーカー アプライアンスのアプリケーション固有の定義を含むハードウェア定義ファイルの一部を示しています。

アプリケーションに含まれる周辺機器の中には、2 つのインジケーター LED とプッシュ ボタンがあります。 これらは、それぞれ識別子COFFEEMAKER_STATUS_BREWING、COFFEEMAKER_STATUS_READY、およびCOFFEEMAKER_BUTTON_STARTによってアプリケーション コードで参照されます。 これらの識別子は、架空の MT3620 ボード MyBoard のインポートされたボード固有の定義で定義されている周辺機器にマップされます。

{
    "Metadata": {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "Coffee Maker Application",
        "MainCoreHeaderFileTopContent": [
            "// This file implements the Coffee Maker application-specific definition on MyBoard",
        ]
    },
    "Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
    "Peripherals": [
         {"Name": "COFFEEMAKER_STATUS_BREWING", "Type": "Gpio", "Mapping": "MY_BOARD_LED_RED", "Comment": "Brewing status indicator uses MyBoard RED LED"},
         {"Name": "COFFEEMAKER_STATUS_READY", "Type": "Gpio", "Mapping": "MY_BOARD_LED_GREEN", "Comment": "Ready status indicator uses MyBoard GREEN LED"},
         {"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": "Start button uses MyBoard Button A"},
                                             .
                                             .
                                             .
    ]
}

  • [ Imports]\(インポート\) セクションには、物理ボードまたはモジュールのハードウェア定義ファイルへのパスが含まれています。

    "Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],

  • [周辺機器] セクションでは、CoffeeMaker コントロール ボード周辺機器をボードまたはモジュール上の対応する周辺機器にマップします。

    {"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},

    [名前] - アプリケーション コードで周辺機器に使用される識別子が含まれます。

    マッピング - ボードまたはモジュールのハードウェア定義ファイル内の周辺機器に使用される識別子が含まれます。

次のバージョンのコーヒーメーカーは、MyBoardV2 上に構築される可能性があります。 MY_BOARD_V2_LED_ORANGEなどの周辺機器を含む新しいボード固有の定義が作成されます。 これは、この新しいオレンジ色の LED にCOFFEEMAKER_STATUS_BREWINGマップする、コーヒー メーカーのアプリケーション固有の定義の新しい実装によってインポートされます。 実際のコーヒー メーカー アプリケーション コードは変更されません。

同様に、 Azure Sphere サンプル アプリで使用される "sample_appliance.json" 定義の新しい実装により、これらのサンプル アプリを MyBoard で変更せずに実行できます。

ヘッダー ファイル

ヘッダー ファイルは、ハードウェア定義を含む JSON ファイルから生成されます。 ボード固有の定義とアプリケーション固有の定義の両方に対してヘッダー ファイルを作成する必要があります。

azsphere hardware-definition generate-header コマンドを使用して、ヘッダー ファイルを生成します。

ヘッダー ファイルを作成するには、Azure Sphere コマンド プロンプトで次の行を入力します。 を JSON ファイルの名前に置き換えます <filename> 。

azsphere hardware-definition generate-header --hardware-definition-file <filename>

ヘッダー ファイル filename.h が作成され、フォルダー inc/hw に配置されます。

たとえば、次の行を入力して、JSON ファイルからヘッダー ファイルを生成します。

azsphere hardware-definition generate-header --hardware-definition-file my_board.json

次に、my_board.h ヘッダー ファイルの一部を示します。

#pragma once
#include "... /mt3620/inc/hw/mt3620.h"

// LED Red channel uses GPIO8.
#define MY_BOARD_LED_RED MT3620_GPIO8

// LED Green channel uses GPIO16
#define MY_BOARD_LED_GREEN MT3620_GPIO16

// Button A uses GPIO12
#define MY_BOARD_BUTTON_A MT3620_GPIO12
                   .
                   .
                   .

メモ 既定では、生成されたヘッダー ファイルは に inc/hw配置されます。これは、入力 JSON ファイルを含むディレクトリのサブディレクトリである必要があります。 このサブディレクトリが存在しない場合は、作成されます。

ハードウェア定義 JSON ファイルとそれに付随するヘッダー ファイルを作成したので、アプリケーションで使用する手順については、「 ターゲット ハードウェアの依存関係を管理 する」を参照してください。