Google cam kết thúc đẩy công bằng chủng tộc cho Cộng đồng người da đen. Xem cách thực hiện.

Cảm biến HAL 2

Lớp trừu tượng phần cứng cảm biến (HAL) là giao diện giữa khung cảm biến Android và cảm biến của thiết bị, chẳng hạn như gia tốc kế hoặc con quay hồi chuyển. Cảm biến HAL xác định các chức năng phải được thực hiện để cho phép khuôn khổ điều khiển các cảm biến.

Cảm biến HAL 2.0 có sẵn trong Android 10 trở lên cho các thiết bị mới và nâng cấp. Cảm biến HAL 2.0 dựa trên cảm biến HAL 1.0 nhưng có một số khác biệt quan trọng, trong đó ngăn chặn nó là tương thích ngược. Sử dụng cảm biến HAL 2.0 nhanh tin nhắn Queues (FMQs) để gửi các sự kiện cảm biến từ HAL vào khung cảm biến Android.

Cảm biến HAL 2.1 có sẵn trong Android 11 trở lên cho các thiết bị mới và nâng cấp. Cảm biến HAL 2.1 là một sự lặp lại của cảm biến HAL 2.0 mà cho thấy nhiều HINGE_ANGLE loại cảm biến và cập nhật các phương pháp khác nhau để chấp nhận các HINGE_ANGLE loại.

Giao diện HAL 2.1

Các nguồn chính của tài liệu cho cảm biến HAL 2.1 nằm trong định nghĩa HAL tại phần cứng / interfaces / cảm biến / 2.1 / ISensors.hal . Nếu có một cuộc xung đột của các yêu cầu giữa trang này và ISensors.hal , sử dụng các yêu cầu trong ISensors.hal .

Giao diện HAL 2.0

Các nguồn chính của tài liệu cho cảm biến HAL 2.0 nằm trong định nghĩa HAL tại phần cứng / interfaces / cảm biến / 2.0 / ISensors.hal . Nếu có một cuộc xung đột của các yêu cầu giữa trang này và ISensors.hal , sử dụng các yêu cầu trong ISensors.hal .

Triển khai cảm biến HAL 2.0 và HAL 2.1

Để thực hiện Cảm biến HAL 2.0 hoặc 2.1, một đối tượng phải mở rộng ISensors giao diện và thực hiện tất cả các chức năng quy định tại 2.0/ISensors.hal hoặc 2.1/ISensors.hal .

Khởi tạo HAL

Cảm biến HAL phải được khởi tạo bởi khung cảm biến Android trước khi có thể được sử dụng. Khung gọi initialize() chức năng cho HAL 2.0 và initialize_2_1() chức năng cho HAL 2.1 để cung cấp ba tham số cho các cảm biến HAL: hai FMQ mô tả và một con trỏ đến một ISensorsCallback đối tượng.

HAL sử dụng bộ mô tả đầu tiên để tạo Sự kiện FMQ được sử dụng để ghi các sự kiện cảm biến vào khung. HAL sử dụng mô tả thứ hai để tạo Wake Khóa FMQ sử dụng để đồng bộ hóa khi HAL phát hành khóa trỗi dậy của nó đối với WAKE_UP cảm biến các sự kiện. HAL phải lưu một con trỏ đến ISensorsCallback đối tượng để cho bất kỳ chức năng gọi lại cần thiết có thể được viện dẫn.

Các initialize() hoặc initialize_2_1() chức năng phải là chức năng đầu tiên gọi khi khởi tạo các cảm biến HAL.

Để lộ các cảm biến có sẵn

Để có được một danh sách của tất cả các cảm biến tĩnh có sẵn trong điện thoại, sử dụng getSensorsList() chức năng trên HAL 2.0 và getSensorsList_2_1() chức năng trên HAL 2.1. Hàm này trả về một danh sách các cảm biến, mỗi cảm biến được xác định duy nhất bởi tay cầm của nó. Tay cầm của một cảm biến nhất định không được thay đổi khi quá trình lưu trữ Cảm biến HAL khởi động lại. Các xử lý có thể thay đổi qua các lần khởi động lại thiết bị và trên các lần khởi động lại máy chủ hệ thống.

