Definisi perangkat keras

Artikel
08/09/2023

Bagian ini menjelaskan file definisi perangkat keras dan cara membuatnya untuk papan dan modul Azure Sphere.

Berkas definisi perangkat keras

Definisi perangkat keras melayani dua tujuan terpisah namun terkait:

Definisi khusus papan menentukan periferal tertentu dari modul atau papan lain dan memungkinkan aplikasi untuk mereferensikannya dengan menggunakan pengidentifikasi yang relevan dan bermakna. Misalnya, aplikasi dapat menggunakan "Red_LED_1" dan bukan angka buram seperti GPIO "13". Direktori HardwareDefinitions di Azure Sphere SDK berisi definisi untuk papan Azure Sphere umum dan chip yang mereka gunakan. Direktori ini berada %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions di Windows dan /opt/azurespheresdk/HardwareDefinitions Linux.

Definisi khusus aplikasi memetakan periferal yang direferensikan dalam kode aplikasi ke definisi khusus papan. Definisi khusus aplikasi dibuat berdasarkan definisi khusus papan, dan menentukan sekumpulan pengidentifikasi tunggal yang dapat digunakan untuk mereferensikan periferal di papan apa pun. Jadi, aplikasi yang berjalan di beberapa papan mungkin memiliki definisi khusus aplikasi untuk setiap tipe papan, tetapi aplikasi itu sendiri hanya menggunakan satu set pengidentifikasi periferal. Kode itu sendiri dapat berjalan sepenuhnya tidak berubah pada perangkat keras yang berbeda; pengembang hanya perlu mengubah referensi untuk menggunakan definisi yang sesuai. Misalnya, kode aplikasi untuk pembuat kopi mereferensikan LED indikator BrewingStatus. Papan kontrol pembuat kopi bersumber dari dua pemasok, Contoso dan Fabrikam. Melalui penggunaan definisi khusus aplikasi untuk setiap papan, indikator BrewingStatus dapat dipetakan ke LED 2 pada papan kontrol yang disediakan oleh Contoso dan LED 4 di papan kontrol yang disediakan oleh Fabrikam.

Jika aplikasi Anda menggunakan definisi perangkat keras dari SDK atau dari pemasok perangkat keras Anda—dan Anda tidak membuat definisi khusus aplikasi—maka Anda dapat melewati sisa topik ini untuk saat ini, dan langsung menggunakan dependensi perangkat keras.

Anda membuat file definisi perangkat keras dalam format JSON. Anda kemudian menghasilkan file header C dari file JSON.

Format file definisi perangkat keras

File definisi perangkat keras adalah file JSON dengan format berikut:

{
    "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": " "},
   ]
}

Bagian Metadata berisi informasi tentang file (tipe file, versi, dan sebagainya).

Bagian Deskripsi berisi informasi tentang papan atau modul. Bidang "MainCoreHeaderFileTopContent" berisi informasi yang akan ditempatkan di awal file header yang dihasilkan.

Bagian Impor menentukan nama jalur file definisi perangkat keras untuk platform perangkat keras yang mendasar (papan atau modul).

Bagian Periferal mencantumkan periferal yang diekspos papan ini untuk digunakan dalam aplikasi. Deskripsi periferal memiliki format berikut:

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

Berikut ini adalah elemen bagian Periferal :

Nama - Pengidentifikasi yang digunakan untuk mereferensikan periferal dalam kode aplikasi Anda.

Tipe - Tipe periferal (misalnya, Gpio, Uart, Adc). Lihat file definisi perangkat keras yang tercantum di bagian Impor untuk mendapatkan informasi tipe.

Pemetaan - Memetakan pengidentifikasi dalam bidang Nama ke pengidentifikasi yang digunakan untuk periferal dalam file definisi perangkat keras yang diimpor.

