Αρχιτεκτονική Προγραμμάτων Οδήγησης Στυλό Ανάγνωσης: HAL, BSP και Φορητό Επίπεδο Προγραμμάτων Οδήγησης σε 11 SKU

Κοινό: Αυτός ο οδηγός απευθύνεται σε αρχιτέκτονες firmware, υπεύθυνους μηχανικούς ODM και διαχειριστές προγραμμάτων OEM που θέλουν να κατανοήσουν πώς είναι δομημένο το firmware των reading pen μας, ώστε να μπορούν να το μεταφέρουν σε νέο SoC, να αλλάξουν προμηθευτή αισθητήρα ή να ελέγξουν τη φορητότητα ενός codebase που αγοράζουν. Θεωρείται ότι είστε εξοικειωμένοι με C, έννοιες embedded RTOS και βασικά datasheets SoC.

Η μέρα που ένας αγοραστής ρωτάει «μπορούμε να επανατοποθετήσουμε το firmware σας σε διαφορετικό αισθητήρα OID;» ή «μπορούμε να το επανασχεδιάσουμε για Rockchip SoC αντί για Allwinner;» είναι η μέρα που δοκιμάζεται η αρχιτεκτονική του firmware. Εάν οι drivers είναι μπλεγμένοι με τον κώδικα εφαρμογής, η απάντηση είναι «όχι, έξι μήνες». Εάν οι drivers είναι σωστά δομημένοι σε επίπεδα, η απάντηση είναι «ναι, δύο έως τέσσερις εβδομάδες». Η σειρά μας 11-SKU reading pen (B1, B2, F8, K7, KF1, L5, P2, Q6, Q8, T2, Y6) είναι δομημένη ώστε η δεύτερη απάντηση να είναι η ειλικρινής.

Αυτό το άρθρο σας καθοδηγεί στα τρία επίπεδα driver — HAL, BSP και το driver shim σε επίπεδο εφαρμογής — εξηγεί τους κανόνες εξάρτησης μεταξύ τους και δίνει συγκεκριμένα παραδείγματα κόστους μεταφοράς σε τρεις πραγματικές μετεγκαταστάσεις που παραδώσαμε το 2024–2025.

1. Τι Εννοούμε με HAL, BSP και Driver Shims

Η ορολογία διαφέρει μεταξύ του κλάδου. Εμείς χρησιμοποιούμε:

• BSP (Board Support Package) — ο κώδικας που γνωρίζει ένα συγκεκριμένο PCB. Pin mux, αντιστοιχίσεις GPIO, αριθμοί διαύλου I²C, αλληλουχία PMIC, προφίλ φορτιστή μπαταρίας. Βρίσκεται στο bsp/<sku>/.
• HAL (Hardware Abstraction Layer) — ο κώδικας που ενσωματώνει ένα περιφερειακό SoC σε ένα vendor-neutral API. SPI master, I²C slave, DMA, ADC, audio DAC. Βρίσκεται στο hal/<vendor>/<soc>/.
• Ενδιάμεσο πρόγραμμα οδήγησης (Driver shim) — ο κώδικας που προσαρμόζει ένα vendor-neutral API περιφερειακού σε ένα συγκεκριμένο IC OID/audio/power. Βρίσκεται στο drivers/<component>/.
• MCAL (Microcontroller Abstraction Layer) — ο όρος στυλ AUTOSAR που χρησιμοποιούμε για το HAL στα SKU Cortex-M (B1, B2, K7, KF1, P2, Q6, Q8).

Η πειθαρχία είναι μονοκατευθυντική: application → driver shim → HAL → BSP. Τίποτα στο HAL δεν επιτρέπεται να περιλαμβάνει header από το BSP· τίποτα στο driver shim δεν επιτρέπεται να περιλαμβάνει header από το application. Το επιβάλλουμε με ένα script που εκτελείται στο CI και αποτυγχάνει το build εάν εντοπιστεί απαγορευμένο include.

2. Η Στοίβα 4 Επιπέδων σε ένα Reading Pen

Κάθε firmware reading pen ακολουθεί την ίδια δομή 4 επιπέδων, ανεξάρτητα από SKU ή λειτουργικό:

