이 문서에서는 실수로 인한 인터페이스 변경을 방지하고 인터페이스 변경사항을 철저하게 검사하는 메커니즘인 HIDL 인터페이스 해싱을 설명합니다.
HIDL 인터페이스는 버전이 지정되므로 이 메커니즘은 필수적입니다. 즉, 인터페이스가 릴리스된 후에는 댓글 수정 등의 애플리케이션 바이너리 인터페이스(ABI) 보존 방식을 제외하고는 변경해서는 안 됩니다.
레이아웃
모든 패키지 루트 디렉터리(예: android.hardware의 매핑 대상인 hardware/interfaces, 또는 vendor.foo의 매핑 대상인 vendor/foo/hardware/interfaces)에는 릴리스된 모든 HIDL 인터페이스 파일이 나열된 current.txt 파일이 포함되어야 합니다.
# current.txt files support comments starting with a '#' character# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt# Each line has a SHA-256 hash followed by the name of an interface.# They have been shortened in this doc for brevity but they are# 64 characters in length in an actual current.txt file.d4ed2f0e...995f9ec4vendor.awesome.foo@1.0::IFoo#commentscanalsogohere# types.hal files are also noted in current.txt filesc84da9f5...f8ea2648vendor.awesome.foo@1.0::types# Multiple hashes can be in the file for the same interface. This can be used# to note how ABI sustaining changes were made to the interface.# For instance, here is another hash for IFoo:# Fixes type where "FooCallback" was misspelled in comment on "FooStruct"822998d7...74d63b8cvendor.awesome.foo@1.0::IFoo
참고: 어떤 해시가 어디에서 왔는지 추적하기 위해 Google에서는 HIDL current.txt 파일을 여러 섹션으로 분리합니다. 첫 번째 섹션은 Android 8에서 릴리스됨이며 그다음 섹션은 Android 8 MR1에서 릴리스됨입니다. current.txt 파일에 있는 것과 유사한 레이아웃을 사용하는 것이 좋습니다.
hidl-gen을 사용한 해싱
수동으로 또는 hidl-gen을 사용하여 current.txt 파일에 해시를 추가할 수 있습니다. 다음 코드 스니펫은 hidl-gen과 함께 사용하여 current.txt 파일을 관리할 수 있는 명령어의 예시를 제공합니다(해시는 축약됨).
경고: 이전에 릴리스된 인터페이스의 해시를 교체하지 마세요. 인터페이스를 변경하는 경우 새 해시를 current.txt 파일 끝에 추가합니다. 자세한 내용은 ABI 안정성을 참조하세요.
hidl-gen을 통해 생성된 모든 인터페이스 정의 라이브러리에는 해시가 포함되며 이 해시는 IBase::getHashChain을 호출하여 검색할 수 있습니다. hidl-gen은 인터페이스를 컴파일할 때 HAL 패키지의 루트 디렉터리에 있는 current.txt 파일을 검사하여 HAL이 변경되었는지 확인합니다.
HAL에 해시가 없으면 인터페이스는 릴리스되지 않은 것(개발 중)으로 간주되고 컴파일이 진행됩니다.
해시가 발견되면 이를 현재 인터페이스와 비교합니다.
인터페이스가 해시와 일치하면 컴파일이 진행됩니다.
인터페이스가 해시와 일치하지 않으면 이전에 릴리스된 인터페이스가 변경되고 있음을 의미하므로 컴파일이 중단됩니다.
ABI가 보존되는 변경사항(ABI 안정성 참고)의 경우 current.txt 파일은 컴파일이 진행되기 전에 수정되어야 합니다.
다른 모든 변경사항은 인터페이스의 부 버전 또는 주 버전 업그레이드를 통해 이루어져야 합니다.
ABI 안정성
ABI는 바이너리 링크/호출 규칙 등을 포함합니다. ABI 또는 API가 변경되면 인터페이스가 공식 인터페이스로 컴파일된 일반 system.img를 지원하지 않습니다.
인터페이스의 버전이 지정되고 ABI 안정성이 확보되도록 하는 것이 중요한 이유는 다음과 같습니다.
구현이 공급업체 테스트 도구 모음(VTS)을 통과할 수 있고, 이에 따라 본격적으로 프레임워크 전용 OTA를 진행할 수 있습니다.
OEM으로서 사용하기 쉽고 규정을 준수하는 보드 서포트 패키지(BSP)를 제공할 수 있습니다.
이를 통해 릴리스될 수 있는 인터페이스를 추적할 수 있습니다. 패키지 루트에서 제공 중인 모든 인터페이스의 내역과 상태를 확인할 수 있는 인터페이스 디렉터리의 지도인 current.txt를 살펴보세요.
이미 current.txt에 항목이 있는 인터페이스에 새 해시를 추가할 때는 ABI 안정성을 유지하는 인터페이스를 나타내는 해시만 추가해야 합니다. 다음 변경 유형을 검토하세요.
허용되는 변경사항
댓글 변경(이 변경으로 인해 메서드의 의미가 변경되지 않는 경우에 한함)
매개변수의 이름 변경
반환 매개변수의 이름 변경
주석 변경
허용되지 않는 변경사항
인수, 메서드 등의 순서 재지정
인터페이스의 이름 변경 또는 새 패키지로 인터페이스 이동
패키지 이름 변경
인터페이스 내 임의의 위치에 메서드/구조체 필드 등 추가
C++ vtable을 깨뜨릴 수 있는 모든 변경사항
등
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-27(UTC)
[[["이해하기 쉬움","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(UTC)"],[],[],null,["# Interface hashing\n\nThis document describes HIDL interface hashing, a mechanism to prevent\naccidental interface changes and ensure interface changes are thoroughly vetted.\nThis mechanism is required because HIDL interfaces are versioned, which means\nthat after an interface is released it must not be changed except in an\napplication binary interface (ABI) preserving manner (such as a comment\ncorrection).\n\nLayout\n------\n\nEvery package root directory (i.e. `android.hardware` mapping to\n`hardware/interfaces` or `vendor.foo` mapping to\n`vendor/foo/hardware/interfaces`) must contain a\n`current.txt` file that lists all released HIDL interface files. \n\n```objective-c\n# current.txt files support comments starting with a '#' character\n# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt\n\n# Each line has a SHA-256 hash followed by the name of an interface.\n# They have been shortened in this doc for brevity but they are\n# 64 characters in length in an actual current.txt file.\nd4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here\n\n# types.hal files are also noted in current.txt files\nc84da9f5...f8ea2648 vendor.awesome.foo@1.0::types\n\n# Multiple hashes can be in the file for the same interface. This can be used\n# to note how ABI sustaining changes were made to the interface.\n# For instance, here is another hash for IFoo:\n\n# Fixes type where \"FooCallback\" was misspelled in comment on \"FooStruct\"\n822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo\n```\n\n**Note:** To help keep track of which hashes come\nfrom where, Google separates HIDL `current.txt` files into different\nsections: The first section is *Released in Android 8* ; the next section\nwill be *Released in Android 8 MR1* . We strongly recommend using a\nsimilar layout in your `current.txt` file.\n\nHash with hidl-gen\n------------------\n\nYou can add a hash to a `current.txt` file manually or by\nusing `hidl-gen`. The following code snippet provides examples of\ncommands you can use with `hidl-gen` to manage a\n`current.txt` file (hashes have been shortened): \n\n hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::types\n 9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types\n hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::INfc\n 07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc\n hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0\n 9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types\n 07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc\n f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback\n hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0 \u003e\u003e vendor/awesome/hardware/interfaces/current.txt\n\n**Warning:** Do not replace a hash for a\npreviously-released interface. When changing such an interface, add a new hash\nto the end of the `current.txt` file. For details, refer to\n[ABI stability](#abi-stability).\n\nEvery interface definition library generated by `hidl-gen`\nincludes hashes, which can be retrieved by calling\n`IBase::getHashChain`. When `hidl-gen` is compiling an\ninterface, it checks the `current.txt` file in the root directory of\nthe HAL package to see if the HAL has been changed:\n\n- If no hash for the HAL is found, the interface is considered unreleased (in development) and compilation proceeds.\n- If hashes are found, they are checked against the current interface:\n - If the interface does match the hash, compilation proceeds.\n - If the interface does not match a hash, compilation is halted as this means a previously-released interface is being changed.\n - For an ABI-preserving change (see [ABI stability](#abi-stability)), the `current.txt` file must be modified before compilation can proceed.\n - All other changes should be made in a minor or major version upgrade of the interface.\n\nABI stability\n-------------\n\n| **Key Point:** Please read and understand this section carefully.\n\nAn ABI includes the binary\nlinkages/calling conventions/etc. If the ABI or API changes, the interface no\nlonger works with a generic `system.img` that was compiled with\nofficial interfaces.\n\nMaking sure that interfaces are versioned and ABI stable is\n**crucial** for several reasons:\n\n- It ensures your implementation can pass the Vendor Test Suite (VTS), which puts you on track to being able to do framework-only OTAs.\n- As an OEM, it enables you to provide a Board Support Package (BSP) that is straightforward to use and compliant.\n- It helps you keep track of what interfaces can be released. Consider `current.txt` a map of an interfaces directory that allows you to see the history and state of all interfaces being provided in a package root.\n\nWhen adding a new hash for an interface that already has an entry in\n`current.txt`, make sure to add only the hashes that represent\ninterfaces which maintain ABI stability. Review the following types of changes:\n\n| Changes allowed | - Changing a comment (unless this changes the meaning of a method). - Changing the name of a parameter. - Changing the name of a return parameter. - Changing annotations. |\n| Changes not allowed | - Reordering arguments, methods, etc. - Renaming an interface or moving it to a new package. - Renaming a package. - Adding a method/struct field/etc. anywhere in the interface. - Anything that would break a C++ vtable. - etc. |\n|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|"]]
