वर्शन

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

एचआईडीएल कोड संरचना

HIDL कोड उपयोगकर्ता-परिभाषित प्रकारों, इंटरफेस और पैकेजों में व्यवस्थित होता है:

  • उपयोगकर्ता-परिभाषित प्रकार (यूडीटी) । HIDL आदिम डेटा प्रकारों के एक सेट तक पहुँच प्रदान करता है जिसका उपयोग संरचनाओं, यूनियनों और गणनाओं के माध्यम से अधिक जटिल प्रकारों की रचना के लिए किया जा सकता है। यूडीटी इंटरफेस के तरीकों के लिए पारित कर रहे हैं, और एक पैकेज के स्तर पर (सभी इंटरफेस के लिए आम) या स्थानीय रूप से एक इंटरफेस के लिए परिभाषित किया जा सकता है।
  • इंटरफेस । HIDL के बुनियादी निर्माण खंड के रूप में, एक इंटरफ़ेस में UDT और विधि घोषणाएँ होती हैं। इंटरफेस दूसरे इंटरफेस से भी इनहेरिट कर सकते हैं।
  • पैकेज । संबंधित एचआईडीएल इंटरफेस और डेटा प्रकारों को व्यवस्थित करता है जिस पर वे काम करते हैं। एक पैकेज को एक नाम और एक संस्करण द्वारा पहचाना जाता है और इसमें निम्नलिखित शामिल होते हैं:
    • डेटा-प्रकार परिभाषा फ़ाइल जिसे types.hal कहा जाता है।
    • शून्य या अधिक इंटरफ़ेस, प्रत्येक की अपनी .hal फ़ाइल में।

डेटा-प्रकार परिभाषा फ़ाइल types.hal में केवल UDTs होते हैं (सभी पैकेज-स्तरीय UDTs को एक फ़ाइल में रखा जाता है)। पैकेज में सभी इंटरफेस के लिए लक्ष्य भाषा में प्रतिनिधित्व उपलब्ध हैं।

संस्करण दर्शन

एक एचआईडीएल पैकेज (जैसे android.hardware.nfc ), किसी दिए गए संस्करण (जैसे 1.0 ) के लिए प्रकाशित होने के बाद अपरिवर्तनीय है; इसे बदला नहीं जा सकता। पैकेज में इंटरफेस में संशोधन या इसके यूडीटी में कोई भी बदलाव केवल दूसरे पैकेज में ही हो सकता है।

एचआईडीएल में, वर्जनिंग पैकेज स्तर पर लागू होती है, इंटरफेस स्तर पर नहीं, और पैकेज में सभी इंटरफेस और यूडीटी समान संस्करण साझा करते हैं। पैकेज संस्करण पैच स्तर और बिल्ड-मेटाडेटा घटकों के बिना सिमेंटिक वर्जनिंग का पालन करते हैं। किसी दिए गए पैकेज के भीतर, एक मामूली संस्करण बम्प का अर्थ है कि पैकेज का नया संस्करण पुराने पैकेज के साथ पीछे की ओर संगत है और एक प्रमुख संस्करण बंप का अर्थ है कि पैकेज का नया संस्करण पुराने पैकेज के साथ संगत नहीं है।

वैचारिक रूप से, एक पैकेज दूसरे पैकेज से कई तरीकों से संबंधित हो सकता है:

  • बिलकुल नहीं ।
  • पैकेज-स्तर पश्चगामी-संगत एक्स्टेंसिबिलिटी । यह एक पैकेज के नए लघु-संस्करण uprevs (अगले वृद्धिशील संशोधन) के लिए होता है; नए पैकेज का वही नाम और प्रमुख संस्करण है जो पुराने पैकेज का है, लेकिन एक उच्चतर लघु संस्करण है। कार्यात्मक रूप से, नया पैकेज पुराने पैकेज का सुपरसेट है, जिसका अर्थ है:
    • पेरेंट पैकेज के शीर्ष-स्तरीय इंटरफेस नए पैकेज में मौजूद हैं, हालांकि इंटरफेस में नए तरीके, नए इंटरफेस-स्थानीय यूडीटी (नीचे वर्णित इंटरफ़ेस-स्तरीय एक्सटेंशन), ​​और नए यूडीटी types.hal में हो सकते हैं।
    • नए पैकेज में नए इंटरफेस भी जोड़े जा सकते हैं।
    • पेरेंट पैकेज के सभी डेटा प्रकार नए पैकेज में मौजूद हैं और पुराने पैकेज से (संभवतः पुन: कार्यान्वित) विधियों द्वारा नियंत्रित किया जा सकता है।
    • नए डेटा प्रकारों को या तो उन्नत मौजूदा इंटरफेस के नए तरीकों या नए इंटरफेस द्वारा उपयोग के लिए जोड़ा जा सकता है।
  • इंटरफ़ेस-स्तर पश्चगामी-संगत एक्स्टेंसिबिलिटी । नया पैकेज तार्किक रूप से अलग इंटरफेस से मिलकर मूल पैकेज का विस्तार भी कर सकता है जो केवल अतिरिक्त कार्यक्षमता प्रदान करता है, न कि मूल। इस प्रयोजन के लिए, निम्नलिखित वांछनीय हो सकते हैं:
    • नए पैकेज में इंटरफेस को पुराने पैकेज के डेटा प्रकारों का सहारा लेना होगा।
    • नए पैकेज में इंटरफेस एक या अधिक पुराने पैकेजों के इंटरफेस का विस्तार कर सकते हैं।
  • मूल पिछड़ा-असंगति बढ़ाएँ । यह पैकेज का एक प्रमुख संस्करण है और दोनों के बीच कोई संबंध होने की आवश्यकता नहीं है। जहां तक ​​है, इसे पैकेज के पुराने संस्करण के प्रकारों के संयोजन और पुराने पैकेज इंटरफेस के सबसेट की विरासत के साथ व्यक्त किया जा सकता है।