Komentar - Menyediakan informasi berguna untuk muncul dalam file header yang dihasilkan. Misalnya, sematkan tugas untuk periferal ISU*, atau pemetaan LED di papan ke pin GPIO dari MCU atau Modul yang mendasar.

Contoh: definisi board-specific

Contoh berikut ini memperlihatkan sebagian file definisi perangkat keras yang berisi definisi khusus papan untuk papan pengembangan MT3620 fiksi yang disebut MyBoard. Ini menentukan definisi pinout periferal untuk MyBoard. Ini mengimpor definisi sumber daya dari file definisi perangkat keras khusus chip (mt3620.json) untuk MCU MT3620. Informasi di bagian Periferal menghasilkan pemetaan pin-ke-pin sumber daya yang diekspos oleh MyBoard ke sumber daya yang disediakan oleh MCU MT3620 yang mendasar.

{
    "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"},
                              .
                              .
                              .
    ]
}

Anda dapat melihat contoh tambahan file definisi khusus papan di direktori HardwareDefinitions yang merupakan bagian dari penginstalan Azure Sphere SDK.

Contoh: application-specific definition

Contoh berikut ini memperlihatkan sebagian file definisi perangkat keras yang berisi definisi aplikasi khusus untuk alat pembuat kopi fiksi.

Di antara periferal yang disertakan dalam aplikasi adalah dua LED indikator dan tombol tekan. Kode tersebut dirujuk dalam kode aplikasi oleh pengidentifikasi COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY, dan COFFEEMAKER_BUTTON_START. Pengidentifikasi ini dipetakan ke periferal yang ditentukan dalam definisi khusus papan yang diimpor untuk papan FIKSI 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"},
                                             .
                                             .
                                             .
    ]
}

Bagian Impor berisi jalur ke file definisi perangkat keras untuk papan atau modul fisik.
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
Bagian Periferal memetakan periferal papan kontrol CoffeeMaker ke periferal terkait di papan atau modul.
```
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
```
Nama - berisi pengidentifikasi yang digunakan untuk periferal dalam kode aplikasi.

Pemetaan - berisi pengidentifikasi yang digunakan untuk periferal dalam file definisi perangkat keras untuk papan atau modul.

Versi pembuat kopi berikutnya mungkin dibuat di MyBoardV2. Ini akan memiliki definisi khusus papan baru dengan periferal seperti MY_BOARD_V2_LED_ORANGE. Ini akan diimpor oleh implementasi baru dari definisi aplikasi pembuat kopi yang memetakan COFFEEMAKER_STATUS_BREWING ke LED oranye baru ini. Kode aplikasi pembuat kopi aktual akan tetap tidak berubah.

Demikian pula, implementasi baru definisi "sample_appliance.json", yang digunakan oleh aplikasi sampel Azure Sphere, dapat memungkinkan aplikasi sampel ini untuk berjalan tidak berubah di MyBoard.

File header

File header dihasilkan dari file JSON yang berisi definisi perangkat keras. Anda harus membuat file header untuk definisi khusus papan dan aplikasi.

Gunakan perintah azsphere hardware-definition generate-header untuk menghasilkan file header.

Untuk membuat file header, masukkan baris berikut ini di Prompt Perintah Azure Sphere. Ganti <filename> dengan nama file JSON.

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

Nama file header.h akan dibuat dan ditempatkan di folder inc/hw.

Misalnya, masukkan baris berikut ini untuk menghasilkan file header dari file JSON.

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

Berikut ini memperlihatkan sebagian file header 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
                   .
                   .
                   .

Catatan Secara default, file header yang dihasilkan akan ditempatkan di inc/hw, yang harus merupakan subdirektori direktori yang berisi file JSON input. Jika subdirektori ini tidak ada, subdirektori ini akan dibuat.

Setelah membuat file JSON definisi perangkat keras dan file header yang menyertainya, lihat Mengelola dependensi perangkat keras target untuk langkah-langkah menggunakannya dalam aplikasi Anda.

Bagikan melalui