Nếu một vài cảm biến chia sẻ các loại cảm biến tương tự và tài sản đánh thức, sau đó các cảm biến đầu tiên trong danh sách được gọi là cảm biến mặc định và được trả lại cho các ứng dụng sử dụng các getDefaultSensor(int sensorType, bool wakeUp) chức năng.

Tính ổn định của danh sách cảm biến

Sau khi khởi động lại Cảm biến HAL, nếu dữ liệu được trả về bởi getSensorsList() hoặc getSensorsList_2_1() chỉ ra một sự thay đổi đáng kể so với danh sách cảm biến lấy ra trước khi khởi động lại, khuôn khổ gây nên khởi động lại thời gian chạy Android. Những thay đổi đáng kể đối với danh sách cảm biến bao gồm các trường hợp thiếu cảm biến với một tay cầm nhất định hoặc có các thuộc tính thay đổi hoặc khi các cảm biến mới được giới thiệu. Mặc dù việc khởi động lại thời gian chạy Android gây khó chịu cho người dùng, nhưng điều này là bắt buộc vì khung công tác Android không còn có thể đáp ứng hợp đồng API Android mà các cảm biến tĩnh (không hợp thời trang) không thay đổi trong suốt thời gian hoạt động của ứng dụng. Điều này cũng có thể ngăn khung thiết lập lại các yêu cầu cảm biến đang hoạt động do các ứng dụng thực hiện. Do đó, các nhà cung cấp HAL nên ngăn chặn các thay đổi danh sách cảm biến có thể tránh được.

Để đảm bảo tay cầm cảm biến ổn định, HAL phải ánh xạ một cách xác định một cảm biến vật lý nhất định trong thiết bị với tay cầm của nó. Mặc dù giao diện Sensors HAL không bắt buộc triển khai cụ thể nhưng các nhà phát triển có sẵn một số tùy chọn để đáp ứng yêu cầu này.

Ví dụ: danh sách cảm biến có thể được sắp xếp bằng cách sử dụng kết hợp các thuộc tính cố định của từng cảm biến, chẳng hạn như nhà cung cấp, kiểu máy và loại cảm biến. Một lựa chọn khác dựa trên thực tế là thiết lập của thiết bị cảm biến tĩnh được cố định trong phần cứng, do đó HAL cần phải biết khi nào tất cả các cảm biến mong đợi đã hoàn thành khởi tạo trước khi trở về từ getSensorsList() hoặc getSensorsList_2_1() . Danh sách các cảm biến dự kiến ​​này có thể được biên dịch thành tệp nhị phân HAL hoặc được lưu trữ trong tệp cấu hình trong hệ thống tệp và thứ tự xuất hiện có thể được sử dụng để lấy ra các tay cầm ổn định. Mặc dù giải pháp tốt nhất phụ thuộc vào chi tiết triển khai cụ thể của HAL của bạn, nhưng yêu cầu quan trọng là tay cầm cảm biến không thay đổi khi khởi động lại HAL.

Cấu hình cảm biến

Trước khi một cảm biến được kích hoạt, các bộ cảm biến phải được cấu hình với thời gian lấy mẫu và tối đa báo cáo độ trễ bằng cách sử dụng batch() chức năng.

Một cảm biến phải có khả năng được cấu hình lại bất cứ lúc nào sử dụng batch() mà không làm mất dữ liệu cảm biến.

Thời gian lấy mẫu

Khoảng thời gian lấy mẫu có một ý nghĩa khác dựa trên loại cảm biến đang được định cấu hình:

  • Liên tục: Các sự kiện cảm biến được tạo với tốc độ liên tục.
  • Khi thay đổi: Các sự kiện được tạo không nhanh hơn chu kỳ lấy mẫu và có thể được tạo với tốc độ chậm hơn chu kỳ lấy mẫu nếu giá trị đo được không thay đổi.
  • Một lần: Khoảng thời gian lấy mẫu bị bỏ qua.
  • Đặc biệt: Để biết thêm chi tiết, xem các loại cảm biến .