संरचना इंटरफेस

एक अच्छी तरह से संरचित इंटरफ़ेस के लिए, नए प्रकार की कार्यक्षमता जोड़ने जो मूल डिज़ाइन का हिस्सा नहीं हैं, उन्हें HIDL इंटरफ़ेस में संशोधन की आवश्यकता होनी चाहिए। इसके विपरीत, यदि आप इंटरफ़ेस के दोनों किनारों पर परिवर्तन करने की अपेक्षा कर सकते हैं या कर सकते हैं जो इंटरफ़ेस को बदले बिना नई कार्यक्षमता का परिचय देता है, तो इंटरफ़ेस संरचित नहीं है।

ट्रेबल अलग-अलग संकलित विक्रेता और सिस्टम घटकों का समर्थन करता है जिसमें किसी डिवाइस पर विक्रेता.आईएमजी और vendor.img को अलग से संकलित system.img जा सकता है। वेंडर. vendor.img और system.img के बीच सभी इंटरैक्शन स्पष्ट रूप से और पूरी तरह से परिभाषित होने चाहिए ताकि वे कई वर्षों तक काम करना जारी रख सकें। इसमें कई एपीआई सतहें शामिल हैं, लेकिन एक प्रमुख सतह IPC तंत्र है जो vendor.img system.img / विक्रेता.img सीमा पर इंटरप्रोसेस संचार के लिए उपयोग करता है।

आवश्यकताएं

एचआईडीएल के माध्यम से पारित सभी डेटा को स्पष्ट रूप से परिभाषित किया जाना चाहिए। एक कार्यान्वयन सुनिश्चित करने के लिए और क्लाइंट अलग से संकलित या स्वतंत्र रूप से विकसित होने पर भी एक साथ काम करना जारी रख सकता है, डेटा को निम्नलिखित आवश्यकताओं का पालन करना चाहिए:

  • अर्थ नाम और अर्थ के साथ सीधे एचआईडीएल में वर्णित किया जा सकता है (स्ट्रक्चर एनम आदि का उपयोग करके)।
  • सार्वजनिक मानक जैसे ISO/IEC 7816 द्वारा वर्णित किया जा सकता है।
  • हार्डवेयर मानक या हार्डवेयर के भौतिक लेआउट द्वारा वर्णित किया जा सकता है।
  • यदि आवश्यक हो तो अपारदर्शी डेटा (जैसे सार्वजनिक कुंजी, आईडी, आदि) हो सकता है।

यदि अपारदर्शी डेटा का उपयोग किया जाता है, तो इसे केवल HIDL इंटरफ़ेस के एक तरफ से पढ़ा जाना चाहिए। उदाहरण के लिए, यदि विक्रेता. vendor.img कोड system.img पर एक स्ट्रिंग संदेश या vec<uint8_t> डेटा पर एक घटक देता है, तो उस डेटा को system.img द्वारा पार्स नहीं किया जा सकता है; व्याख्या करने के लिए इसे केवल विक्रेता. vendor.img को वापस भेजा जा सकता है। system.img या किसी अन्य डिवाइस पर वेंडर. vendor.img से वेंडर कोड में कोई मान पास करते समय, डेटा का प्रारूप और इसकी व्याख्या कैसे की जानी चाहिए, इसका सटीक वर्णन किया जाना चाहिए और यह अभी भी इंटरफ़ेस का हिस्सा है ।

