drives/input: support ST7123 touchscreen controller

Documentation/components/drivers/character/input/index.rst

@@ -9,5 +9,6 @@ Input Devices
   keypad.rst
   mpr121.rst
   sbutton.rst
+  st7123.rst
 
 See ``include/nuttx/input/*.h`` for registration information.

Documentation/components/drivers/character/input/st7123.rst

@@ -0,0 +1,101 @@
+==============================
+ST7123 Capacitive Touchscreen
+==============================
+
+**What is the ST7123**. The ST7123 is an I2C capacitive multi-touch
+controller used on TDDI (Touch and Display Driver Integration) panels.
+It reports up to ten simultaneous contacts, optional gesture codes, and
+contact intensity.  The same I2C register map is also used by related
+parts such as the ST7121.
+
+**Purpose**. The ST7123 driver is a touchscreen lower-half that probes
+the controller over I2C, reads complete touch frames on interrupt, and
+delivers multi-touch samples through the common touchscreen upper-half.
+Once registered, the device appears as ``/dev/inputN`` and applications
+read ``struct touch_sample_s`` samples as described in
+:doc:`../touchscreen`.
+
+**Driver Overview**. On each falling edge of the controller interrupt
+line the board ISR calls ``st7123_interrupt_callback()``, which queues
+``st7123_data_worker()`` on the high-priority work queue.  The worker
+fetches one full touch frame (advanced-touch header plus every touch
+area) in a single I2C transaction, converts per-area *valid* bits into
+``TOUCH_DOWN`` / ``TOUCH_MOVE`` / ``TOUCH_UP`` transitions, and pushes
+the sample with ``touch_event()``.  The upper half stores the sample in
+a circular buffer for ``read()`` / ``poll()`` clients.
+
+**Configuration**. Enable the driver with:
+
+- ``CONFIG_INPUT=y``
+- ``CONFIG_INPUT_TOUCHSCREEN=y``
+- ``CONFIG_INPUT_ST7123=y``
+- ``CONFIG_SCHED_HPWORK=y`` (required; frame processing runs on HPWORK)
+- ``CONFIG_INPUT_ST7123_I2C_FREQUENCY`` (default ``400000``)
+- ``CONFIG_INPUT_ST7123_I2C_ADDRESS`` (default ``0x55``)
+
+**Board Support**. To support the ST7123 a board must provide:
+
+#. **I2C Bus**
+
+   - An initialized ``struct i2c_master_s`` instance that can reach the
+     controller at ``CONFIG_INPUT_ST7123_I2C_ADDRESS``.
+
+#. **Interrupt GPIO**
+
+   - A GPIO configured as an interrupt input for the controller INT pin
+     (typically active-low / falling edge with pull-up).
+   - The board ISR must call ``st7123_interrupt_callback()``.
+     Interrupts that arrive before ``st7123_register()`` completes are
+     ignored by the driver.
+
+#. **Registration Hook**
+
+   - Call ``st7123_register(i2c, minor)`` during board bring-up to probe
+     the part and create ``/dev/inputN``.
+   - Enable the interrupt only *after* registration succeeds, so an early
+     edge cannot reach an uninitialized device.
+
+**Data Path Summary**.
+
+- Board obtains the I2C master and calls ``st7123_register(i2c, 0)``
+- ``st7123_register()`` probes firmware / resolution / touch count,
+  fills ``struct touch_lowerhalf_s``, and calls
+  ``touch_register(..., "/dev/input0", maxpoint)``
+- Board attaches its GPIO ISR and enables the INT line
+- Each INT schedules ``st7123_data_worker()`` on HPWORK
+- The worker reads the frame starting at register ``0x10`` and reports
+  contacts through ``touch_event()``
+- Applications open ``/dev/input0`` and read
+  ``struct touch_sample_s`` (sized with ``SIZEOF_TOUCH_SAMPLE_S(n)``)
+
+**Open / Close Behavior**.
+
+- ``open()`` powers the controller up (clears ``DEV_CTRL``), disables
+  smart-wakeup with a read-modify-write of ``MISC_CTRL`` when the part
+  advertises that feature, and waits until ``STATUS`` reports
+  ``NORMAL``.
+- ``close()`` sets the power-down bit in ``DEV_CTRL`` and verifies that
+  ``STATUS`` reports ``POWER_DOWN``.
+
+**Touch Samples**. Each reported contact uses the touch-area index as
+its stable ``id``.  Flags follow the common touchscreen conventions:
+
+- First contact: ``TOUCH_DOWN | TOUCH_ID_VALID | TOUCH_POS_VALID | TOUCH_PRESSURE_VALID``
+- Continued contact: ``TOUCH_MOVE`` with the same validity bits
+- Lost contact: ``TOUCH_UP | TOUCH_ID_VALID | TOUCH_POS_VALID`` at the
+  last known coordinates
+
+Supported gesture codes from the controller are mapped onto the common
+``TOUCH_*`` gesture values (double-click and slide directions).
+
+**Application Notes**.
+
+- ``read()`` returns a variable-length sample.  Buffers must be at least
+  ``SIZEOF_TOUCH_SAMPLE_S(maxpoint)`` bytes; reading only
+  ``sizeof(struct touch_sample_s)`` (one contact) desynchronizes the
+  stream when multiple fingers are down.
+- The example under ``apps/examples/touchscreen`` currently assumes a
+  single-point sample size and is not suitable for multi-touch testing
+  without a larger read buffer.
+- Header: ``include/nuttx/input/st7123.h``
+- Driver: ``drivers/input/st7123.c``

Documentation/components/drivers/character/touchscreen.rst

@@ -41,14 +41,14 @@ Application Programming Interface
 =================================
 
 The first thing to be done in order to use the touchscreen driver from an
-application is to include the correct header filer. It contains the 
+application is to include the correct header filer. It contains the
 Application Programming Interface to the driver. To do so, include
 
 .. code-block:: c
 
   #include <nuttx/input/touchscreen.h>
 
-Touchscreen driver is registered as a POSIX character device file into 
+Touchscreen driver is registered as a POSIX character device file into
 ``/dev`` namespace. It is necessary to open the device to get a file descriptor
 for further operations. This can be done with standard POSIX ``open()`` call.
 
@@ -63,4 +63,11 @@ This command let the current handle has the device grabbed. When a handle grabs
 a device it becomes sole recipient for all touchscreen events coming from the
 device. An argument is an ``int32_t`` variable to enable or disable the grab.
 
+Supported Controllers
+=====================
 
+Individual touchscreen controller drivers are documented under
+:doc:`input/index`.  Controllers currently covered there include:
+
+- :doc:`input/st7123` — ST7123 (and related ST7121) capacitive multi-touch
+  controller over I2C

drivers/input/CMakeLists.txt

@@ -94,6 +94,10 @@ if(CONFIG_INPUT)
     list(APPEND SRCS gt9xx.c)
   endif()
 
+  if(CONFIG_INPUT_ST7123)
+    list(APPEND SRCS st7123.c)
+  endif()
+
   if(CONFIG_INPUT_BUTTONS)
     list(APPEND SRCS button_upper.c)
 

drivers/input/Kconfig

@@ -166,6 +166,30 @@ config UINPUT_KEYBOARD_BUFNUMBER
 
 endif
 
+config INPUT_ST7123
+	bool "ST7123 Touch Screen Controller"
+	default n
+	select I2C
+	select INPUT_TOUCHSCREEN
+	---help---
+		Enable support for the ST7123 touchscreen controller.
+
+if INPUT_ST7123
+
+config INPUT_ST7123_I2C_FREQUENCY
+	int "I2C frequency"
+	default 400000
+	---help---
+		Select the I2C frequency for the ST7123 touchscreen controller.
+
+config INPUT_ST7123_I2C_ADDRESS
+	hex "I2C address"
+	default 0x55
+	---help---
+		Select the I2C address for the ST7123 touchscreen controller.
+
+endif # INPUT_ST7123
+
 config INPUT_MAX11802
 	bool "MAX11802 touchscreen controller"
 	default n

drivers/input/Make.defs

@@ -143,6 +143,10 @@ ifeq ($(CONFIG_INPUT_MPR121_KEYPAD),y)
   CSRCS += mpr121.c
 endif
 
+ifeq ($(CONFIG_INPUT_ST712X),y)
+  CSRCS += st7123.c
+endif
+
 # Include input device driver build support
 
 DEPPATH += --dep-path input