4/11/2013
This section lists the functional requirements for Chrome OS drivers and describes how to implement the drivers using U-Boot APIs and configuration files. It provides links to useful code samples from the U-Boot source tree. Board ConfigurationEach board has a file that contains config options for each board component. For example, the Samsung SMDK5250 (Exynos5250) board is specified in the file include/configs/smdk5250.h. This file controls which components are enabled and specifies certain parameters for each board component. Driver ConfigurationTo add a driver for a particular class of peripheral, you need to do the following:
Audio Codec and Inter-Integrated Circuit Sound (I2S)The audio codec is commonly connected to I2S to provide the audio data and to I2C to set up the codec (for example, to control volume, output speed, headphone and speaker output). Implementation NotesThe sound.c file defines the sound_init() function, which sets up the audio codec and I2S support. Currently, this file supports the Samsung WM8994 audio codec and the Samsung I2S driver. This system would need to be expanded for other architectures to add support for new codec and I2S drivers. The sound_play() file, also defined in sound.c, plays a sound at a particular frequency for a specified period. The samsung-i2s.c file defines the i2s_tx_init() function, which sets up the I2S driver for sending audio data to the codec. It also defines i2s_transfer_tx_data(), which transfers the data to the codec. The wm8994.c file defines the wm8994_init() function, which initializes the codec hardware. Command Line InterfaceThe console commands sound_init and sound_play can be used to control the audio codec.
ClockThe AP has a number clocks that drive devices such as the eMMC, SPI flash, and display. Although the clock structure can be very complex, with a tree of 50 or more interdependent clocks, U-Boot has a simple clock implementation. With U-Boot, you need to turn on a clock, set its frequency, and then just let it run. Implementation NotesThe preferred technique is to create clock.c, which implements the clock functionality. Important clock functions to implement include the following:
EthernetAn Ethernet connection is often used during development to download a kernel from the network. This connection is also used in the factory to download the kernel and ramdisk. U-Boot supports the following network protocols:
Many x86 devices have a built-in Ethernet port. Another way to provide Ethernet to a system is to connect a USB-to-Ethernet adapter to the USB port. If the device has a built-in port, Ethernet is detected when the board starts up and is available for use. To enable the USB-to-Ethernet connection, use the U-Boot command
usb start .Another useful feature for development is that when you want to use an NFS root from the network, U-Boot can provide suitable boot arguments to the kernel on the Linux command line. Implementation NotesThe structure You need to implement the following functions for the Ethernet driver:
For USB Ethernet, the structure The xxx_eth_probe() function probes for the device and must return nonzero if it finds a device. The xxx_eth_get_info() function obtains information about the device and fills in the ueth_data structure.
Modern APs can contain hundreds of GPIOs (General Purpose Input/Output pins). GPIOs can be used to control a given line or to sense its current state. A given GPIO can serve multiple purposes. Also, peripheral pins can often also be used as GPIOs. For example, an AP MMC interface requires 11 pins that can be used as GPIOs if the MMC function is not needed.
A GPIO can be either an input or an output. If an input, its value can be read as 0 or 1. If an output, then its value can be set to 0 or 1. Generic GPIO InterfaceU-Boot provides a generic GPIO interface in
include/asm-generic/gpio.h . This interface provides the following functions:
In U-Boot, GPIOs are numbered from 0, with enums specified in the AP header file
gpio.h . For example:
The generic GPIO functions specify the GPIO pin by its number, as described in gpio.h. Additional FunctionsThe generic GPIO interface does not cover all features of a typical AP. For example, custom AP functions are required to specify the following:
Command Line InterfaceThe GPIO driver has a corresponding
Inter-Integrated Circuit Communication (I2C)The inter-integrated circuit communication (I2C) driver is the most-used driver in U-Boot for Chrome OS. For example, the I2C driver is used to send and receive data from the following devices:
Because I2C drivers form a critical part of U-Boot, they should be tested to ensure that a given I2C bus works correctly with multiple slaves and at all supported speeds. Be sure the driver correctly handles NAK messages from slaves and provides robust error handling. SetupOrdering of multiple I2C buses (there are usually half a dozen or more) is specified in the device tree file aliases section (for example, see board/samsung/dts/exynos5250-smdk5250.dts). Bus numbering is zero-based. The following function is called by the board file to set up I2C ports:
blob is the device tree.Given a node in the device tree, the following function returns the bus number of that node:
An I2C bus typically runs at either 100 kHz or 400 kHz. Ideally the driver should support exactly these speeds. In no case should the driver exceed the specified speed. The bus speed is specified in the device tree for a given bus. Although the U-Boot driver header files include functions for setting I2C bus speeds, these functions should not be used directly. Instead, set one speed for each I2C bus in the device tree, choosing the speed that matches the slowest device on a given bus. CommunicationSeveral of the I2C functions use the concept of a "current bus":
Typically, you follow this pattern:
The functions
where
Command Line InterfaceThe I2C bus has a corresponding
i2c command line interface that can be used to read and write data.
KeyboardIn Chrome OS, the keyboard is managed by the embedded controller (EC), which reports key presses to the AP using messages. Implementing support in U-Boot for the keyboard driver is different for x86 and ARM systems. On x86 systems, 8042 keyboard emulation is used over ACPI to report key presses. On ARM systems, the Chrome OS EC protocol is used to report key scans. Implementation NotesOn x86 Systems On x86 systems, the 8042 protocol is handled by a keyboard driver that communicates with the AP using an x86 I/O port. On these systems, you are responsible for implementing the keyboard driver that reports key presses to the AP.
On ARM Systems On ARM systems, the The device tree contains a keyboard node that has a linux, keymap property that defines the keycode at each position in the keyboard matrix. You may need to edit this file to reflect your keyboard. Setting up the keyboard driver. Three functions are used to initialize and register a new keyboard driver (see the function tegra_kbc_check() in tegra-kbc.c for an example of waiting for input and then checking for key presses):
Functions provided by the input layer. The following functions are defined by the input layer (input.c) and must be implemented for your driver: (TRUE? or do they just use these functions?)
Keyboard auto-repeat is handled by the input layer automatically. Functions used by input devices. U-Boot supports multiple console devices for input and output. Input devices are controlled by the environment variable stdin which contains a list of devices that can supply input. It is common for this variable to contain both serial input and keyboard input, so you can use either type of input during development. An input device has three main functions to implement for use by input_stdio_register(). Each of these functions communications with the input layer.
Configuration options. The following configuration options describe how the keyboard is connected to the EC. Include the appropriate option in the board configuration file.
LCD/VideoThe display is used to present several screens to the user. If the firmware is unable to boot, the screen displays recovery boot instructions for the user. Similarly, when the system enters developer mode, a special screen warns the user before entering this unprotected mode.
(sample screen here)
RequirementsTotal wait time to enable the LCD should be as close to zero as possible. Initialization of the LCD can be interspersed with other startup operations, but blocking time during the initialization process should be less than 10 ms.
Implementation NotesBoard File. Add a function to the board file, board_early_init_f(), to set up three LCD parameters in the panel_info struct.
U-Boot allocates memory for your display based on these parameters. (Alternatively, set up the LCD driver in the driver .c file and then add a function to the board file that calls the setup function in your driver .c file. For an example of this technique, see drivers/video/tegra.c.) lcd_ctrl_init( ) function. Sets up the display hardware. You may want to set up cache flushing in this function to speed up your display. See lcd_set_flush_dcache(), which is provided for you in common/lcd.c.Efficient Initialization. Because LCD initialization takes a long time (sometimes as much as .5 to 1 second), you may want to use a function that manages the initialization efficiently and keeps things moving. For example, see tegra_lcd_check_next_stage() in tegra.c. lcd_enable() function. As its name suggests, this function is used to enable the LCD. However, it is normally a null operation in Chrome OS because the lcd_check_next_stage() function will enable the LCD.U-Boot controls drawing characters and images and scrolling. The driver specifies a basic data structure that describes the screen parameters. The generic driver is defined in the lcd.h file: typedef struct vidinfo { ushort vl_height; /* Height of display area in millimeters */ /* LCD configuration register */ The LCD driver specifies where screen starts in memory; pixel depth, width, and height of screen. It also declares functions to enable the screen and turn it on, including the backlight.
The ARM and x86 platforms use slightly different APIs. ARM uses lcd.h and x86 uses video.h. The implementation files for both ARM and X86 are located in the drivers/video directory.
ARM Files
x86 FilesOn the x86 platform, video has its own U-Boot interface, but the existing coreboot driver will initialize the video without any further modification to U-Boot.
NANDU-Boot provides support for the following types of raw NAND drivers:
Chrome OS currently does not use raw NAND flash. Instead, it uses EMMC or SATA drivers, which provide a high-level interface to the underlying NAND flash.
Pin MultiplexingEach AP vendor is responsible for writing the code in Implementation NotesFor maximum speed, U-Boot should initialize only the pins it uses during its boot. All other pins are left in their default configuration and can be initialized later by the kernel. For example, the WiFi pinmux is not required at boot time and can be initialized later by the kernel.
PowerU-Boot code initializes both the AP power as well as the power to the system peripherals. Power to the AP is initialized using the PMIC (Power Management IC) driver. In addition to PMIC, the drivers/power directory includes subdirectories for power-related drivers for controlling the battery and for the fuel gauge that measures the current amount of power in the battery. (Chrome OS may or may not use these additional drivers.) Implementation NotesThe board-specific code is located in board/manufacturer/boardname/boardname.c (for example, board/samsung/trats/trats.c). In this file, you implement the following initialization function, which is called by the file arch/arm/lib/board.c:
This function initializes the AP power through the PMIC and turns on peripherals such as the display and eMMC. It also checks the battery if needed.
Pulse Width Modulation (PWM)The pulse width modulation (PWM) driver is often used to control display contrast and LCD backlight brightness. Implementation NotesThis driver requires you to implement generic functions defined in include/pwm.h as well as chip-specific functions defined in the AP directory. Basic functions to implement include the following:
The same driver is typically used by both the SDMMC and the eMMC. Secure Digital Multimedia Memory Card (SDMMC) refers to an external SD card. eMMC is an internal mass storage device. Chrome OS divides the disk using the EFI partitions table. The kernel is read directly from the partition without using the file system. Be sure to enable the EFI partition table in the board file using the following option:
RequirementsSDMMC
eMMC
Implementation NotesSet up the struct mmc and call mmc_register(mmc) for each MMC device (for example, once for the SDMMC and once for the eMMC). Important functions to implement include the following:
Some of the functions perform differently depending on which type of device is being initialized. For example, mmc_getcd() indicates whether an SC card is currently in the slot. This function always returns TRUE for an eMMC card. Key values to set in struct mmc include the following:
SPIThe SPI driver specifies the list of known SPI buses in a structure stored in the drivers/spi/ directory (for an example, see the exynos_spi_slave structure in drivers/spi/exynos_spi.c). The first field in this structure is another spi_slave structure, slave, which describes the bus (slave.bus) and chip select (slave.cs) for each SPI slave device. Ordering of multiple SPI buses is specified in the device tree file (for example, board/samsung/dts/exynos5250-smdk5250.dts). Each device connected to the SPI bus (for example, the EC, touchpad, and SPI flash could all be connected to this bus) contains a reference to the Implementation NotesUse this function to set up a device on the SPI bus: To drop the device from the bus, use this function:
spi_release_bus() function.
SPI FlashThe SPI flash stores the firmware and consists of a Read Only section that cannot be changed after manufacturing and a Read/Write section that can be updated in the field. RequirementsSize: The SPI flash is typically 4 or 8 Mbytes, with half allocated to the Read Only portion and half to the Read/Write portion.Speed: Because this component directly affects boot time, it must be fast: 5 Mbytes/second performance is required.Implementation NotesThere are several steps to implementing the SPI flash. First, define a prototype for your SPI flash, with a name in the form spi_flash_probe_yourDeviceName(). Add this function to spi_flash_internal.h. Also, modify spi_flash.c, adding the config option that links your prototype to the #define. For example, for the Winbond SPI flash, these lines link the spi_flash_probe_winbond() prototype to its #define:
This code passes in the first byte of the chip's ID (here, 0xef). If the ID code matches that of the attached SPI flash, the struct spi_flash is created. You also need to define the spi_flash structure that describes the SPI flash:
In this structure, you set the appropriate fields and either implement the functions for reading, writing, and erasing the SPI flash or use existing functions defined in spi_flash_internal.h.
Thermal Management Unit (TMU)The thermal management unit (TMU) monitors the temperature of the AP. If the temperature reaches the upper limit, the TMU can do one of the following:
The Implementation NotesTo implement this driver, you have two tasks:
TimerThe U-Boot timer is measured in milliseconds and increases monotonically from the time it is started. There is no concept of time of day in U-Boot. ImplementationThe timer requires two basic functions:
Typical UseThe timer is commonly used in U-Boot while the system is waiting for a specific event or response. The following example shows a typical use of the timer that can be used to ensure that there are no infinite loops or hangs during boot:
A base_value is passed into the get_timer() function, and the function returns the elapsed time since that base_value (that is, it subtracts the base_value from the current value and returns the difference). Other UsesThe
timer_get_us() function returns the current monotonic time in microseconds. This function is used in Chrome OS verified boot to obtain the current time. It is also used by bootstage to track boot time (see common/bootstage.c). It should be as fast and as accurate as possible.DelaysThe __udelay() function, also implemented in
timer.c , is called by U-Boot internally from its udelay (delay for a period in microseconds) and mdelay (delay for a period in milliseconds) functions (declared in common.h ):This function introduces a delay for a given number of microseconds. The delay should be as accurate as possible. In no case should the delay occur for less than the specified time. Command Line InterfaceThe time command can be used to time other commands. This feature is useful for benchmarking.
Trusted Platform Module (TPM)The Trusted Platform Module (TPM) is the security chip that maintains rollback counters for firmware and kernel versions and stores keys for the system. The TPM is normally connected on an LPC, SPI, or I2C bus. RequirementsThe TPM is a critical contributor to Chromium OS boot time, so it must be as fast as possible. ImplementationAll message formatting is handled in vboot_reference, so the functions you must implement for the TPM in U-Boot are for low-level initialization, open/close, and send/receive functionality:
UARTThe UART is used for serial communication to drive the serial console, which provides output during the boot process. This console allows the user to enter commands for testing and debugging.
Requirements
Implementation NotesYou register this driver by setting up a structure (serial_device{}) and then call serial_register(). The AP typically has built-in serial functions that this driver can use.
In the final shipping product, the console needs to run in silent mode. For example, this code in the driver tells the console to run in silent mode: if (fdtdec_get_config_int(gd->fdt_blob, "silent_console", 0)) gd->flags |= GD_FLG_SILENT;
USB host is used by Chrome OS in two ways:
On x86 systems, USB is often used to connect other peripherals, such as cameras and SD card readers, but Chrome OS does not require U-Boot drivers for these USB peripherals.
U-Boot supports both the EHCI and OHCI standards for USB. Be sure to test a variety of common USB storage devices to ensure that they work with your U-Boot driver. USB HubIn some cases, the USB or AP is connected to a USB hub to expand the number of USB ports. The board file may need to power up this hub and configure it. Be careful to power up the hub only if USB is used by the system. EFI Partition TableChrome OS uses an EFI partition table. To enable this table, add the following entry to the board file:
Implementation NotesUSB should not be initialized in the normal boot path. Loading a kernel from USB is a slow process (it could take a second or more) as well as a potential security risk. The two main functions to implement are the following:
int ehci_hcd_init(int index, struct ehci_hccr **hccr, struct ehci_hcor **hcor)
int ehci_hcd_stop(int index) These functions create (and destroy) the appropriate control structures to manage a new EHCI host controller. Much of this interface is standardized and implemented by U-Boot. You just point U-Boot to the address of the peripheral. Configuration OptionsThe configuration options for USB are specified in the board configuration file (for example, include/configs/seaboard.h). There are a number of #defines for different aspects of USB, including the following:
Other sections in U-Boot Porting Guide 2. Concepts
3. U-Boot Drivers (this page)
|