1# Touchscreen 2 3 4## Overview 5 6### Functions 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-overview-foundation.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.<br>The input driver model provides configuration files to help you quickly develop your drivers. 27 28 29## How to Develop 30 31### When to Use 32 33The 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. 34 35### Available APIs 36 37#### Hardware Interfaces 38 39The hardware interfaces for touchscreens can be classified into the following types based on the pin attributes: 40 41- Power interfaces 42 43- I/O control interfaces 44 45- Communication interfaces 46 47**Figure 2** Common touchscreen pins 48 49 50 51The interfaces shown in the preceding figure are described as follows: 52 531. **Power interfaces** 54 55 - **LDO_1P8**: 1.8 V digital circuit 56 - **LDO_3P3**: 3.3 V analog circuit 57 58 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. 59 602. **I/O control interfaces** 61 62 - **RESET**: pin used to reset the driver IC on the host when the kernel is put into hibernation or waken up. 63 - **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. 64 653. **Communication interfaces** 66 67 - 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). 68 - 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). 69 70#### Software Interfaces 71 72The 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. 73 74- input_manager.h 75 76 | API | Description | 77 | ------------------------------------------------------------------------------------- | -------------------| 78 | int32_t (*OpenInputDevice)(uint32_t devIndex); | Opens an input device. | 79 | int32_t (*CloseInputDevice)(uint32_t devIndex); | Closes an input device. | 80 | int32_t (*GetInputDevice)(uint32_t devIndex, DeviceInfo **devInfo); | Obtains information about an input device.| 81 | int32_t (*GetInputDeviceList)(uint32_t *devNum, DeviceInfo **devList, uint32_t size); | Obtains the input device list.| 82 83- input_reporter.h 84 85 | API | Description | 86 | ----------------------------------------------------------------------------------- | ------------------ | 87 | int32_t (*RegisterReportCallback)(uint32_t devIndex, InputReportEventCb *callback); | Registers a callback for an input device.| 88 | int32_t (*UnregisterReportCallback)(uint32_t devIndex); | Unregisters the callback for an input device.| 89 | void (*ReportEventPkgCallback)(const EventPackage **pkgs, uint32_t count); | Called to report input event data. | 90 91- input_controller.h 92 93 | API | Description | 94 | --------------------------------------------------------------------------------------------------- |--------------- | 95 | int32_t (*SetPowerStatus)(uint32_t devIndex, uint32_t status); | Sets the power status. | 96 | int32_t (*GetPowerStatus)(uint32_t devIndex, uint32_t *status); | Obtains the power status. | 97 | int32_t (*GetDeviceType)(uint32_t devIndex, uint32_t *deviceType); | Obtains the device type. | 98 | int32_t (*GetChipInfo)(uint32_t devIndex, char *chipInfo, uint32_t length); | Obtains the chip information of a device.| 99 | int32_t (*GetVendorName)(uint32_t devIndex, char *vendorName, uint32_t length); | Obtains the module vendor name of a device. | 100 | int32_t (*GetChipName)(uint32_t devIndex, char *chipName, uint32_t length); | Obtains the driver chip name of a device. | 101 | int32_t (*SetGestureMode)(uint32_t devIndex, uint32_t gestureMode); | Sets the gesture mode. | 102 | int32_t (*RunCapacitanceTest)(uint32_t devIndex, uint32_t testType, char *result, uint32_t length); | Performs a capacitance test.| 103 | int32_t (*RunExtraCommand)(uint32_t devIndex, InputExtraCmd *cmd); | Executes the specified command. | 104 105For more information, see [input](https://gitee.com/openharmony/drivers_peripheral/tree/master/input). 106 107### Development Procedure 108 109The load process of the input driver model (for the touchscreen driver) is as follows: 110 1111. The device configuration, including the driver loading priority, board-specific hardware information, and private data, is complete. 112 1132. The HDF driver loads the input device manager driver to create and initialize the device manager. 114 1153. The HDF loads the platform driver to parse the board-specific configuration, initialize the hardware, and provide the API for registering the touchscreen. 116 1174. The HDF loads the touchscreen driver to instantiate the touchscreen device, parse the private data, and implement the differentiated APIs for the platform. 118 1195. 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. 120 1216. The instantiated input device registers with the input device manager for unified management. 122 123 124The development process of the touchscreen driver is as follows: 125 1261. 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 the driver configuration, see [HDF Driver Development Process](driver-hdf-manage.md). 127 1282. 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. 129 1303. 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). 131 132 133### Development Example 134 135The following example describes how to develop the touchscreen driver for an RK3568 development board. 136 1371. Configure device information. 138 139 Configure the modules of the input driver model in **vendor/hihope/rk3568/hdf_config/khdf/device_info/device_info.hcs**. For details, see [HDF Driver Development Process](driver-hdf-manage.md). The HDF loads modules of the input model in sequence based on the configuration information. 140 141 ```c 142 input :: host { 143 hostName = "input_host"; 144 priority = 100; 145 device_input_manager :: device { 146 device0 :: deviceNode { 147 policy = 2; // The driver provides services externally. 148 priority = 100; // Loading priority. In the input model, the manager module has the highest priority. 149 preload = 0; // Whether to load the driver. The value 0 means to load the driver; 1 means the opposite. 150 permission = 0660; 151 moduleName = "HDF_INPUT_MANAGER"; 152 serviceName = "input_dev_manager"; 153 deviceMatchAttr = ""; 154 } 155 } 156 device_hdf_touch :: device { 157 device0 :: deviceNode { 158 policy = 2; 159 priority = 120; 160 preload = 0; 161 permission = 0660; 162 moduleName = "HDF_TOUCH"; 163 serviceName = "event1"; 164 deviceMatchAttr = "touch_device1"; 165 } 166 } 167 168 device_touch_chip :: device { 169 device0 :: deviceNode { 170 policy = 0; 171 priority = 130; 172 preload = 0; 173 permission = 0660; 174 moduleName = "HDF_TOUCH_SAMPLE"; 175 serviceName = "hdf_touch_sample_service"; 176 deviceMatchAttr = "zsj_sample_5p5"; 177 } 178 } 179 } 180 ``` 181 1822. Configure board-specific and private data for the touchscreen. 183 184 Configure the data in **vendor/hihope/rk3568/hdf_config/khdf/input/input_config.hcs**. The following is an example. You can modify the configuration as required. 185 186 ```c 187 root { 188 input_config { 189 touchConfig { 190 touch0 { 191 boardConfig { 192 match_attr = "touch_device1"; 193 inputAttr { 194 inputType = 0; // 0 indicates touchscreen. 195 solutionX = 480; 196 solutionY = 960; 197 devName = "main_touch"; // Device name. 198 } 199 busConfig { 200 busType = 0; // 0 indicates I2C. 201 busNum = 6; 202 clkGpio = 86; 203 dataGpio = 87; 204 i2cClkIomux = [0x114f0048, 0x403]; // Register of the I2C_CLK pin. 205 i2cDataIomux = [0x114f004c, 0x403]; // Register of the I2C_DATA pin. 206 } 207 pinConfig { 208 rstGpio = 3; 209 intGpio = 4; 210 rstRegCfg = [0x112f0094, 0x400]; // Register of the reset pin. 211 intRegCfg = [0x112f0098, 0x400]; // Register of the interrupt pin. 212 } 213 powerConfig { 214 vccType = 2; // The value 1 stands for LDO, 2 for GPIO, and 3 for PMIC. 215 vccNum = 20; // Set the GPIO number to 20. 216 vccValue = 1800; // Set the voltage amplitude to 1800 mV. 217 vciType = 1; 218 vciNum = 12; 219 vciValue = 3300; 220 } 221 featureConfig { 222 capacitanceTest = 0; 223 gestureMode = 0; 224 gloverMOde = 0; 225 coverMode = 0; 226 chargerMode = 0; 227 knuckleMode = 0; 228 } 229 } 230 chipConfig { 231 template touchChip { 232 match_attr = ""; 233 chipName = "sample"; 234 vendorName = "zsj"; 235 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. 236 busType = 0; 237 deviceAddr = 0x5D; 238 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. 239 maxSpeed = 400; 240 chipVersion = 0; 241 powerSequence { 242 /* Description of the power-on sequence: 243 [type, status, direction, delay] 244 <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. 245 <status> 0 stands for power-off or pull-down; 1 for power-on or pull-up; 2 for no operation. 246 <dir> 0 stands for input; 1 for output; 2 for no operation. 247 <delay> indicates the delay, in milliseconds. For example, 20 indicates 20 ms delay. 248 */ 249 powerOnSeq = [4, 0, 1, 0, 250 3, 0, 1, 10, 251 3, 1, 2, 60, 252 4, 2, 0, 0]; 253 suspendSeq = [3, 0, 2, 10]; 254 resumeSeq = [3, 1, 2, 10]; 255 powerOffSeq = [3, 0, 2, 10, 256 1, 0, 2, 20]; 257 } 258 } 259 chip0 :: touchChip { 260 match_attr = "zsj_sample_5p5"; 261 chipInfo = "ZIDN45100"; 262 chipVersion = 0; 263 } 264 } 265 } 266 } 267 } 268 } 269 ``` 270 2713. Add the touchscreen driver. 272 273 Implement the touchscreen-specific APIs in **drivers/hdf_core/framework/model/input/driver/touchscreen/touch_gt911.c**. 274 275 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
