From 4d251019ee1b9845580c3d916655c93400222be7 Mon Sep 17 00:00:00 2001
From: Android Partner Docs
/** */
mainly for Function documents/"docstrings" used for
-generated documentation. Example:
+/** */
for generated documentation. These can be applied
+only to type, method, field, and enum value declarations. Example:
/** Replied status */ -enum FooStatus { - OK = 0, // no error - ERR_TRANSPORT = 1, // transport level error - ERR_ARG = 2 // invalid args +enum TeleportStatus { + /** Object entirely teleported. */ + OK = 0, + /** Methods return this if teleportation is not completed. */ + ERROR_TELEPORT = 1, + /** + * Teleportation could not be completed due to an object + * obstructing the path. + */ + ERROR_OBJECT = 2, + ... }
/**
, use
diff --git a/en/devices/architecture/hidl/index.html b/en/devices/architecture/hidl/index.html
index 5790b78c..35b166dd 100644
--- a/en/devices/architecture/hidl/index.html
+++ b/en/devices/architecture/hidl/index.html
@@ -135,7 +135,8 @@ of =
and |
) is part of the grammar.
Code Style Guide.
/** */
indicates a documentation comment./** */
indicates a documentation comment. These can be applied
+only to type, method, field, and enum value declarations./* */
indicates a multiline comment.//
indicates a comment to end of line. Aside from
//
, newlines are the same as any other whitespace.
+The flash
command should not erase the partition unless the host
+fastboot
tool sends an erase
command first. This
+allows flashing a very large partition in multiple smaller chunks using multiple
+sparse images that start with a "skip" block to seek over the already-written
+area. Creating these images on the fly is already handled by the
+fastboot
host side tool.
+
+Sanity checks should be done on radio and bootloader images prior to flashing in
+unlocked mode. For examples, compare to android-info.txt
created
+from the build and confirm the version matches. Also check bootloader image
+signature at flash time to make sure it will pass validation during boot (which
+may include anti-rollback features).
+
+On Google-branded devices, flashing to older versions of +bootloaders should work properly, starting from the first commercially-shipped +bootloader -- ideally sooner. +
++The kernel command line should be concatenated together from the following +locations: +
+defconfig
: from CONFIG_CMDLINEboot.img
: from cmdline (see
+system/core/mkbootimg/bootimg.h
for offsets and
+ sizes)LINUX_REBOOT_CMD_RESTART2
)
+messaging, to land as:
+androidboot.bootreason=<reason>
+Refer to Verifying +Boot. +
++To support the Google over-the-air (GOTA) +update process a recovery RAM disk must be present. +
+ ++If the standard AOSP recovery image is being used, during boot the bootloader +should read the first 32 bytes on the misc partition and boot into the recovery +image if the data there matches: "boot-recovery" This allows any pending +recovery work (e.g. applying an OTA, performing data removal, etc.) to resume +until being finished successfully. +
+
+See bootable/recovery/bootloader_message/bootloader_message.h
+for details regarding the content of a block in flash that is used for recovery
+and the bootloader to communicate.
+
+If the OEM chooses to support A/B +updates for a given device, the bootloader should meet the following +criteria: +
+has-slot:
with a value of: "yes"
+/firmware/android/slot_suffix
+Or:
+ androidboot.slot_suffix
+hardware/libhardware/include/hardware/boot_control.h
).
+/system
under A/B, the bootloader should pass ro
+root=/dev/[node] rootwait skip_initramfs init=/init
on the kernel command
+line.
+Not passing skip_initramfs will boot to recovery.
+slot-retry-count
is reset to a positive value (usually "3")
+either by the boot control HAL through the setActiveBootSlot
+callback or through the fastboot set_active
command.
+slot-successful
AND
+ slot-retry-count
= 0?fastboot
+flash system system.img
will first query the
+current-slot
variable then concatenate the result to
+system to generate the name of the partition that should be flashed (eg system_a
+or system_b)
+set_active
or the
+boot control HAL's setActiveBootSlot
, the bootloader should update
+the current slot, clear slot-unbootable
, clear
+slot-successful
, and reset the retry-count
. These are
+the only ways to clear slot-unbootable
.
+markBootSuccessful
from the HAL. The bootloader should
+never mark a partition as successfully booted.Non-A/B updatable devices should meet +these criteria to support updates:
++A bootloader is a vendor-proprietary image responsible for bringing up the +kernel on a device. It guards the device state and is responsible for +initializing the Trusted +Execution Environment (TEE) and binding its root of trust. +
+
+The bootloader is comprised of many things including splash screen. To
+start boot, the bootloader may directly flash a new image into an appropriate
+partition or optionally use recovery
to start the reflashing
+process that will match how it is done for OTA. Some device manufacturers create
+multi-part bootloaders and then combine them into a single bootloader.img file.
+At flash time, the bootloader extracts the individual bootloaders and flashes
+them all.
+
+Most importantly, the bootloader verifies the integrity of the boot and recovery +partitions before moving execution to the kernel and displays the warnings +specified in the section Boot state.
+ + diff --git a/en/devices/bootloader/partitions-images.html b/en/devices/bootloader/partitions-images.html new file mode 100644 index 00000000..7f171fef --- /dev/null +++ b/en/devices/bootloader/partitions-images.html @@ -0,0 +1,240 @@ + + +
+Android devices include several partitions that serve different functions in the
+boot process. To support A/B
+updates, the device will need one slot per partition for
+boot
, system
, vendor
, and
+radio
.
+
boot
partition contains a kernel
+image and a RAM disk combined via mkbootimg
. In order to flash the
+kernel directly without flashing a new boot partition, a virtual partition can
+be used: kernel
partition
+overwrites only the kernel (zImage, zImage-dtb, Image.gz-dtb) by writing the new
+image over the old one. To do this, it determines the start location of the
+existing kernel image in eMMC and copies to that location, keeping in mind that
+the new kernel image may be larger than the existing one. The bootloader can
+either make space by moving any data following it or abandoning the operation
+with an error. If the development kernel supplied is incompatible, you may need
+to update the dtb partition if present, or vendor or system partition with
+associated kernel modules.
+ ramdisk
partition
+overwrites only the RAM disk by writing the new image over the old one. To do
+this, it determines the start location of the existing ramdisk.img
+in eMMC and copies to that location, keeping in mind that the new RAM disk maybe
+be larger than the existing one. The bootloader can either make space by moving
+any data following it or abandon the operation with an error.system
partition mainly contains
+the Android framework.
+recovery
partition stores the
+recovery image, booted during the OTA process. If the device supports A/B updates,
+recovery can be a RAM disk contained in the boot image rather than a separate
+image.
+cache
partition stores temporary
+data and is optional if a device uses A/B updates. The cache partition doesn't
+need to be writable from the bootloader, only erasable. The size depends on the
+device type and the availability of space on userdata. Currently 50MB-100MB
+should be ok.
+misc
partition is used by recovery
+and is 4KB or larger.
+userdata
partition contains
+user-installed applications and data, including customization data.
+metadata
partition is used when
+device is encrypted and is 16MB or larger.
+vendor
partition contains any
+binary that is not distributable to the Android Open Source Project (AOSP). If
+there is no proprietary information, this partition may be omitted.
+radio
partition contains the radio
+image. This partition is only necessary for devices that include a radio that
+have radio-specific software in a dedicated partition.
+tos
partition stores the binary image
+of the Trusty OS and is only used if the device includes Trusty.+Here is how the bootloader operates: +
init
from the RAM disk and
+newer devices load it from the /system
partition.
+/system
, init
launches and starts mounting
+all the other partitions, such as /vendor
, /oem
, and
+/odm
, and then starts executing code to start the device+The bootloader relies upon these images. +
++Kernel images are created in a standard Linux format, such as zImage, Image, or +Image.gz. Kernel images can be flashed independently, combined with RAM disk +images, and flashed to the boot partition or booted from memory. When creating +kernel images, concatenated device-tree binaries are recommended over using a +separate partition for the device tree. When using multiple Device Tree Blobs +(DTBs) for different board revisions, concatenate multiple DTBs in descending +order of board revision. +
++RAM disks should contain a root file system suitable for mounting as a rootfs. +RAM disk images are combined with kernel images using mkbootfs and then flashed +into the boot partition. +
+
+Boot images should contain a kernel and RAM disk combined using an unmodified
+mkbootimg
.
+
+The mkbootimg
implementation can be found at: system/core/mkbootimg
+
+The bootloader reads the bootimg.h
+header file generated by mkbootimg and updates the kernel header to contain the
+correct location and size of the RAM disk in flash, base address of the kernel,
+command line parameters, and more. The bootloader then appends the command line
+specified in the boot image to the end of the bootloader-generated command
+line.
+
+
+If using raw NAND storage, these images must be YAFFS2, generated by an unmodified mkyaffs2image, as found in the Android Open Source Project (AOSP) at external/yaffs2/yaffs2/utils
. They have the format:
+
+
+| 2k bytes of data| yaffs extra data | padding | | 0 2048 | 0 64 | variable|
+
+
++The bootloader is responsible for consuming these images and relocating the +yaffs extra data into the appropriate location in the out-of-band area for the +given nand hardware. If software ECC is required, the bootloader should also +do that computation at this time. +
+
+The sparse image format should be supported. It is described in the document
+"ext4 compressed images" and in system/core/libsparse/sparse_format.h
;
+it is implemented in: system/core/libsparse/sparse_read.cpp
+
+If using a block-based storage device, ext4 or f2fs should be supported. To
+quickly transfer and flash large, empty ext4 file systems (userdata), store the
+image in a sparse format that contains information about which areas of the file
+system can be left unwritten. The file format is written by the
+mke2fs
utility that is also used to create the images the file
+format is read and flashed by the bootloader. See the sections below for
+attributes:
+
+ +
+32-bit CRC32 checksum of original data, counting "don't care" as 0 Standard +802.3 polynomial, use a public domain table implementation +
+
+The mke2fs
utility already knows what areas of the image need
+to be written, and will encode "don't care" chunks between them. Another tool,
+img2simg
, will convert regular (non-sparse) images to sparse
+images. Regular images have no information about "don't care" areas; the best a
+conversion can do is look for blocks of repeated data to reduce the resulting
+image size.
+
+Readers should reject images with unknown major versions and should accept images +with unknown minor versions. Readers may reject images with chunk sizes they do +not support. +
++Once the major version is validated, the reader should ignore chunks with unknown +type fields. It should skip over the chunk in the file using the "chunk size in +file" and skip "chunk size in blocks" blocks on the output. +
+
+A Cyclic Redundancy Check - 802.3 CRC32 - should be calculated for the data that
+will be written to disk. Any area that is not written (don't care, or a skipped
+chunk), should be counted as 0s in the CRC. The total number of blocks written
+or skipped should be compared against the "total blocks" field in the header.
+The tool simg2img
will convert the sparse image format to a
+standard image, which will lose the sparse information.
+
+All Google-branded devices should be made unlockable so that all partitions
+listed above can be reflashed. This unlocked mode is set with fastboot
+flashing unlock
, and once set this mode should persist across reboots.
+
+Devices should deny the fastboot flashing unlock
command
+unless fastboot flashing get_unlock_ability
is: "1" If
+get_unlock_ability
is "0" the user needs to boot to the home
+screen, go into the Settings > System > Developer
+options menu and enable the OEM unlocking option to
+set unlock_ability
to: "1" That flag should be persistent across
+reboots and across factory data resets.
+
+When the fastboot flashing unlock
command is sent, the device should
+prompt users to warn them that they may encounter problems with unofficial
+images. After acknowledging, a factory data reset should be done to prevent
+unauthorized data access. The bootloader should reset the device even if it is not
+able to reformat it properly. Only after reset can the persistent flag be set so
+that the device can be reflashed.
+
+The fastboot flashing lock
command relocks and resets the device so
+that future flash/unlock attempts require another data reset.
+
+All RAM not already overwritten should be reset during the fastboot flashing
+unlock
process. This measure prevents attacks that read leftover RAM
+contents from the previous boot. Similarly, unlocked devices should clear RAM at
+every boot if this does not create an unacceptable delay, but should leave the
+region used for the kernel's ramoops
.
+
+Devices intended for retail should be shipped in the locked state (and with
+get_unlock_ability
returning "0"). This is to ensure an attacker
+cannot compromise the device by installing their own system or boot image.
+
+The ro.oem_unlock_supported
property should be set at build time
+based on whether the device supports flashing unlock.
+ro.oem_unlock_supported
should be set to "0" if flashing unlock is
+not supported on the device or "1" if flashing unlock is supported.
+
+If the device supports flashing unlock (i.e. ro.oem_unlock_supported =
+1
), then the bootloader should indicate the lock status by setting the
+kernel command line variable androidboot.flash.locked
(or the
+/firmware/android/flash.locked
DT property) to "1" if locked or "0"
+if unlocked.
+
+Note: For devices that support dm-verity,
+you can instead use ro.boot.verifiedbootstate
to set the value of
+ro.boot.flash.locked
where the value is "0" i.e. unlocked if the
+verified boot state is orange.
+
+The device should support locking and unlocking of critical sections. Those +critical sections are defined as whatever is needed to boot the device into the +bootloader. This might include fuses, virtual partitions for a sensor hub, +first-stage bootloader, and more. +
++Locking of critical sections is defined as preventing any code (kernel, recovery +image, OTA code, etc.) running on the device from deliberately modifying any +critical section. This implies that OTAs should fail to update critical sections +if the device is in lock critical state. Transitioning from locked to unlocked +state should require a physical interaction with the device. +
+
+The physical interaction is similar to what fastboot flashing
+unlock
would cause: the user would have to press some physical buttons on the
+device. The design should not allow programmatically transitioning from
+lock critical
to unlock critical
without physical
+interaction. Devices should ship in the unlock critical
state.
+
+Any partitions or data needed for the device to run, need to be either: +
fastboot oem
command
++This includes per-device factory-specific settings, serial numbers, calibration +data, etc. +
+
+If a device supports "off-mode charging" or otherwise autoboots into a
+special mode when power is applied, fastboot oem off-mode-charge 0
+should bypass these special modes and boot as if the user had pressed the power
+button.
+
+Trusty is Google's +implementation of a Trusted Execution Environment (TEE) OS that runs alongside +Android. This is the specification for devices using ARM TrustzoneTM +technology to provide a TEE. +
++If Trusty is used as the secure OS solution on your ARM device, the bootloader +should be implemented as described within the following sections. +
++In order to load and initialize the Trusty OS (TOS), a bootloader should: +
+The following state should be configured at entry: +
+Note: r0-r3/x0-x3 also serve as scratch registers to TOS. Do +not expect their values to be preserved upon return. +
++On a 64-bit platform: +
+TOS will return to the bootloader in non-secure mode (SCR.NS set to "1") when it +is done initializing so that the bootloader may continue loading the primary +operating system (e.g., Android). +
+ + diff --git a/en/devices/camera/camera3.html b/en/devices/camera/camera3.html index 7115722e..bb2e6833 100644 --- a/en/devices/camera/camera3.html +++ b/en/devices/camera/camera3.html @@ -22,57 +22,18 @@ --> -Android's camera Hardware Abstraction Layer (HAL) connects the higher level camera framework APIs in -android.hardware.Camera -to your underlying camera driver and hardware. Android 5.0 introduced a new, -underlying implementation of the camera stack. If you have previously developed -a camera HAL module and driver for older versions of Android, be aware of -significant changes in the camera pipeline.
- -Note: The new camera HAL is in active -development and can change at any time. This document describes the high-level -design of the camera subsystem; for details, see -Camera Version Support.
- -Version 1 of the camera subsystem was designed as a black box with high-level -controls and the following three operating modes:
- -Each mode has slightly different and overlapping capabilities. This made it -hard to implement new types of features, such as burst mode, since it would fall -between two of these modes.
- -Figure 1. Camera components
- -Android 7.0 continues to support camera HAL1 as many devices still rely on -it. In addition, the Android camera service supports implementing both HALs (1 -and 3), which is useful when you want to support a less-capable front-facing -camera with camera HAL1 and a more advanced back-facing camera with camera -HAL3.
- -Note: Camera HAL2 is not supported as it was a -temporary step on the way to camera HAL3.
- -There is a single camera HAL module (with its own -version -number), which lists multiple independent camera devices that each have -their own version number. Camera module 2 or newer is required to support -devices 2 or newer, and such camera modules can have a mix of camera device -versions (this is what we mean when we say Android supports implementing both -HALs).
+android.hardware.camera2 +to your underlying camera driver and hardware. Android 8.0 introduced +Treble, switching the CameraHal API +to a stable interface defined by the HAL Interface Description Language (HIDL). +If you have previously developed a camera +HAL module and driver for older versions of Android, be aware of significant +changes in the camera pipeline. -The aim of the Android Camera API redesign is to substantially increase the ability of applications to control the camera subsystem on Android devices while @@ -125,5 +86,40 @@ have priority over repeating requests.
Figure 2. Camera core operation model
+Version 1 of the camera subsystem was designed as a black box with high-level +controls and the following three operating modes:
+ +Each mode has slightly different and overlapping capabilities. This made it +hard to implement new features such as burst mode, which falls between two of +the operating modes.
+ +Figure 1. Camera components
+ +Android 7.0 continues to support camera HAL1 as many devices still rely on +it. In addition, the Android camera service supports implementing both HALs (1 +and 3), which is useful when you want to support a less-capable front-facing +camera with camera HAL1 and a more advanced back-facing camera with camera +HAL3.
+ +There is a single camera HAL module (with its own +version +number), which lists multiple independent camera devices that each have +their own version number. Camera module 2 or newer is required to support +devices 2 or newer, and such camera modules can have a mix of camera device +versions (this is what we mean when we say Android supports implementing both +HALs).
+