The touchscreen driver is used to power on its integrated circuit \(IC\), configure and initialize hardware pins, register interrupts, configure Inter-Integrated Circuit \(I2C\) or SPI APIs, set input-related configurations, and download and update firmware.
### Function Introduction
The touchscreen driver powers on its integrated circuit (IC), initializes hardware pins, registers interrupts, configures the communication (I2C or SPI) interface, sets input configurations, and downloads and updates firmware.
-**Layers of the Touchscreen driver**
The touchscreen driver is developed based on the OpenHarmony input driver model, which applies basic APIs of the operating system abstraction layer (OSAL) and platform interface layer on the OpenHarmony Hardware Driver Foundation [(HDF)](../driver/driver-hdf-development.md). Common APIs include the bus communication APIs and OS native APIs (such as memory, lock, thread, and timer APIs). The OSAL and platform APIs shield the differences of underlying hardware. This allows the use of the touchscreen driver across platforms and OSs. In this regard, you can develop the touchscreen driver only once and deploy it on multiple devices.
This section describes how to develop the touchscreen driver based on the input driver model. [Figure 1](#fig6251184817261) shows an overall architecture of the touchscreen driver.
### Working Principles
The input driver is developed based on the hardware driver foundation \(HDF\), platform APIs, and operating system abstraction layer \(OSAL\) APIs. It provides hardware driver capabilities through the input Hardware Device Interfaces \(HDIs\) for upper-layer input services to control the touchscreen.
The input driver model is developed based on the HDF and APIs of the platform and OSAL. It provides hardware driver capabilities through the input Hardware Driver Interface (HDI) for upper-layer input services to control the touchscreen. The following figure shows the architecture of the input driver model.
**Figure 1** Input driver model
**Figure 1** Architecture of the input driver model<aname="fig6251184817261"></a>
The input driver model mainly consists of the device manager, common drivers, and chip drivers. The platform data channel provides capabilities for sending data generated by the touchscreen from the kernel to the user space. The driver model adapts to different touchscreen devices and hardware platforms via the configuration file, improving the efficiency of the touchscreen development. The description for each part of the input driver model is as follows:
- Input Device Manager: provides APIs for input device drivers to register and deregister input devices and manages the input device list in a unified manner.
- Common input drivers: provide common APIs that are applicable to different input devices (such as the common driver APIs for touchscreens). The APIs can be used to initialize board-specific hardware, handle hardware interrupts, and register input devices with the Input Device Manager.
- Input chip drivers: provide differentiated APIs for the drivers form different vendors. You can use these APIs to develop your drivers with minimum modification.
- Event Hub: provides a unified channel for different input devices to report input events.
- HDF input config: parses and manages the board-specific and private configuration of input devices.
- Input device manager: provides input device drivers with the APIs for registering or unregistering input devices and manages the input device list.
The input driver model provides configuration files to help you quickly develop your drivers.
- Input common driver: provides common abstract drivers \(such as the touchscreen common driver\) of various input devices for initializing the board-level hardware, processing hardware interrupts, and registering input devices with the input device manager.
- Input chip driver: provides different chip drivers of each vendor. You can minimize the workload for the input chip driver development by calling differentiated APIs reserved by the input platform driver.
## How to Develop
- Event hub: provides a unified data reporting channel, which enables input devices to report input events.
### When to Use
- HDF input config: parses and manages the board-level configuration as well as the private configuration of input devices.
The input module provides APIs for powering on the touchscreen driver IC, configuring and initializing hardware pins, registering interrupts, configuring the communication (I2C or SPI) interface, setting input configurations, and downloading and updating firmware.
### Available APIs
-**Advantages of developing drivers based on the HDF**
#### Hardware Interfaces
The touchscreen driver is developed based on the [HDF](driver-hdf-development.md) and is implemented via calls to the OSAL and platform APIs, including bus APIs and OS native APIs \(such as memory, lock, thread, and timer\). The OSAL and platform APIs hide the differences of underlying hardware, so that the touchscreen driver can be migrated across platforms and OSs. In this regard, you can develop the touchscreen driver only once but deploy it on multiple devices.
The hardware interfaces for touchscreens can be classified into the following types based on the pin attributes:
- Power interfaces
## Available APIs<a name="section105459441659"></a>
- I/O control interfaces
Based on the attributes of the pins, interfaces on the touchscreens can be classified into the following types:
- Communication interfaces
- Power interfaces
**Figure 2** Common touchscreen pins
- I/O control interfaces
- Communications interfaces
**Figure 2** Common pins of the touchscreen<aname="fig1290384314416"></a>
The interfaces shown in the figure are described as follows:
The interfaces shown in the preceding figure are described as follows:
1.**Power interfaces**
-**LDO_1P8**: 1.8 V digital circuit
-**LDO_3P3**: 3.3 V analog circuit
If the touchscreen driver and ICD driver have its own IC, the touchscreen driver IC requires 1.8 V and 3.3 V power supplies. If the touchscreen driver and LCD driver have an integrated IC, you only need to care about the 1.8 V power supply for the touchscreen. The 3.3 V power supply required can be provided by the LCD VSP power (typically 5.5 V) in the driver IC.
2.**I/O control interfaces**
-**RESET**: pin used to reset the driver IC on the host when the kernel is put into hibernation or waken up.
-**INT**: interrupt pin, which must be set to the input pull-up state during driver initialization. After detecting an external touch signal, the driver triggers an interrupt by operating the interrupt pin. Then, the driver reads the touch reporting data in an interrupt handler.
3.**Communication interfaces**
-**Power interfaces**
- I2C: I2C is used if a small amount of data is reported by the touchscreen. For details about the I2C protocol and related operation APIs, see [I2C](../driver/driver-platform-i2c-des.md).
- LDO\_1P8: 1.8 V digital circuits
- SPI: SPI is used if a large amount of data is reported by the touchscreen. For details about the SPI protocol and related operation APIs, see [SPI](../driver/driver-platform-spi-des.md).
- LDO\_3P3: 3.3 V analog circuits
Generally, the touchscreen driver IC is separated from the LCD driver IC. In this case, the touchscreen driver IC requires both 1.8 V and 3.3 V power supplies. Nowadays, the touchscreen driver IC and LCD driver IC can be integrated. Therefore, the touchscreen, requires only the 1.8 V power supply, and the 3.3 V power required internally is supplied by the LCD VSP power \(typical value: 5.5 V\) in the driver IC.
#### Software Interfaces
-**I/O control interfaces**
The HDI driver APIs provided for the input service can be classified into the input manager module, input reporter module, and input controller module. The following tables describe the available APIs.
- RESET: reset pin, which is used to reset the driver IC on the host when suspending or resuming the system.
- INT: interrupt pin, which needs to be set to the input direction and pull-up status during driver initialization. After detecting an external touch signal, the driver triggers the interrupt by operating the interrupt pin. The driver reads the touch reporting data in the ISR function.
-**Communications interfaces**
- input_manager.h
- I2C: Since only a small amount of touch data is reported by the touchscreen, I2C is used to transmit the reported data. For details about the I2C protocol and interfaces, see [I2C](driver-platform-i2c-des.md#section5361140416).
- SPI: In addition to touch reporting data coordinates, some vendors need to obtain basic capacitance data. Therefore, Serial Peripheral Interface \(SPI\) is used to transmit such huge amount of data. For details about the SPI protocol and interfaces, see [SPI](driver-platform-spi-des.md#overview).
## How to Develop<a name="section65745222184"></a>
- input_reporter.h
Regardless of the OS and system on a chip \(SoC\), the input driver is developed based on the HDF, platform, and OSAL APIs to provide a unified driver model for touchscreen devices.
| int32_t (*RegisterReportCallback)(uint32_t devIndex, InputReportEventCb *callback); | Registers a callback for an input device.|
| int32_t (*UnregisterReportCallback)(uint32_t devIndex); | Unregisters the callback for an input device.|
| void (*ReportEventPkgCallback)(const EventPackage **pkgs, uint32_t count); | Called to report input event data. |
The following uses the touchscreen driver as an example to describe the loading process of the input driver model:
- input_controller.h
1. Complete the device description configuration, such as the loading priority, board-level hardware information, and private data, by referring to the existing template.
2. Load the input device management driver. The input management driver is loaded automatically by the HDF to create and initialize the device manager.
For more information, see [input](https://gitee.com/openharmony/drivers_peripheral/tree/master/input).
3. Load the platform driver. The platform driver is loaded automatically by the HDF to parse the board-level configuration, initialize the hardware, and provide the API for registering the touchscreen.
### Development Procedure
4. Load the touchscreen driver. The touchscreen driver is loaded automatically by the HDF to instantiate the touchscreen device, parse the private data, and implement differentiated APIs provided by the platform.
The load process of the input driver model (for the touchscreen driver) is as follows:
5. Register the instantiated touchscreen device with the platform driver. Then bind this device to the platform driver, and complete touchscreen initialization such as interrupt registration and power-on and power-off.
1. The device configuration, including the driver loading priority, board-specific hardware information, and private data, is complete.
6. Instantiate the input device and register it with the input manager after the touchscreen is initialized.
2. The HDF driver loads the input device manager driver to create and initialize the device manager.
3. The HDF loads the platform driver to parse the board-specific configuration, initialize the hardware, and provide the API for registering the touchscreen.
Perform the following steps:
4. The HDF loads the touchscreen driver to instantiate the touchscreen device, parse the private data, and implement the differentiated APIs for the platform.
1. Add the touchscreen driver-related descriptions.
5. The instantiated touchscreen device registers with the platform driver to bind the device and the driver and complete the device initialization, including interrupt registration and device power-on and power-off.
Currently, the input driver is developed based on the HDF and is loaded and started by the HDF. Register the driver information, such as whether to load the driver and the loading priority in the configuration file. Then, the HDF starts the registered driver modules one by one. For details about the driver configuration, see [How to Develop](driver-hdf-development.md).
6. The instantiated input device registers with the input device manager for unified management.
2. Complete the board-level configuration and private data configuration of the touchscreen.
Configure the required I/O pins. For example, configure a register for the I2C pin reserved for the touchscreen to use I2C for transmitting data.
The development process of the touchscreen driver is as follows:
3. Implement differentiated adaptation APIs of the touchscreen.
1. Configure device information. <br>The input driver is developed based on the HDF. The HDF loads and starts the driver in a unified manner. You need to configure the driver information, such as whether to load the driver and the loading priority, in the configuration file. Then, the HDF starts the registered driver modules one by one. For details about how to configure the driver, see [Driver Development](../driver/driver-hdf-development.md#how-to-develop).
Use the platform APIs to perform operations for the reset pins, interrupt pins, and power based on the communications interfaces designed for boards. For details about the GPIO-related operations, see [GPIO](driver-platform-gpio-des.md#overview).
2. Configure board-specific information and touchscreen private information.<br>Configure the I/O pin functions. For example, set registers for the I2C pins on the board for the touchscreen to enable I2C communication.
3. Implement device-specific APIs.<br>Based on the communication interfaces designed for the board, use the pin operation APIs provided by the platform interface layer to configure the corresponding reset pin, interrupt pin, and power operations. For details about GPIO operations, see [GPIO](../driver/driver-platform-gpio-des.md).
## Development Example<a name="section263714411191"></a>
This example describes how to develop the touchscreen driver.
### Development Example
### Adding the Touchscreen Driver-related Description<a name="section18249155619195"></a>
The following example describes how to develop the touchscreen driver for an RK3568 development board.
The information about modules of the input driver model is shown as follows and enables the HDF to load the modules in sequence. For details, see [Driver Development](driver-hdf-development.md).
1. Configure device information.
```
Configure the modules of the input driver model in **drivers/adapter/khdf/linux/hcs/device_info/device_info.hcs**. For details, see [Driver Development](../driver/driver-hdf-development.md). Then, the HDF loads the modules of the input model in sequence based on the configuration information.
input :: host {
```c
input::host{
hostName="input_host";
hostName="input_host";
priority=100;
priority=100;
device_input_manager::device{
device_input_manager::device{
device0::deviceNode{
device0::deviceNode{
policy = 2; // Publish services externally.
policy=2;// The driver provides services externally.
priority = 100; // Loading priority. The input device manager in the input driver has the highest priority.
priority=100;// Loading priority. In the input model, the manager module has the highest priority.
preload = 0; // Value 0 indicates that the driver is to be loaded, and value 1 indicates the opposite.
preload=0;// Whether to load the driver. The value 0 means to load the driver; 1 means the opposite.
permission=0660;
permission=0660;
moduleName="HDF_INPUT_MANAGER";
moduleName="HDF_INPUT_MANAGER";
serviceName="input_dev_manager";
serviceName="input_dev_manager";
...
@@ -145,44 +178,44 @@ input :: host {
...
@@ -145,44 +178,44 @@ input :: host {
deviceMatchAttr="zsj_sample_5p5";
deviceMatchAttr="zsj_sample_5p5";
}
}
}
}
}
}
```
```
### Adding Board Configuration and Touchscreen Private Configuration<a name="section3571192072014"></a>
2. Configure board-specific and private data for the touchscreen.
The following describes the configuration of the board-level hardware and private data of the touchscreen. You can modify the configuration based on service requirements.
Configure the data in **drivers/adapter/khdf/linux/hcs/input/input_config.hcs**. The following is an example. You can modify the configuration as required.
```
```c
root {
root{
input_config{
input_config{
touchConfig{
touchConfig{
touch0{
touch0{
boardConfig{
boardConfig{
match_attr="touch_device1";
match_attr="touch_device1";
inputAttr{
inputAttr{
inputType = 0; // Value 0 indicates that the input device is a touchscreen.
inputType=0;// 0 indicates touchscreen.
solutionX=480;
solutionX=480;
solutionY=960;
solutionY=960;
devName = "main_touch"; // Device name
devName="main_touch";// Device name.
}
}
busConfig{
busConfig{
busType = 0; // Value 0 indicates the I2C bus.
busType=0;// 0 indicates I2C.
busNum=6;
busNum=6;
clkGpio=86;
clkGpio=86;
dataGpio=87;
dataGpio=87;
i2cClkIomux = [0x114f0048, 0x403]; // Register configuration of the i2c_clk pin
i2cClkIomux=[0x114f0048,0x403];// Register of the I2C_CLK pin.
i2cDataIomux = [0x114f004c, 0x403]; // Register configuration of the i2c_data pin
i2cDataIomux=[0x114f004c,0x403];// Register of the I2C_DATA pin.
}
}
pinConfig{
pinConfig{
rstGpio=3;
rstGpio=3;
intGpio=4;
intGpio=4;
rstRegCfg = [0x112f0094, 0x400]; // Register configuration of the reset pin
rstRegCfg=[0x112f0094,0x400];// Register of the reset pin.
intRegCfg = [0x112f0098, 0x400]; // Register configuration of the interrupt pin
intRegCfg=[0x112f0098,0x400];// Register of the interrupt pin.
}
}
powerConfig{
powerConfig{
vccType = 2; // Values 1, 2, and 3 indicate the low-dropout regulator (LDO), GPIO, and PMIC, respectively.
vccType=2;// The value 1 stands for LDO, 2 for GPIO, and 3 for PMIC.
vccNum = 20; // The GPIO number is 20.
vccNum=20;// Set the GPIO number to 20.
vccValue = 1800; // The voltage amplitude is 1800 mV.
vccValue=1800;// Set the voltage amplitude to 1800 mV.
vciType=1;
vciType=1;
vciNum=12;
vciNum=12;
vciValue=3300;
vciValue=3300;
...
@@ -201,19 +234,19 @@ root {
...
@@ -201,19 +234,19 @@ root {
match_attr="";
match_attr="";
chipName="sample";
chipName="sample";
vendorName="zsj";
vendorName="zsj";
chipInfo = "AAAA11222"; // The first four characters indicate the product name. The fifth and sixth characters indicate the IC model. The last three characters indicate the chip model.
chipInfo="AAAA11222";// The first four characters indicate the product name. The fifth and sixth characters indicate the IC model. The last three characters indicate the model number.
busType=0;
busType=0;
deviceAddr=0x5D;
deviceAddr=0x5D;
irqFlag = 2; // Values 1 and 2 indicate that the interrupt is triggered on the rising and falling edges, respectively. Values 4 and 8 indicate that the interrupt is triggered by the high and low levels, respectively.
irqFlag=2;// The value 1 means to trigger an interrupt on the rising edge, 2 means to trigger an interrupt on the falling edge, 4 means to trigger an interrupt by the high level, and 8 means to trigger an interrupt by the low level.
maxSpeed=400;
maxSpeed=400;
chipVersion=0;
chipVersion=0;
powerSequence{
powerSequence{
/* Power-on sequence is described as follows:
/* Description of the power-on sequence:
[Type, status, direction, delay]
[type, status, direction, delay]
<type> Value 0 indicates the power or pin is empty. Values 1 and 2 indicate the VCC (1.8 V) and VCI (3.3 V) power, respectively. Values 3 and 4 indicate the reset and interrupt pins, respectively.
<type> 0 stands for null; 1 for VCC power (1.8 V); 2 for VCI power (3.3 V); 3 for reset pin; 4 for interrupt pin.
<status> Values 0 and 1 indicate the power-off or pull-down, and the power-on or pull-up, respectively. Value 2 indicates that no operation is performed.
<status> 0 stands for power-off or pull-down; 1 for power-on or pull-up; 2 for no operation.
<dir> Values 0 and 1 indicate the input and output directions, respectively. Value 2 indicates that no operation is performed.
<dir> 0 stands for input; 1 for output; 2 for no operation.
<delay> Delay time, in milliseconds.
<delay> indicates the delay, in milliseconds. For example, 20 indicates 20 ms delay.
*/
*/
powerOnSeq=[4,0,1,0,
powerOnSeq=[4,0,1,0,
3,0,1,10,
3,0,1,10,
...
@@ -234,17 +267,17 @@ root {
...
@@ -234,17 +267,17 @@ root {
}
}
}
}
}
}
}
}
```
```
### Adding the Touchscreen Driver<a name="section6356758162015"></a>
3. Add the touchscreen driver.
The following example shows how to implement the differentiated APIs provided by the platform driver to obtain and parse the touchscreen data. You can adjust the development process based on the board and touchscreen in use.
Implement the touchscreen-specific APIs in **divers/framework/model/input/driver/touchscreen/touch_gt911.c**. The following uses the APIs for obtaining and parsing device data as an example. You can implement the related APIs to match your development.
```
```c
/* Parse the touch reporting data read from the touchscreen into coordinates. */
/* Parse the touch reporting data read from the touchscreen into coordinates. */
