• Implement the APIs specified in the driver class header file. 
• Add config option(s) for the peripheral to the board configuration file in include/configs.
• Add a node for the driver to the device tree file (.dts), specifying its properties and values as well as any additional devices that are connected to it.

The 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 Notes

The preferred technique is to create clock.c, which implements the clock functionality. Important clock functions to implement include the following:

• clock_set_rate() - sets the rate for a particular clock
• clock_start_periph_pll() - starts a peripheral clock at a particular rate
• clock_set_enable() - enable and disable a clock
• reset_periph() -  reset a peripheral
• clock_get_rate() - queries the clock rate

GPIO 

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.

The generic GPIO functions specify the GPIO pin by its number, as described in gpio.h.

Additional Functions

Command Line Interface

The GPIO driver has a corresponding gpio command line interface that can be used to set and get GPIO values. See common/cmd_gpio.c for a list of commands (input, set, clear, toggle). The gpio status command, which you must implement, displays the status of all GPIOs in the system. This useful command should be able to accept both numbers and names for GPIO pins, as defined in gpio.h.

back to top

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:

• PMIC (Power Module)
• Trusted Platform Module (TPM)
• Embedded Controller
• Battery gas gauge
• Battery charger
• LCD/EDID
• Audio codec

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.

Setup

1. Call i2c_get_bus_num() to obtain the current bus.
2. Store this bus number so that you can restore this state when you are finished with your transaction.  
3. Call i2c_set_bus_num() to set the bus for your current transaction.
4. Perform processing on this bus (sending and receiving data).  
5. Finally, call i2c_set_bus_num() to reset the bus to its original number.

back to top

Keyboard

In 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 Notes

    On 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 cros_ec driver communicates with the EC and requests key scans. Each message contains the state of every key on the keyboard. This design is chosen to keep the EC as simple as possible. On ARM systems, the U-Boot and Linux code provides built-in support for converting key scans into key presses through the input layer (input.c and key_matrix.c).

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):

• input_init() - initializes a new keyboard driver.
• read_keys() - called when the input layer is ready for more keyboard input.
• input_stdio_register() -  registers a new input device (see "Functions Used by Input Devices," below).

    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.

• getc() - obtains a character and then passes it to input_getc() in the input layer.
• tstc() - checks whether a character is present (but does not read it) and then passes the result to input_tst().
• start() - starts the input device; is called by the input system when the device is selected for input.

back to top

LCD/Video

Requirements

Implementation Notes

Board File. Add a function to the board file, board_early_init_f(), to set up three LCD parameters in the panel_info struct.

• vl_col
• vl_row
• vl_bpix

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.)

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.

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: 

x86 Files 

back to top

• MTD - drivers for communicating with a NAND device as a block device. A wide variety of NAND chips are supported.
• ECC - support for error correction and detection
• YAFFS2 - a type of file system used by NAND flash
• UBIFS - another type of file system used by NAND flash

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.

Power

U-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 Notes

back to top

Pulse Width Modulation (PWM)

The pulse width modulation (PWM) driver is often used to control display contrast and LCD backlight brightness.

Implementation Notes

This 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:

back to top

SDMMC and eMMC

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.

We do not currently use eMMC boot blocks. Chrome OS can boot from an external SD card or from internal eMMC. It is convenient to be able to boot from eMMC for development purposes. 

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:

• #define CONFIG_EFI_PARTITION

Requirements

SDMMC

• 4-bit.
• Speed not critical as this device is used only in developer/recovery modes. 

eMMC 

• 8-bit data width, ideally DDR.
• Speed:  For reading, 40Mbytes/sec or better is required.  Writing speed is less critical because the eMMC rarely performs write operations in U-Boot.

Implementation Notes

Set 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:

• send_cmd() -  send a command to the MMC device
• set_ios() - to set the I/O speed
• init() - to initialize the driver

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:

• voltages - supported voltages
• host_caps - capabilities of your chip
• f_min - minimum frequency
• f_max - maximum frequency

 back to top

SPI

back to top

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:

• Slow the system down until it cools to a certain point
• Power off the system before it melts

The dtt command can be used on the console to perform these functions.

Implementation Notes

To implement this driver, you have two tasks:

• Create a TMU driver and connect it to the dtt command by modifying the file common/cmd_dtt.c.
• Set up a thermal trip in your board file. The temperature limits should be defined in the device tree.

back to top

Timer

The 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. 

Implementation

Typical Use

The 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 Uses

Delays

Command Line Interface

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.

back to top

UART

Requirements

Implementation Notes

struct serial_device {
	/* enough bytes to match alignment of following func pointer */
	char	name[16];

	int	(*start)(void);
	int	(*stop)(void);
	void	(*setbrg)(void);
	int	(*getc)(void);
	int	(*tstc)(void);
	void	(*putc)(const char c);
	void	(*puts)(const char *s);
#if CONFIG_POST & CONFIG_SYS_POST_UART
	void	(*loop)(int);
#endif
	struct serial_device	*next;
};

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:

Other sections in U-Boot Porting Guide