Каноническая причина загрузки

Android 9 включает следующие изменения в спецификацию причины загрузки загрузчика.

Причины загрузки

Загрузчик использует уникально доступные аппаратные ресурсы и ресурсы памяти, чтобы определить, почему устройство перезагрузилось, а затем сообщает об этом определении, добавляя androidboot.bootreason=<reason> в командную строку ядра Android для его запуска. Затем init транслирует эту командную строку для распространения на свойство Android bootloader_boot_reason_prop ( ro.boot.bootreason ). Для устройств, запускаемых с Android 12 или выше, использующих ядро ​​версии 5.10 или выше, androidboot.bootreason=<reason> добавляется в bootconfig вместо командной строки ядра.

Спецификации причины загрузки

Предыдущие выпуски Android указывали формат причины загрузки, который не использовал пробелы, был полностью строчным, включал несколько требований (например, для сообщения kernel_panic , watchdog , cold / warm / hard ) и который допускал другие уникальные причины. Эта свободная спецификация привела к распространению сотен пользовательских (а иногда и бессмысленных) строк причины загрузки, что, в свою очередь, привело к неуправляемой ситуации. Начиная с текущего выпуска Android, явный импульс почти не поддающегося анализу или бессмысленного контента, поданного загрузчиком, создал проблемы соответствия для bootloader_boot_reason_prop .

С выпуском Android 9 команда Android осознает, что устаревший bootloader_boot_reason_prop имеет существенный импульс и не может быть переписан во время выполнения. Поэтому любые улучшения спецификации причины загрузки должны исходить из взаимодействия с разработчиками загрузчика и настроек существующей системы. Для этого команда Android:

  • Взаимодействие с разработчиками загрузчиков с целью побудить их:
    • Укажите канонические, анализируемые и распознаваемые причины для bootloader_boot_reason_prop .
    • Участвуйте в списке system/core/bootstat/bootstat.cpp kBootReasonMap .
  • Добавление контролируемого и перезаписываемого во время выполнения источника system_boot_reason_prop ( sys.boot.reason ). Ограниченный набор системных приложений (таких как bootstat и init ) может перезаписывать это свойство, но всем приложениям могут быть предоставлены права sepolicy на его чтение.
  • Информирование пользователей о причине загрузки о необходимости подождать, пока будут смонтированы пользовательские данные, прежде чем доверять содержимому свойства причины загрузки системы system_boot_reason_prop .

Почему так поздно? Хотя bootloader_boot_reason_prop доступен на ранней стадии загрузки, он блокируется политикой безопасности Android по мере необходимости, поскольку представляет неточную, не поддающуюся анализу и неканоническую информацию. В большинстве ситуаций доступ к этой информации должен быть необходим только разработчикам с глубокими знаниями о системе загрузки. Уточненный, поддающийся анализу и канонический API для причины загрузки с system_boot_reason_prop может быть надежно и точно получен только после монтирования пользовательских данных. В частности:

  • До монтирования пользовательских данных system_boot_reason_prop будет содержать значение из bootloader_boot_reason_prop .
  • После монтирования пользовательских данных system_boot_reason_prop может быть обновлен для соответствия требованиям или предоставления более точной информации.

По этой причине Android 9 увеличивает период времени, в течение которого причина загрузки может быть официально получена, изменяя ее с немедленной точности при загрузке (с помощью bootloader_boot_reason_prop ) на доступность только после монтирования пользовательских данных (с помощью system_boot_reason_prop ).

Логика Bootstat зависит от более информативного и соответствующего bootloader_boot_reason_prop . Когда это свойство использует предсказуемый формат, оно повышает точность всех контролируемых сценариев перезагрузки и выключения, что в свою очередь улучшает и расширяет точность и значение system_boot_reason_prop .

Формат канонической причины загрузки

Канонический формат причины загрузки для bootloader_boot_reason_prop в Android 9 использует следующий синтаксис:

<reason>,<subreason>,<detail>…

Правила форматирования:

  • Нижний регистр
  • Без пробелов (используйте подчеркивание)
  • Все печатные символы
  • Разделенные запятыми reason , subreason и один или несколько detail примеров.
    • Обязательная reason , представляющая собой наиболее приоритетную причину, по которой устройство должно было перезагрузиться или выключиться.
    • Необязательная subreason , которая представляет собой краткое описание причины перезагрузки или выключения устройства (или того, кто перезагрузил или выключил устройство).
    • Одно или несколько необязательных значений detail . detail может указывать на подсистему, чтобы помочь определить, какая конкретная система привела к subreason . Вы можете указать несколько значений detail , которые, как правило, должны следовать иерархии важности. Однако также приемлемо сообщать несколько значений detail равной важности.

