Hardverdefiníciók

Cikk
08/09/2023

Ez a szakasz a hardverdefiníciós fájlokat és azok Azure Sphere-táblákhoz és -modulokhoz való létrehozását ismerteti.

Hardverdefiníciós fájlok

A hardverdefiníciók két külön, de egymáshoz kapcsolódó célt szolgálnak:

A táblaspecifikus definíciók meghatározzák egy modul vagy más tábla meghatározott perifériáit, és lehetővé teszik az alkalmazások számára, hogy releváns és értelmezhető azonosítók használatával hivatkozhassanak rájuk. Egy alkalmazás például "Red_LED_1" használható átlátszatlan szám helyett, például GPIO "13". Az Azure Sphere SDK HardwareDefinitions könyvtára ilyen definíciókat tartalmaz a gyakori Azure Sphere-táblákhoz és az általuk használt chipekhez. Ez a %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions könyvtár Windowson és /opt/azurespheresdk/HardwareDefinitions Linuxon található.

Az alkalmazásspecifikus definíciók az alkalmazáskódban hivatkozott perifériákat táblaspecifikus definíciókhoz rendelik. Az alkalmazásspecifikus definíciók táblaspecifikus definíciókra épülnek, és egyetlen azonosítókészletet határoznak meg, amelyek bármely tábla perifériáira hivatkozhatnak. Így a több táblán futó alkalmazások mindegyik táblatípushoz rendelkezhetnek alkalmazásspecifikus definícióval, de maga az alkalmazás csak egy perifériaazonosító-készletet használ. Maga a kód teljesen változatlanul futhat a különböző hardvereken; a fejlesztőnek csak a megfelelő definíció használatához kell módosítania a hivatkozást. Egy kávéfőző alkalmazáskódja például egy BrewingStatus jelző LED-re hivatkozik. A kávéfőző vezérlőtáblát két beszállító, a Contoso és a Fabrikam szolgáltatja. Az egyes táblák alkalmazásspecifikus definícióinak használatával a BrewingStatus jelző LED 2-re leképezhető a Contoso által biztosított vezérlőtáblán és a Fabrikam által biztosított vezérlőtáblán található LED 4-re.

Ha az alkalmazás az SDK-ból vagy a hardverszolgáltatótól származó hardverdefiníciókat használ – és nem saját alkalmazásspecifikus definíciót hoz létre –, akkor egyelőre kihagyhatja a témakör hátralévő részét, és közvetlenül a hardverfüggőségek használatára léphet.

A hardverdefiníciós fájlokat JSON formátumban hozza létre. Ezután létrehozza a C fejlécfájlokat a JSON-fájlokból.

Hardverdefiníciós fájl formátuma

A hardverdefiníciós fájl egy JSON-fájl a következő formátumban:

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

A Metaadatok szakasz a fájlra (fájltípusra, verzióra stb.) vonatkozó információkat tartalmaz.

A Leírás szakasz a táblával vagy modullal kapcsolatos információkat tartalmaz. A "MainCoreHeaderFileTopContent" mező olyan információkat tartalmaz, amelyek a generált fejlécfájl elejére kerülnek.

Az Import (Importálás) szakasz a mögöttes hardverplatform (tábla vagy modul) hardverdefiníciós fájljának elérési útját adja meg.

A Perifériák szakasz felsorolja azokat a perifériákat, amelyeket ez a tábla az alkalmazásokban való használatra tesz elérhetővé. A periférialeírás formátuma a következő:

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

A Perifériák szakasz elemei a következők:

Name – A periféria alkalmazáskódban való hivatkozásához használt azonosító.

Type – A periféria típusa (például Gpio, Uart, Adc). A típusadatok beszerzéséhez tekintse meg az Import szakaszban felsorolt hardverdefiníciós fájlt.

Leképezés – Leképezi a Name (Név) mezőben szereplő azonosítót az importált hardverdefiníciós fájl perifériájának azonosítójára.

Megjegyzések – Hasznos információkat nyújt a létrehozott fejlécfájlban való megjelenéshez. Rögzítheti például az ISU* perifériák hozzárendeléseit, vagy a fedélzeti LED-eket a mögöttes MCU vagy modul GPIO-tűihez rendelheti.