Τα SKU Linux (F8, L5, T2, Y6) χωρίζουν το HAL σε δύο μέρη: kernel-space και user-space. Το HAL σε kernel-space είναι ο driver συσκευής Linux· το HAL σε user-space ενσωματώνει ALSA, PulseAudio ή τον δικό μας audio daemon. Ισχύει ο ίδιος μονοκατευθυντικός κανόνας.

3. Ο Χάρτης HAL/BSP για τα 11 SKU

Το HAL είναι το πιο ακριβό επίπεδο για αλλαγή. Ένας νέος προμηθευτής SoC σημαίνει περίπου 4.800–6.500 LOC εργασίας HAL. Μια νέα πλακέτα PCB στο ίδιο SoC σημαίνει 1.500–2.800 LOC εργασίας BSP. Ένας νέος προμηθευτής αισθητήρα OID σημαίνει 600–1.200 LOC εργασίας driver shim. Το επίπεδο εφαρμογής ιδανικά δεν θα πρέπει να χρειάζεται αλλαγές.

4. Το συμβόλαιο του ενδιάμεσου προγράμματος οδήγησης (Driver Shim Contract)

Κάθε driver shim υλοποιεί μια σταθερή σύμβαση. Για παράδειγμα, το audio DAC shim σε κάθε SKU εκθέτει:

audio_err_t audio_dac_init(const audio_config_t *cfg);
audio_err_t audio_dac_start(audio_stream_t *stream);
audio_err_t audio_dac_stop(void);
audio_err_t audio_dac_set_volume(uint8_t pct);
audio_err_t audio_dac_get_status(audio_status_t *status);

Το struct audio_config_t περιέχει ρυθμό δειγματοληψίας, βάθος bit, αριθμό καναλιών και δείκτη buffer DMA. Το HAL υλοποιεί τις κλήσεις σε επίπεδο καταχωρητών I²S ή TDM. Το BSP ρυθμίζει το pin mux για το I²S0 και τις ράγες PMIC. Η εφαρμογή δεν αγγίζει ποτέ απευθείας κανέναν καταχωρητή.

Αυτή η σύμβαση μας επιτρέπει να αλλάξουμε τον προμηθευτή audio DAC (έχουμε παραδώσει με Maxim MAX98357A, Texas Instruments TLV320AIC23 και AKM AK4633 τους τελευταίους 24 μήνες) χωρίς να αλλάξουμε ούτε μία γραμμή κώδικα εφαρμογής.

5. Σταθερότητα και Έκδοση του HAL API

Το HAL API εκδίδεται με σημασιολογική εκδοχοποίηση (semantic versioning): MAJOR.MINOR.PATCH. Μια αλλαγή MAJOR σημαίνει σπάσιμο συμβατότητας· η MINOR προσθέτει νέα API· η PATCH είναι μόνο διορθώσεις σφαλμάτων. Ο κώδικας εφαρμογής είναι καρφιτσωμένος σε μια MAJOR έκδοση του HAL. Οι τρέχουσες εκδόσεις HAL είναι:

Οι αλλαγές MAJOR του HAL είναι σπάνιες — κατά μέσο όρο μία κάθε 18 μήνες. Το HAL είναι το κομμάτι κώδικα με τη μεγαλύτερη διάρκεια ζωής στο αποθετήριο firmware μας. Ο κώδικας εφαρμογής στο B2 δεν χρειάστηκε να αλλάξει από το firmware 2.4.0, επειδή το HAL API παρέμεινε σταθερό.

6. Μετανάστευση BSP το 2024–2025: Τρία Πραγματικά Περιστατικά

Μεταναστεύσαμε τρία SKU πέρα από το όριο του BSP τους τελευταίους 18 μήνες. Το κόστος σε κάθε περίπτωση:

Η πρώτη περίπτωση ήταν ένας διαγωνισμός λιανοπωλητή από χώρα του Κόλπου που απαιτούσε αισθητήρα OID υψηλότερης ανάλυσης. Αντικαταστήσαμε τον αισθητήρα στο επίπεδο BSP (1.400 γραμμές κώδικα pin-mux και διαμόρφωσης διαύλου I²C), κάναμε μια μικρή αλλαγή στη μορφή του πίνακα αποκωδικοποιητή OID (80 γραμμές κώδικα στην εφαρμογή) και παραδώσαμε σε 6 εβδομάδες.

Η δεύτερη περίπτωση ήταν μια ευρωπαϊκή σχολική περιφέρεια που ήθελε πιο δυνατό ηχείο (5 W αντί για 3 W) στην πλατφόρμα L5. Μεταβαίνοντας σε νέο audio DAC, χρειάστηκε να αλλάξουν μόνο 200 γραμμές κώδικα HAL, επειδή ο νέος DAC μοιραζόταν την περιφερειακή I²S. Ο κώδικας της εφαρμογής δεν επηρεάστηκε καθόλου.

Η τρίτη περίπτωση ήταν ένας πελάτης B2B που επέμενε σε συγκεκριμένο ολοκληρωμένο κύκλωμα μέτρησης μπαταρίας. Αντικαταστήσαμε το τσιπ μέτρησης στο PCB του Q6 ώστε να ταιριάζει με το υλικό του Q8. Το HAL ήταν πανομοιότυπο (ίδια οικογένεια προμηθευτή), επομένως η μόνη εργασία ήταν στο BSP.

7. Πού επιτρέπεται να φτάσει το επίπεδο εφαρμογής

Το επίπεδο εφαρμογής επιτρέπεται να καλεί shim προγραμμάτων οδήγησης και API λειτουργικού συστήματος (ουρές FreeRTOS, work items Zephyr, pthreads Linux, ALSA). Απαγορεύεται να καλεί απευθείας το HAL. Το επιβάλλουμε με έναν κανόνα CI lint στον γράφο των include. Μια υποχώρηση που κάνει import το hal/spi_master.h από το app/audio_player.c αποτυγχάνει στο build.

Υπάρχουν τρεις εξαιρέσεις:

1. Ο χρόνος εκκίνησης bsp/<sku>/pinmux.c επιτρέπεται να καλεί απευθείας συναρτήσεις HAL, επειδή το pin mux είναι εγγενώς HAL-aware.
2. Η κατάτμηση TEE του TrustZone σε SKU Linux επιτρέπεται να καλεί το HAL, επειδή πρόκειται για ξεχωριστή εικόνα firmware.
3. Ο κώδικας διαχείρισης ενέργειας σε SKU RTOS επιτρέπεται να καλεί το HAL, επειδή διαχειρίζεται τα ρολόγια πυρήνα και τις λειτουργίες αδράνειας.

Αυτές οι εξαιρέσεις τεκμηριώνονται στο firmware README και ελέγχονται σε κάθε έκδοση.

8. Επιβολή μέσω CI και στατική ανάλυση

Το CI μας εκτελεί τέσσερις ελέγχους σε κάθε pull request:

1. Έλεγχος γράφου include — επιβάλλει τον κανόνα μονοκατευθυντικής εξάρτησης.
2. Έλεγχος σταθερότητας API HAL — αποτυγχάνει το build εάν αλλάξει μια υπογραφή HAL χωρίς αναβάθμιση MAJOR.
3. Έλεγχος θύρας BSP — επαληθεύει ότι το BSP για ένα SKU-στόχο μεταγλωττίζεται αυτόνομα.
4. Έλεγχος γραμμών κώδικα εφαρμογής — θέτει ανώτατο όριο αύξησης των LOC της εφαρμογής στο +10 % ανά έκδοση, ώστε να αποθαρρύνεται η εισχώρηση επιχειρηματικής λογικής σε λάθος επίπεδο.

Το CI εκτελείται στους self-hosted runners μας στο GitLab, σε Shenzhen και Yantai. Μια πλήρης επικύρωση διαρκεί 22 λεπτά για SKU RTOS και 48 λεπτά για SKU Linux.

9. Σημεία προσαρμογής OEM

Εάν είστε αγοραστής OEM, τα επίπεδα που συνήθως τροποποιείτε είναι:

• BSP — pin mux, ανάθεση GPIO, μοτίβο LED, debounce κουμπιού.
• Shim προγράμματος οδήγησης — εάν προσθέτετε δικό σας audio DAC, αισθητήρα OID ή τσιπ μέτρησης μπαταρίας.
• Εφαρμογή — γλωσσικά πακέτα, φωνητικές προτροπές, λογότυπο OEM στην οθόνη εκκίνησης, προσαρμοσμένες βιβλιοθήκες OID.

Το HAL σπάνια τροποποιείται, εκτός εάν αλλάζετε προμηθευτή SoC. Έχουμε πραγματοποιήσει τρία ports HAL από το 2023 (Allwinner → NXP i.MX, STM32F4 → GD32, και μια πιλοτική Rockchip). Το καθένα διήρκεσε 16–22 εβδομάδες μηχανικής εργασίας.

Συμβουλή αγοραστή: Εάν ο διαγωνισμός σας απαιτεί συγκεκριμένο προμηθευτή SoC, ρωτήστε τον OEM εάν το επίπεδο HAL του είναι αφαιρετικό ή κωδικοποιημένο για έναν μόνο προμηθευτή. Το κωδικοποιημένο HAL σημαίνει 4–6 μήνες porting, ενώ το αφαιρετικό HAL σημαίνει 6–10 εβδομάδες.

10. Τι κερδίζετε από την αρχιτεκτονική

Μια καλά δομημένη αρχιτεκτονική firmware σας προσφέρει τρία πράγματα:

1. Φορητότητα — μπορείτε να μεταβείτε σε νέο SoC, αισθητήρα ή DAC σε εβδομάδες, όχι σε μήνες.
2. Ελεγξιμότητα — η ομάδα συμμόρφωσής σας μπορεί να ελέγξει ένα επίπεδο κάθε φορά.
3. Δυνατότητα ελέγχου — τα shim προγραμμάτων οδήγησης μπορούν να ελεγχθούν μοναδιαία με mocks, χωρίς να χρειάζεται πραγματικό υλικό.

Η σειρά των 11 SKU που παραδίδουμε σήμερα αποτελεί την απόδειξη. Έχουμε μεταφέρει 6 από τα 11 SKU τουλάχιστον μία φορά από το 2023 χωρίς επανεγγραφές στο επίπεδο εφαρμογής, και το μέσο κόστος porting είναι πλέον 4–8 εβδομάδες μηχανικής εργασίας σε γνωστό κόστος.

Εάν έχετε μια ερώτηση porting, στείλτε μας τα SKU προέλευσης και στόχου και θα σας απαντήσουμε με μια προσφορά σταθερής τιμής εντός 48 ωρών.

11. Πραγματικά παραδείγματα shim προγραμμάτων οδήγησης

Για να γίνουν τα αφηρημένα επίπεδα συγκεκριμένα, παραθέτουμε τέσσερα πραγματικά shim προγραμμάτων οδήγησης που περιλαμβάνονται στο υπάρχον υλικό firmware παραγωγής μας.

Shim αισθητήρα OID. Κάθε SKU χρησιμοποιεί το ίδιο API oid_sensor_read_page() ανεξάρτητα από το αν ο αισθητήρας είναι OID2000, κάμερα βασισμένη σε CMOS ή μονάδα ToF. Το shim μεταφράζει το API στις I²C συναλλαγές του προμηθευτή. Το B2 χρησιμοποιεί ριπή 12 καρέ στα 30 fps, το L5 χρησιμοποιεί ένα μεμονωμένο καρέ 720p, το T2 χρησιμοποιεί καρέ με σχολιασμό βάθους ToF στα 60 fps. Και τα τρία καλούν το ίδιο shim, το οποίο αναλαμβάνει τη μετάφραση.

Ενδιάμεσο πρόγραμμα οδήγησης (shim) για τον DAC ήχου. Το shim του audio DAC διαχειρίζεται τη μετατροπή ρυθμού δειγματοληψίας, τη ράμπα έντασης και τη σίγαση. Στο B2 firmware 2.4.7 παραδίδουμε MAX98357A, στο L5 firmware 4.2.0 παραδίδουμε TLV320AIC23. Η συνάρτηση audio_dac_set_volume() του shim υλοποιεί λογαριθμική ράμπα σε 40 ms για την αποφυγή θορύβου zipper. Η εφαρμογή δεν βλέπει ποτέ εγγραφή καταχωρητή.