Пустое значение bootloader_boot_reason_prop считается недопустимым (поскольку это позволяет другим агентам внедрять причину загрузки постфактум).

Требования к обоснованию

Значение, указанное для reason (первый промежуток, до завершения или запятой), должно быть из следующего набора, разделенного на основные, веские и прямые причины:

  • набор ядер:
    • " watchdog"
    • "kernel_panic"
  • сильный набор:
    • "recovery"
    • "bootloader"
  • тупой набор:
    • "cold" . Обычно означает полный сброс всех устройств, включая память.
    • "hard" . Обычно указывает на то, что состояние оборудования сброшено, и ramoops должен сохранять постоянное содержимое.
    • "warm" . Обычно указывает на то, что память и устройства сохраняют некоторое состояние, а резервное хранилище ramoops (см. драйвер pstore в ядре) содержит постоянное содержимое.
    • "shutdown"
    • "reboot" . Обычно означает, что состояние ramoops неизвестно и состояние оборудования неизвестно. Это значение является универсальным, поскольку значения cold , hard и warm дают подсказки относительно глубины сброса для устройства.

Загрузчики должны предоставить reason набора ядра или blunt set и настоятельно рекомендуется предоставить subreason , если ее можно определить. Например, долгое нажатие клавиши питания, которое может иметь или не иметь резервную копию ramoops , будет иметь причину загрузки "reboot,longkey" .

Ни одна reason первого диапазона не может быть частью какой-либо subreason или detail . Однако, поскольку причины набора ядра не могут быть созданы пространством пользователя, "watchdog" может быть повторно использован после грубой причины набора вместе с подробностью источника (например, "reboot,watchdog,service_manager_unresponsive" или "reboot,software,watchdog" ).

Причины загрузки не должны требовать экспертных внутренних знаний для расшифровки и/или должны быть понятны человеку с интуитивно понятным отчетом. Примеры: "shutdown,vbxd" (плохо), "shutdown,uv" (лучше), "shutdown,undervoltage" (предпочтительно).

Комбинации причина-подпричина

Android резервирует набор комбинаций reason - subreason , которые не должны быть перегружены при обычном использовании, но могут использоваться в каждом конкретном случае, если комбинация точно отражает связанное состояние. Примеры зарезервированных комбинаций включают:

  • "reboot,userrequested"
  • "shutdown,userrequested"
  • "shutdown,thermal" (от thermald )
  • "shutdown,battery"
  • "shutdown,battery,thermal" (из BatteryStatsService )
  • "reboot,adb"
  • "reboot,shell"
  • "reboot,bootloader"
  • "reboot,recovery"

Более подробную информацию можно найти в kBootReasonMap в system/core/bootstat/bootstat.cpp и в соответствующей истории изменений git в исходном репозитории Android.

Сообщить о причинах загрузки

Все причины загрузки, как из загрузчика, так и записанные в канонической причине загрузки, должны быть записаны в разделе kBootReasonMap system/core/bootstat/bootstat.cpp . Список kBootReasonMap представляет собой смесь совместимых и устаревших несовместимых причин. Разработчики загрузчика должны регистрировать здесь только новые совместимые причины (и не должны регистрировать несовместимые причины, если только продукт уже не был отправлен и не может быть изменен).

Мы настоятельно рекомендуем использовать существующие, совместимые записи в system/core/bootstat/bootstat.cpp и проявлять сдержанность перед использованием несовместимой строки. В качестве руководства это:

  • Допустимо сообщать "kernel_panic" из загрузчика, поскольку bootstat может проверить ramoops на kernel_panic signatures , чтобы уточнить подпричины в каноническом system_boot_reason_prop .
  • Недопустимо сообщать загрузчику о несоответствующей строке в kBootReasonMap (например "panic") , поскольку это в конечном итоге нарушит возможность уточнения reason .

Например, если kBootReasonMap содержит "wdog_bark" , разработчик загрузчика должен:

  • Измените на "watchdog,bark" и добавьте в список в kBootReasonMap .
  • Подумайте, что означает "bark" для тех, кто не знаком с этой технологией, и определите, существует ли более значимая subreason .

Проверка соответствия причины загрузки

В настоящее время Android не предоставляет активный тест CTS, который может точно запустить или проверить все возможные причины загрузки, которые может предоставить загрузчик; партнеры все равно могут попытаться запустить пассивный тест для определения совместимости.

В результате, соответствие загрузчика требует от разработчиков загрузчика добровольно придерживаться духа правил и рекомендаций, описанных выше. Мы призываем таких разработчиков вносить вклад в AOSP (в частности, в system/core/bootstat/bootstat.cpp ) и использовать эту возможность как форум для обсуждения проблем с загрузкой.