Példa: táblaspecifikus definíció

Az alábbi példa a hardverdefiníciós fájl egy részét mutatja be, amely a MyBoard nevű fiktív MT3620 fejlesztői tábla táblaspecifikus definícióját tartalmazza. Meghatározza a MyBoard perifériás kitűződefinícióit. Erőforrás-definíciókat importál az MT3620 MCU chipspecifikus hardverdefiníciós fájljából (mt3620.json). A Perifériák szakaszban található információk a MyBoard által közzétett erőforrások pin-to-pin leképezését eredményezik az alapul szolgáló MT3620 MCU által biztosított erőforrásokhoz.

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

Az Azure Sphere SDK telepítésének részét képező HardwareDefinitions könyvtárban további példákat láthat a táblaspecifikus definíciós fájlokra.

Példa: alkalmazásspecifikus definíció

Az alábbi példa egy hardverdefiníciós fájl egy részét mutatja be, amely egy fiktív kávéfőző berendezés alkalmazásspecifikus definícióját tartalmazza.

Az alkalmazás perifériái között két jelző LED és egy nyomógomb található. Az alkalmazáskódban a COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY és COFFEEMAKER_BUTTON_START azonosítók hivatkoznak rájuk. Ezek az azonosítók a fiktív MT3620 tábla MyBoard táblájának importált táblaspecifikus definíciójában meghatározott perifériákra vannak leképezve.

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

Az Import (Importálások ) szakasz a fizikai tábla vagy modul hardverdefiníciós fájljának elérési útját tartalmazza.
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
A Perifériák szakasz a CoffeeMaker vezérlőfal perifériáit képezi le a megfelelő perifériákra egy táblán vagy modulon.
```
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
```
Name – a periféria alkalmazáskódban használt azonosítóját tartalmazza.

Leképezés – a tábla vagy modul hardverdefiníciós fájljában a perifériához használt azonosítót tartalmazza.

A kávéfőző következő verziója a MyBoardV2-ra épülhet. Egy új táblaspecifikus definícióval rendelkezik, amely perifériákkal rendelkezik, például MY_BOARD_V2_LED_ORANGE. Ezt a kávéfőző alkalmazásspecifikus definíciójának egy új implementációja importálná, amely COFFEEMAKER_STATUS_BREWING képez le erre az új narancssárga LED-re. A kávéfőző tényleges alkalmazáskódja változatlan marad.

Hasonlóképpen, az Azure Sphere-mintaalkalmazások által használt "sample_appliance.json" definíció új implementációja lehetővé teheti, hogy ezek a mintaalkalmazások változatlanul fussanak a MyBoardon.

Fejlécfájlok

A fejlécfájlok a hardverdefiníciókat tartalmazó JSON-fájlokból jönnek létre. Táblaspecifikus és alkalmazásspecifikus definíciókhoz is létre kell hoznia fejlécfájlokat.

Fejlécfájl létrehozásához használja az azsphere hardware-definition generate-header parancsot.

A fejlécfájl létrehozásához írja be a következő sort az Azure Sphere parancssorába. Cserélje le <filename> a elemet a JSON-fájl nevére.

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

A fájlnév.h fejlécfájl létrejön, és az inc/hw mappába kerül.

Írja be például a következő sort, hogy létrehozzon egy fejlécfájlt a JSON-fájlból.

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

Az alábbiakban a my_board.h fejlécfájl egy része látható:

#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
                   .
                   .
                   .

Megjegyzés Alapértelmezés szerint a generált fejlécfájl a fájlba inc/hwkerül, amelynek a bemeneti JSON-fájlt tartalmazó könyvtár alkönyvtárának kell lennie. Ha ez az alkönyvtár nem létezik, létrejön.

Most, hogy létrehozta a hardverdefiníciós JSON-fájlt és a hozzá tartozó fejlécfájlt, a célhardver-függőségek kezelése című témakörben találja az alkalmazásban való használatának lépéseit.

Megosztás a következőn keresztül: