שידורי HAL ברדיו

בקטעים הבאים מוסבר איך לעבוד עם שכבת ההפשטה של החומרה (HAL) כדי להטמיע רדיו לשידור.

ממשק HAL של רדיו לשידור

ה-HAL של רדיו השידור מספק מבני נתונים וממשקים ברמת החומרה כדי להטמיע רדיו שידור, כמו רדיו AM/FM ורדיו DAB.

ממשקי HIDL 2.0 ו-AIDL

ה-HAL של הרדיו לשידור משתמש בממשקים שמתוארים בקטעים הבאים.

IAnnouncementListener

IAnnouncementListener הוא ממשק ה-callback של ה-listener להודעות, שאפשר לרשום ב-HAL של רדיו השידור כדי לקבל הודעות. הממשק כולל את השיטות הבאות:

IAnnouncementListener
תיאור: הפונקציה נקראת בכל פעם שרשימה של ההודעות השתנתה.
	HIDL 2.0	oneway onListUpdated(vec<Announcement> announcements)
	AIDL	oneway void onListUpdated(in Announcement[] announcements)

ICloseHandle

ICloseHandle הוא ה-handle הכללי לסגירה, שמאפשר להסיר קריאה חוזרת (callback) שלא צריכה ממשק פעיל.

ICloseHandle
תיאור: סוגרים את הידית.
	HIDL 2.0	close()
	AIDL	void close()

ITunerCallback

ITunerCallback הוא ממשק ה-callback שנקרא על ידי ה-HAL של הרדיו לשידור כדי לשלוח עדכונים לשירות הלקוח של HAL.

ITunerCallback
תיאור: HAL קורא לפונקציה הזו כשפעולת כוונון (tune, ‏ seek (ב-AIDL) או scan (ב-HIDL) ו-step מצליחה) נכשלת באופן אסינכרוני.
	HIDL 2.0	oneway onCurrentProgramInfoChanged(ProgramInfo info)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
תיאור: הפונקציה נקראת כשהפעולות tune,‏ seek (ב-AIDL) או scan (ב-HIDL) או step מסתיימות בהצלחה.
	HIDL 2.0	oneway onTuneFailed(Result result, ProgramSelector selector)
	AIDL	void onTuneFailed(in Result result, in ProgramSelector selector)
תיאור: הפונקציה נקראת כשהפעולות tune,‏ seek (ב-AIDL) או scan (ב-HIDL) או step מסתיימות בהצלחה.
	HIDL 2.0	oneway onCurrentProgramInfoChanged(ProgramInfo info)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
תיאור: הקריאה מתבצעת כשרשימת התוכניות מתעדכנת. הגודל של כל מקטע צריך להיות מוגבל ל-500KB.
	HIDL 2.0	oneway onProgramListUpdated(ProgramListChunk chunk)
	AIDL	oneway onProgramListUpdated(ProgramListChunk chunk)
תיאור: הפונקציה נקראת כשהאנטנה מחוברת או מנותקת.
	HIDL 2.0	oneway onAntennaStateChange(bool connected)
	AIDL	void onCurrentProgramInfoChanged(in ProgramInfo info)
תיאור: הקריאה מתבצעת כשערכים של פרמטרים ספציפיים לספק מתעדכנים באופן פנימי ב-HAL (אין להפעיל אותה אחרי קריאה ל-setParameters על ידי לקוח HAL).
	HIDL 2.0	oneway onParametersUpdated(vec<VendorKeyValue> parameters)
	AIDL	void onParametersUpdated(in VendorKeyValue[] parameters)
תיאור: חדש ב-AIDL. הקריאה מתבצעת כשדגל ההגדרה מתעדכן באופן פנימי ב-HAL (לא צריך להפעיל אותה אחרי קריאה ל-setConfigFlag על ידי לקוח HAL).
	HIDL 2.0	לא ישים.
	AIDL	void onConfigFlagUpdated(in ConfigFlag flag, in boolean value)

IBroadcastRadio

