1# Touchscreen 2 3 4## Overview 5 6### Function Introduction 7 8The 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. 9 10The 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. 11 12### Working Principles 13 14The 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. 15 16**Figure 1** Input driver model 17 18 19 20The input driver model consists of the following: 21 22- 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. 23- 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. 24- Input chip drivers: provide differentiated APIs for the drivers form different vendors. You can use these APIs to develop your drivers with minimum modification. 25- Event Hub: provides a unified channel for different input devices to report input events. 26- HDF input config: parses and manages the board-specific and private configuration of input devices. 27 28The input driver model provides configuration files to help you quickly develop your drivers. 29 30 31## How to Develop 32 33### When to Use 34 35The 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. 36 37### Available APIs 38 39#### Hardware Interfaces 40 41The hardware interfaces for touchscreens can be classified into the following types based on the pin attributes: 42 43- Power interfaces 44 45- I/O control interfaces 46 47- Communication interfaces 48 49**Figure 2** Common touchscreen pins 50 51 52 53The interfaces shown in the preceding figure are described as follows: 54 551. **Power interfaces** 56 57 - **LDO_1P8**: 1.8 V digital circuit 58 - **LDO_3P3**: 3.3 V analog circuit 59 60 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. 61 622. **I/O control interfaces** 63 64 - **RESET**: pin used to reset the driver IC on the host when the kernel is put into hibernation or waken up. 65 - **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. 66 673. **Communication interfaces** 68 69 - 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). 70 - 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). 71 72#### Software Interfaces 73 74The 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. 75 76- input_manager.h 77 78 | API | Description | 79 | ------------------------------------------------------------------------------------- | -------------------| 80 | int32_t (*OpenInputDevice)(uint32_t devIndex); | Opens an input device. | 81 | int32_t (*CloseInputDevice)(uint32_t devIndex); | Closes an input device. | 82 | int32_t (*GetInputDevice)(uint32_t devIndex, DeviceInfo **devInfo); | Obtains information about an input device.| 83 | int32_t (*GetInputDeviceList)(uint32_t *devNum, DeviceInfo **devList, uint32_t size); | Obtains the input device list.| 84 85- input_reporter.h 86 87 | API | Description | 88 | ----------------------------------------------------------------------------------- | ------------------ | 89 | int32_t (*RegisterReportCallback)(uint32_t devIndex, InputReportEventCb *callback); | Registers a callback for an input device.| 90 | int32_t (*UnregisterReportCallback)(uint32_t devIndex); | Unregisters the callback for an input device.| 91 | void (*ReportEventPkgCallback)(const EventPackage **pkgs, uint32_t count); | Called to report input event data. | 92 93- input_controller.h 94 95 | API | Description | 96 | --------------------------------------------------------------------------------------------------- |--------------- | 97 | int32_t (*SetPowerStatus)(uint32_t devIndex, uint32_t status); | Sets the power status. | 98 | int32_t (*GetPowerStatus)(uint32_t devIndex, uint32_t *status); | Obtains the power status. | 99 | int32_t (*GetDeviceType)(uint32_t devIndex, uint32_t *deviceType); | Obtains the device type. | 100 | int32_t (*GetChipInfo)(uint32_t devIndex, char *chipInfo, uint32_t length); | Obtains the chip information of a device.| 101 | int32_t (*GetVendorName)(uint32_t devIndex, char *vendorName, uint32_t length); | Obtains the module vendor name of a device. | 102 | int32_t (*GetChipName)(uint32_t devIndex, char *chipName, uint32_t length); | Obtains the driver chip name of a device. | 103 | int32_t (*SetGestureMode)(uint32_t devIndex, uint32_t gestureMode); | Sets the gesture mode. | 104 | int32_t (*RunCapacitanceTest)(uint32_t devIndex, uint32_t testType, char *result, uint32_t length); | Performs a capacitance test.| 105 | int32_t (*RunExtraCommand)(uint32_t devIndex, InputExtraCmd *cmd); | Executes the specified command. | 106 107For more information, see [input](https://gitee.com/openharmony/drivers_peripheral/tree/master/input). 108 109### Development Procedure 110 111The load process of the input driver model (for the touchscreen driver) is as follows: 112 1131. The device configuration, including the driver loading priority, board-specific hardware information, and private data, is complete. 114 1152. The HDF driver loads the input device manager driver to create and initialize the device manager. 116 1173. The HDF loads the platform driver to parse the board-specific configuration, initialize the hardware, and provide the API for registering the touchscreen. 118 1194. The HDF loads the touchscreen driver to instantiate the touchscreen device, parse the private data, and implement the differentiated APIs for the platform. 120 1215. 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. 122 1236. The instantiated input device registers with the input device manager for unified management. 124 125 126The development process of the touchscreen driver is as follows: 127 1281. 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). 129 1302. 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. 131 1323. 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). 133 134 135### Development Example 136 137The following example describes how to develop the touchscreen driver for an RK3568 development board. 138 1391. Configure device information. 140 141 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. 142 143 ```c 144 input :: host { 145 hostName = "input_host"; 146 priority = 100; 147 device_input_manager :: device { 148 device0 :: deviceNode { 149 policy = 2; // The driver provides services externally. 150 priority = 100; // Loading priority. In the input model, the manager module has the highest priority. 151 preload = 0; // Whether to load the driver. The value 0 means to load the driver; 1 means the opposite. 152 permission = 0660; 153 moduleName = "HDF_INPUT_MANAGER"; 154 serviceName = "input_dev_manager"; 155 deviceMatchAttr = ""; 156 } 157 } 158 device_hdf_touch :: device { 159 device0 :: deviceNode { 160 policy = 2; 161 priority = 120; 162 preload = 0; 163 permission = 0660; 164 moduleName = "HDF_TOUCH"; 165 serviceName = "event1"; 166 deviceMatchAttr = "touch_device1"; 167 } 168 } 169 170 device_touch_chip :: device { 171 device0 :: deviceNode { 172 policy = 0; 173 priority = 130; 174 preload = 0; 175 permission = 0660; 176 moduleName = "HDF_TOUCH_SAMPLE"; 177 serviceName = "hdf_touch_sample_service"; 178 deviceMatchAttr = "zsj_sample_5p5"; 179 } 180 } 181 } 182 ``` 183 1842. Configure board-specific and private data for the touchscreen. 185 186 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. 187 188 ```c 189 root { 190 input_config { 191 touchConfig { 192 touch0 { 193 boardConfig { 194 match_attr = "touch_device1"; 195 inputAttr { 196 inputType = 0; // 0 indicates touchscreen. 197 solutionX = 480; 198 solutionY = 960; 199 devName = "main_touch"; // Device name. 200 } 201 busConfig { 202 busType = 0; // 0 indicates I2C. 203 busNum = 6; 204 clkGpio = 86; 205 dataGpio = 87; 206 i2cClkIomux = [0x114f0048, 0x403]; // Register of the I2C_CLK pin. 207 i2cDataIomux = [0x114f004c, 0x403]; // Register of the I2C_DATA pin. 208 } 209 pinConfig { 210 rstGpio = 3; 211 intGpio = 4; 212 rstRegCfg = [0x112f0094, 0x400]; // Register of the reset pin. 213 intRegCfg = [0x112f0098, 0x400]; // Register of the interrupt pin. 214 } 215 powerConfig { 216 vccType = 2; // The value 1 stands for LDO, 2 for GPIO, and 3 for PMIC. 217 vccNum = 20; // Set the GPIO number to 20. 218 vccValue = 1800; // Set the voltage amplitude to 1800 mV. 219 vciType = 1; 220 vciNum = 12; 221 vciValue = 3300; 222 } 223 featureConfig { 224 capacitanceTest = 0; 225 gestureMode = 0; 226 gloverMOde = 0; 227 coverMode = 0; 228 chargerMode = 0; 229 knuckleMode = 0; 230 } 231 } 232 chipConfig { 233 template touchChip { 234 match_attr = ""; 235 chipName = "sample"; 236 vendorName = "zsj"; 237 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. 238 busType = 0; 239 deviceAddr = 0x5D; 240 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. 241 maxSpeed = 400; 242 chipVersion = 0; 243 powerSequence { 244 /* Description of the power-on sequence: 245 [type, status, direction, delay] 246 <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. 247 <status> 0 stands for power-off or pull-down; 1 for power-on or pull-up; 2 for no operation. 248 <dir> 0 stands for input; 1 for output; 2 for no operation. 249 <delay> indicates the delay, in milliseconds. For example, 20 indicates 20 ms delay. 250 */ 251 powerOnSeq = [4, 0, 1, 0, 252 3, 0, 1, 10, 253 3, 1, 2, 60, 254 4, 2, 0, 0]; 255 suspendSeq = [3, 0, 2, 10]; 256 resumeSeq = [3, 1, 2, 10]; 257 powerOffSeq = [3, 0, 2, 10, 258 1, 0, 2, 20]; 259 } 260 } 261 chip0 :: touchChip { 262 match_attr = "zsj_sample_5p5"; 263 chipInfo = "ZIDN45100"; 264 chipVersion = 0; 265 } 266 } 267 } 268 } 269 } 270 } 271 ``` 272 2733. Add the touchscreen driver. 274 275 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. 276 277 ```c 278 /* Parse the touch reporting data read from the touchscreen into coordinates. */ 279 static void ParsePointData(ChipDevice *device, FrameData *frame, uint8_t *buf, uint8_t pointNum) 280 { 281 int32_t resX = device->driver->boardCfg->attr.resolutionX; 282 int32_t resY = device->driver->boardCfg->attr.resolutionY; 283 284 for (int32_t i = 0; i < pointNum; i++) { 285 frame->fingers[i].y = (buf[GT_POINT_SIZE * i + GT_X_LOW] & ONE_BYTE_MASK) | 286 ((buf[GT_POINT_SIZE * i + GT_X_HIGH] & ONE_BYTE_MASK) << ONE_BYTE_OFFSET); 287 frame->fingers[i].x = (buf[GT_POINT_SIZE * i + GT_Y_LOW] & ONE_BYTE_MASK) | 288 ((buf[GT_POINT_SIZE * i + GT_Y_HIGH] & ONE_BYTE_MASK) << ONE_BYTE_OFFSET); 289 frame->fingers[i].valid = true; 290 } 291 } 292 /* Obtain the touch reporting data from the device. */ 293 static int32_t ChipDataHandle(ChipDevice *device) 294 { 295 int32_t ret; 296 uint8_t touchStatus = 0; 297 uint8_t pointNum; 298 uint8_t buf[GT_POINT_SIZE * MAX_SUPPORT_POINT] = {0}; 299 InputI2cClient *i2cClient = &device->driver->i2cClient; 300 uint8_t reg[GT_ADDR_LEN] = {0}; 301 FrameData *frame = &device->driver->frameData; 302 reg[0] = (GT_BUF_STATE_ADDR >> ONE_BYTE_OFFSET) & ONE_BYTE_MASK; 303 reg[1] = GT_BUF_STATE_ADDR & ONE_BYTE_MASK; 304 ret = InputI2cRead(i2cClient, reg, GT_ADDR_LEN, &touchStatus, 1); 305 if (ret < 0 || touchStatus == GT_EVENT_INVALID) { 306 return HDF_FAILURE; 307 } 308 OsalMutexLock(&device->driver->mutex); 309 (void)memset_s(frame, sizeof(FrameData), 0, sizeof(FrameData)); 310 if (touchStatus == GT_EVENT_UP) { 311 frame->realPointNum = 0; 312 frame->definedEvent = TOUCH_UP; 313 goto exit; 314 } 315 reg[0] = (GT_X_LOW_BYTE_BASE >> ONE_BYTE_OFFSET) & ONE_BYTE_MASK; 316 reg[1] = GT_X_LOW_BYTE_BASE & ONE_BYTE_MASK; 317 pointNum = touchStatus & GT_FINGER_NUM_MASK; 318 if (pointNum <= 0 || pointNum > MAX_SUPPORT_POINT) { 319 HDF_LOGE("%s: pointNum is invalid, %d", __func__, pointNum); 320 (void)ChipCleanBuffer(i2cClient); 321 OsalMutexUnlock(&device->driver->mutex); 322 return HDF_FAILURE; 323 } 324 frame->realPointNum = pointNum; 325 frame->definedEvent = TOUCH_DOWN; 326 /* Read the touch reporting data from the register. */ 327 (void)InputI2cRead(i2cClient, reg, GT_ADDR_LEN, buf, GT_POINT_SIZE * pointNum); 328 /* Parse the touch reporting data. */ 329 ParsePointData(device, frame, buf, pointNum); 330 exit: 331 OsalMutexUnlock(&device->driver->mutex); 332 if (ChipCleanBuffer(i2cClient) != HDF_SUCCESS) { 333 return HDF_FAILURE; 334 } 335 return HDF_SUCCESS; 336 } 337 338 static struct TouchChipOps g_sampleChipOps = { 339 .Init = ChipInit, 340 .Detect = ChipDetect, 341 .Resume = ChipResume, 342 .Suspend = ChipSuspend, 343 .DataHandle = ChipDataHandle, 344 }; 345 346 static TouchChipCfg *ChipConfigInstance(struct HdfDeviceObject *device) 347 { 348 TouchChipCfg *chipCfg = (TouchChipCfg *)OsalMemAlloc(sizeof(TouchChipCfg)); 349 if (chipCfg == NULL) { 350 HDF_LOGE("%s: instance chip config failed", __func__); 351 return NULL; 352 } 353 (void)memset_s(chipCfg, sizeof(TouchChipCfg), 0, sizeof(TouchChipCfg)); 354 /* Parse the touchscreen private configuration. */ 355 if (ParseTouchChipConfig(device->property, chipCfg) != HDF_SUCCESS) { 356 HDF_LOGE("%s: parse chip config failed", __func__); 357 OsalMemFree(chipCfg); 358 chipCfg = NULL; 359 } 360 return chipCfg; 361 } 362 363 static ChipDevice *ChipDeviceInstance(void) 364 { 365 ChipDevice *chipDev = (ChipDevice *)OsalMemAlloc(sizeof(ChipDevice)); 366 if (chipDev == NULL) { 367 HDF_LOGE("%s: instance chip device failed", __func__); 368 return NULL; 369 } 370 (void)memset_s(chipDev, sizeof(ChipDevice), 0, sizeof(ChipDevice)); 371 return chipDev; 372 } 373 374 static void FreeChipConfig(TouchChipCfg *config) 375 { 376 if (config->pwrSeq.pwrOn.buf != NULL) { 377 OsalMemFree(config->pwrSeq.pwrOn.buf); 378 } 379 if (config->pwrSeq.pwrOff.buf != NULL) { 380 OsalMemFree(config->pwrSeq.pwrOff.buf); 381 } 382 OsalMemFree(config); 383 } 384 385 static int32_t HdfSampleChipInit(struct HdfDeviceObject *device) 386 { 387 TouchChipCfg *chipCfg = NULL; 388 ChipDevice *chipDev = NULL; 389 HDF_LOGE("%s: enter", __func__); 390 if (device == NULL) { 391 return HDF_ERR_INVALID_PARAM; 392 } 393 /* Parse the touchscreen private configuration. */ 394 chipCfg = ChipConfigInstance(device); 395 if (chipCfg == NULL) { 396 return HDF_ERR_MALLOC_FAIL; 397 } 398 /* Instantiate the touchscreen device. */ 399 chipDev = ChipDeviceInstance(); 400 if (chipDev == NULL) { 401 goto freeCfg; 402 } 403 chipDev->chipCfg = chipCfg; 404 chipDev->ops = &g_sampleChipOps; 405 chipDev->chipName = chipCfg->chipName; 406 chipDev->vendorName = chipCfg->vendorName; 407 408 /* Register the touchscreen device with the platform driver. */ 409 if (RegisterChipDevice(chipDev) != HDF_SUCCESS) { 410 goto freeDev; 411 } 412 HDF_LOGI("%s: exit succ, chipName = %s", __func__, chipCfg->chipName); 413 return HDF_SUCCESS; 414 415 freeDev: 416 OsalMemFree(chipDev); 417 freeCfg: 418 FreeChipConfig(chipCfg); 419 return HDF_FAILURE; 420 } 421 422 struct HdfDriverEntry g_touchSampleChipEntry = { 423 .moduleVersion = 1, 424 .moduleName = "HDF_TOUCH_SAMPLE", 425 .Init = HdfSampleChipInit, 426 }; 427 428 HDF_INIT(g_touchSampleChipEntry); 429 ``` 430 4314. Call the Input HDI APIs. 432 433 The following sample code shows how an upper-layer input system service calls Input HDI APIs. 434 435 ```c 436 #include "input_manager.h" 437 #define DEV_INDEX 1 438 439 IInputInterface *g_inputInterface; 440 InputReportEventCb g_callback; 441 442 /* Define the callback for data reporting. */ 443 static void ReportEventPkgCallback(const EventPackage **pkgs, uint32_t count) 444 { 445 if (pkgs == NULL || count > MAX_PKG_NUM) { 446 return; 447 } 448 for (uint32_t i = 0; i < count; i++) { 449 HDF_LOGI("%s: pkgs[%d] = 0x%x, 0x%x, %d", __func__, i, pkgs[i]->type, pkgs[i]->code, pkgs[i]->value); 450 } 451 } 452 453 int InputServiceSample(void) 454 { 455 uint32_t devType = INIT_DEFAULT_VALUE; 456 457 /* Obtain the input driver APIs. */ 458 int ret = GetInputInterface(&g_inputInterface); 459 if (ret != INPUT_SUCCESS) { 460 HDF_LOGE("%s: get input interfaces failed, ret = %d", __func__, ret); 461 return ret; 462 } 463 464 INPUT_CHECK_NULL_POINTER(g_inputInterface, INPUT_NULL_PTR); 465 INPUT_CHECK_NULL_POINTER(g_inputInterface->iInputManager, INPUT_NULL_PTR); 466 /* Open an input device. */ 467 ret = g_inputInterface->iInputManager->OpenInputDevice(DEV_INDEX); 468 if (ret) { 469 HDF_LOGE("%s: open input device failed, ret = %d", __func__, ret); 470 return ret; 471 } 472 473 INPUT_CHECK_NULL_POINTER(g_inputInterface->iInputController, INPUT_NULL_PTR); 474 /* Obtain the type of the input device. */ 475 ret = g_inputInterface->iInputController->GetDeviceType(DEV_INDEX, &devType); 476 if (ret) { 477 HDF_LOGE("%s: get device type failed, ret: %d", __FUNCTION__, ret); 478 return ret; 479 } 480 HDF_LOGI("%s: device1's type is %u\n", __FUNCTION__, devType); 481 482 /* Register the data reporting callback for the input device. */ 483 g_callback.ReportEventPkgCallback = ReportEventPkgCallback; 484 INPUT_CHECK_NULL_POINTER(g_inputInterface->iInputReporter, INPUT_NULL_PTR); 485 ret = g_inputInterface->iInputReporter->RegisterReportCallback(DEV_INDEX, &g_callback); 486 if (ret) { 487 HDF_LOGE("%s: register callback failed, ret: %d", __FUNCTION__, ret); 488 return ret; 489 } 490 HDF_LOGI("%s: wait 10s for testing, pls touch the panel now", __FUNCTION__); 491 OsalMSleep(KEEP_ALIVE_TIME_MS); 492 493 /* Unregister the callback for the input device. */ 494 ret = g_inputInterface->iInputReporter->UnregisterReportCallback(DEV_INDEX); 495 if (ret) { 496 HDF_LOGE("%s: unregister callback failed, ret: %d", __FUNCTION__, ret); 497 return ret; 498 } 499 500 /* Close the input device. */ 501 ret = g_inputInterface->iInputManager->CloseInputDevice(DEV_INDEX); 502 if (ret) { 503 HDF_LOGE("%s: close device failed, ret: %d", __FUNCTION__, ret); 504 return ret; 505 } 506 return 0; 507 } 508 ``` 509