Để tìm hiểu về sự tương tác giữa một khoảng thời gian lấy mẫu và chế độ báo cáo của một cảm biến, xem báo cáo chế độ .

Độ trễ báo cáo tối đa

Độ trễ báo cáo tối đa đặt thời gian tối đa tính bằng nano giây mà các sự kiện có thể bị trì hoãn và được lưu trữ trong FIFO phần cứng trước khi được ghi vào Event FMQ thông qua HAL trong khi SoC hoạt động.

Giá trị 0 có nghĩa là các sự kiện phải được báo cáo ngay sau khi chúng được đo, bỏ qua hoàn toàn FIFO hoặc làm trống FIFO ngay khi một sự kiện từ cảm biến có mặt trong FIFO.

Ví dụ: một gia tốc kế được kích hoạt ở tần số 50 Hz với độ trễ báo cáo tối đa bằng 0, bộ kích hoạt sẽ ngắt 50 lần mỗi giây khi SoC hoạt động.

Khi độ trễ báo cáo tối đa lớn hơn 0, các sự kiện cảm biến không cần phải được báo cáo ngay khi chúng được phát hiện. Các sự kiện có thể được lưu trữ tạm thời trong FIFO phần cứng và được báo cáo theo lô, miễn là không có sự kiện nào bị trì hoãn nhiều hơn độ trễ báo cáo tối đa. Tất cả các sự kiện kể từ đợt trước được ghi lại và trả về cùng một lúc. Điều này làm giảm số lần ngắt gửi đến SoC và cho phép SoC chuyển sang chế độ năng lượng thấp hơn trong khi cảm biến đang thu thập và phân phối dữ liệu.

Mỗi sự kiện có một dấu thời gian được liên kết với nó. Việc trì hoãn thời gian một sự kiện được báo cáo không được ảnh hưởng đến dấu thời gian của sự kiện. Dấu thời gian phải chính xác và tương ứng với thời gian mà sự kiện đã xảy ra trên thực tế, không phải thời gian nó được báo cáo.

Để biết thêm thông tin và các yêu cầu về báo cáo sự kiện cảm biến với độ trễ báo cáo tối đa khác không, thấy định lượng .

Kích hoạt cảm biến

Khuôn khổ cho phép và vô hiệu hóa các cảm biến sử dụng activate() chức năng. Trước khi kích hoạt một bộ cảm biến, đầu tiên khuôn khổ phải cấu hình các cảm biến sử dụng batch() .

Sau khi một cảm biến bị tắt, các sự kiện cảm biến bổ sung từ cảm biến đó không được ghi vào Event FMQ.

Cảm biến xả

Nếu một bộ cảm biến được cấu hình để dữ liệu cảm biến hàng loạt, khuôn khổ có thể buộc một tuôn ra ngay lập tức các sự kiện cảm biến batched bằng cách gọi flush() . Điều này làm cho các sự kiện cảm biến theo đợt đối với tay cầm cảm biến được chỉ định sẽ được ghi ngay lập tức vào FMQ Sự kiện. Các cảm biến HAL phải nối thêm một sự kiện hoàn toàn tuôn ra đến khi kết thúc sự kiện cảm biến được viết như là kết quả của một cuộc gọi đến flush() .

Quá trình xả xảy ra không đồng bộ (nghĩa là hàm này phải trả về ngay lập tức). Nếu quá trình triển khai sử dụng một FIFO duy nhất cho một số cảm biến, FIFO đó sẽ được xóa và sự kiện hoàn thành xả chỉ được thêm vào cho cảm biến được chỉ định.

Nếu cảm biến định không có FIFO (không đệm có thể), hoặc nếu FIFO trống rỗng tại thời điểm cuộc gọi, flush() vẫn phải thành công và gửi một sự kiện hoàn toàn tuôn ra cho cảm biến đó. Điều này áp dụng cho tất cả các cảm biến không phải là cảm biến chụp một lần.