IBroadcastRadio הוא הממשק הראשי של HAL לרדיו לשידור. ב-HAL של HIDL 2.0, משתמשים בממשק ITunerSession לכוונן כדי לבצע קריאות לפעולות. עם זאת, רק ממיר אחד פעיל בכל רגע נתון (בתנאי שלכל מכשיר HAL של רדיו לשידור יש רק צ'יפ ממיר אחד). ITunerSession הוסר מהממשקים של AIDL והממשקים שלו הועברו אל IBroadcastRadio.

IBroadcastRadio
תיאור: הצגת התיאור של המודול והיכולות שלו.
	HIDL 2.0	getProperties() generates (Properties properties)
	AIDL	Properties getProperties()
תיאור: אחזור של ההגדרה הנוכחית או האפשרית של אזור ה-AM/FM.
	HIDL 2.0	getAmFmRegionConfig(bool full) generates (Result result, AmFmRegionConfig config)
	AIDL	AmFmRegionConfig getAmFmRegionConfig(bool full)
תיאור: אחזור ההגדרה הנוכחית של אזור ה-DAB.
	HIDL 2.0	getDabRegionConfig() generates (Result result, vec<DabTableEntry> config)
	AIDL	DabTableEntry[] getDabRegionConfig()
תיאור: אחזור תמונה מהמטמון של מודול הרדיו. ב-AIDL, גודל התמונה חייב להיות קטן מ-1MB בגלל מגבלה קפדנית על מאגר הטרנזקציות של ה-binder.
	HIDL 2.0	getImage(uint32_t id) generates (vec<uint8_t> image)
	AIDL	byte[] getImage(in int id)
תיאור: רישום של מעבד האירועים של ההודעה.
	HIDL 2.0	registerAnnouncementListener(vec<AnnouncementType> enabled,IAnnouncementListener listener) generates (Result result, ICloseHandle closeHandle)
	AIDL	ICloseHandle registerAnnouncementListener(in IAnnouncementListener listener, in AnnouncementType[] enabled)
תיאור: HIDL HAL: כשפותחים סשן חדש של מקלט, צריך לסיים את הסשן הישן. AIDL HAL: מאחר שאין סשן של מקלט זמין, צריך להגדיר רק את פונקציית ה-call back של המקלט. אם הוא קיים, צריך לבטל את ההגדרה של פונקציית ה-callback הישנה.
	HIDL 2.0	openSession(ITunerCallback callback) יוצר (Result result, ITunerSession session)
	AIDL	void setTunerCallback(in ITunerCallback callback)
תיאור: HIDL HAL: סגירת סשן של מקלט לא יכולה להיכשל, וצריך להנפיק אותה רק פעם אחת. AIDL HAL: אין מקלט, ורק צריך לבטל את החזרה של הקריאה (callback) של המקלט.
	HIDL 2.0	close()
	AIDL	unsetTunerCallback()
תיאור: מכוון את הטלוויזיה לתוכנית מסוימת.
	HIDL 2.0	tune(ProgramSelector program) generates (Result result)
	AIDL	void tune(in ProgramSelector program)
תיאור: חיפוש התוכנית החוקית הבאה בשידור. כדי למנוע בלבול ב-AIDL, השם של scan השתנה ל-seek.
	HIDL 2.0	scan(bool directionUp, bool skipSubChannel) generates (Result result)
	AIDL	void seek(in boolean directionUp, in boolean skipSubChannel)
תיאור: השלבים לערוץ הסמוך, שאסור שיהיה בו תוכן של אף תוכנית.
	HIDL 2.0	step(bool directionUp) generates (Result result)
	AIDL	void step(in boolean directionUp)
תיאור: ביטול פעולות של כוונון בהמתנה, סריקת (ב-HIDL) או דילוג (ב-AIDL) או פעולות של שלבים.
	HIDL 2.0	cancel()
	AIDL	void cancel()
תיאור: מחיל מסנן על רשימת התוכניות ומתחיל לשלוח עדכונים של רשימת התוכניות דרך קריאה חוזרת (callback) של onProgramListUpdated.
	HIDL 2.0	startProgramListUpdates(ProgramFilter filter) generates (Result result)
	AIDL	void startProgramListUpdates(in ProgramFilter filter)
תיאור: הפסקת שליחת עדכונים של רשימת התוכניות.
	HIDL 2.0	stopProgramListUpdates()
	AIDL	void stopProgramListUpdates()
תיאור: אחזור ההגדרה הנוכחית של דגל תצורה נתון.
	HIDL 2.0	isConfigFlagSet(ConfigFlag flag) generates (Result result, bool value)
	AIDL	boolean isConfigFlagSet(in ConfigFlag flag)
תיאור: הגדרת דגל התצורה הנתון.
	HIDL 2.0	setConfigFlag(ConfigFlag flag, bool value) generates (Result result)
	AIDL	void setConfigFlag(in ConfigFlag flag, boolean value)
תיאור: הגדרת ערכי פרמטרים ספציפיים לספק.
	HIDL 2.0	setParameters(vec<VendorKeyValue> parameters) יוצר, (vec<VendorKeyValue> results)
	AIDL	VendorKeyValue[] setParameters(in VendorKeyValue[] parameters)
תיאור: אחזור של ערכי פרמטרים ספציפיים לספק.
	HIDL 2.0	getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters)
	AIDL	VendorKeyValue[] getParameters(in String[] keys)