दिशा-निर्देश

आपको केवल .hal फ़ाइलों का उपयोग करके एचएएल के कार्यान्वयन या क्लाइंट को लिखने में सक्षम होना चाहिए (यानी आपको एंड्रॉइड स्रोत या सार्वजनिक मानकों को देखने की आवश्यकता नहीं होनी चाहिए)। हम सटीक आवश्यक व्यवहार निर्दिष्ट करने की अनुशंसा करते हैं। "एक कार्यान्वयन ए या बी कर सकता है" जैसे कथन कार्यान्वयन को उन ग्राहकों के साथ जुड़ने के लिए प्रोत्साहित करते हैं जिनके साथ वे विकसित होते हैं।

एचआईडीएल कोड लेआउट

HIDL में कोर और वेंडर पैकेज शामिल हैं।

कोर एचआईडीएल इंटरफेस वे हैं जो Google द्वारा निर्दिष्ट किए गए हैं। वे पैकेज जो वे android.hardware. और सबसिस्टम द्वारा नामित हैं, संभावित रूप से नामकरण के नेस्टेड स्तरों के साथ। उदाहरण के लिए, NFC पैकेज का नाम android.hardware.nfc है और कैमरा पैकेज android.hardware.camera है। सामान्य तौर पर, एक कोर पैकेज का नाम android.hardware. [ name1 ]। [ name2 ]…। एचआईडीएल पैकेज में उनके नाम के अतिरिक्त एक संस्करण भी होता है। उदाहरण के लिए, पैकेज android.hardware.camera संस्करण 3.4 पर हो सकता है; यह महत्वपूर्ण है, क्योंकि पैकेज का संस्करण स्रोत ट्री में इसके स्थान को प्रभावित करता है।

सभी कोर पैकेज hardware/interfaces/ बिल्ड सिस्टम में रखे गए हैं। पैकेज android.hardware. [ name1 ].[ name2 ]… संस्करण में $m.$n hardware/interfaces/name1/name2/ … /$m.$n/ के अंतर्गत है; पैकेज android.hardware.camera संस्करण 3.4 निर्देशिका hardware/interfaces/camera/3.4/. पैकेज उपसर्ग android.hardware. और पथ hardware/interfaces/ .

गैर-कोर (विक्रेता) पैकेज वे हैं जो एसओसी विक्रेता या ओडीएम द्वारा उत्पादित होते हैं। गैर-कोर पैकेज के लिए उपसर्ग vendor.$(VENDOR).hardware. जहां $(VENDOR) एक SoC विक्रेता या OEM/ODM को संदर्भित करता है। यह पथ vendor/$(VENDOR)/interfaces के लिए मानचित्र करता है (यह मानचित्रण भी हार्ड-कोडित है)।

पूरी तरह से योग्य उपयोगकर्ता-परिभाषित-प्रकार के नाम

एचआईडीएल में, प्रत्येक यूडीटी का एक पूर्ण-योग्य नाम होता है जिसमें यूडीटी नाम, पैकेज का नाम जहां यूडीटी परिभाषित होता है, और पैकेज संस्करण होता है। पूर्ण-योग्य नाम का उपयोग केवल तभी किया जाता है जब प्रकार के उदाहरण घोषित किए जाते हैं और न कि जहां प्रकार स्वयं परिभाषित होता है। उदाहरण के लिए, पैकेज android.hardware.nfc, संस्करण 1.0 NfcData नामक एक संरचना को परिभाषित करता है। घोषणा की साइट पर (चाहे types.hal में या किसी इंटरफ़ेस की घोषणा के भीतर), घोषणा में केवल यह कहा गया है:

struct NfcData {
    vec<uint8_t> data;
};

इस प्रकार का उदाहरण घोषित करते समय (चाहे डेटा संरचना के भीतर या विधि पैरामीटर के रूप में), पूर्ण-योग्य प्रकार के नाम का उपयोग करें:

android.hardware.nfc@1.0::NfcData

सामान्य वाक्यविन्यास PACKAGE @ VERSION :: UDT है, जहां:

  • PACKAGE एक एचआईडीएल पैकेज का डॉट-सेपरेटेड नाम है (उदाहरण के लिए, android.hardware.nfc )।
  • VERSION पैकेज का डॉट-सेपरेटेड major.minor-version स्वरूप है (उदा., 1.0 )।
  • UDT एक HIDL UDT का डॉट-सेपरेटेड नाम है। चूंकि एचआईडीएल नेस्टेड यूडीटी का समर्थन करता है और एचआईडीएल इंटरफेस में यूडीटी (एक प्रकार का नेस्टेड घोषणा) हो सकता है, नामों तक पहुंचने के लिए डॉट्स का उपयोग किया जाता है।