Nếu flush() được gọi là cho một cảm biến one-shot, sau đó flush() phải trả lại BAD_VALUE và không tạo ra một sự kiện hoàn toàn tuôn ra.

Ghi các sự kiện cảm biến vào FMQ

Sự kiện FMQ được Sensors HAL sử dụng để đẩy các sự kiện cảm biến vào khung cảm biến Android.

Sự kiện FMQ là một FMQ được đồng bộ hóa, có nghĩa là bất kỳ nỗ lực nào để ghi nhiều sự kiện vào FMQ hơn dung lượng khả dụng đều cho phép dẫn đến việc ghi không thành công. Trong trường hợp đó, HAL nên xác định xem nên viết nhóm sự kiện hiện tại dưới dạng hai nhóm sự kiện nhỏ hơn hay viết tất cả các sự kiện cùng nhau khi có đủ dung lượng.

Khi cảm biến HAL đã viết số mong muốn của các sự kiện cảm biến để các tổ chức sự kiện FMQ, các cảm biến HAL phải thông báo khuôn khổ các sự kiện đã sẵn sàng bằng cách viết các EventQueueFlagBits::READ_AND_PROCESS chút để các tổ chức sự kiện FMQ của EventFlag::wake chức năng. Các EventFlag có thể được tạo ra từ các tổ chức sự kiện FMQ sử dụng EventFlag::createEventFlag và tổ chức sự kiện FMQ của getEventFlagWord() chức năng.

Cảm biến HAL 2.0 / 2.1 hỗ trợ cả writewriteBlocking trên Event FMQ. Việc thực hiện mặc định cung cấp một tài liệu tham khảo cho việc sử dụng write . Nếu writeBlocking chức năng được sử dụng, readNotification cờ phải được thiết lập để EventQueueFlagBits::EVENTS_READ , được thiết lập bởi khuôn khổ khi nó đọc các sự kiện từ các tổ chức sự kiện FMQ. Các ghi thông báo treo cờ phải được thiết lập để EventQueueFlagBits::READ_AND_PROCESS , mà thông báo cho khuôn khổ các sự kiện đã được ghi vào tổ chức sự kiện FMQ.

Sự kiện WAKE_UP

WAKE_UP sự kiện là những sự kiện cảm biến gây bộ vi xử lý ứng dụng (AP) để thức dậy và xử lý sự kiện này ngay lập tức. Bất cứ khi nào một WAKE_UP sự kiện được ghi vào tổ chức sự kiện FMQ, các cảm biến HAL phải đảm bảo một khóa trỗi dậy để đảm bảo rằng ở lại hệ thống tỉnh táo cho đến khi khuôn khổ có thể xử lý sự kiện này. Khi nhận được WAKE_UP sự kiện, khuôn khổ chặt khóa trỗi dậy của riêng mình, cho phép cảm biến HAL để phát hành khóa trỗi dậy của nó. Để đồng bộ hóa khi Cảm biến HAL phát hành khóa đánh thức, hãy sử dụng Wake Lock FMQ.

Các cảm biến HAL phải đọc Wake Khóa FMQ để xác định số lượng WAKE_UP sự kiện khuôn khổ đã xử lý. HAL chỉ nên phát hành khóa trỗi dậy của nó đối với WAKE_UP sự kiện nếu tổng số unhandled WAKE_UP sự kiện là zero. Sau khi xử lý các sự kiện cảm biến, khung đếm số sự kiện được đánh dấu là WAKE_UP sự kiện và viết số này trở lại để Wake Khóa FMQ.

Khung đặt WakeLockQueueFlagBits::DATA_WRITTEN ghi thông báo trên Wake Khóa FMQ bất cứ khi nào nó ghi dữ liệu vào Wake Khóa FMQ.

Cảm biến động

Cảm biến động là cảm biến không phải là một bộ phận vật lý của thiết bị nhưng có thể được sử dụng làm đầu vào cho thiết bị, chẳng hạn như gamepad với gia tốc kế.

