1# Touchscreen<a name="EN-US_TOPIC_0000001052857350"></a> 2 3## Overview<a name="section175431838101617"></a> 4 5- **Functions of the Touchscreen driver** 6 7 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. 8 9 10- **Layers of the Touchscreen driver** 11 12 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. 13 14 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. 15 16 17**Figure 1** Architecture of the input driver model<a name="fig6251184817261"></a> 18 19 20- **Input driver model** 21 22 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: 23 24 - Input device manager: provides input device drivers with the APIs for registering or unregistering input devices and manages the input device list. 25 26 - 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. 27 28 - 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. 29 30 - Event hub: provides a unified data reporting channel, which enables input devices to report input events. 31 32 - HDF input config: parses and manages the board-level configuration as well as the private configuration of input devices. 33 34 35- **Advantages of developing drivers based on the HDF** 36 37 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. 38 39 40## Available APIs<a name="section105459441659"></a> 41 42Based on the attributes of the pins, interfaces on the touchscreens can be classified into the following types: 43 44- Power interfaces 45- I/O control interfaces 46- Communications interfaces 47 48**Figure 2** Common pins of the touchscreen<a name="fig1290384314416"></a> 49 50 51The interfaces shown in the figure are described as follows: 52 53- **Power interfaces** 54 - LDO\_1P8: 1.8 V digital circuits 55 - LDO\_3P3: 3.3 V analog circuits 56 57 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. 58 59- **I/O control interfaces** 60 - RESET: reset pin, which is used to reset the driver IC on the host when suspending or resuming the system. 61 - 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. 62 63- **Communications interfaces** 64 - 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). 65 - 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#section193356154511). 66 67 68## How to Develop<a name="section65745222184"></a> 69 70Regardless 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. 71 72The following uses the touchscreen driver as an example to describe the loading process of the input driver model: 73 741. Complete the device description configuration, such as the loading priority, board-level hardware information, and private data, by referring to the existing template. 75 762. Load the input device management driver. The input management driver is loaded automatically by the HDF to create and initialize the device manager. 77 783. 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. 79 804. 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. 81 825. 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. 83 846. Instantiate the input device and register it with the input manager after the touchscreen is initialized. 85 86 87Perform the following steps: 88 891. Add the touchscreen driver-related descriptions. 90 91 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/driver-hdf-development.md#how-to-develop). 92 932. Complete the board-level configuration and private data configuration of the touchscreen. 94 95 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. 96 973. Implement differentiated adaptation APIs of the touchscreen. 98 99 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). 100 101 102## Development Example<a name="section263714411191"></a> 103 104This example describes how to develop the touchscreen driver. 105 106### Adding the Touchscreen Driver-related Description<a name="section18249155619195"></a> 107 108The 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). 109 110``` 111input :: host { 112 hostName = "input_host"; 113 priority = 100; 114 device_input_manager :: device { 115 device0 :: deviceNode { 116 policy = 2; // Publish services externally. 117 priority = 100; // Loading priority. The input device manager in the input driver has the highest priority. 118 preload = 0; // Value 0 indicates that the driver is to be loaded, and value 1 indicates the opposite. 119 permission = 0660; 120 moduleName = "HDF_INPUT_MANAGER"; 121 serviceName = "input_dev_manager"; 122 deviceMatchAttr = ""; 123 } 124 } 125 device_hdf_touch :: device { 126 device0 :: deviceNode { 127 policy = 2; 128 priority = 120; 129 preload = 0; 130 permission = 0660; 131 moduleName = "HDF_TOUCH"; 132 serviceName = "event1"; 133 deviceMatchAttr = "touch_device1"; 134 } 135 } 136 137 device_touch_chip :: device { 138 device0 :: deviceNode { 139 policy = 0; 140 priority = 130; 141 preload = 0; 142 permission = 0660; 143 moduleName = "HDF_TOUCH_SAMPLE"; 144 serviceName = "hdf_touch_sample_service"; 145 deviceMatchAttr = "zsj_sample_5p5"; 146 } 147 } 148} 149``` 150 151### Adding Board Configuration and Touchscreen Private Configuration<a name="section3571192072014"></a> 152 153The following describes the configuration of the board-level hardware and private data of the touchscreen. You can modify the configuration based on service requirements. 154 155``` 156root { 157 input_config { 158 touchConfig { 159 touch0 { 160 boardConfig { 161 match_attr = "touch_device1"; 162 inputAttr { 163 inputType = 0; // Value 0 indicates that the input device is a touchscreen. 164 solutionX = 480; 165 solutionY = 960; 166 devName = "main_touch"; // Device name 167 } 168 busConfig { 169 busType = 0; // Value 0 indicates the I2C bus. 170 busNum = 6; 171 clkGpio = 86; 172 dataGpio = 87; 173 i2cClkIomux = [0x114f0048, 0x403]; // Register configuration of the i2c_clk pin 174 i2cDataIomux = [0x114f004c, 0x403]; // Register configuration of the i2c_data pin 175 } 176 pinConfig { 177 rstGpio = 3; 178 intGpio = 4; 179 rstRegCfg = [0x112f0094, 0x400]; // Register configuration of the reset pin 180 intRegCfg = [0x112f0098, 0x400]; // Register configuration of the interrupt pin 181 } 182 powerConfig { 183 vccType = 2; // Values 1, 2, and 3 indicate the low-dropout regulator (LDO), GPIO, and PMIC, respectively. 184 vccNum = 20; // The GPIO number is 20. 185 vccValue = 1800; // The voltage amplitude is 1800 mV. 186 vciType = 1; 187 vciNum = 12; 188 vciValue = 3300; 189 } 190 featureConfig { 191 capacitanceTest = 0; 192 gestureMode = 0; 193 gloverMOde = 0; 194 coverMode = 0; 195 chargerMode = 0; 196 knuckleMode = 0; 197 } 198 } 199 chipConfig { 200 template touchChip { 201 match_attr = ""; 202 chipName = "sample"; 203 vendorName = "zsj"; 204 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. 205 busType = 0; 206 deviceAddr = 0x5D; 207 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. 208 maxSpeed = 400; 209 chipVersion = 0; 210 powerSequence { 211 /* Power-on sequence is described as follows: 212 [Type, status, direction, delay] 213 <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. 214 <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. 215 <dir> Values 0 and 1 indicate the input and output directions, respectively. Value 2 indicates that no operation is performed. 216 <delay> Delay time, in milliseconds. 217 */ 218 powerOnSeq = [4, 0, 1, 0, 219 3, 0, 1, 10, 220 3, 1, 2, 60, 221 4, 2, 0, 0]; 222 suspendSeq = [3, 0, 2, 10]; 223 resumeSeq = [3, 1, 2, 10]; 224 powerOffSeq = [3, 0, 2, 10, 225 1, 0, 2, 20]; 226 } 227 } 228 chip0 :: touchChip { 229 match_attr = "zsj_sample_5p5"; 230 chipInfo = "ZIDN45100"; 231 chipVersion = 0; 232 } 233 } 234 } 235 } 236 } 237} 238``` 239 240### Adding the Touchscreen Driver<a name="section6356758162015"></a> 241 242The 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. 243 244``` 245/* Parse the touch reporting data read from the touchscreen into coordinates. */ 246static void ParsePointData(ChipDevice *device, FrameData *frame, uint8_t *buf, uint8_t pointNum) 247{ 248 int32_t resX = device->driver->boardCfg->attr.resolutionX; 249 int32_t resY = device->driver->boardCfg->attr.resolutionY; 250 251 for (int32_t i = 0; i < pointNum; i++) { 252 frame->fingers[i].y = (buf[GT_POINT_SIZE * i + GT_X_LOW] & ONE_BYTE_MASK) | 253 ((buf[GT_POINT_SIZE * i + GT_X_HIGH] & ONE_BYTE_MASK) << ONE_BYTE_OFFSET); 254 frame->fingers[i].x = (buf[GT_POINT_SIZE * i + GT_Y_LOW] & ONE_BYTE_MASK) | 255 ((buf[GT_POINT_SIZE * i + GT_Y_HIGH] & ONE_BYTE_MASK) << ONE_BYTE_OFFSET); 256 frame->fingers[i].valid = true; 257 } 258} 259/* Obtain the touch reporting data from the chip. */ 260static int32_t ChipDataHandle(ChipDevice *device) 261{ 262 int32_t ret; 263 uint8_t touchStatus = 0; 264 uint8_t pointNum; 265 uint8_t buf[GT_POINT_SIZE * MAX_SUPPORT_POINT] = {0}; 266 InputI2cClient *i2cClient = &device->driver->i2cClient; 267 uint8_t reg[GT_ADDR_LEN] = {0}; 268 FrameData *frame = &device->driver->frameData; 269 reg[0] = (GT_BUF_STATE_ADDR >> ONE_BYTE_OFFSET) & ONE_BYTE_MASK; 270 reg[1] = GT_BUF_STATE_ADDR & ONE_BYTE_MASK; 271 ret = InputI2cRead(i2cClient, reg, GT_ADDR_LEN, &touchStatus, 1); 272 if (ret < 0 || touchStatus == GT_EVENT_INVALID) { 273 return HDF_FAILURE; 274 } 275 OsalMutexLock(&device->driver->mutex); 276 (void)memset_s(frame, sizeof(FrameData), 0, sizeof(FrameData)); 277 if (touchStatus == GT_EVENT_UP) { 278 frame->realPointNum = 0; 279 frame->definedEvent = TOUCH_UP; 280 goto exit; 281 } 282 reg[0] = (GT_X_LOW_BYTE_BASE >> ONE_BYTE_OFFSET) & ONE_BYTE_MASK; 283 reg[1] = GT_X_LOW_BYTE_BASE & ONE_BYTE_MASK; 284 pointNum = touchStatus & GT_FINGER_NUM_MASK; 285 if (pointNum <= 0 || pointNum > MAX_SUPPORT_POINT) { 286 HDF_LOGE("%s: pointNum is invalid, %d", __func__, pointNum); 287 (void)ChipCleanBuffer(i2cClient); 288 OsalMutexUnlock(&device->driver->mutex); 289 return HDF_FAILURE; 290 } 291 frame->realPointNum = pointNum; 292 frame->definedEvent = TOUCH_DOWN; 293 /* Read the touch reporting data from the register. */ 294 (void)InputI2cRead(i2cClient, reg, GT_ADDR_LEN, buf, GT_POINT_SIZE * pointNum); 295 /* Parse the touch reporting data. */ 296 ParsePointData(device, frame, buf, pointNum); 297exit: 298 OsalMutexUnlock(&device->driver->mutex); 299 if (ChipCleanBuffer(i2cClient) != HDF_SUCCESS) { 300 return HDF_FAILURE; 301 } 302 return HDF_SUCCESS; 303} 304 305static struct TouchChipOps g_sampleChipOps = { 306 .Init = ChipInit, 307 .Detect = ChipDetect, 308 .Resume = ChipResume, 309 .Suspend = ChipSuspend, 310 .DataHandle = ChipDataHandle, 311}; 312 313static TouchChipCfg *ChipConfigInstance(struct HdfDeviceObject *device) 314{ 315 TouchChipCfg *chipCfg = (TouchChipCfg *)OsalMemAlloc(sizeof(TouchChipCfg)); 316 if (chipCfg == NULL) { 317 HDF_LOGE("%s: instance chip config failed", __func__); 318 return NULL; 319 } 320 (void)memset_s(chipCfg, sizeof(TouchChipCfg), 0, sizeof(TouchChipCfg)); 321 /* Parse the private configuration of the touchscreen. */ 322 if (ParseTouchChipConfig(device->property, chipCfg) != HDF_SUCCESS) { 323 HDF_LOGE("%s: parse chip config failed", __func__); 324 OsalMemFree(chipCfg); 325 chipCfg = NULL; 326 } 327 return chipCfg; 328} 329 330static ChipDevice *ChipDeviceInstance(void) 331{ 332 ChipDevice *chipDev = (ChipDevice *)OsalMemAlloc(sizeof(ChipDevice)); 333 if (chipDev == NULL) { 334 HDF_LOGE("%s: instance chip device failed", __func__); 335 return NULL; 336 } 337 (void)memset_s(chipDev, sizeof(ChipDevice), 0, sizeof(ChipDevice)); 338 return chipDev; 339} 340 341static void FreeChipConfig(TouchChipCfg *config) 342{ 343 if (config->pwrSeq.pwrOn.buf != NULL) { 344 OsalMemFree(config->pwrSeq.pwrOn.buf); 345 } 346 if (config->pwrSeq.pwrOff.buf != NULL) { 347 OsalMemFree(config->pwrSeq.pwrOff.buf); 348 } 349 OsalMemFree(config); 350} 351 352static int32_t HdfSampleChipInit(struct HdfDeviceObject *device) 353{ 354 TouchChipCfg *chipCfg = NULL; 355 ChipDevice *chipDev = NULL; 356 HDF_LOGE("%s: enter", __func__); 357 if (device == NULL) { 358 return HDF_ERR_INVALID_PARAM; 359 } 360 /* Parse the private configuration of the touchscreen. */ 361 chipCfg = ChipConfigInstance(device); 362 if (chipCfg == NULL) { 363 return HDF_ERR_MALLOC_FAIL; 364 } 365 /* Instantiate the touchscreen device. */ 366 chipDev = ChipDeviceInstance(); 367 if (chipDev == NULL) { 368 goto freeCfg; 369 } 370 chipDev->chipCfg = chipCfg; 371 chipDev->ops = &g_sampleChipOps; 372 chipDev->chipName = chipCfg->chipName; 373 chipDev->vendorName = chipCfg->vendorName; 374 375 /* Register the touchscreen device with the platform driver. */ 376 if (RegisterChipDevice(chipDev) != HDF_SUCCESS) { 377 goto freeDev; 378 } 379 HDF_LOGI("%s: exit succ, chipName = %s", __func__, chipCfg->chipName); 380 return HDF_SUCCESS; 381 382freeDev: 383 OsalMemFree(chipDev); 384freeCfg: 385 FreeChipConfig(chipCfg); 386 return HDF_FAILURE; 387} 388 389struct HdfDriverEntry g_touchSampleChipEntry = { 390 .moduleVersion = 1, 391 .moduleName = "HDF_TOUCH_SAMPLE", 392 .Init = HdfSampleChipInit, 393}; 394 395HDF_INIT(g_touchSampleChipEntry); 396``` 397 398