उदाहरण के लिए, यदि निम्न नेस्टेड घोषणा पैकेज android.hardware.example संस्करण 1.0 में सामान्य प्रकार फ़ाइल में परिभाषित किया गया था:

// types.hal
package android.hardware.example@1.0;
struct Foo {
    struct Bar {
        // …
    };
    Bar cheers;
};

Bar का पूर्णतः योग्य नाम android.hardware.example@1.0::Foo.Bar है। यदि, उपरोक्त पैकेज में होने के अलावा, नेस्टेड घोषणा IQuux नामक इंटरफ़ेस में थी:

// IQuux.hal
package android.hardware.example@1.0;
interface IQuux {
    struct Foo {
        struct Bar {
            // …
        };
        Bar cheers;
    };
    doSomething(Foo f) generates (Foo.Bar fb);
};

Bar का पूर्ण-योग्य नाम android.hardware.example@1.0::IQuux.Foo.Bar है।

दोनों ही मामलों में, Bar को केवल Foo की घोषणा के दायरे में Bar के रूप में संदर्भित किया जा सकता है। पैकेज या इंटरफ़ेस स्तर पर, आपको Bar को Foo के माध्यम से संदर्भित करना होगा: Foo.Bar , जैसा कि विधि की घोषणा में है doSomething ऊपर। वैकल्पिक रूप से, आप विधि को अधिक मौखिक रूप से घोषित कर सकते हैं:

// IQuux.hal
doSomething(android.hardware.example@1.0::IQuux.Foo f) generates (android.hardware.example@1.0::IQuux.Foo.Bar fb);

पूरी तरह से योग्य गणना मूल्य

यदि एक यूडीटी एक एनम प्रकार है, तो एनम प्रकार के प्रत्येक मूल्य में एक पूर्ण-योग्य नाम होता है जो एनम प्रकार के पूर्ण-योग्य नाम से शुरू होता है, उसके बाद एक कोलन होता है, उसके बाद एनम वैल्यू का नाम होता है। उदाहरण के लिए, पैकेज android.hardware.nfc, संस्करण 1.0 एक एनम प्रकार NfcStatus को परिभाषित करता है:

enum NfcStatus {
    STATUS_OK,
    STATUS_FAILED
};

STATUS_OK का जिक्र करते समय, पूर्णतः योग्य नाम है:

android.hardware.nfc@1.0::NfcStatus:STATUS_OK

सामान्य वाक्यविन्यास PACKAGE @ VERSION :: UDT : VALUE है, जहां:

  • PACKAGE @ VERSION :: UDT एनम प्रकार के लिए पूरी तरह से योग्य नाम है।
  • VALUE मान का नाम है।

स्वत: अनुमान नियम

एक पूर्ण-योग्य UDT नाम को निर्दिष्ट करने की आवश्यकता नहीं है। एक UDT नाम निम्नलिखित को सुरक्षित रूप से छोड़ सकता है:

  • पैकेज, जैसे @1.0::IFoo.Type
  • पैकेज और संस्करण दोनों, जैसे IFoo.Type

HIDL ऑटो-हस्तक्षेप नियमों का उपयोग करके नाम को पूरा करने का प्रयास करता है (निचला नियम संख्या का अर्थ उच्च प्राथमिकता है)।

नियम 1

यदि कोई पैकेज और संस्करण प्रदान नहीं किया गया है, तो स्थानीय नाम देखने का प्रयास किया जाता है। उदाहरण:

interface Nfc {
    typedef string NfcErrorMessage;
    send(NfcData d) generates (@1.0::NfcStatus s, NfcErrorMessage m);
};

NfcErrorMessage को स्थानीय रूप से देखा जाता है, और इसके ऊपर typedef पाया जाता है। NfcData को स्थानीय रूप से भी देखा जाता है, लेकिन चूंकि इसे स्थानीय रूप से परिभाषित नहीं किया जाता है, इसलिए नियम 2 और 3 का उपयोग किया जाता है। @1.0::NfcStatus एक संस्करण प्रदान करता है, इसलिए नियम 1 लागू नहीं होता है।

नियम 2