הבהרות לגבי ממשק

התנהגות אסינכרונית

מכיוון שכל פעולת כוונון (למשל, כוונון, סריקה (ב-HIDL) או חיפוש (ב-AIDL) ושלבים) עשויה להיות זמן רב, ולא כדאי לחסום את השרשור למשך זמן רב, צריך לתזמן פעולות שדורשות זמן רב כך שיתבצעו מאוחר יותר ולהחזיר במהירות סטטוס או תוצאה. בפירוט, כל פעולה צריכה:

• ביטול כל פעולות ההתאמה שבהמתנה.
• בדיקה אם ניתן לעבד את הפעולה על סמך הקלט של השיטה והסטטוס של המקלט.
• מסמנים את משימת הכוונון לתזמון ואז מחזירים את הערך Result (ב-HIDL) או את הערך status (ב-AIDL) באופן מיידי. אם הערך של Result או status הוא OK, צריך להפעיל את פונקציית ה-callback של ה-tuner‏ tuneFailed או currentProgramInfoChanged כשמשימה הכוונון נכשלת (למשל, בגלל זמן קצוב לתפוגה) או מסתיימת.

באופן דומה, startProgramListUpdates גם מתזמן את המשימה הממושכת של עדכון רשימת התוכניות כך שתתבצע מאוחר יותר, כדי להחזיר סטטוס או תוצאה במהירות. השיטה קודם מבטלת בקשות עדכון בהמתנה, ואז מתזמנת את המשימה של העדכון ומחזירה במהירות את התוצאה.

מרוץ תהליכים

בגלל ההתנהגות האסינכרונית של פעולות כוונון (לדוגמה, כוונון, סריקה (ב-HIDL) או חיפוש (ב-AIDL) ושלבים), יש תנאי מרוץ בין ביטול הפעולה לבין פעולות הכוונון. אם cancel נקרא אחרי שה-HAL משלים פעולת כוונון ולפני שהקריאה החוזרת מסתיימת, אפשר להתעלם מהביטול והקריאה החוזרת אמורה להסתיים ולהתקבל על ידי לקוח ה-HAL.

באופן דומה, אם stopProgramListUpdates נקרא אחרי שה-HAL משלים עדכון של רשימת התוכניות, וקודם שהקריאה החוזרת (callback) של onCurrentProgramInfoChanged מסתיימת, אפשר להתעלם מ-stopProgramListUpdates והקריאה החוזרת אמורה להסתיים.

מגבלת גודל הנתונים

