인터페이스 해싱

이 문서에서는 실수로 인한 인터페이스 변경을 방지하고 인터페이스 변경사항을 철저하게 검사하는 메커니즘인 HIDL 인터페이스 해싱을 설명합니다. HIDL 인터페이스는 버전이 지정되므로 이 메커니즘은 필수적입니다. 즉, 인터페이스가 릴리스된 후에는 댓글 수정 등의 ABI(Application Binary Interface) 보존 방식을 제외하고는 변경해서는 안 됩니다.

레이아웃

모든 패키지 루트 디렉터리(예: 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...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here

# types.hal files are also noted in current.txt files
c84da9f5...f8ea2648 vendor.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...74d63b8c vendor.awesome.foo@1.0::IFoo

참고: 어떤 해시가 어디에서 왔는지 추적하기 위해 Google에서는 HIDL current.txt 파일을 여러 섹션으로 분리합니다. 첫 번째 섹션은 Android O에서 릴리스됨이며 그다음 섹션은 Android O MR1에서 릴리스됨입니다. current.txt 파일에 있는 것과 유사한 레이아웃을 사용하는 것이 좋습니다.

hidl-gen을 사용한 해싱

수동으로 또는 hidl-gen을 사용하여 current.txt 파일에 해시를 추가할 수 있습니다. 다음 코드 스니펫은 hidl-gen과 함께 사용하여 current.txt 파일을 관리할 수 있는 명령어의 예시를 제공합니다(해시는 축약됨).

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
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
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
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
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
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback
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 >> vendor/awesome/hardware/interfaces/current.txt

경고: 이전에 릴리스된 인터페이스의 해시를 교체하지 마세요. 인터페이스를 변경하는 경우 새 해시를 current.txt 파일 끝에 추가합니다. 자세한 내용은 ABI 안정성을 참조하세요.

hidl-gen을 통해 생성된 모든 인터페이스 정의 라이브러리에는 해시가 포함되며 이 해시는 IBase::getHashChain을 호출하여 검색할 수 있습니다. hidl-gen은 인터페이스를 컴파일할 때 HAL 패키지의 루트 디렉터리에 있는 current.txt 파일을 검사하여 HAL이 변경되었는지 확인합니다.

HAL에 해시가 없으면 인터페이스는 릴리스되지 않은 것(개발 중)으로 간주되고 컴파일이 진행됩니다.
해시가 발견되면 이를 현재 인터페이스와 비교합니다.
- 인터페이스가 해시와 일치하면 컴파일이 진행됩니다.
- 인터페이스가 해시와 일치하지 않으면 이전에 릴리스된 인터페이스가 변경되고 있음을 의미하므로 컴파일이 중단됩니다.
  - ABI가 보존되는 변경사항(ABI 안정성 참고)의 경우 current.txt 파일은 컴파일이 진행되기 전에 수정되어야 합니다.
  - 다른 모든 변경사항은 인터페이스의 부 버전 또는 주 버전 업그레이드를 통해 이루어져야 합니다.

ABI 안정성

ABI(Application Binary Interface)는 바이너리 링크/호출 규칙 등을 포함합니다. ABI/API가 변경되면 인터페이스가 공식 인터페이스로 컴파일된 일반 system.img를 지원하지 않습니다.

인터페이스의 버전이 지정되고 ABI 안정성이 확보되도록 하는 것이 중요한 이유는 다음과 같습니다.

구현이 공급업체 테스트 도구 모음(VTS)을 통과할 수 있고, 이에 따라 본격적으로 프레임워크 전용 OTA를 진행할 수 있습니다.
OEM으로서 사용하기 쉽고 규정을 준수하는 보드 서포트 패키지(BSP)를 제공할 수 있습니다.
이를 통해 릴리스될 수 있는 인터페이스를 추적할 수 있습니다. 패키지 루트에서 제공 중인 모든 인터페이스의 내역과 상태를 확인할 수 있는 인터페이스 디렉터리의 지도인 current.txt를 살펴보세요.

이미 current.txt에 항목이 있는 인터페이스에 새 해시를 추가할 때는 ABI 안정성을 유지하는 인터페이스를 나타내는 해시만 추가해야 합니다. 다음 변경 유형을 검토하세요.

허용되는 변경사항	댓글 변경(이 변경으로 인해 메서드의 의미가 변경되지 않는 경우에 한함) 매개변수의 이름 변경 반환 매개변수의 이름 변경 주석 변경
허용되지 않는 변경사항	인수, 메서드 등의 순서 재지정 인터페이스의 이름 변경 또는 새 패키지로 인터페이스 이동 패키지 이름 변경 인터페이스 내 임의의 위치에 메서드/구조체 필드 등 추가 C++ vtable을 깨뜨릴 수 있는 모든 변경사항 기타