यदि नियम 1 विफल हो जाता है और पूर्ण-योग्य नाम का एक घटक गायब है (पैकेज, संस्करण, या पैकेज और संस्करण), तो घटक वर्तमान पैकेज की जानकारी से स्वतः भर जाता है। एचआईडीएल कंपाइलर तब वर्तमान फ़ाइल (और सभी आयातों) में स्वत: पूर्ण-योग्य नाम खोजने के लिए देखता है। उपरोक्त उदाहरण का उपयोग करते हुए, मान लें कि ExtendedNfcData की घोषणा उसी पैकेज ( android.hardware.nfc ) में उसी संस्करण ( 1.0 ) में NfcData के रूप में की गई थी, जो निम्नानुसार है:

struct ExtendedNfcData {
    NfcData base;
    // … additional members
};

HIDL कंपाइलर वर्तमान पैकेज से पैकेज का नाम और संस्करण का नाम भरता है ताकि पूरी तरह से योग्य UDT नाम android.hardware.nfc@1.0::NfcData । जैसा कि नाम वर्तमान पैकेज में मौजूद है (यह मानते हुए कि इसे ठीक से आयात किया गया है), इसका उपयोग घोषणा के लिए किया जाता है।

वर्तमान पैकेज में एक नाम केवल तभी आयात किया जाता है जब निम्न में से कोई एक सत्य हो:

  • यह स्पष्ट रूप से एक import विवरण के साथ आयात किया जाता है।
  • इसे वर्तमान पैकेज में types.hal में परिभाषित किया गया है

उसी प्रक्रिया का पालन किया जाता है यदि NfcData केवल संस्करण संख्या द्वारा योग्य था:

struct ExtendedNfcData {
    // autofill the current package name (android.hardware.nfc)
    @1.0::NfcData base;
    // … additional members
};

नियम 3

यदि नियम 2 एक मैच बनाने में विफल रहता है (यूडीटी को वर्तमान पैकेज में परिभाषित नहीं किया गया है), तो एचआईडीएल कंपाइलर सभी आयातित पैकेजों के भीतर एक मैच के लिए स्कैन करता है। उपरोक्त उदाहरण का उपयोग करते हुए, मान लें कि ExtendedNfcData पैकेज android.hardware.nfc के संस्करण 1.1 में घोषित किया गया है, 1.1 आयात 1.0 जैसा होना चाहिए ( पैकेज-स्तर एक्सटेंशन देखें), और परिभाषा केवल यूडीटी नाम निर्दिष्ट करती है:

struct ExtendedNfcData {
    NfcData base;
    // … additional members
};

कंपाइलर NfcData नाम के किसी भी UDT की तलाश करता है और android.hardware.nfc संस्करण 1.0 में एक ढूंढता है, जिसके परिणामस्वरूप android.hardware.nfc@1.0::NfcData का पूर्ण-योग्य UDT प्राप्त होता है। यदि किसी दिए गए आंशिक रूप से योग्य UDT के लिए एक से अधिक मैच मिलते हैं, तो HIDL कंपाइलर एक त्रुटि फेंकता है।

उदाहरण

नियम 2 का उपयोग करते हुए, वर्तमान पैकेज में परिभाषित एक आयातित प्रकार को किसी अन्य पैकेज से आयातित प्रकार पर पसंद किया जाता है:

// hardware/interfaces/foo/1.0/types.hal
package android.hardware.foo@1.0;
struct S {};

// hardware/interfaces/foo/1.0/IFooCallback.hal
package android.hardware.foo@1.0;
interface IFooCallback {};

// hardware/interfaces/bar/1.0/types.hal
package android.hardware.bar@1.0;
typedef string S;

// hardware/interfaces/bar/1.0/IFooCallback.hal
package android.hardware.bar@1.0;
interface IFooCallback {};

// hardware/interfaces/bar/1.0/IBar.hal
package android.hardware.bar@1.0;
import android.hardware.foo@1.0;
interface IBar {
    baz1(S s); // android.hardware.bar@1.0::S
    baz2(IFooCallback s); // android.hardware.foo@1.0::IFooCallback
};
  • S को android.hardware.bar@1.0::S के रूप में प्रक्षेपित किया गया है, और bar/1.0/types.hal में पाया जाता है (क्योंकि types.hal स्वचालित रूप से आयात किया जाता है)।
  • IFooCallback को android.hardware.bar@1.0::IFooCallback के रूप में नियम 2 का उपयोग करके प्रक्षेपित किया गया है, लेकिन इसे नहीं पाया जा सकता क्योंकि bar/1.0/IFooCallback.hal स्वचालित रूप से आयात नहीं किया जाता है (जैसा कि types.hal है)। इस प्रकार, नियम 3 इसे इसके बजाय android.hardware.foo@1.0::IFooCallback पर हल करता है, जिसे import android.hardware.foo@1.0; )

प्रकार.हाली

