Le style de code HIDL ressemble au code C++ du framework Android, avec quatre espaces retraits et noms de fichiers avec casse mixte. Déclarations, importations et docstrings de packages sont semblables à celles de Java, avec de légères modifications.
Les exemples suivants pour IFoo.hal
et types.hal
illustrer les styles de code HIDL et fournir des liens rapides vers des détails sur chaque style.
(IFooClientCallback.hal
, IBar.hal
et
IBaz.hal
ont été omis.
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; }; |
Conventions d'attribution de noms
Les noms de fonctions, de variables et de noms de fichiers doivent être descriptifs. éviter
sur l'abréviation. Traitez les acronymes comme des mots (par exemple, utilisez INfc
à la place).
sur INFC
).
Structure de répertoire et nommage de fichier
La structure de répertoires doit se présenter comme suit:
ROOT-DIRECTORY
MODULE
SUBMODULE
(facultatif, il peut y avoir plusieurs niveau) <ph type="x-smartling-placeholder">- </ph>
VERSION
Android.mk
IINTERFACE_1.hal
IINTERFACE_2.hal
…
IINTERFACE_N.hal
types.hal
(facultatif)
Où :
ROOT-DIRECTORY
est: <ph type="x-smartling-placeholder">- </ph>
hardware/interfaces
pour les packages HIDL de base.vendor/VENDOR/interfaces
pour les packages des fournisseurs oùVENDOR
fait référence à un fournisseur de SoC ou OEM/ODM.
MODULE
doit être un mot en minuscules décrivant le sous-système (par exemple,nfc
). Si plusieurs mots sont nécessaires, utilisezSUBMODULE
imbriqué. Il peut y avoir plusieurs niveaux ou l'imbrication.VERSION
doit correspondre exactement à la même version (major.minor), comme indiqué dans la section Versions.IINTERFACE_X
doit être le nom de l'interface avecUpperCamelCase
/PascalCase
(par exemple,INfc
) comme indiqué dans la section Noms d'interface.
Exemple :
hardware/interfaces
nfc
1.0
Android.mk
INfc.hal
INfcClientCallback.hal
types.hal
Remarque:Tous les fichiers doivent contenir des fichiers non exécutables (dans Git).
Noms des packages
Les noms de package doivent utiliser le nom complet suivant :
(FQN) (appelé PACKAGE-NAME
):
PACKAGE.MODULE[.SUBMODULE[.SUBMODULE[…]]]@VERSION
Où :
PACKAGE
est le package correspondant auROOT-DIRECTORY
En particulier,PACKAGE
est: <ph type="x-smartling-placeholder">- </ph>
android.hardware
pour les packages HIDL de base (mappé surhardware/interfaces
).vendor.VENDOR.hardware
pour les packages des fournisseurs, oùVENDOR
fait référence à un fournisseur de SoC ou à un OEM/ODM (mappage àvendor/VENDOR/interfaces
).
MODULE[.SUBMODULE[.SUBMODULE[…]]]@VERSION
sont exactement les mêmes noms de dossiers dans la structure décrite dans Structure des répertoires :- Les noms des packages doivent être en minuscules. S'ils comportent plusieurs mots, le
les mots doivent être utilisés comme sous-modules ou écrits dans
snake_case
. - Les espaces ne sont pas autorisés.
Le nom de domaine complet est toujours utilisé dans les déclarations de package.
Versions
Les versions doivent respecter le format suivant:
MAJOR.MINOR
Les versions MAJOR et MINOR doivent être uniques entier. HIDL utilise des de gestion des versions.
Importations
Une importation a l'un des trois formats suivants:
- Importations du package entier:
import PACKAGE-NAME;
- Importations partielles:
import PACKAGE-NAME::UDT;
(ou, si le fichier se trouve dans le même package,import UDT;
- Importations de types uniquement:
import PACKAGE-NAME::types;
PACKAGE-NAME
suit le format de
Noms des packages. Le package actuel
types.hal
(s'il existe) est importé automatiquement (ne pas importer)
explicitement).
Noms complets
N'utilisez des noms complets pour une importation de type défini par l'utilisateur qu'en cas de nécessité.
Omettez PACKAGE-NAME
si le type d'importation est le même
d'un package. Un nom de domaine complet ne doit pas contenir d'espaces. Exemple de nom complet:
android.hardware.nfc@1.0::INfcClientCallback
Dans un autre fichier, sous android.hardware.nfc@1.0
, reportez-vous au
ci-dessus en tant que INfcClientCallback
. Sinon, utilisez uniquement la
nom complet.
Regrouper et trier les importations
Utilisez une ligne vide après la déclaration du package (avant les importations). Chaque importation doit occuper une seule ligne et ne doit pas être en retrait. Les importations de groupes dans dans l'ordre suivant:
- Autres packages
android.hardware
(utilisez des noms complets). - Autres packages
vendor.VENDOR
(utilisez les formats complets noms).- Chaque fournisseur doit être un groupe.
- Classez les fournisseurs par ordre alphabétique.
- Importation depuis d'autres interfaces du même package (utilisez des noms simples).
Utilisez une ligne vide entre les groupes. Dans chaque groupe, trier les importations par ordre alphabétique. Exemple :
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;
Noms des interfaces
Les noms d'interface doivent commencer par I
, suivi d'un
Nom UpperCamelCase
/PascalCase
. Une interface portant un nom
IFoo
doit être défini dans le fichier IFoo.hal
. Ce fichier
ne peut contenir des définitions que pour l'interface IFoo
(interface
INAME
doit se trouver dans INAME.hal
).
Fonctions
Pour les noms de fonction, les arguments et les noms des variables de retour, utilisez
lowerCamelCase
Exemple :
open(INfcClientCallback clientCallback) generates (int32_t retVal); oneway pingAlive(IFooCallback cb);
Noms des champs de structure et d'union
Pour les noms de champs de structure ou d'union, utilisez lowerCamelCase
. Exemple :
struct FooReply { vec<uint8_t> replyData; }
Noms des types
Les noms de type font référence à des définitions de structure ou d'union, des définitions de type d'énumération et
typedef
s. Pour ces noms, utilisez
UpperCamelCase
/PascalCase
. Exemples:
enum NfcStatus : int32_t { /*...*/ }; struct NfcData { /*...*/ };
Valeurs enum
Les valeurs enum doivent être UPPER_CASE_WITH_UNDERSCORES
. Lors de la transmission
en tant qu'arguments de fonction et en les renvoyant sous forme de résultats de fonction, utilisez
le type d'énumération réel (pas le type d'entier sous-jacent). Exemple :
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 };
Remarque:Le type sous-jacent d'un type d'énumération est déclaré explicitement après les deux-points. Comme il n'est pas dépendant d'un compilateur, l'utilisation de la classe le type d'énumération réel est plus clair.
Pour les noms complets des valeurs enum, le signe deux-points est utilisé. entre le nom du type d'énumération et le nom de la valeur d'énumération:
PACKAGE-NAME::UDT[.UDT[.UDT[…]]:ENUM_VALUE_NAME
Le nom complet ne doit pas contenir d'espaces. Utilisez un nom complet nom uniquement si nécessaire et omettez les parties inutiles. Exemple :
android.hardware.foo@1.0::IFoo.IFooInternal.FooEnum:ENUM_OK
Commentaires
Pour un commentaire sur une seule ligne, //
, /* */
et /** */
sont acceptés.
// This is a single line comment /* This is also single line comment */ /** This is documentation comment */
-
Utilisez
/* */
pour les commentaires. Alors que HIDL prend en charge//
pour les commentaires, ils sont déconseillés car ils n'apparaissent pas dans la sortie générée. - Utilisez
/** */
pour la documentation générée. Ceux-ci peuvent être appliqués uniquement pour les déclarations de type, de méthode, de champ et de valeur d'énumération. Exemple :/** 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, ... }
- Commencez les commentaires sur plusieurs lignes par
/**
sur une ligne distincte. Utilisez*
au début de chaque ligne. Terminez le commentaire par*/
sur une ligne distincte, en alignant les astérisques. Exemple :/** * My multi-line * comment */
- La notification de licence et les journaux de modifications doivent commencer par une nouvelle ligne avec
/*
(un seul astérisque), utilisez*
au début de chaque ligne et placez*/
, tout seul sur la dernière ligne (les astérisques doivent s'aligner). Exemple :/* * Copyright (C) 2017 The Android Open Source Project * ... */ /* * Changelog: * ... */
Commentaires sur le fichier
Commencez chaque fichier par la mention de licence appropriée. Pour les HAL principales,
doit être la licence Apache AOSP
development/docs/copyright-templates/c.txt
N'oubliez pas de modifier l'année et d'utiliser des commentaires multilignes de style /* */
comme expliqué ci-dessus.
Vous pouvez éventuellement placer une ligne vide après la notification de licence, suivie
par des informations de journal de
modifications/de gestion des versions. Utiliser le style /* */
comme expliqué ci-dessus, placez la ligne vide après la balise
journal des modifications, puis suivez
la déclaration de package.
TODO de commentaires
Les tâches à effectuer doivent inclure la chaîne TODO
tout en majuscules, suivie d'un
deux-points. Exemple :
// TODO: remove this code before foo is checked in.
Les commentaires TODO ne sont autorisés que pendant le développement. il doit n'existent pas dans les interfaces publiées.
Commentaires sur l'interface et la fonction (docstrings)
Utilisez /** */
pour les docstrings multilignes et monolignes. Ne pas utiliser
//
pour les docstrings.
Les Docstrings pour les interfaces doivent décrire les mécanismes généraux l'interface, la logique de conception, l'objectif, etc. Les Docstrings pour les fonctions doivent être spécifique à la fonction (la documentation au niveau du paquet se trouve dans un fichier README le répertoire du package).
/** * 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(); };
Vous devez ajouter des éléments @param
et @return
pour chacun
paramètre/valeur renvoyée:
- Vous devez ajouter
@param
pour chaque paramètre. Il doit s'agir suivi du nom du paramètre, puis de la docstring. @return
doit être ajouté pour chaque valeur renvoyée. Il doit être suivi du nom de la valeur renvoyée, puis de la docstring.
Exemple :
/** * 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);
Règles de mise en forme
Les règles générales de mise en forme incluent les suivantes:
- Longueur de ligne. Chaque ligne de texte ne doit pas dépasser 100 colonnes
- Espaces blancs : Aucun espace blanc final sur les lignes lignes vides ne doit pas contenir d'espaces blancs.
- Espaces ou onglets : N'utilisez que des espaces.
- Taille du retrait : Utilisez 4 espaces pour les blocs et 8 espaces pour les retours à la ligne
- Braces : À l'exception des annotations
, une accolade open s'ajoute à la ligne précédente
mais une accolade fermante et le point-virgule suivant occupent
toute la ligne. Exemple :
interface INfc { close(); };
Déclaration de colis
La déclaration de package doit se trouver en haut du fichier, après la licence doit occuper toute la ligne et ne doit pas être en retrait. Les packages sont déclaré à l'aide du format suivant (pour en savoir plus sur la mise en forme du nom, consultez Noms des packages):
package PACKAGE-NAME;
Exemple :
package android.hardware.nfc@1.0;
Déclarations de fonction
Le nom de la fonction, les paramètres, generates
et les valeurs de retour doivent
être sur la même ligne
s’ils s’adaptent. Exemple :
interface IFoo { /** ... */ easyMethod(int32_t data) generates (int32_t result); };
S'ils ne tiennent pas sur la même ligne, essayez de placer des paramètres et de renvoyer
valeurs au même niveau de retrait et à distinguer generate
pour
au lecteur de voir rapidement les paramètres
et les valeurs renvoyées. Exemple :
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); }
Informations supplémentaires :
- Une parenthèse ouverte se trouve toujours sur la même ligne que le nom de la fonction.
- Aucun espace entre le nom de la fonction et la parenthèse ouverte.
- Pas d'espace entre les parenthèses et les paramètres, sauf lorsqu'il existe sont des sauts de ligne entre eux.
- Si
generates
se trouve sur la même ligne que la ligne de fermeture précédente parenthèse, utilisez un espace qui précède. Sigenerates
est identique comme parenthèse suivante, faites suivre d’un espace. - Alignez tous les paramètres et les valeurs renvoyées (si possible).
- Le retrait par défaut est de 4 espaces.
- Les paramètres encapsulés sont alignés sur les premiers paramètres de la ligne précédente, sinon, ils ont un retrait de 8 espaces.
Annotations
Utilisez le format suivant pour les annotations:
@annotate(keyword = value, keyword = {value, value, value})
Triez les annotations par ordre alphabétique et utilisez des espaces autour des signes égal. Exemple :
@callflow(key = value) @entry @exit
S'assurer qu'une annotation occupe la totalité de la ligne. Exemples :
/* Good */ @entry @exit /* Bad */ @entry @exit
Si les annotations ne peuvent pas tenir sur la même ligne, mettez en retrait 8 espaces. Exemple :
@annotate( keyword = value, keyword = { value, value }, keyword = value)
Si le tableau de valeurs entier ne peut pas tenir sur la même ligne, placez des sauts de ligne après
accolades {
et après chaque virgule dans le tableau. Fermeture du lieu
parenthèse juste après la dernière valeur. Ne mettez pas d'accolades s'il y a
une seule valeur.
Si le tableau de valeurs entier peut tenir sur la même ligne, n'utilisez pas d'espaces après les accolades ouvertes et avant les accolades fermantes, et utilisez un espace après chaque virgule. Exemples :
/* Good */ @callflow(key = {"val", "val"}) /* Bad */ @callflow(key = { "val","val" })
Il ne doit PAS y avoir de lignes vides entre les annotations et la fonction. la déclaration. Exemples :
/* Good */ @entry foo(); /* Bad */ @entry foo();
Déclarations d'énumération
Utilisez les règles suivantes pour les déclarations d'énumération:
- Si les déclarations d'énumération sont partagées avec un autre package, placez-les
dans
types.hal
plutôt que d'être intégré dans une interface. - Utilisez un espace avant et après les deux-points, et un espace après le type sous-jacent avant l'accolade ouvrante.
- Il est possible que la dernière valeur d'énumération ne comporte pas de virgule supplémentaire.
Déclarations de structure
Utilisez les règles suivantes pour les déclarations struct:
- Si les déclarations struct sont partagées avec un autre package, placez les déclarations
dans
types.hal
plutôt que d'être intégré dans une interface. - Ajoutez un espace après le nom du type de structure avant l'accolade ouvrante.
- Aligne les noms des champs (facultatif). Exemple :
struct MyStruct { vec<uint8_t> data; int32_t someInt; }
Déclarations de tableau
N'insérez pas d'espaces entre les éléments suivants:
- Type d'élément et crochet ouvert.
- Crochet ouvert et taille du tableau.
- Taille du tableau et crochet fermant
- Crochet fermé et crochet ouvrant suivant, s'il y en a plusieurs existe.
Exemples :
/* Good */ int32_t[5] array; /* Good */ int32_t[5][6] multiDimArray; /* Bad */ int32_t [ 5 ] [ 6 ] array;
Vecteurs
N'insérez pas d'espaces entre les éléments suivants:
vec
et chevron ouvert.- Crochet ouvrant et type d'élément (Exception: le type d'élément est également
vec
). - Type d'élément et chevron fermant (Exception: le type d'élément est également
vec
).
Exemples :
/* 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;