程式碼樣式指南

HIDL 程式碼樣式類似於 Android 架構中的 C++ 程式碼，具有 4 個空格的縮排和大小寫混合的檔案名稱。套件宣告、匯入和文件字串與 Java 中的類似，但略有修改。

以下 IFoo.hal 和 types.hal 和 IFooClientCallback.hal 的範例，說明 HIDL 程式碼樣式，並提供各樣式詳細資料的快速連結 (已省略 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
          • IINTERFACE_1.hal
          • IINTERFACE_2.hal
          • …
          • IINTERFACE_N.hal
          • types.hal (非必要)

其中：

  • ROOT-DIRECTORY 是：
    • hardware/interfaces，適用於核心 HIDL 套件。
    • vendor/VENDOR/interfaces 供應商套件，其中 VENDOR 是指 SoC 供應商或 OEM/ODM。
  • MODULE 應為一個小寫單字，用來描述子系統 (例如 nfc)。如果需要多個單字，請使用巢狀 SUBMODULE。巢狀結構可有多個層級。
  • VERSION 應與「版本」一節所述的完全相同 (主要.次要)。
  • IINTERFACE_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 是指 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 遵循套件名稱的格式。系統會自動匯入目前套件的 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.hal 中必須定義名稱為 IFoo 的介面。這個檔案只能包含 IFoo 介面的定義 (介面 INAME 應位於 INAME.hal 中)。

函式

函式名稱、引數和傳回變數名稱請使用 lowerCamelCase。例子：

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

結構體和聯集欄位名稱

如果是 struct 或聯集欄位名稱，請使用 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，後接半形冒號。例子：

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

TODO 註解只能在開發期間使用，發布的介面中不得有這類註解。

介面和函式註解 (docstring)

使用 /** */ 處理多行和單行文件字串。請勿在文件字串中使用 //。

介面的 Docstring 應說明介面的一般機制、設計原理、用途等。函式的 Docstring 應專屬於該函式 (套件層級的文件會放在套件目錄的 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 欄。
  • 空白字元。行尾不得有空白字元；空白行不得包含空白字元。
  • 空格與 Tab 鍵。只能使用空格。
  • 縮排大小：區塊使用 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 中，而不是嵌入介面內。
  • 在冒號前後加上空格，並在基礎型別後方、左大括號前方加上空格。
  • 最後一個列舉值可能沒有額外的半形逗號。

結構體宣告

請使用下列結構體宣告規則：

  • 如果 struct 宣告會與其他套件共用，請將宣告放在 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;