प्रत्येक HIDL पैकेज में एक types.hal फ़ाइल होती है जिसमें UDTs होते हैं जो उस पैकेज में भाग लेने वाले सभी इंटरफेस के बीच साझा किए जाते हैं। HIDL प्रकार हमेशा सार्वजनिक होते हैं; इस बात की परवाह किए बिना कि UDT को types.hal में घोषित किया गया है या इंटरफ़ेस घोषणा के भीतर, ये प्रकार उस दायरे से बाहर पहुंच योग्य हैं जहां उन्हें परिभाषित किया गया है। types.hal एक पैकेज के सार्वजनिक एपीआई का वर्णन करने के लिए नहीं है, बल्कि पैकेज के भीतर सभी इंटरफेस द्वारा उपयोग किए जाने वाले यूडीटी को होस्ट करने के लिए है। एचआईडीएल की प्रकृति के कारण, सभी यूडीटी इंटरफेस का हिस्सा हैं।

types.hal में यूडीटी और import विवरण शामिल हैं। क्योंकि types.hal पैकेज के प्रत्येक इंटरफ़ेस के लिए उपलब्ध कराया गया है (यह एक अंतर्निहित आयात है), ये import विवरण परिभाषा के अनुसार पैकेज-स्तर हैं। types.hal में यूडीटी में यूडीटी और इस प्रकार आयात किए गए इंटरफेस भी शामिल हो सकते हैं।

उदाहरण के लिए, IFoo.hal के लिए:

package android.hardware.foo@1.0;
// whole package import
import android.hardware.bar@1.0;
// types only import
import android.hardware.baz@1.0::types;
// partial imports
import android.hardware.qux@1.0::IQux.Quux;
// partial imports
import android.hardware.quuz@1.0::Quuz;

निम्नलिखित आयात किए जाते हैं:

  • android.hidl.base@1.0::IBase (अंतर्निहित)
  • android.hardware.foo@1.0::types (निहित रूप से)
  • android.hardware.bar@1.0 में सब कुछ (सभी इंटरफेस और इसके types.hal सहित)
  • android.hardware.baz@1.0 android.hardware.baz@1.0::types से types.hal (Android.hardware.baz@1.0 में इंटरफेस आयात नहीं किए जाते हैं)
  • android.hardware.qux@1.0 . से IQux.hal और types.hal
  • android.hardware.quuz@1.0 से Quuz (माना जाता है कि Quuz को Quuz में परिभाषित किया गया है, संपूर्ण types.hal फ़ाइल को पार्स किया जाता है, लेकिन types.hal के अलावा अन्य प्रकार आयात नहीं किए Quuz हैं)।

इंटरफ़ेस-स्तरीय संस्करण

पैकेज के भीतर प्रत्येक इंटरफ़ेस अपनी फ़ाइल में रहता है। इंटरफ़ेस जिस पैकेज से संबंधित है, उसे package स्टेटमेंट का उपयोग करके इंटरफ़ेस के शीर्ष पर घोषित किया जाता है। पैकेज घोषणा के बाद, शून्य या अधिक इंटरफ़ेस-स्तरीय आयात (आंशिक या संपूर्ण-पैकेज) सूचीबद्ध हो सकते हैं। उदाहरण के लिए:

package android.hardware.nfc@1.0;

HIDL में, extends कीवर्ड का उपयोग करके इंटरफेस अन्य इंटरफेस से इनहेरिट कर सकते हैं। एक इंटरफ़ेस के लिए दूसरे इंटरफ़ेस का विस्तार करने के लिए, उसे एक import विवरण के माध्यम से उस तक पहुंच होनी चाहिए। इंटरफ़ेस का नाम बढ़ाया जा रहा है (आधार इंटरफ़ेस) ऊपर वर्णित प्रकार-नाम योग्यता के नियमों का पालन करता है। एक इंटरफ़ेस केवल एक इंटरफ़ेस से इनहेरिट कर सकता है; HIDL एकाधिक वंशानुक्रम का समर्थन नहीं करता है।

नीचे दिए गए uprev संस्करण उदाहरण निम्नलिखित पैकेज का उपयोग करते हैं:

// types.hal
package android.hardware.example@1.0
struct Foo {
    struct Bar {
        vec<uint32_t> val;
    };
};

// IQuux.hal
package android.hardware.example@1.0
interface IQuux {
    fromFooToBar(Foo f) generates (Foo.Bar b);
}

उप्रेव नियम

पैकेज को परिभाषित करने के लिए package@major.minor , या तो A या सभी B सत्य होना चाहिए:

