인터페이스 해싱

이 문서에서는 실수로 인한 인터페이스 변경을 방지하고 인터페이스 변경사항을 철저하게 검사하는 메커니즘인 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을 깨뜨릴 수 있는 모든 변경사항
  • 기타