1# Development Example for Peripheral Drivers<a name="EN-US_TOPIC_0000001157063303"></a> 2 3## Overview<a name="section86753818426"></a> 4 5This document describes how to develop a touchscreen driver on the Hi3516D V300 development board using the HDF input driver model, helping you quickly get started with OpenHarmony peripheral driver development. 6 7### Hardware Resources<a name="section123071189431"></a> 8 9The touchscreen integrated circuit \(IC\) provided by the Hi3516D V300 development board is GT911, which uses the standard inter-integrated circuit \(I2C\) to communicate with the development board and connects to the main board through the 6-pin flexible flat cable. The following figure shows the distribution of the 6 pins and their connection. 10 11 12 13### Input Driver Model<a name="section53684425430"></a> 14 15The input driver model mainly consists of the device manager, common drivers, and chip drivers. 16 17- Input device manager: provides various input device drivers with the APIs for registering or unregistering input devices and manages the input device list. 18- Input common driver: provides common drivers for initializing the board-level hardware, processing hardware interrupts, and registering input devices with the input device manager. 19- Input chip driver: calls differentiated APIs reserved by the input platform driver to minimize the workload for input chip driver development. 20 21In addition, the input driver model implements functions for reporting input data and parsing input device configurations. 22 23For details about the input driver model, see [Touchscreen Overview](../driver/driver-peripherals-touch-des.md). 24 25## Setting Up the Environment<a name="section661075474418"></a> 26 27Follow the instructions in [Quick Start Overview](../quick-start/quickstart-overview.md). 28 29> **NOTICE** 30>This development example applies to standard, small, and mini OpenHarmony systems. The following sections use the standard system as an example. You can refer to the specific guide for your system to set up the environment. 31 32## Developing a Touchscreen Driver<a name="section15233162984520"></a> 33 34Complete the following tasks to adapt a touchscreen IC based on the input driver model. 35 36### Configuring Device Driver Descriptions<a name="section16761205604515"></a> 37 38Configure the touchscreen driver description required for registering the driver with the HDF, for example, whether the driver is loaded and what is the loading priority. 39 40You can configure the device driver description in the configuration file at **./drivers/adapter/khdf/linux/hcs/device\_info/device\_info.hcs**. 41 42The **device\_info.hcs** file contains all necessary information for registering drivers in the input driver model with the HDF. You do not need to make any modification for the information unless otherwise required in special scenarios. The private configuration data of each driver uses the **deviceMatchAttr** field to match the **match\_attr** field in the **input\_config.hcs** file. 43 44The input-related fields in the configuration file are as follows. For details about these fields, see [Driver Development](../driver/driver-hdf-development.md). 45 46``` 47input :: host { 48 hostName = "input_host"; 49 priority = 100; 50 device_input_manager :: device { // Specify the device driver description of the input device manager. 51 device0 :: deviceNode { 52 policy = 2; // Services are released to both the kernel space and the user space. 53 priority = 100; // The default priority for the input device manager is 100. 54 preload = 0; // Load the driver. 55 permission = 0660; // Specify the permission for the driver to create device nodes. 56 moduleName = "HDF_INPUT_MANAGER"; // Match the moduleName in the driver entry structure. 57 serviceName = "hdf_input_host"; // Specify the device node name to be generated by the HDF. 58 deviceMatchAttr = ""; // Leave this field empty because private configuration data is not required by the input device manager currently. 59 } 60 } 61 62 device_hdf_touch :: device { // Specify the device driver description of the input common driver. 63 device0 :: deviceNode { 64 policy = 2; // Services are released to both the kernel space and the user space. 65 priority = 120; // The default priority for the input common driver is 120. 66 preload = 0; // Load the driver. 67 permission = 0660; // Specify the permission for the driver to create device nodes. 68 moduleName = "HDF_TOUCH"; // Match the moduleName in the driver entry structure. 69 serviceName = "hdf_input_event1"; // Specify the device node name to be generated by the HDF. 70 deviceMatchAttr = "touch_device1"; // Keep this value the same as the match_attr value in the private configuration data. 71 } 72 } 73 74 device_touch_chip :: device { // Specify the device description of the input chip driver. 75 device0 :: deviceNode { 76 policy = 0; // Services are not released to the kernel space or the user space. 77 priority = 130; // The default priority for the input chip driver is 130. 78 preload = 0; // Load the driver. 79 permission = 0660; // Specify the permission for the driver to create device nodes. 80 moduleName = "HDF_TOUCH_GT911"; // Match the moduleName in the driver entry structure. 81 serviceName = "hdf_touch_gt911_service";// Specify the device node name to be generated by the HDF. 82 deviceMatchAttr = "zsj_gt911_5p5"; // Keep this value the same as the match_attr value in the private configuration data. 83 } 84 } 85 } 86``` 87 88Pay attention to the following fields in the configuration file: 89 90**priority**: specifies the driver loading priority. 91 92**preload**: specifies whether to load the driver. 93 94**moduleName**: This value must be the same as the **moduleName** value in the driver entry structure. 95 96**serviceName**: This value is used by the HDF to create a device node name. 97 98**deviceMatchAttr**: This value must be the same as the **match\_attr** value in the private configuration data. 99 100After the device descriptions are configured, the HDF matches the configuration with the code registered with the driver entry structure based on the **moduleName** field, ensuring that drivers can be loaded properly. If multiple drivers are configured, the **priority** field determines the loading sequence of each driver. 101 102### Configuring the Touchscreen<a name="section156331030144617"></a> 103 104The private data includes the power-on and power-off sequence, and the platform hardware information includes the GPIO port that connects the touchscreen to the main board. 105 106You can configure the touchscreen in the configuration file at **./drivers/adapter/khdf/linux/hcs/input/input\_config.hcs**. 107 108The **input\_config.hcs** file consists of the private configuration data of both the common driver and chip driver. Information of this file is read and parsed by the driver code. The configuration in the file includes the board-level hardware information and private configuration of the touchscreen. You can tailor the configuration during your development. 109 110``` 111root { 112 input_config { 113 touchConfig { 114 touch0 { // Configure the first touchscreen. 115 boardConfig { // Specify the board-level hardware information. 116 match_attr = "touch_device1"; // Keep this value the same as the match_attr field in the private configuration data of the input common driver in the device description. 117 inputAttr { 118 /* 0:touch 1:key 2:keyboard 3:mouse 4:button 5:crown 6:encoder */ 119 inputType = 0; // Set the input type to touch. 120 solutionX = 480; // Set the resolution in the X-axis. 121 solutionY = 960; // Set the resolution in the Y-axis. 122 devName = "main_touch"; // Set the device name. 123 } 124 busConfig { 125 /* 0:i2c 1:spi */ 126 busType = 0; // GT911 uses the I2C bus for communication. 127 busNum = 6; // Use the sixth bus of the chip to communicate with the development board through I2C. 128 clkGpio = 86; // Set the SCL pin of the chip. 129 dataGpio = 87; // Set the SDA pin of the chip. 130 i2cClkIomux = [0x114f0048, 0x403]; // Configure the SCL pin information. 131 i2cDataIomux = [0x114f004c, 0x403]; // Configure the SDA pin information. 132 } 133 pinConfig { 134 rstGpio = 3; // Set the reset pin. 135 intGpio = 4; // Set the interrupt pin. 136 rstRegCfg = [0x112f0094, 0x400]; // Configure the reset pin information. 137 intRegCfg = [0x112f0098, 0x400]; // Configure the interrupt pin information. 138 } 139 powerConfig { 140 /* 0:unused 1:ldo 2:gpio 3:pmic */ 141 vccType = 2; // Set the VCC type. Value 2 indicates the GPIO power supply. 142 vccNum = 20; // gpio20 143 vccValue = 1800; // Set the voltage amplitude to 1800 mV. 144 vciType = 1; // Set the VCI type. Value 1 indicates the LDO power supply. 145 vciNum = 12; // ldo12 146 vciValue = 3300; // Set the voltage amplitude to 3300 mV. 147 } 148 149 featureConfig { 150 capacitanceTest = 0; // Configure the capacitance test. 151 gestureMode = 0; // Configure the gesture mode. 152 gloverMode = 0; // Configure the gloves mode. 153 coverMode = 0; // Configure the cover mode. 154 chargerMode = 0; // Configure the charging mode. 155 knuckleMode = 0; // Configure the knuckle mode. 156 } 157 } 158 chipConfig { // Configure the private data of the touchscreen chip. 159 template touchChip { // Set the template. 160 match_attr = ""; 161 chipName = "gt911"; // Set the touchscreen IC model. 162 vendorName = "zsj"; // Set the vendor name. 163 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. 164 busType = 0; // 0 indicates the I2C bus, and 1 indicates the SPI bus. 165 deviceAddr = 0x5D; // Set the IC communication address. 166 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. 167 maxSpeed = 400; // Set the maximum communication rate to 400 Hz. 168 chipVersion = 0; // Set the touchscreen IC version. 169 powerSequence { 170 /* Power-on sequence is described as follows: 171 [Type, status, direction, delay] 172 <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. 173 <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. 174 <dir> Values 0 and 1 indicate the input and output directions, respectively. Value 2 indicates that no operation is performed. 175 <delay> Delay time, in milliseconds. 176 */ 177 powerOnSeq = [4, 0, 1, 0, // Set the output direction for the interrupt pin and pull down the pin. 178 3, 0, 1, 10, // Set the output direction for the reset pin and pull down the pin, with a delay of 10 ms. 179 3, 1, 2, 60, // No operation is performed on the reset pin. Pull up the pin, with a delay of 60 ms. 180 4, 2, 0, 0]; // Set the input direction for the interrupt pin. 181 suspendSeq = [3, 0, 2, 10]; // No operation is performed on the reset pin. Pull down the pin, with a delay of 10 ms. 182 resumeSeq = [3, 1, 2, 10]; // No operation is performed on the reset pin. Pull up the pin, with a delay of 10 ms. 183 powerOffSeq = [3, 0, 2, 10, // No operation is performed on the reset pin. Pull down the pin, with a delay of 10 ms. 184 1, 0, 2, 20]; // No operation is performed on the positive pin. Pull down the pin, with a delay of 20 ms. 185 } 186 } 187 188 chip0 :: touchChip { 189 match_attr = "zsj_gt911_5p5"; // Keep this value the same as the match_attr field in the touchscreen private configuration data in the device description. 190 chipInfo = "ZIDN45100"; // The chip information is composed of the product name, module number, and chip number, used to identity the current touchscreen in user space. 191 chipVersion = 0; // Set the IC model version. 192 } 193 } 194 } 195 } 196 } 197} 198``` 199 200In the example, **touchConfig** contains the **touch0** configuration, which describes the **boardConfig** and **chipConfig** configuration information. The **boardConfig** field provides the board-level hardware information of Hi3516D V300, and the **chipConfig** field provides the private configuration data of the touchscreen. To use another touchscreen, you can change the value of the **chipConfig** field. You can also configure multiple touchscreens for your product. In this example, **touch0** represents the hardware interface and chip configuration of the default touchscreen. If you need to configure a secondary touchscreen, add a **touch1** block parallel to **touch0**. 201 202### Adapting to the Private Drivers of the Touchscreen<a name="section17127331595"></a> 203 204The input driver model abstracts the development process of input devices. You only need to adapt to the input chip driver without making any modifications for the input device manager and common driver. 205 206The input driver model consists of three parts of drivers. To develop a brand-new touchscreen driver, you only need to adapt your code with the input chip driver and implement differentiated APIs. The sample code in this section illustrates how you will complete the adaptation. 207 2081. Implement differentiated APIs for the touchscreen to adapt to the input chip driver. 209 210 You can obtain the sample code at **./drivers/framework/model/input/driver/touchscreen/touch\_gt911.c**. 211 212 ``` 213 static struct TouchChipOps g_gt911ChipOps = { // IC options of the touchscreen 214 .Init = ChipInit, // Initialize the chip. 215 .Detect = ChipDetect, // Detect the chip. 216 .Resume = ChipResume, // Resume the chip. 217 .Suspend = ChipSuspend, // Suspend the chip. 218 .DataHandle = ChipDataHandle, // Read the chip data. 219 .UpdateFirmware = UpdateFirmware, // Update the firmware. 220 }; 221 222 /* The ICs may be different depending on the touchscreen vendors, and the corresponding register operations are also different. Therefore, the code for the input chip driver focuses only on the adaptation of differentiated APIs. The following sample code demonstrates the data parsing of GT911. */ 223 224 static int32_t ChipDataHandle(ChipDevice *device) 225 { 226 ... 227 /* Read the status register before GT911 obtains coordinates. */ 228 reg[0] = (GT_BUF_STATE_ADDR >> ONE_BYTE_OFFSET) & ONE_BYTE_MASK; 229 reg[1] = GT_BUF_STATE_ADDR & ONE_BYTE_MASK; 230 ret = InputI2cRead(i2cClient, reg, GT_ADDR_LEN, &touchStatus, 1); 231 if (ret < 0 || touchStatus == GT_EVENT_INVALID) { 232 return HDF_FAILURE; 233 } 234 ... 235 /* Read data from the data register based on the value of the status register. */ 236 reg[0] = (GT_X_LOW_BYTE_BASE >> ONE_BYTE_OFFSET) & ONE_BYTE_MASK; 237 reg[1] = GT_X_LOW_BYTE_BASE & ONE_BYTE_MASK; 238 pointNum = touchStatus & GT_FINGER_NUM_MASK; 239 if (pointNum == 0 || pointNum > MAX_SUPPORT_POINT) { 240 HDF_LOGE("%s: pointNum is invalid, %u", __func__, pointNum); 241 (void)ChipCleanBuffer(i2cClient); 242 OsalMutexUnlock(&device->driver->mutex); 243 return HDF_FAILURE; 244 } 245 frame->realPointNum = pointNum; 246 frame->definedEvent = TOUCH_DOWN; 247 (void)InputI2cRead(i2cClient, reg, GT_ADDR_LEN, buf, GT_POINT_SIZE * pointNum); 248 /* Parse the obtained data. */ 249 ParsePointData(device, frame, buf, pointNum); 250 ... 251 } 252 static void ParsePointData(ChipDevice *device, FrameData *frame, uint8_t *buf, uint8_t pointNum) 253 { 254 ... 255 /* Each coordinate value consists of two bytes. Obtain the final coordinate value by combining the obtained single-byte data. */ 256 for (i = 0; i < pointNum; i++) { 257 frame->fingers[i].trackId = buf[GT_POINT_SIZE * i + GT_TRACK_ID]; 258 frame->fingers[i].y = (buf[GT_POINT_SIZE * i + GT_X_LOW] & ONE_BYTE_MASK) | 259 ((buf[GT_POINT_SIZE * i + GT_X_HIGH] & ONE_BYTE_MASK) << ONE_BYTE_OFFSET); 260 frame->fingers[i].x = (buf[GT_POINT_SIZE * i + GT_Y_LOW] & ONE_BYTE_MASK) | 261 ((buf[GT_POINT_SIZE * i + GT_Y_HIGH] & ONE_BYTE_MASK) << ONE_BYTE_OFFSET); 262 /* Print the parsed coordinate value. */ 263 HDF_LOGD("%s: x = %d, y = %d", __func__, frame->fingers[i].x, frame->fingers[i].y); 264 } 265 } 266 ``` 267 2682. Initialize the input chip driver and register the driver with the HDF. 269 270 You can obtain the sample code at **./drivers/framework/model/input/driver/touchscreen/touch\_gt911.c**. 271 272 ``` 273 static int32_t HdfGoodixChipInit(struct HdfDeviceObject *device) 274 { 275 ... 276 /* Use the chipCfg structure to allocate memory, parse the configuration information, and mount the parsed data. */ 277 chipCfg = ChipConfigInstance(device); 278 ... 279 /* Instantiate the touchscreen device. */ 280 chipDev = ChipDeviceInstance(); 281 ... 282 /* Mount touchscreen chip configuration and private operation data. */ 283 chipDev->chipCfg = chipCfg; 284 chipDev->ops = &g_gt911ChipOps; 285 ... 286 /* Register the chip driver with the platform driver. */ 287 RegisterChipDevice(chipDev); 288 ... 289 } 290 struct HdfDriverEntry g_touchGoodixChipEntry = { 291 .moduleVersion = 1, 292 .moduleName = "HDF_TOUCH_GT911", // The value must match the moduleName field of the chip driver in the device_info.hcs file. 293 .Init = HdfGoodixChipInit, // Initialize the touchscreen chip driver. 294 }; 295 HDF_INIT(g_touchGoodixChipEntry); // Register the touchscreen chip driver with the HDF. 296 ``` 297 298 The private chip drivers present the major differentiations among chip vendors, such as hibernation and wakeup, data parsing, and firmware update. 299 300 Now, you have completed the adaptation for the touchscreen driver based on the HDF and input driver model. 301 302 303## Building Source Code and Burning Images<a name="section16465031164711"></a> 304 3051. Compile the Makefile. 306 307 Open the file at **./drivers/adapter/khdf/linux/model/input/Makefile**. 308 309 Add the following content: 310 311 ``` 312 obj-$(CONFIG_DRIVERS_HDF_TP_5P5_GT911) += \ 313 $(INPUT_ROOT_DIR)/touchscreen/touch_gt911.o 314 ``` 315 316 **touch\_gt911.o** is the content added in this example. 317 3182. Build source code and burn images. For details, see the related sections in [Quick Start Overview](../quick-start/quickstart-overview.md). 319 320## Debugging and Verification<a name="section62577313482"></a> 321 322The following is part of the startup log: 323 324``` 325[I/HDF_INPUT_DRV] HdfInputManagerInit: enter // Initialize the input device manager. 326[I/HDF_INPUT_DRV] HdfInputManagerInit: exit succ // The initialization is successful. 327[I/osal_cdev] add cdev hdf_input_host success 328[I/HDF_LOG_TAG] HdfTouchDriverProbe: enter // Initialize the input common driver. 329[I/HDF_LOG_TAG] HdfTouchDriverProbe: main_touch exit succ // The initialization is successful. 330[I/osal_cdev] add cdev hdf_input_event1 success 331[I/HDF_INPUT_DRV] HdfGoodixChipInit: enter // Initialize the input chip driver. 332[I/HDF_INPUT_DRV] ChipDetect: IC FW version is 0x1060 333[I/HDF_INPUT_DRV] Product_ID: 911_1060, x_sol = 960, y_sol = 480 334[I/HDF_LOG_TAG] ChipDriverInit: chipDetect succ, ret = 0 335[I/HDF_LOG_TAG] InputDeviceInstance: inputDev->devName = main_touch 336[I/HDF_INPUT_DRV] HdfGoodixChipInit: exit succ, chipName = gt911 // The initialization is successful. 337``` 338 339## Input Driver Model Workflow Analysis<a name="section1578569154917"></a> 340 341To help you get familiarized with the working process of the input driver model, the following sections will describe the key code loaded by the input driver model. 342 343> **NOTICE:** 344>You do not need to perform development related to the input driver model. 345 346### Parsing Private Configuration Data<a name="section1310113815495"></a> 347 348You can obtain the sample code at **./drivers/framework/model/input/driver/input\_config\_parser.c**. 349 350The configuration parsing functions provided by the OSAL can parse the fields in the **hcs** file. For details, see the implementation of each function in **input\_config\_parser.c**. If the provided template cannot meet business requirements, add required information to the **hcs** file and then develop parsing functions based on the added fields. 351 352``` 353static int32_t ParseAttr(struct DeviceResourceIface *parser, const struct DeviceResourceNode *attrNode, BoardAttrCfg *attr) 354{ 355 int32_t ret; 356 ret = parser->GetUint8(attrNode, "inputType", &attr->devType, 0); // Obtain the inputType field and save it in the BoardAttrCfg structure. 357 CHECK_PARSER_RET(ret, "GetUint8"); 358 ... 359 return HDF_SUCCESS; 360} 361``` 362 363### Initializing the Input Device Manager and Registering the Driver with the HDF<a name="section614512119500"></a> 364 365You can obtain the sample code at **./drivers/framework/model/input/driver/hdf\_input\_device\_manager.c**. 366 367``` 368static int32_t HdfInputManagerInit(struct HdfDeviceObject *device) 369{ 370 /* Allocate memory to the device manager, which will store all input devices. */ 371 g_inputManager = InputManagerInstance(); 372 ... 373} 374struct HdfDriverEntry g_hdfInputEntry = { 375 .moduleVersion = 1, 376 .moduleName = "HDF_INPUT_MANAGER", 377 .Bind = HdfInputManagerBind, 378 .Init = HdfInputManagerInit, 379 .Release = HdfInputManagerRelease, 380}; 381 382HDF_INIT(g_hdfInputEntry); // Driver input entry 383``` 384 385### Initializing the Input Common Driver and Registering the Driver with the HDF<a name="section16194201755019"></a> 386 387You can obtain the sample code at **./drivers/framework/model/input/driver/hdf\_touch.c**. 388 389``` 390static int32_t HdfTouchDriverProbe(struct HdfDeviceObject *device) 391{ 392 ... 393 /* Use the boardCfg structure to allocate memory and parse the configuration information obtained from the HCS. */ 394 boardCfg = BoardConfigInstance(device); 395 ... 396 /* Allocate memory in the touchDriver structure. */ 397 touchDriver = TouchDriverInstance(); 398 ... 399 /* Initialize common resources based on the parsed board-level information, such as IIC initialization. */ 400 ret = TouchDriverInit(touchDriver, boardCfg); 401 if (ret == HDF_SUCCESS) { 402 ... 403 /* Add the driver to the common driver management linked list, which is used to query the driver after it is bound to the device. */ 404 AddTouchDriver(touchDriver); 405 ... 406 } 407 ... 408} 409struct HdfDriverEntry g_hdfTouchEntry = { 410 .moduleVersion = 1, 411 .moduleName = "HDF_TOUCH", 412 .Bind = HdfTouchDriverBind, 413 .Init = HdfTouchDriverProbe, 414 .Release = HdfTouchDriverRelease, 415}; 416 417 HDF_INIT(g_hdfTouchEntry); // Driver input entry 418``` 419 420### Initializing the Input Chip Driver and Registering the Driver with the HDF<a name="section1090743312505"></a> 421 422For details, see related content in [Adapting to the Private Drivers of the Touchscreen](#section17127331595). 423 424### Function Invocation Logic<a name="section81801147529"></a> 425 426The init function of the input device manager initializes the device management linked list, and the init function of the common driver allocates memory for related structures. The **RegisterChipDevice** function passes touchscreen chip driver information to the related structures of the input common driver and initializes hardware information \(for example, interrupt registration\). The **RegisterInputDevice** function registers **inputDev** \(binding the device and the driver\) with the device manager. The **RegisterInputDevice** function adds **inputDev** to the device management linked list. The function implementation is as follows: 427 428``` 429// Code location: ./drivers/framework/model/input/driver/hdf_touch.c 430int32_t RegisterChipDevice(ChipDevice *chipDev) 431{ 432 ... 433 /* Bind the device to the driver and create an inputDev instance using InputDeviceInstance. */ 434 DeviceBindDriver(chipDev); 435 ... 436 /* Implement the interrupt registration and interrupt handling functions. The interrupt handling function contains the channel for reporting data to the user space. */ 437 ChipDriverInit(chipDev); 438 ... 439 /* Allocate memory for instantiating inputDev. */ 440 inputDev = InputDeviceInstance(chipDev); 441 ... 442 /* Register inputDev with the input device manager. */ 443 RegisterInputDevice(inputDev); 444 ... 445} 446 447// Code location: ./drivers/framework/model/input/driver/hdf_input_device_manager.c 448int32_t RegisterInputDevice(InputDevice *inputDev) 449{ 450 ... 451 /* Allocate a device ID, which is unique for each input device. */ 452 ret = AllocDeviceID(inputDev); 453 ... 454 /* This function contains special processing for hid devices but does nothing for the touchscreen driver. */ 455 CreateDeviceNode(inputDev); 456 /* Apply for the buffer for the IOService capability, which is required to transmit kernel-space data to the user space. */ 457 AllocPackageBuffer(inputDev); 458 /* Add the input device to the global device management linked list. */ 459 AddInputDevice(inputDev); 460 ... 461} 462``` 463 464
