Introduction ============ The PIL (Peripheral Image Loader) driver loads peripheral images into memory and interfaces with the Peripheral Authentication Service (PAS) to authenticate and reset peripherals embedded in the SoC. The PAS could either be running under secure mode in the application processor (secure boot support) or be running as a non-secure kernel driver (non-secure boot support). The PIL driver also does housekeeping to handle cases where more than one client driver is using the same peripheral. Some examples of peripherals are modem, DSP and sensors. Hardware description ==================== The memory used by the peripherals for code and data storage will be accessible as normal memory to the application processor. The non-secure code (Linux kernel) will have read/write permissions to the peripheral memory by default. The PAS will have access to a MPU (memory protection unit) that can lock away the pages of memory from the Linux kernel. It will also have access to registers that can reset each peripheral. Software description ==================== The PAS provides the following three APIs: * Init image - Takes as input the peripheral id and firmware metadata and returns a status indicating the authenticity of the firmware metadata. The firmware metadata consists of a standard ELF32 header followed by a program header table and an optional blob of data used to authenticate the metadata and the rest of the firmware. * Verify segment - Takes as input the firmware segment id and the length of the segment. Authenticates whatever amount (specified by the "length" parameter) of the firmware segment that has been loaded and removes non-secure mode read/write permissions for the pages belonging to the firmware segment. Allows multiple calls for the same firmware segment to allow partial loading and authentication. * Auth and Reset - Verifies all the necessary firmware segments have been loaded and authenticated and then resets the peripheral. The user space is expected to provide the firmware metadata and firmware segments as separate files on persistent storage. See "Interface" section for further details. The PIL driver will use the request_firmware API provided by the Linux kernel to read the firmware and firmware metadata from persistent storage. When a client driver requests for a peripheral to be enabled, the PIL driver increments the reference count for that peripheral, loads the firmware metadata and calls the PAS Init Image API that initializes the authentication state machine using the firmware metadata. If the initialization succeeds, the PIL driver loads the appropriate firmware segments into their respective memory locations and call the PAS Verify segment API on each of the loaded segments to authenticate and lock it. After all the firmware segments have been successfully loaded and authenticated, the PAS Auth and Reset API is called to reset the peripheral and initiate its boot sequence. A peripheral enable request to the PIL driver will block until it succeeds (or fails) to initiate the peripheral boot sequence but will NOT block until the peripheral is ready. It is not possible to block until a peripheral is ready since the semantics of "ready" is subjective to the caller. The PIL driver will maintain a reference count for each of the peripherals. So, if a peripheral is already under use and another client driver requests for the peripheral to be enabled, the PIL driver will immediately return a value to indicate success. When all the client drivers of a particular peripheral no longer need the peripheral and the reference count reaches zero, the PIL driver can cleanly shut down the peripheral. Since a lot of drivers in their current state can't handle a peripheral restart, the PIL driver will never let the reference count go back to zero. All information about a peripheral, like firmware filenames, peripheral ID passed to PAS, etc, will be hard coded in the PIL driver. All the PIL APIs will execute in the context of the caller. This includes calls from the PIL driver to the PAS driver. The PAS driver might decide to switch into secure mode from a separate workqueue or in the same context as the caller, but that shouldn't have any implications for the PIL API callers since all the PIL APIs are blocking calls. Dependencies: ------------- * Firmware class (CONFIG_FW_LOADER) for using the request_firmware API to load firmware from persistent storage. * PAS to authenticate firmware and bring a peripheral out of reset. Error cases: ------------ The PIL driver could fail to enable a peripheral for several reasons like not having enough memory to load firmware and metadata, being unable to communicate with the PAS, the PAS returning with an error, etc. For all possible error cases, the PIL driver does not perform any retries and returns an appropriate error code. The client drivers should always check for success before trying to access the peripheral. Design ====== Design goals: ------------- * The PIL driver must be agnostic to the actual format and method used to authenticate the firmware. * Allow for future expansion to support demand loading of parts of firmware for each peripheral. * Move most of the work into the preprocessing/building stage of the firmware. * Provide an API to the client drivers that absolves them from having to know the structure or names of the firmware in persistent storage. * Handle multiple client drivers wanting to enable the same peripheral. Design reasons: --------------- The user space is expected to provide the firmware metadata and segments as separate files for the following reasons: * Don't need to load the whole ELF file if the authentication info is invalid. * Works better during low memory conditions since the amount of memory used at any given instant when loading one segment at a time is smaller than loading the whole ELF file. * Since an ELF segment in memory can be much bigger than on file, having a flat binary would waste a lot of space due to zero-fills. * Allows for future enhancements to the loading procedure. Design tradeoffs: ----------------- * With appropriate changes to the request_firmware API, the firmware blobs could be directly loaded into the right memory location. But due to the additional work and community approval that would be needed for modifying the request_firmware API, we load the firmware blobs into kernel memory and then copy them into the appropriate locations. Alternate designs: ------------------ One of the alternate designs that were considered required the firmware to be a flat binary. Although this design would simplify the PIL driver, it would result in the waste of a lot of persistent storage space (due to large zero-fills), prevent demand loading of segments in the future and use a lot more memory while loading the firmware. Software layering: ------------------ The peripheral authentication, reset and shutdown implementation is factored away into a Peripheral Authentication Service driver to allow the PIL driver to be agnostic of secure vs. non-secure boot and the mechanisms needed for communicating with any code that might be running in secure mode. Power Management ================ Some of the peripherals might support being turned off when not in use. Support for this might be disabled in the initial implementation of the PIL driver since many of the existing drivers can not handle peripheral restart. SMP/multi-core ============== Will use mutexes to protected data that might be shared (reference count, etc). Security ======== The PIL driver must validate the physical memory addresses specified in the ELF and program header table before loading firmware segments to make sure it's not overwriting any memory used by the kernel and possibly PMEM regions (if it can be done without being an ugly hack). The PIL driver might need to maintain a white list or black list of physical memory address ranges to perform the address validation. Performance =========== As mentioned in the design section, the loading of firmware segments is not optimal and has room for improvement. Interface ========= In kernel APIs: void * pil_get(char *peripheral_name) - Enables (if not already enabled) a peripheral and returns a handle that can be used to disable the peripheral at a later time. If peripheral can't be enabled successfully, then returns an error (use IS_ERR) indicating the reason. void pil_put(void *peripheral_handle) - Inform PIL that this client no longer needs the peripheral to be active. Does not necessarily mean that the peripheral would be disabled or powered off. User space APIs: All firmware must be located in the path that is expected by the hotplug (or compatible) daemon. A hotplug (or compatible) daemon should be running and be able to handle events from the kernel requesting for a firmware file. The basename of the firmware files will depend on the peripheral. For a given peripheral, the metadata filename should end with a ".mdt" and the firmware segment files should end with ".bXX" where XX denotes the index of the firmware segment starting from 0. Android hotplug compatible daemon expects the firmware files to be under /etc/firmware. Driver parameters ================= No module or kernel command line parameters supported. Config options ============== This driver is enabled using the MSM_PIL kernel config option and will depend on the CONFIG_FW_LOADER being available. Dependencies ============ Depends on firmware class module for the request_firmware API. Interacts with the PAS to authenticate the firmware and to initiate the boot sequence of a peripheral. Doesn't communicate with other processors since the secure code, if any, will be running on the application processor cores. User space utilities ==================== None. Other ===== The firmware_class driver might be changed in the future to directly load the firmware into memory locations provided by the caller of request_firmware(). Known issues ============ Since support for cleanly shutting down peripherals is yet to be added, the reference count of peripherals will never be allowed to go to zero once it becomes non-zero. To do ===== * Add support for turning off peripherals when they are not in use. * Modify request_firmware() to directly copy firmware blobs into the appropriate memory locations. * Add support for demand loading of firmware segments. * Add support for forced peripheral restarts.