代碼風格指南

HIDL 代碼樣式類似於 Android 框架中的 C++ 代碼，具有 4 個空格縮進和混合大小寫的文件名。包聲明、導入和文檔字符串與 Java 中的類似，只是稍作修改。

以下IFoo.hal和types.hal示例說明了 HIDL 代碼樣式，並提供了每個樣式詳細信息的快速鏈接（已省略IFooClientCallback.hal 、 IBar.hal和IBaz.hal ）。

hardware/interfaces/foo/1.0/IFoo.hal
/*
 * (License Notice)
 */

package android.hardware.foo@1.0;

import android.hardware.bar@1.0::IBar;

import IBaz;
import IFooClientCallback;

/**
 * IFoo is an interface that…
 */
interface IFoo {

    /**
     * This is a multiline docstring.
     *
     * @return result 0 if successful, nonzero otherwise.
     */
     foo() generates (FooStatus result);

    /**
     * Restart controller by power cycle.
     *
     * @param bar callback interface that…
     * @return result 0 if successful, nonzero otherwise.
     */
    powerCycle(IBar bar) generates (FooStatus result);

    /** Single line docstring. */
    baz();


    /**
     * The bar function.
     *
     * @param clientCallback callback after function is called
     * @param baz related baz object
     * @param data input data blob
     */
    bar(IFooClientCallback clientCallback,
        IBaz baz,
        FooData data);

};
hardware/interfaces/foo/1.0/types.hal
/*
 * (License Notice)
 */

package android.hardware.foo@1.0;

/** Replied status. */
enum Status : int32_t {
    OK,
    /* invalid arguments */
    ERR_ARG,
    /* note, no transport related errors */
    ERR_UNKNOWN = -1,
};

struct ArgData {
    int32_t[20]  someArray;
    vec<uint8_t> data;
};

命名約定

函數名、變量名和文件名應該是描述性的；避免過度縮寫。將首字母縮略詞視為單詞（例如，使用INfc代替INFC ）。

目錄結構和文件命名

目錄結構應如下所示：

  • ROOT-DIRECTORY
    • MODULE
      • SUBMODULE （可選，可以多於一層）
        • VERSION
          • Android.mk
          • I INTERFACE_1 .hal
          • I INTERFACE_2 .hal
          • …
          • I INTERFACE_N .hal
          • types.hal （可選）

在哪裡：

  • ROOT-DIRECTORY是：
    • 核心 HIDL 包的hardware/interfaces 。
    • vendor/ VENDOR /interfaces ，其中供應VENDOR是指 SoC 供應商或 OEM/ODM。
  • MODULE應該是一個描述子系統的小寫單詞（例如nfc ）。如果需要多個單詞，請使用嵌套SUBMODULE 。可以有不止一層嵌套。
  • VERSION應該與 Versions 中描述的版本完全相同（major.minor）。
  • I INTERFACE_X應該是接口名稱中的UpperCamelCase / PascalCase （例如INfc ），如接口名稱中所述。

例子：

  • hardware/interfaces
    • nfc
      • 1.0
        • Android.mk
        • INfc.hal
        • INfcClientCallback.hal
        • types.hal

注意：所有文件都必須具有不可執行的權限（在 Git 中）。

包名稱

包名稱必須使用以下完全限定名稱 (FQN)格式（稱為PACKAGE-NAME ）：

PACKAGE.MODULE[.SUBMODULE[.SUBMODULE[…]]]@VERSION

在哪裡：

  • PACKAGE是映射到ROOT-DIRECTORY的包。特別是， PACKAGE是：
    • android.hardware用於核心 HIDL 包（映射到hardware/interfaces ）。
    • vendor. VENDOR .hardware供應商包的vendor. VENDOR .hardware ，其中VENDOR指的是 SoC 供應商或 OEM/ODM（​​映射到vendor/ VENDOR /interfaces ）。
  • MODULE [. SUBMODULE [. SUBMODULE […]]]@ VERSION與目錄結構中描述的結構中的文件夾名稱完全相同。
  • 包名應該是小寫的。如果它們的長度超過一個單詞，則這些單詞應該用作子模塊或寫在snake_case中。
  • 不允許有空格。