Shim συνύπαρξης Wi-Fi/BT. Στα F8, L5, T2 και Y6, το Wi-Fi/BT shim επιλύει την πρόσβαση στην κεραία μεταξύ του ραδιοφώνου Wi-Fi και του ραδιοφώνου BLE. Το shim είναι χτισμένο πάνω στη διεπαφή Packet Traffic Arbitration (PTA) του προτύπου LTE. Το HAL υλοποιεί τα 4 καλώδια PTA. Η εφαρμογή βλέπει μία μόνο κλήσηwireless_tx_request().

Shim μετρητή μπαταρίας. Τα Q6, Q8, K7, KF1, L5, T2 και Y6 διαθέτουν μετρητή καυσίμου TI BQ27426 ή BQ40Z50. Το shim εκθέτει τα battery_get_soc_pct(), battery_get_temperature_c(), battery_get_voltage_mv() και battery_get_health(). Το shim αποθηκεύει προσωρινά τις μετρήσεις για 1 δευτερόλεπτο, ώστε να μην ενεργοποιείται ο μετρητής περισσότερο από μία φορά ανά κύκλο.

12. Χάρτες Μνήμης και Σενάρια Σύνδεσης ανά Επίπεδο

Κάθε επίπεδο έχει περιορισμένο χάρτη μνήμης. Κατανέμουμε προϋπολογισμούς RAM και Flash ανά επίπεδο και τους επιβάλλουμε με σενάρια σύνδεσης. Ο προϋπολογισμός για το firmware 2.4.7 του B2 έχει ως εξής:

Το συνολικό αποτύπωμα Flash στο firmware 2.4.7 του B2 είναι 1,4 MB· το συνολικό αποτύπωμα RAM είναι 64 KB. Τα SKU Linux έχουν μεγαλύτερους προϋπολογισμούς — το firmware 4.2.0 του L5 δεσμεύει 140 MB για την εφαρμογή, 28 MB για το HAL και 12 MB για τα driver shim.

13. Πώς να Ελέγξετε ένα Firmware Στυλό Ανάγνωσης για Φορητότητα

Εάν είστε υπεύθυνος συμμόρφωσης ή αγοραστής OEM που αξιολογεί ένα firmware τρίτου κατασκευαστή, ορίστε ο έλεγχος 12 ερωτήσεων που μπορείτε να εκτελέσετε σε 2 ώρες:

1. Μπορεί ο κώδικας της εφαρμογής να μεταγλωττιστεί χωρίς τις κεφαλίδες HAL να είναι διαθέσιμες;
2. Μεταγλωττίζεται το επίπεδο BSP αυτόνομα;
3. Υπάρχει τεκμηριωμένος κανόνας μονόδρομης εξάρτησης;
4. Επιβάλλει το CI τον κανόνα εξάρτησης;
5. Έχει εκδοθεί έκδοση για το API του HAL;
6. Παραμένει το LOC της εφαρμογής εντός προϋπολογισμού αύξησης 10 % ανά έκδοση;
7. Τα ενδιάμεσα προγράμματα οδήγησης (driver shims) υποβάλλονται σε δοκιμές μονάδας με mocks;
8. Το μέγεθος του BSP τεκμηριώνεται ανά SKU;
9. Υπάρχει αριθμομηχανή κόστους μεταφοράς HAL;
10. Ελέγχεται η σταθερότητα του HAL στο CI;
11. Τεκμηριώνονται οι εξαιρέσεις στον κανόνα εξάρτησης;
12. Είναι το script του linker ανά επίπεδο;

Εάν η απάντηση και στα 12 είναι ναι, το firmware είναι φορητό. Εάν λιγότερα από 8 είναι ναι, αντιμετωπίστε τη βάση κώδικα ως υποχρέωση ενός SKU.

Σχετική Ανάγνωση

• Διαδικασία Κατασκευής OEM Reading Pen
• Reading Pen RTOS έναντι Ενσωματωμένου Linux
• Πολυδιεργασιακός Scheduler και Προτεραιότητα Reading Pen
• Κρυπτογραφία και TrustZone στο Reading Pen
• Ροή εκκίνησης BIOS του Reading Pen και αξιόπιστη εκκίνηση
• Καθυστέρηση Διακοπών και Real Time στο Reading Pen