Google is committed to advancing racial equity for Black communities. See how.
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

代碼樣式指南

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

以下IFoo.haltypes.hal示例說明了HIDL代碼樣式,並提供了指向每種樣式的詳細信息的快速鏈接( IFooClientCallback.halIBar.halIBaz.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/ 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是:
    • 用於核心HIDL包的android.hardware (映射到hardware/interfaces )。
    • vendor. VENDOR .hardware供應商軟件包的vendor. VENDOR .hardware ,其中VENDOR指SoC供應商或OEM / ODM(映射到vendor/ VENDOR /interfaces )。
  • MODULE [. SUBMODULE [. SUBMODULE […]]]@ VERSION是在結構上完全相同的文件夾名稱中描述的目錄結構
  • 軟件包名稱應為小寫。如果它們的長度超過一個字,則應將這些字用作子模塊或用snake_case編寫。
  • 不允許有空格。

FQN始終在包聲明中使用。

版本號

版本應具有以下格式:

MAJOR.MINOR

MAJORMINOR版本均應為單個整數。 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接口的定義(接口I NAME應該在I NAME .hal )。

功能

對於函數名稱,參數和返回變量名稱,請使用lowerCamelCase 。例:

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

結構/聯合字段名稱

對於struct / union字段名稱,請使用lowerCamelCase 。例:

struct FooReply {
    vec<uint8_t> replyData;
}

類型名稱

類型名稱指的是struct / union定義,枚舉類型定義和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許可。請記住要更新年份,並使用/* */樣式的多行註釋,如上所述。

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

TODO評論

TODO應在所有大寫字母中包括字符串TODO ,後跟冒號。例:

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

僅在開發期間才允許TODO註釋;它們一定不能存在於已發布的接口中。

接口/功能註釋(文檔字符串)

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

接口的文檔字符串應描述接口的一般機制,設計原理,用途等。函數的文檔字符串應特定於函數(軟件包級文檔位於package目錄的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而不是嵌入接口中。
  • 在冒號之前和之後使用空格,在基本類型之後在開括號之前使用空格。
  • 最後一個枚舉值可以有也可以沒有逗號。

結構聲明

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

  • 如果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;