नियम ए "एक शुरुआत मामूली संस्करण है": पिछले सभी छोटे संस्करण, package@major.0 , package@major.1 , …, package@major.(minor-1) को परिभाषित नहीं किया जाना चाहिए।
या
नियम बी

निम्नलिखित में से सभी सत्य हैं:

  1. "पिछला छोटा संस्करण मान्य है": package@major.(minor-1) को परिभाषित किया जाना चाहिए और उसी नियम A (पैकेज@ package@major.0 में से कोई भी package@major.(minor-2) परिभाषित नहीं है) या नियम B का पालन करना चाहिए। (यदि यह @major.(minor-2) से एक uprev है);

    तथा

  2. "एक ही नाम के साथ कम से कम एक इंटरफ़ेस प्राप्त करें": एक इंटरफ़ेस package@major.minor::IFoo मौजूद है जो package@major.(minor-1)::IFoo (यदि पिछले पैकेज में एक इंटरफ़ेस है);

    तथा

  3. "एक अलग नाम के साथ कोई विरासत में मिला इंटरफ़ेस नहीं": वहाँ package@major.minor::IBar मौजूद नहीं होना चाहिए जो package@major.(minor-1)::IBaz , जहां IBar और IBaz दो अलग-अलग नाम हैं। यदि समान नाम वाला कोई इंटरफ़ेस है, package@major.minor::IBar को package@major.(minor-k)::IBar का विस्तार करना चाहिए ताकि छोटे k के साथ कोई IBar मौजूद न हो।

नियम ए के कारण:

  • पैकेज किसी भी छोटे संस्करण संख्या से शुरू हो सकता है (उदाहरण के लिए, android.hardware.biometrics.fingerprint @2.1 से शुरू होता है।)
  • आवश्यकता " android.hardware.foo@1.0 परिभाषित नहीं है" का अर्थ है निर्देशिका hardware/interfaces/foo/1.0 भी मौजूद नहीं होना चाहिए।

हालांकि, नियम ए समान पैकेज नाम वाले पैकेज को प्रभावित नहीं करता है, लेकिन एक अलग प्रमुख संस्करण (उदाहरण के लिए, android.hardware.camera.device में @1.0 और @3.2 दोनों परिभाषित हैं; @3.2 को @1.0 के साथ इंटरैक्ट करने की आवश्यकता नहीं है। ।) इसलिए, @3.2::IExtFoo @1.0::IFoo बढ़ा सकता है।

बशर्ते पैकेज का नाम अलग हो, package@major.minor::IBar एक अलग नाम के साथ एक इंटरफ़ेस से विस्तारित हो सकता है (उदाहरण के लिए, android.hardware.bar@1.0::IBar android.hardware.baz@2.2::IBaz विस्तार कर सकता है) ) यदि कोई इंटरफ़ेस स्पष्ट रूप से extend कीवर्ड के साथ सुपर टाइप घोषित नहीं करता है, तो यह android.hidl.base@1.0::IBase ( IBase को छोड़कर) का विस्तार करेगा।

B.2 और B.3 का एक ही समय में पालन किया जाना चाहिए। उदाहरण के लिए, भले ही android.hardware.foo@1.1::IFoo , android.hardware.foo@1.0::IFoo को नियम B.2 पास करने के लिए बढ़ाता है, यदि कोई android.hardware.foo@1.1::IExtBar android.hardware.foo@1.0::IBar , यह अभी भी मान्य uprev नहीं है।

इंटरफेस को ऊपर उठाना

android.hardware.example@1.0 (ऊपर परिभाषित) से @1.1 तक बढ़ाने के लिए:

// types.hal
package android.hardware.example@1.1;
import android.hardware.example@1.0;

// IQuux.hal
package android.hardware.example@1.1
interface IQuux extends @1.0::IQuux {
    fromBarToFoo(Foo.Bar b) generates (Foo f);
}

यह types.hal में android.hardware.example के संस्करण 1.0 का पैकेज-स्तरीय import है। जबकि पैकेज के संस्करण 1.1 में कोई नया यूडीटी नहीं जोड़ा गया है, संस्करण 1.0 में यूडीटी के संदर्भ अभी भी आवश्यक हैं, इसलिए types.hal में पैकेज-स्तरीय आयात। (वही प्रभाव IQuux.hal में एक इंटरफ़ेस-स्तरीय आयात के साथ प्राप्त किया जा सकता था।)