מכיוון שיש מגבלה קפדנית על מאגר הטרנזקציות של ה-binder, מגבלת הנתונים של שיטות ממשק מסוימות שמעבירות נתונים בגודל גדול פועלת לפי ההבהרות ב-HAL של AIDL.

• ב-getImage, התמונה שמוחזרת צריכה להיות קטנה מ-1MB.
• onProgramListUpdate מחייב שכל chunk יהיה קטן מ-500KB. רשימות תוכניות גדולות יותר צריכות להיות מפוצלות על ידי הטמעת HAL למספר קטעים ונשלחות דרך מספר קריאות חזרה (callbacks).

שינויים במבני הנתונים של AIDL HAL

בנוסף לשינויים בממשקים, השינויים האלה הוחלו על מבני הנתונים שמוגדרים ב-HAL של AIDL ברדיו לשידור, שמנצל את ה-AIDL.

• ה-enum של Constant מוסר ב-AIDL ומוגדר כ-const int ב-IBroadcastRadio. בינתיים, השם של ANTENNA_DISCONNECTED_TIMEOUT_MS משתנה ל-ANTENNA_STATE_CHANGE_TIMEOUT_MS. נוספה משתנה const int חדש בשם TUNER_TIMEOUT_MS. כל פעולות ההחלפה, הסריקה והשלבים חייבות להסתיים במהלך פרק הזמן הזה.
• המאפיינים RDS ו-Deemphasis מסוג enum מוסרים ב-AIDL ומוגדרים כ-const int ב-AmFmRegionConfig. בהתאם, גם fmDeemphasis וגם fmRds ב-ProgramInfo מוצהרים כ-int, תוצאת חישוב של ביט של הדגלים המתאימים. במקביל, השמות של D50 ו-D75 ישתנו ל-DEEMPHASIS_D50 ו-DEEMPHASIS_D75, בהתאמה.
• משתני המאפיין ProgramInfoFlags יוסרו ב-AIDL ויוגדרו כ-const int ב-ProgramInfo עם הוספת התחילית FLAG_. בהתאם, המשתנה infoFlags ב-ProgramInfo מוגדר כ-int, תוצאת חישוב של ביט של הדגלים. שם השדה TUNED שונה גם הוא לשם FLAG_TUNABLE, כדי לתאר בצורה טובה יותר את ההגדרה שלו, שבאמצעותה אפשר לכוונן את התחנה.
• ב-AmFmBandRange, השם של scanSpacing השתנה ל-seekSpacing, כי השם של scan השתנה ל-seek ב-AIDL.
• מכיוון שהמושג union מוצג ב-AIDL, כבר לא נעשה שימוש ב-MetadataKey וב-Metadata שהוגדרו ב-HIDL HAL. Metadata הוא איחוד של AIDL שמוגדר ב-HAL של AIDL. כל ערך enum שהיה בעבר ב-MetadataKey הוא עכשיו שדה ב-Metadata עם סוג string או int, בהתאם להגדרות שלהם.

תמיכה ברדיו DAB

בקטע הזה מתוארת התמיכה ברדיו DAB.

מזהים

סוג המזהה הראשי של רדיו DAB ורדיו DMB ב-HAL של רדיו השידור ב-AIDL הוא DAB_SID_EXT. DAB_SID_EXT משתמש במזהי שירות (SID) של 32 ביט, כך שהוא יכול לייצג SID גם של רדיו DAB וגם של רדיו DMB.

בנוסף למזהים ראשיים, יש תמיכה במזהים משניים כמו DAB_ENSEMBLE ו-DAB_FREQUENCY_KHZ. זה חשוב כי כמה תחנות DAB יכולות לשתף DAB_SID_EXT, אבל עם ערכים שונים של DAB_ENSEMBLE או DAB_FREQUENCY_KHZ. כדי להבטיח עדכונים מדויקים של רשימת התוכניות, תחנות עם אותו DAB_SID_EXT מתעדכנות יחד באמצעות ITunerCallback#onProgramListUpdated. לאחר מכן העדכון מועבר לשירות הרדיו של השידור ול-Radio Manager, ולבסוף לאפליקציית הרדיו דרך android.hardware.radio.ProgramList.