Khi một bộ cảm biến động được kết nối, onDynamicSensorConnected chức năng trong ISensorsCallback phải được gọi từ các cảm biến HAL. Điều này thông báo cho khuôn khổ của cảm biến động mới và cho phép cảm biến được điều khiển thông qua khuôn khổ và để khách hàng sử dụng các sự kiện của cảm biến.

Tương tự như vậy, khi một bộ cảm biến động được ngắt kết nối, các onDynamicSensorDisconnected chức năng trong ISensorsCallback phải được gọi để khuôn khổ có thể loại bỏ bất kỳ cảm biến đó là không còn nữa.

Kênh trực tiếp

Kênh trực tiếp là một phương pháp hoạt động trong đó các sự kiện cảm biến được ghi vào bộ nhớ cụ thể thay vì vào FMQ Sự kiện bỏ qua Khung cảm biến Android. Máy khách đăng ký kênh trực tiếp phải đọc các sự kiện cảm biến trực tiếp từ bộ nhớ được sử dụng để tạo kênh trực tiếp và sẽ không nhận các sự kiện cảm biến thông qua khung. Các configDirectReport() chức năng tương tự như batch() cho hoạt động bình thường và cấu hình các kênh báo cáo trực tiếp.

Các registerDirectChannel()unregisterDirectChannel() chức năng tạo ra hoặc phá hủy một kênh trực tiếp mới.

Các chế độ hoạt động

Các setOperationMode() chức năng cho phép khuôn khổ để cấu hình một bộ cảm biến để khuôn khổ có thể tiêm dữ liệu cảm biến vào cảm biến. Điều này rất hữu ích cho việc kiểm tra, đặc biệt là đối với các thuật toán tồn tại bên dưới khuôn khổ.

Các injectSensorData() chức năng trong HAL 2.0 và injectSensorsData_2_1() chức năng trong HAL 2.0 thường được sử dụng để đẩy các thông số hoạt động vào cảm biến HAL. Chức năng này cũng có thể được sử dụng để đưa các sự kiện cảm biến vào một cảm biến cụ thể.

Thẩm định

Để xác thực việc triển khai Cảm biến HAL của bạn, hãy chạy các bài kiểm tra CTS và VTS của cảm biến.

Kiểm tra CTS

Kiểm tra CTS cảm biến tồn tại trong cả kiểm tra CTS tự động và ứng dụng CTS Verifier thủ công.

Các bài kiểm tra tự động được đặt tại cts / xét nghiệm / cảm biến / src / android / phần cứng / cts . Các thử nghiệm này xác minh chức năng tiêu chuẩn của cảm biến, chẳng hạn như kích hoạt cảm biến, chia lô và tỷ lệ sự kiện cảm biến.

Các thử nghiệm CTS Verifier được đặt tại cts / apps / CtsVerifier / src / com / android / cts / verifier / cảm biến . Các thử nghiệm này yêu cầu đầu vào thủ công từ người vận hành thử nghiệm và đảm bảo rằng các cảm biến báo cáo các giá trị chính xác.

Vượt qua các bài kiểm tra CTS là rất quan trọng để đảm bảo rằng thiết bị được kiểm tra đáp ứng tất cả các yêu cầu của CDD.

Kiểm tra VTS

Kiểm tra VTS cho cảm biến HAL 2.0 được đặt tại phần cứng / interfaces / cảm biến / 2.0 / VTS . Kiểm tra VTS cho cảm biến HAL 2.1 được đặt tại phần cứng / interfaces / cảm biến / 2.1 / VTS . Các xét nghiệm đảm bảo rằng các cảm biến HAL được thực hiện đúng và rằng tất cả các yêu cầu trong vòng ISensors.halISensorsCallback.hal được đáp ứng đúng cách.

Nâng cấp lên Cảm biến HAL 2.1 từ 2.0

Khi nâng cấp lên Cảm biến HAL 2.1 từ 2.0, thực hiện HAL của bạn phải bao gồm initialize_2_1() , getSensorsList_2_1() , và injectSensorsData_2_1() phương pháp, cùng với các loại HAL 2.1. Các phương pháp này phải đáp ứng các yêu cầu tương tự được nêu đối với HAL 2.0 ở trên.