FQN 始終用於包聲明中。

版本

版本應具有以下格式：

MAJOR.MINOR

MAJOR和MINOR版本都應該是一個整數。 HIDL 使用語義版本控制規則。

進口

導入具有以下三種格式之一：

  • 整包導入： import PACKAGE-NAME ;
  • 部分導入： import PACKAGE-NAME :: UDT ; （或者，如果導入的類型在同一個包中， import UDT ;
  • 僅類型導入： import PACKAGE-NAME ::types;

PACKAGE-NAME遵循Package names中的格式。當前包的types.hal （如果存在）會自動導入（不要顯式導入）。

完全限定名稱 (FQN)

僅在必要時對用戶定義的類型導入使用完全限定名稱。如果導入類型在同一個包中，則省略PACKAGE-NAME 。 FQN 不得包含空格。完全限定名稱的示例：

android.hardware.nfc@1.0::INfcClientCallback

在android.hardware.nfc@1.0下的另一個文件中，將上述接口稱為INfcClientCallback 。否則，僅使用完全限定名稱。

對導入進行分組和排序

在包聲明後（導入前）使用空行。每個導入應佔一行並且不應縮進。按以下順序對導入進行分組：

  1. 其他android.hardware包（使用完全限定的名稱）。
  2. 其他vendor. VENDOR包（使用完全限定的名稱）。
    • 每個供應商都應該是一個組。
    • 按字母順序排列供應商。
  3. 從同一包中的其他接口導入（使用簡單名稱）。

在組之間使用空行。在每個組內，按字母順序對導入進行排序。例子：

import android.hardware.nfc@1.0::INfc;
import android.hardware.nfc@1.0::INfcClientCallback;

/* Importing the whole module. */
import vendor.barvendor.bar@3.1;

import vendor.foovendor.foo@2.2::IFooBar;
import vendor.foovendor.foo@2.2::IFooFoo;

import IBar;
import IFoo;

接口名稱

接口名稱必須以I開頭，後跟UpperCamelCase / PascalCase名稱。名稱為IFoo的接口必須在文件IFoo.hal中定義。該文件只能包含IFoo接口的定義（接口I NAME應該在I NAME .hal ）。

功能

對於函數名稱、參數和返回變量名稱，請使用lowerCamelCase 。例子：

open(INfcClientCallback clientCallback) generates (int32_t retVal);
oneway pingAlive(IFooCallback cb);

結構/聯合字段名稱

對於結構/聯合字段名稱，請使用lowerCamelCase 。例子：

struct FooReply {
    vec<uint8_t> replyData;
}

類型名稱

類型名稱是指結構/聯合定義、枚舉類型定義和typedef 。對於這些名稱，請使用UpperCamelCase / PascalCase 。例子：

enum NfcStatus : int32_t {
    /*...*/
};
struct NfcData {
    /*...*/
};

枚舉值

枚舉值應該是UPPER_CASE_WITH_UNDERSCORES 。當將枚舉值作為函數參數傳遞並將它們作為函數返回時，請使用實際的枚舉類型（而不是底層整數類型）。例子：

enum NfcStatus : int32_t {
    HAL_NFC_STATUS_OK               = 0,
    HAL_NFC_STATUS_FAILED           = 1,
    HAL_NFC_STATUS_ERR_TRANSPORT    = 2,
    HAL_NFC_STATUS_ERR_CMD_TIMEOUT  = 3,
    HAL_NFC_STATUS_REFUSED          = 4
};

注意：枚舉類型的基礎類型在冒號之後顯式聲明。由於它不依賴於編譯器，因此使用實際的枚舉類型更加清晰。

對於枚舉值的完全限定名稱，在枚舉類型名稱和枚舉值名稱之間使用冒號：