Metadata

בטבלה הבאה מוצגים המטא-נתונים הנתמכים שספציפיים ל-DAB ב-HAL של AIDL Broadcast Radio:

שדה מטא-נתונים	תיאור
dabEnsembleName (צורה מקוצרת: dabEnsembleNameShort)	שם האנסמבל של תחנת ה-DAB
dabServiceName (קיצור של dabServiceNameShort)	שם השירות של תחנת ה-DAB
dabComponentName (קיצור של dabComponentNameShort)	שם הרכיב של תחנת ה-DAB

תמיכה ברדיו באיכות HD

בקטע הזה מתוארת התמיכה ברדיו HD.

מזהים

השדה HD_STATION_ID_EXT משמש כמזהה הראשי של תחנות רדיו HD. כדי לשפר את הזיהוי של התחנה, מוצגים גם מזהים משניים כמו HD_STATION_NAME ו-HD_STATION_LOCATION. השדה HD_STATION_LOCATION, שמספק מידע על המיקום, הוצג ב-Android 15.

הפעלה או השבתה של רדיו דיגיטלי

החל מגרסה 15 של Android, אפשר להפעיל או להשבית רדיו דיגיטלי (כמו רדיו HD) על ידי שינוי ההגדרות של ConfigFlag. כדי לשלוט בהגדרה הזו ברדיו FM, משתמשים בדגל FORCE_ANALOG_FM. כדי לשלוט בהגדרה הזו ברדיו AM, משתמשים בדגל FORCE_ANALOG_AM. הגדרת הדגל לערך false מפעילה רדיו HD, ואילו הגדרתו לערך true מאלצת שימוש ברדיו אנלוגי AM/FM.

ערוצי HD זמינים

החל מגרסה 15 של Android, ערוצי ה-HD שזמינים כרגע לתחנת רדיו HD יכולים להיות מיוצגים על ידי מסכת ביט של 8 ביט, Metadata#hdSubChannelsAvailable, ב-ProgramInfo.metadata. לדוגמה, הערך של ביט 1 מימין מייצג אם ערוץ המשנה HD2 זמין לתחנת ה-HD הזו.

סטטוס קבלת האות

בגרסה 15 ואילך של Android, אפליקציות רדיו יכולות להציג למשתמשים את סטטוס קבלת האות של תחנות רדיו HD. כדאי לעשות זאת כי לפעמים נדרש זמן מה כדי לקבל אות HD חזק.

כדי לספק את המידע הזה, המערכת משתמשת ב-ProgramInfo.infoFlags כדי לעקוב אחרי הסטטוס ומעדכנת את אפליקציית הרדיו דרך ITunerCallback#onCurrentProgramInfoChanged.

כך הסטטוס מיוצג ב-ProgramInfo.infoFlags:

• ביט 6: מציין אם המערכת זיהתה את האות של רדיו HD.
• ביט 7: מציין אם יש נתונים של שירות מידע על תחנות (SIS). SIS מספק מידע נוסף על התחנה ועל מה שמשודר.
• ביט 8: מציין אם אודיו דיגיטלי באיכות HD זמין.

Metadata

בטבלה הבאה מוצגים המטא-נתונים הנתמכים של רדיו HD בגרסאות Android 15 ואילך.

שדה מטא-נתונים	תיאור
commentShortDescription	תיאור קצר של ההקשר של התגובה
commentActualText	טקסט התגובה
commercial	מודעה ברדיו
ufids	מזהים ייחודיים של קבצים (UFID) המשויכים לתוכן
hdStationNameShort	השם המקוצר של תחנת הרדיו ב-HD או השם המקוצר האוניברסלי
hdStationNameLong	השם הארוך של תחנת הרדיו ב-HD, הסלוגן שלה או הודעה ממנה.