Vì HAL phiên bản nhỏ phải hỗ trợ tất cả các chức năng từ HAL trước đó, 2.1 HAL phải hỗ trợ được khởi tạo dưới dạng 2.0 HAL. Để tránh sự phức tạp khi hỗ trợ cả hai phiên bản HAL, bạn nên sử dụng Multi-HAL 2.1.

Đối với một ví dụ về làm thế nào để thực hiện cảm biến của riêng bạn 2.1 HAL, xem Sensors.h .

Nâng cấp lên Cảm biến HAL 2.0 từ 1.0

Khi nâng cấp lên Cảm biến HAL 2.0 từ 1.0, hãy đảm bảo việc triển khai HAL của bạn đáp ứng các yêu cầu sau.

Khởi tạo HAL

Các initialize() chức năng phải được hỗ trợ để thành lập FMQs giữa khung và HAL.

Để lộ các cảm biến có sẵn

Trong cảm biến HAL 2.0, các getSensorsList() chức năng phải trả lại giá trị như nhau trong một thiết bị duy nhất khởi động, khởi động lại ngay cả trên cảm biến HAL. Một yêu cầu mới của getSensorsList() chức năng là nó phải trả về giá trị tương tự trong một khởi động thiết bị duy nhất, thậm chí trên khởi động lại Cảm biến HAL. Điều này cho phép khuôn khổ cố gắng thiết lập lại các kết nối cảm biến nếu máy chủ hệ thống khởi động lại. Giá trị trả về bởi getSensorsList() có thể thay đổi sau này thực hiện thiết bị khởi động lại.

Ghi các sự kiện cảm biến vào FMQ

Thay vì chờ đợi cho poll() được gọi, trong cảm biến HAL 2.0, các cảm biến HAL phải sự kiện cảm biến chủ động ghi vào Event FMQ bất cứ khi nào sự kiện cảm biến có sẵn. HAL cũng chịu trách nhiệm cho việc viết các bit đúng EventFlag để gây ra một FMQ đọc trong khuôn khổ.

Sự kiện WAKE_UP

Trong cảm biến HAL 1.0, HAL đã có thể phát hành khóa trỗi dậy của mình cho bất kỳ WAKE_UP sự kiện trên bất kỳ cuộc gọi tiếp theo để poll() sau một WAKE_UP đã được đăng để poll() bởi vì đây chỉ ra rằng khuôn khổ đã xử lý tất cả các sự kiện cảm biến và đã thu được một khóa đánh thức, nếu cần thiết. Bởi vì, trong cảm biến HAL 2.0, HAL không còn biết khi khuôn khổ đã xử lý sự kiện bằng văn bản cho FMQ, Wake Khóa FMQ cho phép khuôn khổ để giao tiếp với HAL khi nó đã xử lý WAKE_UP sự kiện.

Trong cảm biến HAL 2.0, khóa trỗi dậy bảo đảm bằng cảm biến HAL cho WAKE_UP sự kiện phải bắt đầu với SensorsHAL_WAKEUP .

Cảm biến động

Cảm biến động đã được trả lại bằng cách sử dụng poll() chức năng trong Bộ cảm biến HAL 1.0. Cảm biến HAL 2.0 đòi hỏi onDynamicSensorsConnectedonDynamicSensorsDisconnected trong ISensorsCallback được gọi bất cứ khi nào kết nối cảm biến động thay đổi. Những callbacks có sẵn như là một phần của ISensorsCallback con trỏ được cung cấp thông qua việc initialize() chức năng.

Các chế độ hoạt động

Các DATA_INJECTION chế độ cho WAKE_UP cảm biến phải được hỗ trợ trong cảm biến HAL 2.0.

Hỗ trợ nhiều HAL

Cảm biến HAL 2.0 và 2.1 hỗ trợ multi-HAL bằng cách sử dụng khung cảm biến Multi-HAL . Để biết chi tiết thực hiện, xem Porting từ Cảm biến HAL 1.0 .