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