इंटरफ़ेस हैशिंग

इस दस्तावेज़ में एचआईडीएल इंटरफ़ेस की हैशिंग के बारे में बताया गया है. इसे रोकने के लिए एक तरीका अपनाया जाता है इंटरफ़ेस में गलती से बदलाव होते हैं और इससे यह पक्का होता है कि इंटरफ़ेस में किए गए बदलावों की पूरी तरह से जांच की गई है. यह तरीका इसलिए ज़रूरी है, क्योंकि HIDL इंटरफ़ेस के वर्शन वाले हैं. इसका मतलब है कि कि किसी इंटरफ़ेस के रिलीज़ होने के बाद उसे बदला नहीं जाना चाहिए ऐप्लिकेशन बाइनरी इंटरफ़ेस (एबीआई) से सुरक्षित रखने का तरीका (जैसे, कोई टिप्पणी) सुधार).

लेआउट

हर पैकेज रूट डायरेक्ट्री (जैसे, android.hardware को मैप करना) hardware/interfaces या vendor.foo को मैप किया जा रहा है vendor/foo/hardware/interfaces) में current.txt फ़ाइल, जिसमें रिलीज़ की गई सभी HIDL इंटरफ़ेस फ़ाइलें शामिल हैं.

# 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 8 में रिलीज़ किया गया है; अगले सेक्शन में इसे Android 8 MR1 में रिलीज़ किया जाएगा. हमारा सुझाव है कि आप आपकी current.txt फ़ाइल में मिलता-जुलता लेआउट.

hidl-gen के साथ हैश

current.txt फ़ाइल में मैन्युअल तरीके से हैश जोड़ा जा सकता है. hidl-gen का इस्तेमाल करके. नीचे दिया गया कोड स्निपेट उन निर्देशों का इस्तेमाल करें जिन्हें 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 फ़ाइल के आखिर में जोड़ें. जानकारी के लिए, इसे देखें एबीआई की स्थिरता.

हर इंटरफ़ेस डेफ़िनिशन लाइब्रेरी, जिसे hidl-gen से जनरेट किया गया है इसमें हैश शामिल होते हैं, जिन्हें कॉल करके वापस लाया जा सकता है IBase::getHashChain. जब hidl-gen किसी कंपाइलेशन के लिए इंटरफ़ेस बनाता है. यह इसकी रूट डायरेक्ट्री में current.txt फ़ाइल की जांच करता है HAL पैकेज देखकर यह पता लगाया जा सकता है कि HAL में बदलाव हुआ है या नहीं:

• अगर एचएएल के लिए कोई हैश नहीं मिलता है, तो इंटरफ़ेस को रिलीज़ नहीं किया गया माना जाता है ( डेवलपमेंट) और कंपाइलेशन के नतीजों के बारे में बताया गया है.
• अगर हैश मिलते हैं, तो मौजूदा इंटरफ़ेस के हिसाब से उनकी जांच की जाती है:
  • अगर इंटरफ़ेस हैश से मेल खाता है, तो कंपाइलेशन जारी रहता है.
  • अगर इंटरफ़ेस किसी हैश से मैच नहीं होता है, तो कंपाइलेशन को रोक दिया जाता है. ऐसा इसलिए, क्योंकि पहले से रिलीज़ किए गए इंटरफ़ेस में बदलाव किया जा रहा है.
    • एबीआई के नियमों से जुड़े बदलाव के बारे में जानने के लिए (देखें एबीआई स्टेबिलिटी), current.txt फ़ाइल कंपाइलेशन आगे बढ़ने से पहले संशोधित किया जाना चाहिए.
    • अन्य सभी बदलाव, इंटरफ़ेस पर कॉपी करने की सुविधा मिलती है.

एबीआई की स्थिरता

अहम जानकारी: कृपया पढ़ें और समझें सेक्शन को ध्यान से पढ़ें.

एबीआई में बाइनरी शामिल होती है लिंकेज/कॉलिंग कन्वेंशन/वगैरह. अगर एबीआई या एपीआई में बदलाव होता है, तो इंटरफ़ेस नंबर लंबे समय तक, ऐसे सामान्य system.img के साथ काम करता है जिसे कंपाइल किया गया हो आधिकारिक इंटरफ़ेस हो जाते हैं.

यह पक्का करना कि इंटरफ़ेस के वर्शन और एबीआई स्थिर हैं इसकी कई वजहें हो सकती हैं:

• इससे यह पक्का होता है कि आपका लागू करने पर, वेंडर टेस्ट सुइट (वीटीएस) को पास किया जा सकता है, जो इससे आपको सिर्फ़ फ़्रेमवर्क पर आधारित ओटीए बनाने में मदद मिलती है.
• OEM के तौर पर, यह आपको बोर्ड सपोर्ट पैकेज (बीएसपी) उपलब्ध कराता है इस्तेमाल करने में आसान और नियमों का पालन करने वाला.
• इससे आपको रिलीज़ किए जा सकने वाले इंटरफ़ेस को ट्रैक करने में मदद मिलती है. इन बातों पर ध्यान दें उस इंटरफ़ेस डायरेक्ट्री का मैप current.txt जिसे देखने की अनुमति है किसी पैकेज रूट में दिए जा रहे सभी इंटरफ़ेस का इतिहास और स्थिति.

किसी ऐसे इंटरफ़ेस के लिए नया हैश जोड़ने पर जिसमें पहले से एंट्री मौजूद है current.txt, पक्का करें कि सिर्फ़ वे हैश जोड़े गए हों जिनसे ऐसे इंटरफ़ेस जो एबीआई की स्थिरता बनाए रखते हैं. इस तरह के बदलावों की समीक्षा करें:

बदलाव करने की अनुमति है	टिप्पणी बदलना (जब तक कि इससे किसी टिप्पणी का मतलब नहीं बदलता). किसी पैरामीटर का नाम बदलना. रिटर्न पैरामीटर का नाम बदलना. एनोटेशन बदले जा रहे हैं.
बदलाव करने की अनुमति नहीं है	आर्ग्युमेंट, तरीकों वगैरह को फिर से क्रम में लगाना. इंटरफ़ेस का नाम बदलना या उसे किसी नए पैकेज में ले जाना. पैकेज का नाम बदला जा रहा है. कोई तरीका/निर्देश फ़ील्ड/वगैरह जोड़ना. का इस्तेमाल करें. ऐसी कोई भी चीज़ जिससे C++ व्यू टेबल खराब हो सकती है. इत्यादि.