PACKAGE-NAME::UDT[.UDT[.UDT[…]]:ENUM_VALUE_NAME

完全限定名稱中不能有空格。僅在必要時使用完全限定名稱並省略不必要的部分。例子：

android.hardware.foo@1.0::IFoo.IFooInternal.FooEnum:ENUM_OK

註釋

對於單行註釋， // 、 /* */和/** */都可以。

// This is a single line comment
/* This is also single line comment */
/** This is documentation comment */
  • 使用/* */進行註釋。雖然 HIDL 支持//用於註釋，但不鼓勵使用它們，因為它們不會出現在生成的輸出中。
  • 使用/** */生成文檔。這些只能應用於類型、方法、字段和枚舉值聲明。示例：
    /** Replied status */
enum TeleportStatus {
    /** Object entirely teleported. */
    OK              = 0,
    /** Methods return this if teleportation is not completed. */
    ERROR_TELEPORT  = 1,
    /**
     * Teleportation could not be completed due to an object
     * obstructing the path.
     */
    ERROR_OBJECT    = 2,
    ...
}
  • 以/**在單獨的行開始多行註釋。在每行的開頭使用* 。用*/在單獨的行結束註釋，對齊星號。示例：
    /**
 * My multi-line
 * comment
 */
  • 許可通知和變更日誌應以/* （單個星號）開始新的一行，在每行的開頭使用* ，並將*/單獨放在最後一行（星號應對齊）。示例：
    /*
 * Copyright (C) 2017 The Android Open Source Project
 * ...
 */

/*
 * Changelog:
 * ...
 */

文件評論

以適當的許可通知開始每個文件。對於核心 HAL，這應該是development/docs/copyright-templates/c.txt中的 AOSP Apache 許可證。請記住更新年份並使用/* */樣式的多行註釋，如上所述。

您可以選擇在許可證通知之後放置一個空行，然後是更改日誌/版本信息。如上所述使用/* */樣式的多行註釋，將空行放在更改日誌之後，然後跟隨包聲明。

待辦事項評論

TODO 應包含全部大寫的字符串TODO ，後跟冒號。例子：

// TODO: remove this code before foo is checked in.

僅在開發期間允許 TODO 註釋；它們不得存在於已發布的接口中。

接口/函數註釋（文檔字符串）

對多行和單行文檔字符串使用/** */ 。不要將//用於文檔字符串。

接口的文檔字符串應該描述接口的一般機制、設計原理、用途等。函數的文檔字符串應該特定於函數（包級文檔位於包目錄中的 README 文件中）。

/**
 * IFooController is the controller for foos.
 */
interface IFooController {
    /**
     * Opens the controller.
     *
     * @return status HAL_FOO_OK if successful.
     */
    open() generates (FooStatus status);

    /** Close the controller. */
    close();
};

您必須為每個參數/返回值添加@param和@return ：

  • 必須為每個參數添加@param 。它後面應該是參數的名稱，然後是文檔字符串。
  • @return必須為每個返回值添加。它後面應該是返回值的名稱，然後是文檔字符串。

例子：

/**
 * Explain what foo does.
 *
 * @param arg1 explain what arg1 is
 * @param arg2 explain what arg2 is
 * @return ret1 explain what ret1 is
 * @return ret2 explain what ret2 is
 */
foo(T arg1, T arg2) generates (S ret1, S ret2);

格式化

一般格式規則包括：

  • 線長。每行文本最多應為100列。
  • 空格。行上沒有尾隨空格；空行不能包含空格。
  • 空格與製表符。僅使用空格。
  • 縮進大小。塊使用4 個空格，換行使用8個空格
  • 支撐。除了註釋值之外，左大括號與前面的代碼在同一行，但右大括號和後面的分號佔據整行。示例：
    interface INfc {
    close();
};

包裝聲明

包聲明應該在許可通知之後的文件頂部，應該佔據整行，並且不應該縮進。使用以下格式聲明包（有關名稱格式，請參閱包名稱）：

package PACKAGE-NAME;

例子：

package android.hardware.nfc@1.0;

函數聲明

如果合適的話，函數名、參數、 generates和返回值應該在同一行。例子：

interface IFoo {
    /** ... */
    easyMethod(int32_t data) generates (int32_t result);
};

如果它們不適合在同一行，請嘗試將參數和返回值放在相同的縮進級別並區分generate ，以幫助讀者快速查看參數和返回值。例子：

interface IFoo {
    suchALongMethodThatCannotFitInOneLine(int32_t theFirstVeryLongParameter,
                                          int32_t anotherVeryLongParameter);
    anEvenLongerMethodThatCannotFitInOneLine(int32_t theFirstLongParameter,
                                             int32_t anotherVeryLongParameter)
                                  generates (int32_t theFirstReturnValue,
                                             int32_t anotherReturnValue);
    superSuperSuperSuperSuperSuperSuperLongMethodThatYouWillHateToType(
            int32_t theFirstVeryLongParameter, // 8 spaces
            int32_t anotherVeryLongParameter
        ) generates (
            int32_t theFirstReturnValue,
            int32_t anotherReturnValue
        );
    /* method name is even shorter than 'generates' */
    foobar(AReallyReallyLongType aReallyReallyLongParameter,
           AReallyReallyLongType anotherReallyReallyLongParameter)
        generates (ASuperLongType aSuperLongReturnValue, // 4 spaces
                   ASuperLongType anotherSuperLongReturnValue);
}

額外細節：

  • 左括號總是與函數名在同一行。
  • 函數名和左括號之間沒有空格。
  • 括號和參數之間沒有空格，除非它們之間有換行符。
  • 如果generates與前一個右括號在同一行，請使用前面的空格。如果generates與下一個左括號在同一行，請在後面加上一個空格。
  • 對齊所有參數和返回值（如果可能）。
  • 默認縮進為 4 個空格。
  • 包裝的參數與前一行的第一個參數對齊，否則它們有 8 個空格的縮進。

註釋

使用以下格式進行註釋：

@annotate(keyword = value, keyword = {value, value, value})

按字母順序對註釋進行排序，並在等號周圍使用空格。例子：

@callflow(key = value)
@entry
@exit

確保註釋佔據整行。例子：

/* Good */
@entry
@exit

/* Bad */
@entry @exit

如果註釋不能放在同一行，縮進 8 個空格。例子：

@annotate(
        keyword = value,
        keyword = {
                value,
                value
        },
        keyword = value)

如果整個值數組不能放在同一行中，請在大括號{和數組內的每個逗號之後放置換行符。在最後一個值之後立即放置右括號。如果只有一個值，請不要放置大括號。

如果整個值數組可以放在同一行中，請不要在左大括號之後和右大括號之前使用空格，並且在每個逗號之後使用一個空格。例子：

/* Good */
@callflow(key = {"val", "val"})

/* Bad */
@callflow(key = { "val","val" })

註釋和函數聲明之間不能有空行。例子：

/* Good */
@entry
foo();

/* Bad */
@entry

foo();

枚舉聲明

對枚舉聲明使用以下規則：

  • 如果枚舉聲明與另一個包共享，請將聲明放在types.hal中，而不是嵌入到接口中。
  • 在冒號之前和之後使用空格，在開括號之前的基礎類型之後使用空格。
  • 最後一個枚舉值可能有也可能沒有額外的逗號。

結構聲明

對結構聲明使用以下規則：

  • 如果結構聲明與另一個包共享，請將聲明放在types.hal中，而不是嵌入到接口中。
  • 在結構類型名稱之後，在左大括號之前使用一個空格。
  • 對齊字段名稱（可選）。示例：
    struct MyStruct {
    vec<uint8_t>   data;
    int32_t        someInt;
}

數組聲明

請勿在以下內容之間放置空格：

  • 元素類型和開方括號。
  • 打開方括號和數組大小。
  • 數組大小和右方括號。
  • 如果存在多個維度，則關閉方括號和下一個打開方括號。

例子：

/* Good */
int32_t[5] array;

/* Good */
int32_t[5][6] multiDimArray;

/* Bad */
int32_t [ 5 ] [ 6 ] array;

矢量圖

請勿在以下內容之間放置空格：

  • vec和開尖括號。
  • 打開尖括號和元素類型（例外：元素類型也是vec ）。
  • 元素類型和右尖括號（例外：元素類型也是vec ） 。

例子：

/* Good */
vec<int32_t> array;

/* Good */
vec<vec<int32_t>> array;

/* Good */
vec< vec<int32_t> > array;

/* Bad */
vec < int32_t > array;

/* Bad */
vec < vec < int32_t > > array;