IQuux की घोषणा में extends @1.0::IQuux के विस्तार में, हमने IQuux के संस्करण को IQuux किया है जो विरासत में मिला है (बहुविकल्पी की आवश्यकता है क्योंकि IQuux का उपयोग एक इंटरफ़ेस घोषित करने और एक इंटरफ़ेस से इनहेरिट करने के लिए किया जाता है)। चूंकि घोषणाएं केवल नाम हैं जो घोषणा की साइट पर सभी पैकेज और संस्करण विशेषताओं को प्राप्त करते हैं, असंबद्धता आधार इंटरफ़ेस के नाम पर होनी चाहिए; हम पूरी तरह से योग्य यूडीटी का भी इस्तेमाल कर सकते थे, लेकिन यह बेमानी होता।

नया इंटरफ़ेस IQuux विधि को फिर से घोषित नहीं करता है fromFooToBar() यह @1.0::IQuux से विरासत में मिला है; यह बस उस नई विधि को सूचीबद्ध करता है जो इसे fromBarToFoo() जोड़ता है। HIDL में, इनहेरिट की गई विधियों को चाइल्ड इंटरफेस में फिर से घोषित नहीं किया जा सकता है, इसलिए IQuux इंटरफ़ेस fromFooToBar() विधि को स्पष्ट रूप से घोषित नहीं कर सकता है।

उप्रेव सम्मेलन

कभी-कभी इंटरफ़ेस नामों को विस्तारित इंटरफ़ेस का नाम बदलना चाहिए। हम अनुशंसा करते हैं कि एनम एक्सटेंशन, स्ट्रक्चर और यूनियनों का वही नाम है जो वे विस्तारित करते हैं जब तक कि वे एक नए नाम की गारंटी देने के लिए पर्याप्त रूप से भिन्न न हों। उदाहरण:

// in parent hal file
enum Brightness : uint32_t { NONE, WHITE };

// in child hal file extending the existing set with additional similar values
enum Brightness : @1.0::Brightness { AUTOMATIC };

// extending the existing set with values that require a new, more descriptive name:
enum Color : @1.0::Brightness { HW_GREEN, RAINBOW };

यदि किसी विधि का एक नया शब्दार्थ नाम हो सकता है (उदाहरण के लिए fooWithLocation ) तो उसे प्राथमिकता दी जाती है। अन्यथा, इसका नाम उसी के समान होना चाहिए जिसका वह विस्तार कर रहा है। उदाहरण के लिए, विधि foo_1_1 @1.1::IFoo में foo विधि की कार्यक्षमता को @1.0::IFoo में बदल सकती है यदि कोई बेहतर वैकल्पिक नाम नहीं है।

पैकेज-स्तरीय संस्करण

एचआईडीएल संस्करण पैकेज स्तर पर होता है; पैकेज प्रकाशित होने के बाद, यह अपरिवर्तनीय है (इसके इंटरफेस और यूडीटी के सेट को बदला नहीं जा सकता है)। पैकेज एक-दूसरे से कई तरीकों से संबंधित हो सकते हैं, जिनमें से सभी इंटरफेस-स्तरीय विरासत के संयोजन और संरचना द्वारा यूडीटी के निर्माण के माध्यम से व्यक्त किए जा सकते हैं।

हालांकि, एक प्रकार का संबंध कड़ाई से परिभाषित है और इसे लागू किया जाना चाहिए: पैकेज-स्तर पश्चगामी-संगत विरासत । इस परिदृश्य में, पेरेंट पैकेज वह पैकेज है जिससे इनहेरिट किया जा रहा है और चाइल्ड पैकेज वह है जो पैरेंट को विस्तारित कर रहा है। पैकेज-स्तर पश्च-संगत वंशानुक्रम नियम इस प्रकार हैं:

  1. पेरेंट पैकेज के सभी शीर्ष-स्तरीय इंटरफेस चाइल्ड पैकेज में इंटरफेस से विरासत में मिले हैं।
  2. नए इंटरफेस को नया पैकेज भी जोड़ा जा सकता है (अन्य पैकेजों में अन्य इंटरफेस के संबंधों के बारे में कोई प्रतिबंध नहीं)।
  3. नए डेटा प्रकारों को या तो उन्नत मौजूदा इंटरफेस के नए तरीकों या नए इंटरफेस द्वारा उपयोग के लिए जोड़ा जा सकता है।

इन नियमों को HIDL इंटरफ़ेस-स्तरीय वंशानुक्रम और UDT संरचना का उपयोग करके लागू किया जा सकता है, लेकिन इन संबंधों को जानने के लिए मेटा-स्तरीय ज्ञान की आवश्यकता होती है जो एक पश्च-संगत पैकेज एक्सटेंशन का गठन करते हैं। इस ज्ञान का अनुमान इस प्रकार है:

यदि कोई पैकेज इस आवश्यकता को पूरा करता है, hidl-gen पश्च-संगतता नियमों को लागू करता है।