[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-07-27 (世界標準時間)。"],[],[],null,["# Create the HAL interface\n\n| **Warning:** Android 10 deprecates the ConfigStore HAL and replaces the HAL with system properties. For details, refer to [Configuring](/docs/core/architecture/configuration).\n\nYou must use HIDL to describe all build flags used for conditionally\ncompiling the framework. Relevant build flags must be grouped and included in a\nsingle `.hal` file. Using HIDL for specifying configuration items\nincludes the following benefits:\n\n- Versioned (to add new config items, vendors/OEMs must explicitly extend the HAL)\n- Well-documented\n- Access control using SELinux\n- Sanity check for configuration items through the [Vendor Test\n Suite](/docs/core/tests/vts) (range check, inter-dependency check among items, etc.)\n- Auto-generated APIs in both C++ and Java\n\nIdentify build flags used by the framework\n------------------------------------------\n\nStart by identifying the build configs used to conditionally compile the\nframework, then abandon obsolete configs to make the set smaller. For example,\nthe following set of build flags are identified for `surfaceflinger`:\n\n- `TARGET_USES_HWC2`\n- `TARGET_BOARD_PLATFORM`\n- `TARGET_DISABLE_TRIPLE_BUFFERING`\n- `TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS`\n- `NUM_FRAMEBUFFER_SURFACE_BUFFERS`\n- `TARGET_RUNNING_WITHOUT_SYNC_FRAMEWORK`\n- `VSYNC_EVENT_PHASE_OFFSET_NS`\n- `SF_VSYNC_EVENT_PHASE_OFFSET_NS`\n- `PRESENT_TIME_OFFSET_FROM_VSYNC_NS`\n- `MAX_VIRTUAL_DISPLAY_DIMENSION`\n\nCreate a HAL interface\n----------------------\n\nBuild configs for a subsystem are accessed through a HAL interface, while\ninterfaces for giving configuration values are grouped in the HAL package\n`android.hardware.configstore` (currently at version 1.0).\nFor example, to create a HAL interface file for `surfaceflinger`, in\n`hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal`: \n\n```\npackage android.hardware.configstore@1.0;\n\ninterface ISurfaceFlingerConfigs {\n // TO-BE-FILLED-BELOW\n};\n```\n\nAfter creating the `.hal` file, run\n`hardware/interfaces/update-makefiles.sh` to add the new\n`.hal` file to the `Android.bp` and\n`Android.mk` files.\n\nAdd functions for build flags\n-----------------------------\n\nFor each build flag, add a new function to the interface. For example, in\n`hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal`: \n\n```\ninterface ISurfaceFlingerConfigs {\n disableTripleBuffering() generates(OptionalBool ret);\n forceHwcForVirtualDisplays() generates(OptionalBool ret);\n enum NumBuffers: uint8_t {\n USE_DEFAULT = 0,\n TWO = 2,\n THREE = 3,\n };\n numFramebufferSurfaceBuffers() generates(NumBuffers ret);\n runWithoutSyncFramework() generates(OptionalBool ret);\n vsyncEventPhaseOffsetNs generates (OptionalUInt64 ret);\n presentTimeOffsetFromSyncNs generates (OptionalUInt64 ret);\n maxVirtualDisplayDimension() generates(OptionalInt32 ret);\n};\n```\n\nWhen adding a function:\n\n- **Be concise with names.** Avoid converting makefile variable names into function names and keep in mind that `TARGET_` and `BOARD_` prefixes are no longer necessary.\n- **Add comments.** Help developers understand the purpose of the config item, how it changes framework behavior, valid values, and other relevant information.\n\nFunction return types can be\n`Optional[Bool|String|Int32|UInt32|Int64|UInt64]`. Types are defined\nin `types.hal` in the same directory and wrap primitive values with a\nfield that indicates if the value is specified by the HAL; if not, the default\nvalue is used. \n\n```\nstruct OptionalString {\n bool specified;\n string value;\n};\n```\n\nWhen appropriate, define the enum that best represents the type of the\nconfiguration item and use that enum as the return type. In the example above,\nthe `NumBuffers` enum is defined to limit the number of valid\nvalues. When defining such custom data types, add a field or a enum value (for\nexample, `USE_DEFAULT`) for denoting if the value is/isn't specified\nby the HAL.\n\nIt's not mandatory for a single build flag to become a single function in\nHIDL. Module owners can alternatively aggregate closely related build flags into\na struct and have a function that returns that struct (doing so can reduce\nnumber of function calls).\n\nFor example, an option for aggregating two build flags into a single struct\nin `hardware/interfaces/configstore/1.0/ISurfaceFlingerConfigs.hal`\nis: \n\n```\n interface ISurfaceFlingerConfigs {\n // other functions here\n struct SyncConfigs {\n OptionalInt64 vsyncEventPhaseoffsetNs;\n OptionalInt64 presentTimeoffsetFromSyncNs;\n };\n getSyncConfigs() generates (SyncConfigs ret);\n // other functions here\n};\n```\n\nAlternatives to a single HAL function\n-------------------------------------\n\nAs an alternative to using a single HAL function for all build flags, the HAL\ninterface also provides simple functions such as `getBoolean(string\nkey)` and `getInteger(string key)`. The actual\n`key=value` pairs are stored in separate files and the HAL service\nprovides values by reading/parsing those files.\n\nWhile this approach is easy to define, it doesn't include the benefits\nprovided by HIDL (enforced versioning, ease of documentation, access control)\nand is therefore not recommended.\n| **Note:** When using simple functions, access control is extremely difficult as the HAL cannot identify clients by itself.\n\nSingle and multiple interfaces\n------------------------------\n\nThe design of the HAL interface for configuration items presents two\nchoices:\n\n- A single interface that covers all configuration items\n- Multiple interfaces, each of which covers a set of related configuration items\n\nA single interface is easier but can become unmaintainable as more\nconfiguration items are added to the single file. In addition, access control\nisn't fine-grained, so a process that's granted access to the interface can read\nall configuration items (access to a partial set of configuration items can't be\ngranted). Alternatively, if access isn't granted, configuration items can't be\nread.\n\nBecause of these issues, Android uses multiple interfaces with a single HAL\ninterface for a group of related configuration items. For example,\n`ISurfaceflingerConfigs` for `surfaceflinger`-related\nconfiguration items, and `IBluetoothConfigs` for Bluetooth-related\nconfiguration items."]]
