Add Goodix haptic touchpad 27C6:0F90 support

Part-of: <https://gitlab.freedesktop.org/libinput/libinput/-/merge_requests/1451>

.clang-format

@@ -0,0 +1,82 @@
+AlignAfterOpenBracket: Align
+# This option we want but it's frequently broken and causes bad
+# misalignment. The canary is wheel_click_count_parser, if that works
+# we can actually enable it.
+# AlignArrayOfStructures: Left
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignConsecutiveMacros: true
+AlignConsecutiveShortCaseStatements:
+  Enabled: true
+  AcrossEmptyLines: false
+  AcrossComments: true
+  AlignCaseColons: false
+AlignEscapedNewlines: Right
+AlignOperands: Align
+AlignTrailingComments: true
+AllowAllArgumentsOnNextLine: false
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: false
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakBeforeMultilineStrings: true
+BinPackArguments: false
+BinPackParameters: OnePerLine
+BraceWrapping:
+  AfterFunction: true
+BreakAfterReturnType: All
+BreakBeforeBraces: Custom
+BreakStringLiterals: false
+ColumnLimit: 88
+ContinuationIndentWidth: 8
+Cpp11BracedListStyle: false
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex:           '^(<|")config\.h(>|")'
+    Priority:        0
+    SortPriority:    0
+  - Regex:           '^<.*'
+    Priority:        1
+    SortPriority:    0
+  - Regex:           '^"util-.*'
+    Priority:        2
+    SortPriority:    0
+  - Regex:           '.*'
+    Priority:        3
+    SortPriority:    0
+IndentCaseLabels: false
+IndentGotoLabels: false
+IndentWidth: 8
+MaxEmptyLinesToKeep: 1
+PointerAlignment: Right
+ReflowComments: true
+RemoveEmptyLinesInUnwrappedLines: true
+RemoveParentheses: MultipleParentheses
+RemoveSemicolon: true
+SkipMacroDefinitionBody: true
+SortIncludes: true
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCaseColon: false
+SpaceBeforeParens: ControlStatementsExceptControlMacros
+SpacesInContainerLiterals: true
+SpacesInParens: Custom
+TabWidth: 8
+UseTab: ForContinuationAndIndentation
+
+ForEachMacros:
+  - ARRAY_FOR_EACH
+  - list_for_each
+  - list_for_each_safe
+  - tp_for_each_touch
+  - range_for_each
+  - litest_log_group
+  - litest_with_logcapture
+  - litest_with_parameters
+  - litest_with_event_frame
+  - udev_list_entry_foreach
+# END_TEST is defined as something that enforces a line break
+Macros: [ "CASE_RETURN_STRING(s)=case s: return s", "START_TEST(s)=static void s(void)", "END_TEST=enum foo;"]

.clang-format-ignore

@@ -0,0 +1 @@
+include/**/*

.clang-tidy

@@ -0,0 +1,7 @@
+# optin.core.unix.Malloc: disabled so we can use __attribute__((cleanup)) without leak complaints
+# optin.core.EnumCastOutOfRange: disabled because we use a lot of "wrong" enum values for testing
+#                                and internally and don't want those values leak into the public API
+Checks: >
+  -clang-analyzer-unix.Malloc,
+  -clang-analyzer-optin.core.EnumCastOutOfRange
+WarningsAsErrors: '*'

.clang-tidy-ignore

@@ -0,0 +1 @@
+include/*

.editorconfig

@@ -0,0 +1,25 @@
+# https://editorconfig.org/
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{c,h}]
+indent_size = 8
+indent_style = tab
+
+[*.py]
+indent_size = 4
+indent_style = space
+
+[{meson.build,meson_options.txt}]
+indent_size = 8
+indent_style = tab
+
+[*.sym]
+indent_size = 8
+indent_style = tab

.git-blame-ignore-revs

@@ -0,0 +1,21 @@
+# This file contains revisions to be ignored by git blame.
+# These revisions are expected to be formatting-only changes.
+#
+# Calling `git blame --ignore-revs-file .git-blame-ignore-revs` will
+# tell git blame to ignore changes made by these revisions when assigning
+# assigning blame, as if the change never happened.
+#
+# You can enable this as a default for your local repository by running
+# `git config blame.ignoreRevsFile .git-blame-ignore-revs`
+# Important: if you do this, then switch to a branch without this file,
+# `git blame` will fail with an error.
+#
+
+# Run clang-format over the code
+2a1095924b0be60f822bc0ff20d567e209a9db73
+
+# Add trailing commas to prevent clang-format oddities
+aebf3cd4915adc576cf055926caa621e098ec32b
+
+# Fix some inconsistent whitespace.
+60abf1575560cb8e2220ae48a67e7f74b5dc70dd

.gitlab-ci/ci.template

@@ -0,0 +1,803 @@
+# vim: set expandtab shiftwidth=2 tabstop=8 textwidth=0 filetype=yaml:
+
+{# You're looking at the template here, so you can ignore the below
+   warning. This is the right file to edit #}
+########################################
+#                                      #
+# THIS FILE IS GENERATED, DO NOT EDIT  #
+#                                      #
+########################################
+
+# To change the gitlab CI, edit .gitlab-ci/ci.template and/or .gitlab-ci/config.yaml
+# and run ci-fairy generate-template. For details, see
+# https://freedesktop.pages.freedesktop.org/ci-templates/ci-fairy.html#templating-gitlab-ci-yml
+
+# This is a bit complicated for two reasons:
+# - we really want to run dnf/apt/... only once, updating on the test runner for
+#   each job takes forever. So we create a container image for each distribution
+#   tested, then run the tests on this container image.
+#
+#   This is handled by the ci-templates, ensuring containers are only rebuilt
+#   when the TAG changes.
+#
+# - GitLab only allows one script: set per job but we have a bunch of commands
+#   we need to re-run for each build (meson && ninja && etc). YAML cannot merge
+#   arrays so we're screwed.
+#
+#   So instead we use a default_build template and override everything with
+#   variables. The only two variables that matter:
+#     MESON_ARGS=-Denable-something=true
+#     NINJA_ARGS=dist ... to run 'ninja -C builddir dist'
+#   Note that you cannot use scripts: in any target if you expect default_build
+#   to work.
+#
+#
+# All jobs must follow the naming scheme of
+# <distribution>:<version>@activity:
+#  e.g. fedora:31@build-default
+
+.templates_sha: &template_sha c6aeb16f86e32525fa630fb99c66c4f3e62fc3cb
+
+include:
+  - project: 'freedesktop/ci-templates'
+    ref: *template_sha
+    file:
+      - '/templates/ci-fairy.yml'
+  {% for distro in distributions|sort(attribute="name") %}
+      # {{ distro.name.capitalize() }} container builder template
+      - '/templates/{{distro.name}}.yml'
+  {% endfor %}
+
+workflow:
+  rules:
+    # do not duplicate pipelines on merge pipelines
+    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
+      when: never
+    # merge pipeline
+    - if: &is-merge-attempt $GITLAB_USER_LOGIN == "marge-bot" && $CI_PIPELINE_SOURCE == "merge_request_event"
+      variables:
+        FDO_RUNNER_JOB_PRIORITY_TAG_X86_64: priority:high
+        FDO_RUNNER_JOB_PRIORITY_TAG_X86_64_KVM: priority:high-kvm
+        FDO_RUNNER_JOB_PRIORITY_TAG_AARCH64: priority:high-aarch64
+    # post-merge pipeline
+    - if: &is-post-merge $GITLAB_USER_LOGIN == "marge-bot" && $CI_PIPELINE_SOURCE == "push"
+      variables:
+        FDO_RUNNER_JOB_PRIORITY_TAG_X86_64: priority:high
+        FDO_RUNNER_JOB_PRIORITY_TAG_X86_64_KVM: priority:high-kvm
+        FDO_RUNNER_JOB_PRIORITY_TAG_AARCH64: priority:high-aarch64
+    # Pre-merge pipeline
+    - if: &is-pre-merge $CI_PIPELINE_SOURCE == "merge_request_event"
+    # Push to a branch on a fork
+    - if: $CI_COMMIT_BRANCH
+
+stages:
+  - sanity check     # CI/commit checks
+  - prep             # prep work like rebuilding the container images if there is a change
+  - build            # for actually building and testing things in a container
+  - test-suite       # for running the test suite in a VM
+  - test-suite-no-libwacom # for running the test suite in a VM (libwacom disabled)
+  - valgrind         # for running the test suite under valgrind in a VM
+  - distro           # distribs test
+  - deploy           # trigger wayland's website generation
+  - container_clean  # clean up unused container images (scheduled jobs only)
+
+variables:
+  ###############################################################################
+  # This is the list of packages required to build libinput with the default    #
+  # configuration.                                                              #
+  #                                                                             #
+  # Run dnf install/apt-get install/.. with the list of packages for your       #
+  # distribution                                                                #
+  #                                                                             #
+  # See the documentation here:                                                 #
+  # https://wayland.freedesktop.org/libinput/doc/latest/building.html           #
+  ###############################################################################
+{% for distro in distributions %}
+  {{"%-17s" | format(distro.name.upper() + '_PACKAGES:')}} '{{ distro.packages|join(' ')}}'
+{% endfor %}
+  ############################ end of package lists #############################
+
+  # these tags should be updated each time the list of packages is updated
+  # changing these will force rebuilding the associated image
+  # Note: these tags have no meaning and are not tied to a particular
+  # libinput version
+{% for distro in distributions %}
+  {{"%-13s"| format(distro.name.upper() + '_TAG:')}}'{{distro.tag}}'
+{% endfor %}
+
+  FDO_UPSTREAM_REPO: libinput/libinput
+
+  MESON_BUILDDIR: "build dir"
+  NINJA_ARGS: ''
+  MESON_ARGS: ''
+  MESON_TEST_ARGS: '--no-suite=hardware'
+
+  # udev isn't available/working properly in the containers
+  UDEV_NOT_AVAILABLE: 1
+  GIT_DEPTH: 1
+
+  # Default priority for non-merge pipelines
+  FDO_RUNNER_JOB_PRIORITY_TAG_X86_64: ""  # Empty tags are ignored by gitlab
+  FDO_RUNNER_JOB_PRIORITY_TAG_X86_64_KVM: kvm
+  FDO_RUNNER_JOB_PRIORITY_TAG_AARCH64: aarch64
+
+.policy:
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+  # cancel run when a newer version is pushed to the branch
+  interruptible: true
+  dependencies: []
+
+.policy-retry-on-failure:
+  retry:
+    max: 1
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+  # cancel run when a newer version is pushed to the branch
+  interruptible: true
+  dependencies: []
+
+.default_artifacts:
+  artifacts:
+    name: "meson-logs-$CI_JOB_NAME"
+    when: always
+    expire_in: 1 week
+    paths:
+      - $MESON_BUILDDIR/meson-logs
+      - $MESON_BUILDDIR/valgrind.*.log
+    reports:
+      junit: $MESON_BUILDDIR/*junit*.xml
+
+.fdo-runner-tags:
+  tags:
+    - $FDO_RUNNER_JOB_PRIORITY_TAG_X86_64
+
+
+#################################################################
+#                                                               #
+#                     sanity check stage                        #
+#                                                               #
+#################################################################
+
+fail-if-fork-is-not-public:
+  extends:
+    - .fdo-runner-tags
+  stage: sanity check
+  script:
+    - |
+      if [ $CI_PROJECT_VISIBILITY != "public" ]; then
+           echo "*************************************************************************************"
+           echo "Project visibility must be set to 'public'"
+           echo "Change this in $CI_PROJECT_URL/edit under 'Visibility, project features, permissions'"
+           echo "*************************************************************************************"
+           exit 1
+      fi
+  except:
+    - main@libinput/libinput
+
+# Re-generate the CI script and make sure it's the one currently checked in
+# If this job fails, re-generate the gitlab-ci.yml script, see
+# $SRCDIR/.gitlab-ci/generate-gitlab-ci.py
+#
+check-ci-script:
+  extends:
+    - .fdo.ci-fairy
+    - .fdo-runner-tags
+  stage: sanity check
+  script:
+    - ci-fairy generate-template --verify && exit 0 || true
+    - >
+      printf "%s\n" \
+        "Committed gitlab-ci.yml differs from generated gitlab-ci.yml. Please verify" \
+        "https://wayland.freedesktop.org/libinput/doc/latest/contributing.html"
+    - exit 1
+
+#
+# Verify that commit messages are as expected, etc.
+#
+
+check-commit:
+  extends:
+    - .fdo.ci-fairy
+    - .fdo-runner-tags
+  stage: sanity check
+  script:
+    - ci-fairy -vv check-commits --junit-xml=results.xml && exit 0 || true
+    - >
+      printf "%s\n" \
+        "Error checking commit format. Please verify" \
+        "https://wayland.freedesktop.org/libinput/doc/latest/contributing.html"
+    - exit 1
+  except:
+    - main@libinput/libinput
+  variables:
+    GIT_DEPTH: 100
+  artifacts:
+    reports:
+      junit: results.xml
+
+
+#
+# Check for trailing whitespaces
+#
+
+check-whitespace:
+  extends:
+    - .fdo.ci-fairy
+    - .fdo-runner-tags
+  stage: sanity check
+  script:
+    - .gitlab-ci/whitespace-check.py $(git ls-files)
+
+#
+# pre-commit hooks
+#
+
+pre-commit-hooks:
+  extends:
+    - .fdo.ci-fairy
+    - .fdo-runner-tags
+  stage: sanity check
+  script:
+    - python3 -m venv venv
+    - source venv/bin/activate
+    - pip3 install pre-commit
+    - pre-commit run --all-files
+    - git diff --exit-code || (echo "ERROR - Code style errors found, please fix" && false)
+
+#################################################################
+#                                                               #
+#                          prep stage                           #
+#                                                               #
+#################################################################
+
+{% for distro in distributions %}
+{% for version in distro.versions %}
+{{distro.name}}:{{version}}@container-prep:
+  extends:
+{% if distro.qemu_based %}
+    - .fdo.qemu-build@{{distro.name}}
+{% else %}
+    - .fdo.container-build@{{distro.name}}
+{% endif %}
+    - .policy
+    - .fdo-runner-tags
+{% if distro.qemu_based %}
+  tags:
+    - $FDO_RUNNER_JOB_PRIORITY_TAG_X86_64_KVM
+{% endif %}
+  stage: prep
+  variables:
+    GIT_STRATEGY: none
+    FDO_DISTRIBUTION_VERSION: '{{version}}'
+    FDO_DISTRIBUTION_PACKAGES: ${{distro.name.upper()}}_PACKAGES
+    FDO_DISTRIBUTION_TAG: ${{distro.name.upper()}}_TAG
+
+{% endfor %}
+{% endfor %}
+
+
+#################################################################
+#                                                               #
+#                   container clean stage                       #
+#                 run during the clean stage                    #
+#                                                               #
+#################################################################
+
+#
+# This stage will look for the container images we currently have in
+# the registry and will remove any that are not tagged with the provided
+# $container_image:$tag
+#
+.container-clean:
+  extends:
+    - .policy
+    - .fdo.ci-fairy
+    - .fdo-runner-tags
+  stage: container_clean
+  script:
+    # Go to your Profile, Settings, Access Tokens
+    # Create a personal token with 'api' scope, copy the value.
+    # Go to CI/CD, Schedules, schedule a new monthly job (or edit the existing one)
+    # Define a variable of type File named AUTHFILE. Content is that token
+    # value.
+    - ci-fairy -v --authfile $AUTHFILE delete-image
+            --repository $FDO_DISTRIBUTION_NAME/$FDO_DISTRIBUTION_VERSION
+            --exclude-tag $FDO_DISTRIBUTION_TAG
+  allow_failure: true
+  only:
+    - schedules
+
+{% for distro in distributions %}
+{% for version in distro.versions %}
+{{distro.name}}:{{version}}@container-clean:
+  extends:
+    - .policy
+    - .container-clean
+  variables:
+    GIT_STRATEGY: none
+    CURRENT_CONTAINER_IMAGE: $CI_REGISTRY_IMAGE/{{distro.name}}/$FDO_DISTRIBUTION_VERSION:$FDO_DISTRIBUTION_TAG
+    FDO_DISTRIBUTION_VERSION: '{{version}}'
+    FDO_DISTRIBUTION_TAG: ${{distro.name.upper()}}_TAG
+
+{% endfor %}
+{% endfor %}
+
+#################################################################
+#                                                               #
+#                       build stage                             #
+#                                                               #
+#################################################################
+
+.build@template:
+  extends:
+    - .policy
+    - .default_artifacts
+    - .fdo-runner-tags
+  stage: build
+  script:
+    - .gitlab-ci/meson-build.sh
+
+
+# Run meson and meson test in the container image through qemu
+.build-in-vng@template:
+  extends:
+    - .policy
+    - .default_artifacts
+  tags:
+    - $FDO_RUNNER_JOB_PRIORITY_TAG_X86_64_KVM
+  variables:
+    MESON_BUILDDIR: build_dir
+    VNG_KERNEL: {{ vng.kernel }}
+  script:
+    # first build in the host container
+    - .gitlab-ci/meson-build.sh --skip-test
+
+    - mkdir -p $MESON_BUILDDIR
+    - curl -LO $VNG_KERNEL
+
+    - export -p > .vngenv
+
+    # runs the test suite only
+    - |
+      vng --run ./bzImage \
+          --user root \
+          --overlay-rwdir=$HOME \
+          --append HOME=$HOME \
+          --overlay-rwdir=$(pwd) \
+          --rwdir=$MESON_BUILDDIR \
+          --exec "source $PWD/.vngenv; rm $PWD/.vngenv; .gitlab-ci/meson-build.sh --skip-setup --skip-build --run-test"
+
+#
+# Fedora
+#
+
+.check_tainted: &check_tainted |
+  # make sure the kernel is not tainted
+  if [[ "$(ssh localhost -p 5555 cat /proc/sys/kernel/tainted)" -gt 0 ]];
+  then
+    echo tainted kernel ;
+    exit 1 ;
+  fi
+
+# Run meson and meson test in the qemu image
+.build-in-qemu@template:
+  extends:
+    - .policy
+  tags:
+    - $FDO_RUNNER_JOB_PRIORITY_TAG_X86_64_KVM
+  variables:
+    MESON_BUILDDIR: build_dir
+  script:
+    # start our vm, no args required
+    - /app/vmctl start || (echo "Error - Failed to start the VM." && exit 1)
+
+    - *check_tainted
+
+    - "scp -r $PWD vm:"
+    - echo "CI_JOB_ID=\"$CI_JOB_ID\"" > sshenv
+    - echo "CI_JOB_NAME=\"$CI_JOB_NAME\"" >> sshenv
+    - echo "MESON_ARGS=\"$MESON_ARGS\"" >> sshenv
+    - echo "MESON_BUILDDIR=\"$MESON_BUILDDIR\"" >> sshenv
+    - echo "MESON_TEST_ARGS=\"$MESON_TEST_ARGS\"" >> sshenv
+    - echo "NINJA_ARGS=\"$NINJA_ARGS\"" >> sshenv
+    - "scp sshenv vm:~/$CI_PROJECT_NAME/.meson_environment"
+    - /app/vmctl exec "cd $CI_PROJECT_NAME ; .gitlab-ci/meson-build.sh" && touch .success || true
+    # no matter the results of the tests, we want to fetch the logs
+    - scp -r vm:$CI_PROJECT_NAME/$MESON_BUILDDIR .
+
+    - *check_tainted
+
+    - /app/vmctl stop
+
+    - if [[ ! -e .success ]] ;
+      then
+        exit 1 ;
+      fi
+  artifacts:
+    name: "qemu-meson-logs-$CI_JOB_NAME"
+    when: always
+    expire_in: 1 week
+    paths:
+      - $MESON_BUILDDIR/meson-logs
+      - console.out
+    reports:
+      junit: $MESON_BUILDDIR/*junit*.xml
+
+
+# Run in a test suite. Special variables:
+# - SUITES: the meson test suites to run, or
+# - SUITE_NAMES: all elements will be expanded to libinput-test-suite-$value
+# Set one or the other, not both.
+.test-suite-vm:
+  extends:
+    - .build-in-vng@template
+  stage: test-suite
+  variables:
+    # remove the global --no-suite=hardware
+    MESON_TEST_ARGS: ''
+    LITEST_JOBS: 4
+  before_script:
+    - if ! [[ -z $SUITE_NAMES ]]; then SUITES=$(echo $SUITE_NAMES | sed 's/\([^ ]*\)/libinput-test-suite-\1/g'); fi
+    - echo "Testing $SUITES"
+    - export MESON_TEST_ARGS="$MESON_TEST_ARGS $SUITES"
+
+
+{# qemu tests are only done for the latest version of any distribution #}
+{% for distro in distributions if distro.use_for_qemu_tests %}
+{% set version = "{}".format(distro.versions|last()) %}
+.{{distro.name}}:{{version}}@test-suite-vm:
+  extends:
+    - .fdo.distribution-image@{{distro.name}}
+    - .test-suite-vm
+  variables:
+    FDO_DISTRIBUTION_VERSION: {{version}}
+    FDO_DISTRIBUTION_TAG: ${{distro.name.upper()}}_TAG
+  needs:
+    - "{{distro.name}}:{{version}}@container-prep"
+
+
+{% for suite in test_suites %}
+vm-{{suite.name}}:
+  extends:
+    - .{{distro.name}}:{{version}}@test-suite-vm
+  variables:
+    SUITE_NAMES: '{{suite.suites|join(' ')}}'
+
+vm-{{suite.name}}-no-libwacom:
+  extends:
+    - vm-{{suite.name}}
+  stage: test-suite-no-libwacom
+  variables:
+    MESON_ARGS: '-Dlibwacom=false'
+
+{% endfor %}
+
+{% for suite in test_suites %}
+vm-valgrind-{{suite.name}}:
+  stage: valgrind
+  extends:
+    - vm-{{suite.name}}
+    - .policy-retry-on-failure
+  variables:
+    MESON_TEST_ARGS: '--setup=valgrind'
+    LITEST_JOBS: 0
+  retry:
+    max: 2
+  rules:
+    - if: $GITLAB_USER_LOGIN != "marge-bot"
+
+{% endfor %}
+
+{% endfor %}{# for if distro.use_for_qemu_tests #}
+
+{% for distro in distributions if distro.use_for_custom_build_tests %}
+{% set version = "{}".format(distro.versions|last()) %}
+.{{distro.name}}-build@template:
+  extends:
+    - .fdo.distribution-image@{{distro.name}}
+    - .build@template
+  variables:
+    FDO_DISTRIBUTION_VERSION: '{{version}}'
+    FDO_DISTRIBUTION_TAG: ${{distro.name.upper()}}_TAG
+  needs:
+    - "{{distro.name}}:{{version}}@container-prep"
+
+default-build-release@{{distro.name}}:{{version}}:
+  stage: distro
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dbuildtype=release"
+    CFLAGS: "-Werror"
+
+clang-tidy@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    NINJA_ARGS: ''
+    MESON_TEST_ARGS: ''
+    CC: 'clang'
+  script:
+    - .gitlab-ci/meson-build.sh
+    - ninja -C "$MESON_BUILDDIR" clang-tidy
+
+# Below jobs are build option combinations. We only
+# run them on one image, they shouldn't fail on one distro
+# when they succeed on another.
+
+build-no-libwacom@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dlibwacom=false"
+
+build-no-libwacom-nodeps@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dlibwacom=false"
+  before_script:
+    - dnf remove -y libwacom libwacom-devel
+
+build-no-mtdev@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dmtdev=false"
+
+build-no-mtdev-nodeps@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dmtdev=false"
+  before_script:
+    - dnf remove -y mtdev mtdev-devel
+
+build-no-lua@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dlua-plugins=disabled"
+
+build-no-lua-nodeps@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dlua-plugins=disabled"
+  before_script:
+    - dnf remove -y lua lua-devel
+
+build-docs@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Ddocumentation=true"
+
+build-no-docs-nodeps@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Ddocumentation=false"
+  before_script:
+    - dnf remove -y doxygen graphviz
+
+build-no-debuggui@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Ddebug-gui=false"
+
+build-no-debuggui-nodeps@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Ddebug-gui=false"
+  before_script:
+    - dnf remove -y gtk3-devel gtk4-devel
+
+build-no-tests@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dtests=false"
+
+build-no-tests-nodeps@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_ARGS: "-Dtests=false"
+  before_script:
+    - dnf remove -y check-devel
+
+valgrind@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  variables:
+    MESON_TEST_ARGS: '--suite=valgrind --no-suite=hardware --setup=valgrind'
+
+# Python checks, only run on Fedora
+
+usr-bin-env-python@{{distro.name}}:{{version}}:
+  extends:
+    - .{{distro.name}}-build@template
+  script:
+    - |
+      if git grep -l '^#!/usr/bin/python'; then
+        echo "Use '/usr/bin/env python3' in the above files";
+        /bin/false
+      fi
+
+# A job to check we're actually running all test suites in the CI
+check-test-suites:
+  extends:
+    - .{{distro.name}}-build@template
+  script:
+    - meson setup builddir
+    - meson introspect builddir --test | jq -r '.[].name' | grep 'libinput-test-suite' | sort > meson-testsuites
+    - |
+      cat <<EOF > ci-testsuites ;
+{% for suite in test_suites %}
+{% for name in suite.suites %}
+        libinput-test-suite-{{name}}
+{% endfor %}
+{% endfor %}
+      EOF
+    - sort -o ci-testsuites ci-testsuites
+    - diff -u8 -w ci-testsuites meson-testsuites || (echo "Some test suites are not run in the CI" && false)
+  only:
+    changes:
+      - "meson.build"
+      - ".gitlab-ci.yml"
+{% endfor %}
+
+#
+# coverity run
+#
+# This requires the COVERITY_SCAN_TOKEN. Log into scan.coverity.com and get
+# the token from the respective project settings page.
+# Schedule a pipeline and set a variable COVERITY_SCAN_TOKEN with the token value.
+# https://gitlab.freedesktop.org/$CI_PROJECT_PATH/-/pipeline_schedules
+# Email from coverity will be sent to the GITLAB_USER_EMAIL that scheduled the
+# job.
+#
+# Coverity ratelimits submissions and the coverity tools download is about
+# 700M, do not run this too often.
+#
+coverity:
+  extends:
+    - .fdo.distribution-image@debian
+    - .policy
+    - .fdo-runner-tags
+  stage: build
+  variables:
+    FDO_DISTRIBUTION_VERSION: 'stable'
+    FDO_DISTRIBUTION_TAG: $DEBIAN_TAG
+    # so git-describe works, or should work
+    GIT_DEPTH: 200
+  only:
+    variables:
+      - $COVERITY_SCAN_TOKEN
+  script:
+    - curl https://scan.coverity.com/download/linux64
+        -o /tmp/cov-analysis-linux64.tgz
+        --form project=$CI_PROJECT_NAME
+        --form token=$COVERITY_SCAN_TOKEN
+    - tar xfz /tmp/cov-analysis-linux64.tgz
+    # coverity has special build options in meson, make sure we enable those
+    - meson coverity-build -Ddocumentation=false -Dcoverity=true
+    - cov-analysis-linux64-*/bin/cov-build --dir cov-int  ninja -C coverity-build
+    - tar cfz cov-int.tar.gz cov-int
+    - curl https://scan.coverity.com/builds?project=$CI_PROJECT_NAME
+        --form token=$COVERITY_SCAN_TOKEN --form email=$GITLAB_USER_EMAIL
+        --form file=@cov-int.tar.gz --form version="$(git describe --tags)"
+        --form description="$(git describe --tags) / $CI_COMMIT_TITLE / $CI_COMMIT_REF_NAME:$CI_PIPELINE_ID"
+  artifacts:
+    name: "coverity-submit-data"
+    when: always
+    expire_in: 1 week
+    paths:
+      - cov-int.tar.gz
+  needs:
+    - "debian:stable@container-prep"
+
+#################################################################
+#                                                               #
+#                        distro stage                           #
+#                                                               #
+#################################################################
+
+{% for distro in distributions %}
+{% if not distro.qemu_based %}
+{% for version in distro.versions %}
+{{distro.name}}:{{version}}@default-build:
+  stage: distro
+  extends:
+    - .build@template
+    - .fdo.distribution-image@{{distro.name}}
+  variables:
+    FDO_DISTRIBUTION_VERSION: '{{version}}'
+    FDO_DISTRIBUTION_TAG: ${{distro.name.upper()}}_TAG
+    {# Where we have extra_variables defined, add them to the list #}
+    {% if distro.build is defined and distro.build.extra_variables is defined %}
+    {% for var in distro.build.extra_variables %}
+    {{var}}
+    {% endfor %}
+    {% endif %}
+  needs:
+    - "{{distro.name}}:{{version}}@container-prep"
+
+
+{% endfor %}
+{% else %}
+{% set version = "{}".format(distro.versions|last()) %}
+{{distro.name}}:{{version}}@default-build:
+  stage: distro
+  extends:
+    - .build-in-qemu@template
+    - .fdo.distribution-image@{{distro.name}}
+  variables:
+    FDO_DISTRIBUTION_VERSION: '{{version}}'
+    FDO_DISTRIBUTION_TAG: ${{distro.name.upper()}}_TAG
+    {# Where we have extra_variables defined, add them to the list #}
+    {% if distro.build is defined and distro.build.extra_variables is defined %}
+    {% for var in distro.build.extra_variables %}
+    {{var}}
+    {% endfor %}
+    {% endif %}
+  needs:
+    - "{{distro.name}}:{{version}}@container-prep"
+
+{% endif %}
+{% endfor %}
+
+#################################################################
+#                                                               #
+#                        deploy stage                           #
+#                                                               #
+#################################################################
+
+{% for distro in distributions if distro.name == "fedora" %}
+{% set version = "{}".format(distro.versions|last()) %}
+build rpm:
+  extends:
+    - .fdo.distribution-image@fedora
+    - .policy
+    - .fdo-runner-tags
+  stage: deploy
+  variables:
+    FDO_DISTRIBUTION_VERSION: '{{version}}'
+    FDO_DISTRIBUTION_TAG: $FEDORA_TAG
+  needs:
+    - "fedora:{{version}}@container-prep"
+  script:
+    - meson "$MESON_BUILDDIR"
+    - VERSION=$(meson introspect "$MESON_BUILDDIR" --projectinfo | jq -r .version)
+    - sed -e "s/@PIPELINEID@/${CI_PIPELINE_ID}/"
+          -e "s/@GITVERSION@/${CI_COMMIT_SHA}/"
+          -e "s/@VERSION@/${VERSION}/" .gitlab-ci/libinput.spec.in > libinput.spec
+    - git config --local user.name 'gitlab CI'
+    - git config --local user.email 'noreply@nowhere'
+    - git add libinput.spec && git commit -m 'Add libinput.spec for build testing' libinput.spec
+    - cd "$MESON_BUILDDIR"
+    - meson dist --no-test
+    - rpmbuild -ta meson-dist/libinput*.tar.xz
+{% endfor %}
+
+
+wayland-web:
+  stage: deploy
+  trigger: wayland/wayland.freedesktop.org
+  variables:
+    MESON_ARGS: '-Ddocumentation=true -Ddebug-gui=false -Dlibwacom=false -Dtests=false'
+    MESON_BUILDDIR: 'builddir'
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule"'
+      when: never
+    - if: '$CI_COMMIT_BRANCH == "main" && $GITLAB_USER_LOGIN != "marge-bot" && $CI_PROJECT_PATH == $FDO_UPSTREAM_REPO'
+      when: on_success
+    - when: never

.gitlab-ci/config.yml

@@ -0,0 +1,217 @@
+# This file contains the configuration for the gitlab ci.
+# See the .gitlab-ci/generate-gitlab-ci.py file for more info
+#
+
+# We're happy to rebuild all containers when one changes.
+.default_tag: &default_tag '2026-01-09.0'
+
+distributions:
+  - name: fedora
+    tag: *default_tag
+    versions:
+      - '42'
+      - '43'
+    use_for_custom_build_tests: true
+    use_for_qemu_tests: true
+    packages:
+      - git-core
+      - gcc
+      - gcc-c++
+      - pkgconf-pkg-config
+      - meson
+      - check-devel
+      - libudev-devel
+      - libevdev-devel
+      - doxygen
+      - graphviz
+      - python3-sphinx
+      - python3-recommonmark
+      - python3-sphinx_rtd_theme
+      - python3-pytest-xdist
+      - libwacom-devel
+      - cairo-devel
+      - gtk4-devel
+      - glib2-devel
+      - mtdev-devel
+      - diffutils
+      - wayland-protocols-devel
+      - black           # for the Python black job, optional
+      - clang           # for the clang-tidy build, optional
+      - clang-tools-extra  # for clang-tidy, optional
+      - jq              # for the test suite check job, optional
+      - rpmdevtools     # for the rpm build job, optional
+      - valgrind        # for the valgrind run, optional
+      # below packages are for the qemu runs, so optional
+      - systemd-udev    # for the qemu run
+      - qemu-img
+      - qemu-system-x86-core
+      - qemu-system-aarch64-core
+      - jq
+      - python3-click
+      - python3-rich
+      - virtme-ng
+      - lua-devel
+  - name: debian
+    tag: *default_tag
+    versions:
+      - 'stable'
+    packages:
+      - git
+      - gcc
+      - g++
+      - pkg-config
+      - meson
+      - check
+      - libudev-dev
+      - libevdev-dev
+      - doxygen
+      - graphviz
+      - python3-sphinx
+      - python3-recommonmark
+      - python3-sphinx-rtd-theme
+      - python3-pytest-xdist
+      - libwacom-dev
+      - libcairo2-dev
+      - libgtk-3-dev
+      - libglib2.0-dev
+      - libmtdev-dev
+      - curl            # for the coverity job
+      - lua5.4-dev
+  - name: ubuntu
+    tag: *default_tag
+    versions:
+      - '25.10'
+    packages:
+      - git
+      - gcc
+      - g++
+      - pkg-config
+      - meson
+      - check
+      - libudev-dev
+      - libevdev-dev
+      - doxygen
+      - graphviz
+      - python3-sphinx
+      - python3-recommonmark
+      - python3-sphinx-rtd-theme
+      - python3-pytest-xdist
+      - libwacom-dev
+      - libcairo2-dev
+      - libgtk-3-dev
+      - libglib2.0-dev
+      - libmtdev-dev
+      - lua5.4-dev
+  - name: arch
+    tag: *default_tag
+    versions:
+      - 'rolling'
+    packages:
+      - git
+      - gcc
+      - pkgconfig
+      - meson
+      - check
+      - libsystemd
+      - libevdev
+      - python-pytest-xdist
+      - libwacom
+      - gtk4
+      - mtdev
+      - diffutils
+      - lua
+    build:
+      extra_variables:
+        - "MESON_ARGS: '-Ddocumentation=false'" # python-recommonmark is no longer in the repos
+  - name: alpine
+    tag: *default_tag
+    versions:
+      - 'latest'
+    packages:
+      - git
+      - gcc build-base
+      - pkgconfig
+      - meson
+      - check-dev
+      - eudev-dev
+      - libevdev-dev
+      - libwacom-dev
+      - cairo-dev
+      - gtk4.0-dev
+      - mtdev-dev
+      - bash
+      - lua5.4-dev
+    build:
+      extra_variables:
+        - "MESON_ARGS: '-Ddocumentation=false' # alpine does not have python-recommonmark"
+        # We don't run the tests on alpine. The litest-selftest fails
+        # for any tcase_add_exit_test/tcase_add_test_raise_signal
+        # but someone more invested in musl will have to figure that out.
+        - "MESON_TEST_ARGS: '' # litest-selftest fails on musl"
+
+test_suites:
+  - name: touchpad
+    suites:
+      - touchpad
+  - name: touchpad_palm
+    suites:
+      - touchpad_palm
+  - name: touchpad_dwt
+    suites:
+      - touchpad_dwt
+  - name: tap
+    suites:
+      - touchpad_tap
+  - name: tap-drag
+    suites:
+      - touchpad_tap_drag
+  - name: tap-palm
+    suites:
+      - touchpad_tap_palm
+  - name: touchpad-buttons
+    suites:
+      - touchpad_buttons
+  - name: tablet
+    suites:
+      - tablet
+  - name: tablet_left_handed
+    suites:
+      - tablet_left_handed
+  - name: tablet_proximity_tip
+    suites:
+      - tablet_proximity
+      - tablet_tip
+  - name: tablet_eraser
+    suites:
+      - tablet_eraser
+  - name: gestures
+    suites:
+      - gestures
+  - name: backends
+    suites:
+      - path
+      - udev
+  - name: misc
+    suites:
+      - log
+      - misc
+      - quirks
+      - device
+  - name: other devices
+    suites:
+      - keyboard
+      - pad
+      - switch
+      - trackball
+      - trackpoint
+      - totem
+      - touch
+  - name: pointer
+    suites:
+      - pointer
+  - name: lua
+    suites:
+      - lua
+
+vng:
+  kernel: https://gitlab.freedesktop.org/api/v4/projects/libevdev%2Fhid-tools/packages/generic/kernel-x86_64/v6.14/bzImage

.gitlab-ci/libinput.spec.in

@@ -0,0 +1,149 @@
+# This specfile should not be used outside the CI
+# Its main purpose is to sound alarm if files disappear or are added that
+# weren't intended.
+
+%global udevdir %(pkg-config --variable=udevdir udev)
+
+%global pipelineid @PIPELINEID@
+%global gitversion @GITVERSION@
+
+Name:           libinput
+Version:        @VERSION@
+Release:        %{pipelineid}git%{gitversion}%{?dist}
+Summary:        Input device library
+
+License:        MIT
+URL:            http://www.freedesktop.org/wiki/Software/libinput/
+Source0:        %{name}-%{version}.tar.xz
+
+# No BuildRequires, we rely on the container setup to have
+# all the requires installed
+
+%description
+libinput is a library that handles input devices for display servers and other
+applications that need to directly deal with input devices.
+
+It provides device detection, device handling, input device event processing
+and abstraction so minimize the amount of custom input code the user of
+libinput need to provide the common set of functionality that users expect.
+
+
+%package        devel
+Summary:        Development files for %{name}
+Requires:       %{name}%{?_isa} = %{version}-%{release}
+
+%description    devel
+The %{name}-devel package contains libraries and header files for
+developing applications that use %{name}.
+
+%package        utils
+Summary:        Utilities and tools for debugging %{name}
+Requires:       %{name}%{?_isa} = %{version}-%{release}
+Requires:       python3-pyudev python3-libevdev
+
+%description    utils
+The %{name}-utils package contains tools to debug hardware and analyze
+%{name}.
+
+%package        test
+Summary:        libinput integration test suite
+Requires:       %{name}%{?_isa} = %{version}-%{release}
+
+%description    test
+The %{name}-test package contains the libinput test suite. It is not
+intended to be run by users.
+
+%prep
+%autosetup -S git -n %{name}-%{version}
+
+%build
+%meson -Dtests=true \
+       -Dinstall-tests=true \
+       -Dudev-dir=%{udevdir}
+%meson_build
+
+%install
+%meson_install
+
+%post
+%{?ldconfig}
+
+%ldconfig_postun
+
+
+%files
+%doc COPYING
+%dir %{_sysconfdir}/libinput
+%{_libdir}/libinput.so.*
+%{udevdir}/libinput-device-group
+%{udevdir}/libinput-fuzz-extract
+%{udevdir}/libinput-fuzz-to-zero
+%{udevdir}/rules.d/80-libinput-device-groups.rules
+%{udevdir}/rules.d/90-libinput-fuzz-override.rules
+%{_bindir}/libinput
+%dir %{_libexecdir}/libinput/
+%{_libexecdir}/libinput/libinput-debug-events
+%{_libexecdir}/libinput/libinput-list-devices
+%{_mandir}/man1/libinput.1*
+%{_datadir}/libinput/*.quirks
+%dir %{_datadir}/zsh
+%dir %{_datadir}/zsh/site-functions
+%{_datadir}/zsh/site-functions/*
+%{_mandir}/man1/libinput-list-devices.1*
+%{_mandir}/man1/libinput-debug-events.1*
+
+%files devel
+%{_includedir}/libinput.h
+%{_libdir}/libinput.so
+%{_libdir}/pkgconfig/libinput.pc
+
+%files utils
+%{_libexecdir}/libinput/libinput-debug-gui
+%{_libexecdir}/libinput/libinput-debug-tablet
+%{_libexecdir}/libinput/libinput-debug-tablet-pad
+%{_libexecdir}/libinput/libinput-list-kernel-devices
+%{_libexecdir}/libinput/libinput-measure
+%{_libexecdir}/libinput/libinput-measure-fuzz
+%{_libexecdir}/libinput/libinput-measure-touchpad-tap
+%{_libexecdir}/libinput/libinput-measure-touchpad-pressure
+%{_libexecdir}/libinput/libinput-measure-touch-size
+%{_libexecdir}/libinput/libinput-measure-touchpad-size
+%{_libexecdir}/libinput/libinput-quirks
+%{_libexecdir}/libinput/libinput-record
+%{_libexecdir}/libinput/libinput-replay
+%{_libexecdir}/libinput/libinput-analyze
+%{_libexecdir}/libinput/libinput-analyze-buttons
+%{_libexecdir}/libinput/libinput-analyze-per-slot-delta
+%{_libexecdir}/libinput/libinput-analyze-recording
+%{_libexecdir}/libinput/libinput-analyze-touch-down-state
+%{_mandir}/man1/libinput-debug-gui.1*
+%{_mandir}/man1/libinput-debug-tablet.1*
+%{_mandir}/man1/libinput-debug-tablet-pad.1*
+%{_mandir}/man1/libinput-list-kernel-devices.1*
+%{_mandir}/man1/libinput-measure.1*
+%{_mandir}/man1/libinput-measure-fuzz.1*
+%{_mandir}/man1/libinput-measure-touchpad-tap.1*
+%{_mandir}/man1/libinput-measure-touch-size.1*
+%{_mandir}/man1/libinput-measure-touchpad-size.1*
+%{_mandir}/man1/libinput-measure-touchpad-pressure.1*
+%{_mandir}/man1/libinput-quirks.1*
+%{_mandir}/man1/libinput-quirks-list.1*
+%{_mandir}/man1/libinput-quirks-validate.1*
+%{_mandir}/man1/libinput-record.1*
+%{_mandir}/man1/libinput-replay.1*
+%{_mandir}/man1/libinput-analyze.1*
+%{_mandir}/man1/libinput-analyze-buttons.1*
+%{_mandir}/man1/libinput-analyze-per-slot-delta.1*
+%{_mandir}/man1/libinput-analyze-recording.1*
+%{_mandir}/man1/libinput-analyze-touch-down-state.1*
+
+%files test
+%{_libexecdir}/libinput/libinput-test
+%{_libexecdir}/libinput/libinput-test-suite
+%{_libexecdir}/libinput/libinput-test-utils
+%{_mandir}/man1/libinput-test.1*
+%{_mandir}/man1/libinput-test-suite.1*
+
+%changelog
+* Wed Jul 15 2020 Peter Hutterer <peter.hutterer@redhat.com>
+- Add basic spec file for package build testing

.gitlab-ci/meson-build.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+#
+# This script is sourced from here:
+# https://gitlab.freedesktop.org/whot/meson-helper
+#
+# SPDX-License-Identifier: MIT
+
+set -x
+if [[ -f .meson_environment ]]; then
+	. .meson_environment
+fi
+
+# If test args are set, we assume we want to run the tests
+MESON_RUN_TEST="$MESON_TEST_ARGS"
+
+while [[ $# -gt 0 ]]; do
+	case $1 in
+		--skip-setup)
+			shift
+			MESON_SKIP_SETUP="1"
+			;;
+		--skip-build)
+			shift
+			MESON_SKIP_BUILD="1"
+			;;
+		--skip-test)
+			shift
+			MESON_RUN_TEST=""
+			;;
+		--run-test)
+			shift
+			MESON_RUN_TEST="1"
+			;;
+		*)
+			echo "Unknow commandline argument $1"
+			exit 1
+			;;
+	esac
+done
+
+if [[ -z "$MESON_BUILDDIR" ]]; then
+	echo "\$MESON_BUILDDIR undefined."
+	exit 1
+fi
+
+# emulate a few gitlab variables to make it easier to
+# run and debug locally.
+if [[ -z "$CI_JOB_ID" ]] || [[ -z "$CI_JOB_NAME" ]]; then
+	echo "Missing \$CI_JOB_ID or \$CI_JOB_NAME".
+	CI_PROJECT_NAME=$(basename "$PWD")
+	CI_JOB_ID=$(date +%s)
+	CI_JOB_NAME="$CI_PROJECT_NAME-job-local"
+	echo "Simulating gitlab environment: "
+	echo " CI_JOB_ID=$CI_JOB_ID"
+	echo " CI_JOB_NAME=$CI_JOB_NAME"
+fi
+
+if [[ -n "$FDO_CI_CONCURRENT" ]]; then
+	jobcount="-j$FDO_CI_CONCURRENT"
+	export MESON_TESTTHREADS="$FDO_CI_CONCURRENT"
+fi
+
+echo "*************************************************"
+echo "builddir: $MESON_BUILDDIR"
+echo "meson args: $MESON_ARGS"
+echo "ninja args: $NINJA_ARGS"
+echo "meson test args: $MESON_TEST_ARGS"
+echo "job count: ${jobcount-0}"
+echo "*************************************************"
+
+set -e
+
+if [[ -z "$MESON_SKIP_SETUP" ]]; then
+	rm -rf "$MESON_BUILDDIR"
+	meson setup "$MESON_BUILDDIR" $MESON_ARGS
+fi
+meson configure "$MESON_BUILDDIR"
+
+if [[ -z "$MESON_SKIP_BUILD" ]]; then
+	if [[ -n "$NINJA_ARGS" ]]; then
+		ninja_args="--ninja-args $NINJA_ARGS"
+	fi
+	meson compile -v -C "$MESON_BUILDDIR" $jobcount $ninja_args
+fi
+
+if [[ -n "$MESON_RUN_TEST" ]]; then
+	meson test -C "$MESON_BUILDDIR" $MESON_TEST_ARGS --print-errorlogs
+fi

.gitlab-ci/scanbuild-wrapper.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+scan-build -v --status-bugs -plist-html "$@"

.gitlab-ci/whitespace-check.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+
+from pathlib import Path
+from dataclasses import dataclass
+
+import argparse
+import itertools
+import os
+import sys
+
+
+@dataclass
+class WhitespaceError:
+    message: str
+    lineno: int
+    nlines: int = 1
+    column: None | int = None
+    ncolumns: int = 1
+
+
+def test_duplicate_empty_lines(lines: list[str]) -> list[WhitespaceError]:
+    errors = []
+    for idx, (l1, l2) in enumerate(itertools.pairwise(lines)):
+        if not l1 and not l2:
+            errors.append(WhitespaceError("Duplicated empty lines", idx, nlines=2))
+    return errors
+
+
+def test_tab_after_space(lines: list[str]) -> list[WhitespaceError]:
+    errors = []
+    for idx, l in enumerate(lines):
+        index = l.find(" \t")
+        if index > -1:
+            errors.append(
+                WhitespaceError(
+                    "Tab after space", idx, nlines=index, column=index, ncolumns=2
+                )
+            )
+    return errors
+
+
+def test_trailing_whitespace(lines: list[str]) -> list[WhitespaceError]:
+    errors = []
+    for idx, l in enumerate(lines):
+        if l.rstrip() != l:
+            errors.append(WhitespaceError("Trailing whitespace", idx))
+    return errors
+
+
+def test_empty_line_between_braces(lines: list[str]) -> list[WhitespaceError]:
+    errors = []
+    for idx in range(len(lines) - 3):
+        l1 = lines[idx]
+        l2 = lines[idx + 1]
+        l3 = lines[idx + 2]
+        if l1.strip() == "}" and l3.strip() == "}" and l2.strip() == "":
+            errors.append(WhitespaceError("Empty line between closing braces", idx + 1))
+    return errors
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Whitespace checker script")
+    parser.add_argument(
+        "files",
+        metavar="FILES",
+        type=Path,
+        nargs="+",
+        help="The files to check",
+    )
+
+    args = parser.parse_args()
+
+    have_errors: bool = False
+
+    if os.isatty(sys.stderr.fileno()):
+        red = "\x1b[0;31m"
+        reset = "\x1b[0m"
+    else:
+        red = ""
+        reset = ""
+
+    for file in args.files:
+        lines = [l.rstrip("\n") for l in file.open().readlines()]
+
+        errors = []
+        errors.extend(test_tab_after_space(lines))
+        errors.extend(test_trailing_whitespace(lines))
+        if any(file.name.endswith(suffix) for suffix in [".c", ".h"]):
+            if not file.parts[0] == "include":
+                errors.extend(test_duplicate_empty_lines(lines))
+                errors.extend(test_empty_line_between_braces(lines))
+
+        for e in errors:
+            print(f"{red}ERROR: {e.message} in {file}:{reset}", file=sys.stderr)
+            print(f"{'-' * 72}", file=sys.stderr)
+            lineno = max(0, e.lineno - 5)
+            for idx, l in enumerate(lines[lineno : lineno + 10]):
+                if e.lineno <= lineno + idx < e.lineno + e.nlines:
+                    prefix = "->"
+                    hl = red
+                    nohl = reset
+                else:
+                    prefix = "  "
+                    hl = ""
+                    nohl = ""
+                print(f"{hl}{lineno + idx:3d}: {prefix} {l.rstrip()}{nohl}")
+
+            print(f"{'-' * 72}", file=sys.stderr)
+
+        if errors:
+            have_errors = True
+
+    if have_errors:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

.gitlab/issue_templates/FeatureRequest.md

@@ -0,0 +1,32 @@
+<!--
+
+Before your file a feature request, please read
+
+https://wayland.freedesktop.org/libinput/doc/latest/what-is-libinput.html
+
+The amount of developer time libinput has available is very small.
+Requesting a feature is no guarantee that it will get implemented. Someone
+(you!) needs to step up to do the work.
+
+-->
+
+## Summary
+
+<!-- Summarize the requested feature in a few sentences.  -->
+
+## Feature details
+
+<!-- A step-by-step list of what the feature should achieve (where applicable) -->
+
+## Affected Hardware
+
+<!-- Which hardware types would be affected by this -->
+
+## Implementation in Other Systems
+
+<!-- Does this feature already exist elsewhere? How does it work there? Try
+to provide as many details as possible -->
+
+
+
+/label ~enhancement ~"needs triage"

.gitlab/issue_templates/default.md

@@ -0,0 +1,35 @@
+## Summary
+
+<!--
+Summarize the bug encountered concisely. See
+https://wayland.freedesktop.org/libinput/doc/latest/reporting-bugs.html for
+detailed instructions to report bugs
+-->
+
+## Steps to reproduce
+
+<!-- How to reproduce the issue on a developer machine - this is very important -->
+
+## Required information
+
+<!-- Note: if your libinput version is older than the current stable version,
+please reproduce with a current version instead -->
+
+- libinput version:
+- hardware information:
+- `libinput record` output: do not paste, **attach** the file
+- `libinput debug-events --verbose` output: do not paste, **attach the file**
+
+<!--
+
+Paste any other relevant logs - please use code blocks (```) to format
+console output, logs, and code as it's very hard to read otherwise.)
+
+Do not paste logs longer than 10 lines, **attach** those instead.
+
+If your libinput record is longer than 5-10s, we will not be able to process
+it.
+
+-->
+
+/label ~"bug" ~"needs triage"

.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: end-of-file-fixer
+  - id: trailing-whitespace
+  - id: no-commit-to-branch
+    args: ['--branch', 'main']
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.12.2
+  hooks:
+  - id: ruff-check
+    args: ['--ignore=E741,E501', '--extend-exclude=subprojects', '.']
+  - id: ruff-format
+    args: ['--check', '--diff']
+- repo: https://gitlab.freedesktop.org/freedesktop/ci-templates.git
+  rev: e195d80f35b45cc73668be3767b923fd76c70ed5
+  hooks:
+  - id: check-commits
+  - id: generate-template
+- repo: local
+  hooks:
+  - id: run-sed-script
+    name: Check for whitespace errors
+    entry: ./.gitlab-ci/whitespace-check.py
+    language: system
+- repo: https://github.com/pre-commit/mirrors-clang-format
+  rev: v20.1.6
+  hooks:
+  - id: clang-format
+    types_or: [c]

.triage-policies.yml

@@ -0,0 +1,244 @@
+# This is a set of bugbot commands for issues and merge requests - setting any of the
+# bugbot::foo labels will trigger gitlab-triage to run with this ruleset (well, the
+# one we have on the main branch at the time)
+#
+# Note that for adding labels, the label must first created in the project.
+
+# Re-used in issues and mrs
+.close_needinfo: &close_needinfo
+  name: "Close stale needinfo bugs"
+  conditions:
+    labels:
+      - "bugbot::needinfo-timeout"
+  actions:
+    remove_labels:
+      - "bugbot::needinfo-timeout"
+    comment: |
+      I'm closing this bug because some information we requested a while ago was never supplied and
+      we're not able to continue without this information.
+      Please feel free to re-open.
+    status: "close"
+
+.remind_needinfo: &remind_needinfo
+  name: "Remind users of needinfo bugs"
+  conditions:
+    labels:
+      - "bugbot::needinfo-reminder"
+  actions:
+    labels:
+      - "waiting on reporter"
+    remove_labels:
+      - "bugbot::needinfo-reminder"
+    comment: |
+      Hi. This is a friendly reminder that the maintainers are waiting on some information by
+      you (or maybe someone cc'd on this bug). If the information is not provided we may not
+      be able to proceed with this issue or merge request. Please check the recent comments, thanks.
+
+.help_needed: &help_needed
+  name: "Remind users help is needed"
+  conditions:
+    labels:
+      - "bugbot::help-needed"
+  actions:
+    labels:
+      - "help needed"
+    remove_labels:
+      - "bugbot::help-needed"
+    comment: |
+      Hi. This issue or merge request needs help. This simply means that for
+      the foreseeable future, the maintainers will not have time to work on
+      this.
+
+      If this is a request for a new feature, then the feature is unlikely to
+      be implemented unless you or another contributor files a merge request.
+      If a merge request already exists maybe it needs finishing which often
+      involves adding documentation or tests.
+
+      If this is an issue affecting a specific device then it is unlikely to be
+      fixed. This may be because it requires specific hardware to reproduce or
+      it may be that the use case is niche enough that the maintainers do not
+      have time to implement it.
+
+      In short, to resolve this issue or get this merge request into libinput
+      help is needed.
+
+.libinput_record: &libinput_record
+  name: "Request libinput record output"
+  conditions:
+    labels:
+      - "bugbot::libinput-record"
+  actions:
+    remove_labels:
+      - "bugbot::libinput-record"
+    comment: |
+      Looks like we may need some extra information. Please **attach** (do not paste) the full output
+      of `libinput record` and `libinput debug-events --verbose` (if you haven't yet).
+      The [documentation](https://wayland.freedesktop.org/libinput/doc/latest/tools.html#libinput-record-and-libinput-replay)
+      has some information on what we're looking for to be able to triage bugs.
+
+.hid_recorder: &hid_recorder
+  name: "Request hid-recorder output"
+  conditions:
+    labels:
+      - "bugbot::hid-recorder"
+  actions:
+    remove_labels:
+      - "bugbot::hid-recorder"
+    comment: |
+      Looks like we may need some extra information that isn't yet available in this issue.
+      Please **attach** (do not paste) the output of [`hid-recorder`](https://github.com/hidutils/hid-recorder/)
+      for this device (run `sudo hid-recorder` without argument and it will let you pick the device).
+      This should show the data the kernel receives from the device and may provide a hint on what's going on here.
+
+.udev_hid_bpf: &udev_hid_bpf
+  name: "Punt to udev-hid-bpf"
+  conditions:
+    labels:
+      - "bugbot::udev-hid-bpf"
+  actions:
+    remove_labels:
+      - "bugbot::udev-hid-bpf"
+    comment: |
+      This issue looks like it could or should be fixed with [udev-hid-bpf](https://gitlab.freedesktop.org/libevdev/udev-hid-bpf/).
+      udev-hid-bpf is a collection of BPF programs that modify the HID Report Descriptor and/or HID Reports from the device,
+      making it possible to change the properties of a device and/or the events to make them compatible with the
+      expectations the kernel and userspace has of such devices.
+
+      Please see the [udev-hid-bpf documentation](https://libevdev.pages.freedesktop.org/udev-hid-bpf/) for details
+      and/or in particular the [udev-hid-bpf tutorial](https://libevdev.pages.freedesktop.org/udev-hid-bpf/tutorial.html)
+      if you need to enable a new device.
+    status: "close"
+
+resource_rules:
+  issues:
+    rules:
+      - name: "Close kernel bugs"
+        conditions:
+          labels:
+            - "bugbot::kernel"
+        actions:
+          labels:
+            - "kernel"
+          remove_labels:
+            - "bugbot::kernel"
+          comment: |
+            This bug looks like a kernel issue and it cannot be fixed
+            in libinput directly. I'm closing this bug but do feel free
+            to continue discussing the issue here.
+
+            Kernel bugs are usually best sent to the [`linux-input` list](https://lore.kernel.org/linux-input/).
+          status: "close"
+      - name: "Expect a merge request"
+        conditions:
+          labels:
+            - "bugbot::expect-mr"
+        actions:
+          remove_labels:
+            - "bugbot::expect-mr"
+          comment: |
+            I'm closing this bug in anticipation of a merge request that fixes this issue.
+
+            If you are a new contributor, please see
+            [the freedesktop.org wiki](https://gitlab.freedesktop.org/freedesktop/freedesktop/-/wikis/home)
+            on how to get permissions to fork a project and file a merge request.
+
+            The [libinput documentation](https://wayland.freedesktop.org/libinput/doc/latest/contributing.html)
+            also has more details on how to get started.
+          status: "close"
+      - name: "Point to 60-evdev.hwdb"
+        conditions:
+          labels:
+            - "bugbot::evdev-hwdb"
+        actions:
+          remove_labels:
+            - "bugbot::evdev-hwdb"
+          comment: |
+            Looks like this issue may be solved with a device-specific entry in systemd's hwdb.
+
+            You should have a /usr/lib/udev/hwdb.d/60-evdev.hwdb file which includes those quirks. Please see
+            the top of the file for instructions and follow those. Once the quirk is confirmed working
+            this issue (or parts thereof) should be fixed and you can submit a pull request to the
+            [systemd](https://github.com/systemd/systemd/) repository to get that quirk included.
+            Please link to the systemd issue here, thanks.
+
+            I'm closing this issue now, if the hwdb entry does not fix this issue here, please re-open.
+          status: "close"
+      - name: "Close bug for reopening"
+        conditions:
+          labels:
+            - "bugbot::close"
+        actions:
+          remove_labels:
+            - "bugbot::close"
+          comment: |
+            I'm temporarily closing this bug. The bug may not be fixed yet (see any comments above)
+            and we **want you to reopen it when/if it becomes actionable again**.
+
+            This process may feel unfamiliar but unfortunately closing/re-opening is the only action
+            all GitLab users are permitted to do. So we close it, you re-open it when whatever
+            above has been addressed and then we know we need to look at it again.
+            This issue may be closed more than once in a similar fashion but I only leave this
+            comment once since now you understand how it works. :smile:
+
+            For a detailed explanation on the how and why of this process please see
+            the [Closed Issues wiki page](https://gitlab.freedesktop.org/libinput/libinput/-/wikis/Closed-Issues).
+          status: "close"
+      - name: "Re-close bug for reopening"
+        conditions:
+          labels:
+            - "bugbot::re-close"
+        actions:
+          remove_labels:
+            - "bugbot::re-close"
+          comment: |
+            I'm temporarily closing this bug again. This is not a final close, see my comments above for the open/close process.
+          status: "close"
+      - *udev_hid_bpf
+      - *libinput_record
+      - *hid_recorder
+      - *close_needinfo
+      - *remind_needinfo
+      - *help_needed
+  merge_requests:
+    rules:
+      - name: "Remind contributor of commit rules"
+        conditions:
+          labels:
+            - "bugbot::commit-rules"
+        actions:
+          remove_labels:
+            - "bugbot::commit-rules"
+          comment: |
+            Hi. Looks like the pipeline failed because one or more of the commits in this MR do not meet our requirements.
+            Most commonly this the format of the commit message itself. The "Test summary" above has the details.
+
+            Please see [our docs for commit messages](https://wayland.freedesktop.org/libinput/doc/latest/contributing.html#commit-messages)
+            and [our docs for submitting code](https://wayland.freedesktop.org/libinput/doc/latest/contributing.html#submitting-code)
+            that explain how to amend and force-push to this repo.
+      - name: "Remind contributor that info needs to be in commit messages"
+        conditions:
+          labels:
+            - "bugbot::info-in-commit-message"
+        actions:
+          remove_labels:
+            - "bugbot::info-in-commit-message"
+          comment: |
+            Hi. Thanks for the merge request. I'm here to request that you add
+            some documentation about this merge request to the
+            **commit message** (or messages). You may have already written some
+            in the merge request description and in many cases it's fine to
+            copy/paste that into the commit message(s).
+
+            The reason is simple: once merged, no-one really looks at this this
+            page here anymore. The git log on the other hand is what developers
+            will use to understand the code so the information must be quickly
+            accessible via git.
+
+            Please see [our docs for submitting code](https://wayland.freedesktop.org/libinput/doc/latest/contributing.html#submitting-code)
+            that explain how to amend and force-push to this repo.
+      - *udev_hid_bpf
+      - *libinput_record
+      - *hid_recorder
+      - *close_needinfo
+      - *remind_needinfo
+      - *help_needed

CODING_STYLE

@@ -1,117 +0,0 @@
-- Indentation in tabs, 8 characters wide, spaces after the tabs where
-  vertical alignment is required (see below)
-
-- Max line width 80ch, do not break up printed strings though
-
-- Break up long lines at logical groupings, one line for each logical group
-
-  int a = somelongname() +
-  	  someotherlongname();
-
-  if (a < 0 &&
-      (b > 20 & d < 10) &&
-      d != 0.0)
-
-
-  somelongfunctioncall(arg1,
-  		       arg2,
-  		       arg3);
-
-- Function declarations: return type on separate line, {} on separate line,
-  arguments broken up as above.
-
-  static inline int
-  foobar(int a, int b)
-  {
-
-  }
-
-  void
-  somenamethatiswaytoolong(int a,
-  			   int b,
-  			   int c)
-  {
-  }
-
-- /* comments only */, no // comments
-
-- variable_name, not VariableName or variableName. same for functions.
-
-- no typedefs of structs, enums, unions
-
-- if it generates a compiler warning, it needs to be fixed
-- if it generates a static checker warning, it needs to be fixed or
-  commented
-
-- declare variables at the top, try to keep them as local as possible.
-  Exception: if the same variable is re-used in multiple blocks, declare it
-  at the top.
-  Exception: basic loop variables, e.g. for (int i = 0; ...)
-
-  int a;
-  int c;
-
-  if (foo) {
-  	int b;
-
-  	c = get_value();
-  	usevalue(c);
-  }
-
-  if (bar) {
-  	c = get_value();
-  	useit(c);
-  }
-
-- do not mix function invocations and variable definitions.
-
-  wrong:
-
-  {
-  	  int a = foo();
-  	  int b = 7;
-  }
-
-  right:
-  {
-  	  int a;
-  	  int b = 7;
-
-  	  a = foo();
-  }
-
-  There are exceptions here, e.g. tp_libinput_context(),
-  litest_current_device()
-
-- if/else: { on the same line, no curly braces if both blocks are a single
-  statement. If either if or else block are multiple statements, both must
-  have curly braces.
-
-  if (foo) {
-  	blah();
-  	bar();
-  } else {
-  	a = 10;
-  }
-
-- public functions MUST be doxygen-commented, use doxygen's @foo rather than
-  \foo notation
-
-- include "config.h" comes first, followed by system headers, followed by
-  external library headers, followed by internal headers.
-  sort alphabetically where it makes sense (specifically system headers)
-
-  #include "config.h"
-
-  #include <stdio.h>
-  #include <string.h>
-
-  #include <libevdev/libevdev.h>
-
-  #include "libinput-private.h"
-
-- goto jumps only to the end of the function, and only for good reasons
-  (usually cleanup). goto never jumps backwards
-
-- Use stdbool.h's bool for booleans within the library (instead of 'int').
-  Exception: the public API uses int, not bool.

CODING_STYLE.md

@@ -0,0 +1,244 @@
+# Coding style
+
+- Indentation in tabs, 8 characters wide, spaces after the tabs where
+  vertical alignment is required (see below)
+
+**Note: this file uses spaces due to markdown rendering issues for tabs.
+  Code must be implemented using tabs.**
+
+- Max line width 80ch, do not break up printed strings though
+
+- Break up long lines at logical groupings, one line for each logical group
+
+```c
+int a = somelongname() +
+        someotherlongname();
+
+if (a < 0 &&
+    (b > 20 & d < 10) &&
+    d != 0.0)
+
+
+somelongfunctioncall(arg1,
+                     arg2,
+                     arg3);
+```
+
+- Function declarations: return type on separate line, {} on separate line,
+  arguments broken up as above.
+
+```c
+static inline int
+foobar(int a, int b)
+{
+
+}
+
+void
+somenamethatiswaytoolong(int a,
+                         int b,
+                         int c)
+{
+}
+```
+
+- `/* comments only */`, no `// comments`
+
+- `variable_name`, not `VariableName` or `variableName`. same for functions.
+
+- no typedefs of structs, enums, unions
+
+- if it generates a compiler warning, it needs to be fixed
+- if it generates a static checker warning, it needs to be fixed or
+  commented
+
+- declare variables when they are used first and try to keep them as local as possible.
+  Exception: basic loop variables, e.g. for (int i = 0; ...) should always be
+  declared inside the loop even where multiple loops exist
+
+```c
+int a;
+
+if (foo) {
+        int b = 10;
+
+        a = get_value();
+        usevalue(a, b);
+}
+
+if (bar) {
+        a = get_value();
+        useit(a);
+}
+
+int c = a * 100;
+useit(c);
+```
+
+- avoid uninitialized variables where possible, declare them late instead.
+  Note that most of libinput predates this style, try to stick with the code
+  around you if in doubt.
+
+  wrong:
+
+```c
+        int *a;
+        int b = 7;
+
+        ... some code ...
+
+        a = zalloc(32);
+```
+
+  right:
+
+```c
+        int b = 7;
+        ... some code ...
+
+        int *a = zalloc(32);
+```
+
+- avoid calling non-obvious functions inside declaration blocks for multiple
+  variables.
+
+  bad:
+
+```c
+{
+        int a = 7;
+        int b = some_complicated_function();
+        int *c = zalloc(32);
+}
+```
+
+  better:
+```c
+{
+        int a = 7;
+        int *c = zalloc(32);
+
+        int b = some_complicated_function();
+}
+```
+
+  There is a bit of gut-feeling involved with this, but the goal is to make
+  the variable values immediately recognizable.
+
+- Where statements are near-identical and repeated, try to keep them
+  identical:
+
+  bad:
+```c
+int a = get_some_value(x++);
+do_something(a);
+a = get_some_value(x++);
+do_something(a);
+a = get_some_value(x++);
+do_something(a);
+```
+  better:
+
+```c
+int a;
+a = = get_some_value(x++);
+do_something(a);
+a = get_some_value(x++);
+do_something(a);
+a = get_some_value(x++);
+do_something(a);
+```
+
+- if/else: { on the same line, no curly braces if both blocks are a single
+  statement. If either if or else block are multiple statements, both must
+  have curly braces.
+
+```c
+if (foo) {
+        blah();
+        bar();
+} else {
+        a = 10;
+}
+```
+
+- public functions MUST be doxygen-commented, use doxygen's `@foo` rather than
+  `\foo` notation
+
+- `#include "config.h"` comes first, followed by system headers, followed by
+  external library headers, followed by internal headers.
+  sort alphabetically where it makes sense (specifically system headers)
+
+```c
+#include "config.h"
+
+#include <stdio.h>
+#include <string.h>
+
+#include <libevdev/libevdev.h>
+
+#include "libinput-private.h"
+```
+
+- goto jumps only to the end of the function, and only for good reasons
+  (usually cleanup). goto never jumps backwards
+
+- Use stdbool.h's bool for booleans within the library (instead of `int`).
+  Exception: the public API uses int, not bool.
+
+# Git commit message requirements
+
+Our CI will check the commit messages for a few requirements. Below is the
+list of what we expect from a git commit.
+
+## Commit message content
+
+A [good commit message](http://who-t.blogspot.com/2009/12/on-commit-messages.html) needs to
+answer three questions:
+
+- Why is it necessary? It may fix a bug, it may add a feature, it may
+  improve performance, reliabilty, stability, or just be a change for the
+  sake of correctness.
+- How does it address the issue? For short obvious patches this part can be
+  omitted, but it should be a high level description of what the approach
+  was.
+- What effects does the patch have? (In addition to the obvious ones, this
+  may include benchmarks, side effects, etc.)
+
+These three questions establish the context for the actual code changes, put
+reviewers and others into the frame of mind to look at the diff and check if
+the approach chosen was correct. A good commit message also helps
+maintainers to decide if a given patch is suitable for stable branches or
+inclusion in a distribution.
+
+## Commit message format
+
+The canonical git commit message format is:
+
+```
+one line as the subject line with a high-level note
+
+full explanation of the patch follows after an empty line. This explanation
+can be multiple paragraphs and is largely free-form. Markdown is not
+supported.
+
+You can include extra data where required like:
+- benchmark one says 10s
+- benchmark two says 12s
+```
+
+The subject line is the first thing everyone sees about this commit, so make
+sure it's on point.
+
+## Commit message technical requirements
+
+- The commit message should use present tense (not past tense). Do write
+  "change foo to bar", not "changed foo to bar".
+- The text width of the commit should be 78 chars or less, especially the
+  subject line.
+- The author must be the name you usually identify as and email address. We do
+  not accept the default `@users.noreply` gitlab addresses.
+  ```
+  git config --global user.name Your Name
+  git config --global user.email your@email
+  ```

CONTRIBUTING.md

@@ -0,0 +1,4 @@
+Thank you for your interest in contributing to libinput.
+
+Please find more information about how to contribute in
+[the documentation](https://wayland.freedesktop.org/libinput/doc/latest/contributing.html).

COPYING

@@ -31,4 +31,4 @@ This copy is provided to provide consistent behavior regardless which kernel
 version libinput is compiled against. The header is used during compilation
 only, libinput does not link against GPL libraries.
 
-[1] http://cgit.freedesktop.org/wayland/libinput/tree/include/linux/input.h
+[1] https://gitlab.freedesktop.org/libinput/libinput/blob/main/include/linux/input.h

README.md

@@ -5,76 +5,63 @@ libinput is a library that provides a full input stack for display servers
 and other applications that need to handle input devices provided by the
 kernel.
 
-libinput provides device detection, event handling and abstraction so
-minimize the amount of custom input code the user of libinput need to
+libinput provides device detection, event handling and abstraction to
+minimize the amount of custom input code the user of libinput needs to
 provide the common set of functionality that users expect. Input event
 processing includes scaling touch coordinates, generating
 relative pointer events from touchpads, pointer acceleration, etc.
 
-Architecture
-------------
+User documentation
+------------------
 
-libinput is not used directly by applications. Think of it more as a device
-driver than an application library. It is used by the xf86-input-libinput
-X.Org driver or Wayland compositors. The typical software stack for a system
-running Wayland is:
+Documentation explaining features available in libinput is available
+[here](https://wayland.freedesktop.org/libinput/doc/latest/features.html).
 
-@dotfile libinput-stack-wayland.gv
+This includes the [FAQ](https://wayland.freedesktop.org/libinput/doc/latest/faqs.html)
+and the instructions on
+[reporting bugs](https://wayland.freedesktop.org/libinput/doc/latest/reporting-bugs.html).
 
-The Wayland compositor may be Weston, mutter, KWin, etc. Note that
-Wayland encourages the use of toolkits, so the Wayland client (your
-application) does not usually talk directly to the compositor but rather
-employs a toolkit (e.g. GTK) to do so. The Wayland client does not know
-whether libinput is in use.
-
-The simplified software stack for a system running X.Org is:
-
-@dotfile libinput-stack-xorg.gv
-
-libinput is not employed directly by the X server but by the
-xf86-input-libinput driver instead. That driver is loaded by the server
-on demand, depending on the xorg.conf.d configuration snippets. The X client
-does not know whether libinput is in use.
 
 Source code
 -----------
 
 The source code of libinput can be found at:
-http://cgit.freedesktop.org/wayland/libinput
+https://gitlab.freedesktop.org/libinput/libinput
 
 For a list of current and past releases visit:
-http://www.freedesktop.org/wiki/Software/libinput/
+https://www.freedesktop.org/wiki/Software/libinput/
 
 Build instructions:
-http://wayland.freedesktop.org/libinput/doc/latest/building_libinput.html
+https://wayland.freedesktop.org/libinput/doc/latest/building.html
 
 Reporting Bugs
 --------------
 
-Bugs can be filed in the libinput component of Wayland:
-https://bugs.freedesktop.org/enter_bug.cgi?product=Wayland&component=libinput
+Bugs can be filed on freedesktop.org GitLab:
+https://gitlab.freedesktop.org/libinput/libinput/issues/
 
 Where possible, please provide the `libinput record` output
 of the input device and/or the event sequence in question.
 
-See @ref reporting_bugs for more info.
+See https://wayland.freedesktop.org/libinput/doc/latest/reporting-bugs.html
+for more info.
 
 Documentation
 -------------
 
-- Developer API documentation: http://wayland.freedesktop.org/libinput/doc/latest/modules.html
+- Developer API documentation: https://wayland.freedesktop.org/libinput/doc/latest/development.html
 - High-level documentation about libinput's features:
-http://wayland.freedesktop.org/libinput/doc/latest/pages.html
+  https://wayland.freedesktop.org/libinput/doc/latest/features.html
 - Build instructions:
-http://wayland.freedesktop.org/libinput/doc/latest/building_libinput.html
+  https://wayland.freedesktop.org/libinput/doc/latest/building.html
 - Documentation for previous versions of libinput: https://wayland.freedesktop.org/libinput/doc/
 
 Examples of how to use libinput are the debugging tools in the libinput
 repository. Developers are encouraged to look at those tools for a
 real-world (yet simple) example on how to use libinput.
 
-- A commandline debugging tool: https://cgit.freedesktop.org/wayland/libinput/tree/tools/libinput-debug-events.c
-- A GTK application that draws cursor/touch/tablet positions: https://cgit.freedesktop.org/wayland/libinput/tree/tools/libinput-debug-gui.c
+- A commandline debugging tool: https://gitlab.freedesktop.org/libinput/libinput/tree/main/tools/libinput-debug-events.c
+- A GTK application that draws cursor/touch/tablet positions: https://gitlab.freedesktop.org/libinput/libinput/tree/main/tools/libinput-debug-gui.c
 
 License
 -------
@@ -88,5 +75,10 @@ libinput is licensed under the MIT license.
 > and/or sell copies of the Software, and to permit persons to whom the
 > Software is furnished to do so, subject to the following conditions: [...]
 
-See the [COPYING](http://cgit.freedesktop.org/wayland/libinput/tree/COPYING)
+See the [COPYING](https://gitlab.freedesktop.org/libinput/libinput/tree/main/COPYING)
 file for the full license information.
+
+About
+-----
+
+Documentation generated from git commit [__GIT_VERSION__](https://gitlab.freedesktop.org/libinput/libinput/commit/__GIT_VERSION__)

circle.yml

@@ -1,144 +0,0 @@
-# vim: set expandtab shiftwidth=2 tabstop=8 textwidth=0:
-
-libinput_jobs:
-  default_settings: &default_settings
-    working_directory: ~/libinput
-  # Define a couple of standardized build targets
-  # that we call from every build container
-  build_and_test_default: &build_and_test_default
-    name: Build
-    command: |
-      rm -rf build
-      meson build ${MESON_PARAMS}
-      meson configure build
-      ninja -v -C build ${NINJA_ARGS}
-    environment:
-      MESON_PARAMS: --prefix=/opt/libinput
-  build_and_test: &build_and_test
-    run:
-      <<: *build_and_test_default
-  build_no_libwacom: &build_no_libwacom
-    run:
-      <<: *build_and_test_default
-      name: Build - No libwacom
-      environment:
-        MESON_PARAMS: -Dlibwacom=false
-  build_no_debug_gui: &build_no_debug_gui
-    run:
-      <<: *build_and_test_default
-      name: Build - No debug-gui
-      environment:
-        MESON_PARAMS: -Ddebug-gui=false
-  build_no_tests: &build_no_tests
-    run:
-      <<: *build_and_test_default
-      name: Build - No tests
-      environment:
-        MESON_PARAMS: -Dtests=false
-  build_no_docs: &build_no_docs
-    run:
-      <<: *build_and_test_default
-      name: Build - No docs
-      environment:
-        MESON_PARAMS: -Ddocumentation=false
-  build_dist: &build_dist
-    run:
-      <<: *build_and_test_default
-      name: Build - ninja dist
-      environment:
-        NINJA_ARGS: dist
-  ninja_scan_build: &ninja_scan_build
-    run:
-      <<: *build_and_test_default
-      name: Ninja scan-build
-      environment:
-        NINJA_ARGS: scan-build
-  install: &install
-    run:
-      name: Installing
-      command: ninja -v -C build install
-  export_logs: &export_logs
-    store_artifacts:
-      path: ~/libinput/build/meson-logs
-
-fedora_install: &fedora_install
-  run:
-    name: Install prerequisites
-    command: |
-      dnf upgrade -y libsolv
-      dnf install -y git gcc gcc-c++ meson check-devel libudev-devel libevdev-devel doxygen graphviz valgrind binutils libwacom-devel cairo-devel gtk3-devel glib2-devel mtdev-devel
-
-fedora_build_all: &fedora_build_all
-  <<: *default_settings
-  steps:
-    - *fedora_install
-    - checkout
-    - *build_and_test
-    - *install
-    - *export_logs
-    - *build_no_libwacom
-    - *build_no_debug_gui
-    - *build_no_tests
-    - *build_no_docs
-    - *build_dist
-
-ubuntu_install: &ubuntu_install
-  run:
-    name: Install prerequisites
-    command: |
-      apt-get update
-      apt-get install -y software-properties-common
-      add-apt-repository universe
-      apt-get update
-      apt-get install -y git gcc g++ meson check libudev-dev libevdev-dev doxygen graphviz valgrind binutils libwacom-dev libcairo2-dev libgtk-3-dev libglib2.0-dev libmtdev-dev
-
-ubuntu_build_all: &ubuntu_build_all
-  <<: *default_settings
-  steps:
-    - *ubuntu_install
-    - checkout
-    - *build_and_test
-    - *install
-    - *export_logs
-    - *build_no_libwacom
-    - *build_no_debug_gui
-    - *build_no_tests
-    - *build_no_docs
-    - *build_dist
-
-scan_build_run: &scan_build_run
-  <<: *default_settings
-  steps:
-    - *fedora_install
-    - run:
-        name: Install clang and find
-        command: dnf install -y clang-analyzer findutils
-    - checkout
-    - *ninja_scan_build
-    - *export_logs
-    - run:
-        name: Check scan-build results
-        command: test ! -d ~/libinput/build/meson-logs/scanbuild || test $(find ~/libinput/build/meson-logs/scanbuild -maxdepth 0 ! -empty -exec echo "not empty" \; | wc -l) -eq 0 || (echo "Check scan-build results" && false)
-
-version: 2
-jobs:
-  fedora_latest:
-    <<: *fedora_build_all
-    docker:
-      - image: fedora:latest
-  ubuntu_17_10:
-    <<: *ubuntu_build_all
-    docker:
-      - image: ubuntu:artful
-  scan_build:
-    <<: *scan_build_run
-    docker:
-      - image: fedora:latest
-
-workflows:
-  version: 2
-  compile:
-    jobs:
-      - fedora_latest
-      - scan_build
-      - ubuntu_17_10

completion/zsh/_libinput

@@ -0,0 +1,282 @@
+#compdef libinput
+
+(( $+functions[_libinput_commands] )) || _libinput_commands()
+{
+	local -a commands
+	commands=(
+		"list-devices:List all devices recognized by libinput"
+		"debug-events:Print all events as seen by libinput"
+		"debug-gui:Show a GUI to visualize libinput's events"
+		"debug-tablet:Show tablet axis and button values"
+		"measure:Measure various properties of devices"
+		"analyze:Analyze device data"
+		"record:Record the events from a device"
+		"replay:Replay the events from a device"
+	)
+
+	_describe -t commands 'command' commands
+}
+
+__all_seats()
+{
+	# Obviously only works with logind
+	local -a seats
+	seats=${(f)"$(loginctl --no-legend --no-pager list-seats 2>/dev/null)"}
+	if [[ -z $seats ]]; then
+		# Can always offer seat0, even if we can't enumerate the seats
+		compadd "$@" - seat0
+	else
+		compadd "$@" - $seats
+	fi
+}
+
+(( $+functions[_libinput_list-devices] )) || _libinput_list-devices()
+{
+	_arguments \
+		'--help[Show help and exit]' \
+		'--version[show version information and exit]'
+}
+
+(( $+functions[_libinput_debug-events] )) || _libinput_debug-events()
+{
+	_arguments \
+		'--help[Show debug-events help and exit]' \
+		'--quiet[Only print libinput messages and nothing from this tool]' \
+		'--verbose[Use verbose output]' \
+		'--show-keycodes[Make all keycodes visible]' \
+		'--grab[Exclusively grab all opened devices]' \
+		'--compress-motion-events[Compress repeated motion events on a TTY]' \
+		'--device=[Use the given device with the path backend]:device:_files -W /dev/input/ -P /dev/input/' \
+		'--udev=[Listen for notifications on the given seat]:seat:__all_seats' \
+		'--apply-to=[Apply configuration options where the device name matches the pattern]:pattern' \
+		'--disable-sendevents=[Disable send-events option for the devices matching the pattern]:pattern' \
+		'--set-area=[Set the desired area as "x1/y1 x2/y2" (within \[0.0, 1.0\]) ]' \
+		'--set-calibration=[Set the first 6 elements of the 3x3 calibration matrix ("1.0 0.0 0.0 0.0 1.0 0.0")]' \
+		'--set-click-method=[Set the desired click method]:click-method:(none clickfinger buttonareas)' \
+		'--set-clickfinger-map=[Set button mapping for clickfinger]:tap-map:((  \
+			lrm\:2-fingers\ right-click\ /\ 3-fingers\ middle-click \
+			lmr\:2-fingers\ middle-click\ /\ 3-fingers\ right-click \
+		))' \
+		'--set-eraser-button-button=[Set button mapping for the eraser button]:eraser-button:(BTN_STYLUS BTN_STYLUS2 BTN_STYLUS3)' \
+		'--set-eraser-button-mode=[Set the eraser button mode]:eraser-mode:(default button)' \
+		'--set-pressure-range=[Set the tablet tool pressure range (within range \[0.0, 1.0\])]' \
+		'--set-profile=[Set pointer acceleration profile]:accel-profile:(adaptive flat custom)' \
+		'--set-rotation-angle=[Set the rotation angle in degrees]' \
+		'--set-scroll-button=[Set the button to the given button code]' \
+		'--set-scroll-method=[Set the desired scroll method]:scroll-method:(none twofinger edge button)' \
+		'--set-speed=[Set pointer acceleration speed (within range \[-1, 1\])]' \
+		'--set-tap-map=[Set button mapping for tapping]:tap-map:((  \
+			lrm\:2-fingers\ right-click\ /\ 3-fingers\ middle-click \
+			lmr\:2-fingers\ middle-click\ /\ 3-fingers\ right-click \
+		))' \
+		+ '(custom pointer acceleration)' \
+		'--set-custom-points=[Set n points defining a custom acceleration function]' \
+		'--set-custom-step=[Set the distance along the x axis between the custom points]' \
+		'--set-custom-type=[Set the type of the acceleration function]:custom-type:(fallback motion scroll)' \
+		+ '(drag)' \
+		'--enable-drag[Enable tap-and-drag]' \
+		'--disable-drag[Disable tap-and-drag]' \
+		+ '(drag-lock)' \
+		'--enable-drag-lock[Enable drag-lock]' \
+		'--disable-drag-lock[Disable drag-lock]' \
+		+ '(dwt)' \
+		'--enable-dwt[Enable disable-while-typing]' \
+		'--disable-dwt[Disable disable-while-typing]' \
+		+ '(dwtp)' \
+		'--enable-dwtp[Enable disable-while-trackpointing]' \
+		'--disable-dwtp[Disable disable-while-trackpointing]' \
+		+ '(left-handed)' \
+		'--enable-left-handed[Enable left handed button configuration]' \
+		'--disable-left-handed[Disable left handed button configuration]' \
+		+ '(middlebutton)' \
+		'--enable-middlebutton[Enable middle button emulation]' \
+		'--disable-middlebutton[Disable middle button emulation]' \
+		+ '(natural-scrolling)' \
+		'--enable-natural-scrolling[Enable natural scrolling]' \
+		'--disable-natural-scrolling[Disable natural scrolling]' \
+		+ '(plugins)' \
+		'--enable-plugins[Enable plugins]' \
+		'--disable-plugins[Disable plugins]' \
+		+ '(tap-to-click)' \
+		'--enable-tap[Enable tap-to-click]' \
+		'--disable-tap[Disable tap-to-click]'
+}
+
+(( $+functions[_libinput_debug-gui] )) || _libinput_debug-gui()
+{
+	_arguments \
+		'--help[Show debug-gui help and exit]' \
+		'--verbose[Use verbose output]' \
+		'--grab[Exclusively grab all opened devices]' \
+		'--device=[Use the given device with the path backend]:device:_files -W /dev/input/ -P /dev/input/' \
+		'--udev=[Listen for notifications on the given seat]:seat:_libinput_all_seats'
+}
+
+(( $+functions[_libinput_debug-tablet] )) || _libinput_debug-tablet()
+{
+	_arguments \
+		'--help[Show debug-tablet help and exit]' \
+		'--device=[Use the given device with the path backend]:device:_files -W /dev/input/ -P /dev/input/' \
+		'--udev=[Use the first tablet device on the given seat]:seat:_libinput_all_seats'
+}
+
+
+(( $+functions[_libinput_measure] )) || _libinput_measure()
+{
+	local curcontext=$curcontext state line ret=1
+	local features
+	features=(
+		"fuzz:Measure touch fuzz to avoid pointer jitter"
+		"touch-size:Measure touch size and orientation"
+		"touchpad-tap:Measure tap-to-click time"
+		"touchpad-pressure:Measure touch pressure"
+	)
+
+	_arguments -C \
+		'--help[Print help and exit]' \
+		':feature:->feature' \
+		'*:: :->option-or-argument'
+
+	case $state in
+		(feature)
+			_describe -t features 'feature' features
+			;;
+		(option-or-argument)
+			curcontext=${curcontext%:*:*}:libinput-measure-$words[1]:
+			if ! _call_function ret _libinput_measure_$words[1]; then
+				_message "unknown feature: $words[1]"
+			fi
+			;;
+	esac
+	return ret
+}
+
+(( $+functions[_libinput_measure_fuzz] )) || _libinput_measure_fuzz()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		':device:_files -W /dev/input/ -P /dev/input/'
+}
+
+(( $+functions[_libinput_measure_touch-size] )) || _libinput_measure_touch-size()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		'--touch-threshold=[Assume a touch pressure threshold of "down:up"]' \
+		'--palm-threshold=[Assume a palm threshold of N]' \
+		':device:_files -W /dev/input/ -P /dev/input/'
+}
+
+(( $+functions[_libinput_measure_touchpad-pressure] )) || _libinput_measure_touchpad-pressure()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		'--touch-threshold=[Assume a touch pressure threshold of "down:up"]' \
+		'--palm-threshold=[Assume a palm threshold of N]' \
+		':device:_files -W /dev/input/ -P /dev/input/'
+}
+
+(( $+functions[_libinput_measure_touchpad-tap] )) || _libinput_measure_touchpad-tap()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		'--format=dat[Specify the data format to be printed. The default is "summary"]' \
+		':device:_files -W /dev/input/ -P /dev/input/'
+}
+
+(( $+functions[_libinput_analyze_per-slot-delta] )) || _libinput_analyze_per-slot-delta()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		':recording:_files'
+}
+
+(( $+functions[_libinput_analyze_touch-down-state] )) || _libinput_analyze_touch-down-state()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		':recording:_files'
+}
+
+(( $+functions[_libinput_analyze_recording] )) || _libinput_analyze_recording()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		':recording:_files'
+}
+
+(( $+functions[_libinput_analyze] )) || _libinput_analyze()
+{
+	local curcontext=$curcontext state line ret=1
+	local features
+	features=(
+		"per-slot-delta:analyze relative movement per touch per slot"
+		"recording:analyze a recording by printing a pretty table"
+		"touch-down-state:analyze a recording for logical touch down states"
+	)
+
+	_arguments -C \
+		'--help[Print help and exit]' \
+		':feature:->feature' \
+		'*:: :->option-or-argument'
+
+	case $state in
+		(feature)
+			_describe -t features 'feature' features
+			;;
+		(option-or-argument)
+			curcontext=${curcontext%:*:*}:libinput-analyze-$words[1]:
+			if ! _call_function ret _libinput_analyze_$words[1]; then
+				_message "unknown feature: $words[1]"
+			fi
+			;;
+	esac
+	return ret
+}
+
+(( $+functions[_libinput_record] )) || _libinput_record()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		'--all[Record all /dev/input/event* devices available on the system]' \
+		'--autorestart=[Terminate the current recording after s seconds of device inactivity]' \
+		{-o+,--output=}'[Specify the output file to use]:file:_files -g "*.yml"' \
+		'--multiple[Record multiple devices at once]' \
+		'--show-keycodes[Show keycodes as-is in the recording]' \
+		'--with-libinput[Record libinput events alongside device events]' \
+		'--with-hidraw[Record hidraw events alongside device events]' \
+		'*::device:_files -W /dev/input/ -P /dev/input/'
+}
+
+(( $+functions[_libinput_replay] )) || _libinput_replay()
+{
+	_arguments \
+		'--help[Show help message and exit]' \
+		':recording:_files'
+}
+
+_libinput()
+{
+	local curcontext=$curcontext state line ret=1
+
+	_arguments -C \
+		{-h,--help}'[Show help message and exit]' \
+		'--version[Show version information and exit]' \
+		':command:->command' \
+		'*:: :->option-or-argument' && return
+
+	case $state in
+		(command)
+			_libinput_commands && ret=0
+			;;
+		(option-or-argument)
+			curcontext=${curcontext%:*:*}:libinput-$words[1]:
+			if ! _call_function ret _libinput_$words[1]; then
+				_message "unknown libinput command: $words[1]"
+			fi
+			;;
+	esac
+	return ret
+}
+
+_libinput

completion/zsh/meson.build

@@ -0,0 +1,12 @@
+zshcompletiondir = get_option('zshcompletiondir')
+if zshcompletiondir == ''
+		zshcompletiondir = get_option('datadir') / 'zsh' / 'site-functions'
+endif
+
+if zshcompletiondir != 'no'
+	install_data(
+		'_libinput',
+		install_dir: zshcompletiondir,
+		install_mode: 'rw-r--r--',
+	)
+endif

doc/absolute-coordinate-ranges.dox

@@ -1,117 +0,0 @@
-/**
-@page absolute_coordinate_ranges Coordinate ranges for absolute axes
-
-libinput requires that all touchpads provide a correct axis range and
-resolution. These are used to enable or disable certain features or adapt
-the interaction with the touchpad. For example, the software button area is
-narrower on small touchpads to avoid reducing the interactive surface too
-much. Likewise, palm detection works differently on small touchpads as palm
-interference is less likely to happen.
-
-Touchpads with incorrect axis ranges generate error messages
-in the form:
-<blockquote>
-Axis 0x35 value 4000 is outside expected range [0, 3000]
-</blockquote>
-
-This error message indicates that the ABS_MT_POSITION_X axis (i.e. the x
-axis) generated an event outside the expected range of 0-3000. In this case
-the value was 4000.
-This discrepancy between the coordinate range the kernels advertises vs.
-what the touchpad sends can be the source of a number of perceived
-bugs in libinput.
-
-@section absolute_coordinate_ranges_fix Measuring and fixing touchpad ranges
-
-To fix the touchpad you need to:
--# measure the physical size of your touchpad in mm
--# run touchpad-edge-detector
--# trim the udev match rule to something sensible
--# replace the resolution with the calculated resolution based on physical
-  settings
--# test locally
--# send a patch to the systemd project
-
-Detailed explanations are below.
-
-[libevdev](http://freedesktop.org/wiki/Software/libevdev/) provides a tool
-called **touchpad-edge-detector** that allows measuring the touchpad's input
-ranges. Run the tool as root against the device node of your touchpad device
-and repeatedly move a finger around the whole outside area of the
-touchpad. Then control+c the process and note the output.
-An example output is below:
-
-@code
-$> sudo touchpad-edge-detector /dev/input/event4
-Touchpad SynPS/2 Synaptics TouchPad on /dev/input/event4
-Move one finger around the touchpad to detect the actual edges
-Kernel says:	x [1024..3112], y [2024..4832]
-Touchpad sends:	x [2445..4252], y [3464..4071]
-
-Touchpad size as listed by the kernel: 49x66mm
-Calculate resolution as:
-	x axis: 2088/<width in mm>
-	y axis: 2808/<height in mm>
-
-Suggested udev rule:
-# <Laptop model description goes here>
-evdev:name:SynPS/2 Synaptics TouchPad:dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn20ARS25701:pvrThinkPadT440s:rvnLENOVO:rn20ARS25701:rvrSDK0E50512STD:cvnLENOVO:ct10:cvrNotAvailable:*
- EVDEV_ABS_00=2445:4252:<x resolution>
- EVDEV_ABS_01=3464:4071:<y resolution>
- EVDEV_ABS_35=2445:4252:<x resolution>
- EVDEV_ABS_36=3464:4071:<y resolution>
-
-@endcode
-
-Note the discrepancy between the coordinate range the kernels advertises vs.
-what the touchpad sends.
-To fix the advertised ranges, the udev rule should be taken and trimmed
-before being sent to the [systemd project](https://github.com/systemd/systemd).
-An example commit can be found
-[here](https://github.com/systemd/systemd/commit/26f667eac1c5e89b689aa0a1daef6a80f473e045).
-
-In most cases the match can and should be trimmed to the system vendor (svn)
-and the product version (pvr), with everything else replaced by a wildcard
-(*). In this case, a Lenovo T440s, a suitable match string would be: @code
-evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s*
-@endcode
-
-@note hwdb match strings only allow for alphanumeric ascii characters. Use a
-wildcard (* or ?, whichever appropriate) for special characters.
-
-The actual axis overrides are in the form:
-@code
-# axis number=min:max:resolution
- EVDEV_ABS_00=2445:4252:42
-@endcode
-or, if the range is correct but the resolution is wrong
-@code
-# axis number=::resolution
- EVDEV_ABS_00=::42
-@endcode
-
-Note the leading single space. The axis numbers are in hex and can be found
-in *linux/input-event-codes.h*. For touchpads ABS_X, ABS_Y,
-ABS_MT_POSITION_X and ABS_MT_POSITION_Y are required.
-
-@note The touchpad's ranges and/or resolution should only be fixed when
-there is a significant discrepancy. A few units do not make a difference and
-a resolution that is off by 2 or less usually does not matter either.
-
-Once a match and override rule has been found, follow the instructions at
-the top of the
-[60-evdev.hwdb](https://github.com/systemd/systemd/blob/master/hwdb/60-evdev.hwdb)
-file to save it locally and trigger the udev hwdb reload. Rebooting is
-always a good idea. If the match string is correct, the new properties will
-show up in the
-output of
-@code
-   udevadm info /sys/class/input/event4
-@endcode
-
-Adjust the command for the event node of your touchpad.
-A udev builtin will apply the new axis ranges automatically.
-
-When the axis override is confirmed to work, please submit it as a pull
-request to the [systemd project](https://github.com/systemd/systemd).
-*/

doc/api/libinput.doxygen.in

@@ -7,11 +7,13 @@ OPTIMIZE_OUTPUT_FOR_C  = YES
 EXTRACT_ALL            = YES
 EXTRACT_STATIC         = YES
 MAX_INITIALIZER_LINES  = 0
+WARNINGS               = YES
 QUIET                  = YES
-INPUT                  = @INPUT@
-IMAGE_PATH             = "@top_srcdir@/doc/svg" \
-			 "@top_srcdir@/doc/dot"
+INPUT                  = "@builddir@"
+IMAGE_PATH             = "@builddir@"
+OUTPUT_DIRECTORY       = doc
 GENERATE_HTML          = YES
+HTML_OUTPUT            = html
 SEARCHENGINE           = NO
 USE_MATHJAX            = YES
 MATHJAX_RELPATH        = https://cdn.mathjax.org/mathjax/latest
@@ -20,11 +22,13 @@ MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
 PREDEFINED             = LIBINPUT_ATTRIBUTE_PRINTF(f, a)= \
                          LIBINPUT_ATTRIBUTE_DEPRECATED
-DOTFILE_DIRS           = "@top_srcdir@/doc/dot"
+DOTFILE_DIRS           = "@builddir@"
+EXAMPLE_PATH           = "@builddir@"
+SHOW_NAMESPACES        = NO
+HAVE_DOT               = YES
 
-HTML_HEADER = "@top_srcdir@/doc/style/header.html"
-HTML_FOOTER = "@top_srcdir@/doc/style/footer.html"
-HTML_EXTRA_STYLESHEET = "@top_srcdir@/doc/style/bootstrap.css" \
-			"@top_srcdir@/doc/style/customdoxygen.css" \
-			"@top_srcdir@/doc/style/libinputdoxygen.css"
-USE_MDFILE_AS_MAINPAGE = "@top_srcdir@/README.md"
+HTML_HEADER = "@builddir@/header.html"
+HTML_FOOTER = "@builddir@/footer.html"
+HTML_EXTRA_STYLESHEET = "@builddir@/bootstrap.css" \
+			"@builddir@/customdoxygen.css" \
+			"@builddir@/libinputdoxygen.css"

doc/api/mainpage.dox

@@ -0,0 +1,135 @@
+/**
+@mainpage
+
+This is the libinput API reference.
+
+This documentation is aimed at developers of Wayland compositors. User
+documentation is available
+[here](https://wayland.freedesktop.org/libinput/doc/latest).
+
+@section concepts Concepts
+
+@subsection concepts_initialization Initialization of a libinput context
+
+libinput provides two different backends:
+- a @ref libinput_udev_create_context "udev backend" where notifications
+  about new and removed devices are provided by udev, and
+- a @ref libinput_path_create_context "path backend" where
+  @ref libinput_path_add_device "device addition" and
+  @ref libinput_path_remove_device "device removal" need to be handled by
+  the caller.
+
+See section @ref base for information about initializing a libinput context.
+
+@subsection concepts_events Monitoring for events
+
+libinput exposes a single @ref libinput_get_fd "file descriptor" to the
+caller. This file descriptor should be monitored by the caller, whenever
+data is available the caller **must** immediately call libinput_dispatch().
+Failure to do so will result in erroneous behavior.
+
+libinput_dispatch() may result in one or more events being available to the
+caller. After libinput_dispatch() a caller **should** call
+libinput_get_event() to retrieve and process this event. Whenever
+libinput_get_event() returns `NULL`, no further events are available.
+
+See section @ref event for more information about events.
+
+@subsection concepts_seats Device grouping into seats
+
+All devices are grouped into physical and logical seats. Button and key
+states are available per-device and per-seat. See @ref seat for more
+information.
+
+@subsection concepts_devices Device capabilities
+
+libinput does not use device types. All devices have @ref
+libinput_device_has_capability "capabilities" that define which events may
+be generated. See @ref device for more information about devices.
+
+Specific event types include:
+- @ref event_keyboard
+- @ref event_pointer
+- @ref event_touch
+- @ref event_gesture
+- @ref event_tablet
+- @ref event_tablet_pad
+- @ref event_switch
+
+
+@subsection concepts_configuration Device configuration
+
+libinput relies on the caller for device configuration. See
+@ref config for more information.
+
+@subsection example An example libinput program
+
+The simplest libinput program looks like this:
+
+@code
+static int open_restricted(const char *path, int flags, void *user_data)
+{
+	int fd = open(path, flags);
+	return fd < 0 ? -errno : fd;
+}
+
+static void close_restricted(int fd, void *user_data)
+{
+	close(fd);
+}
+
+const static struct libinput_interface interface = {
+	.open_restricted = open_restricted,
+	.close_restricted = close_restricted,
+};
+
+
+int main(void) {
+	struct libinput *li;
+	struct libinput_event *event;
+
+	li = libinput_udev_create_context(&interface, NULL, udev);
+	libinput_udev_assign_seat(li, "seat0");
+	libinput_dispatch(li);
+
+	while ((event = libinput_get_event(li)) != NULL) {
+
+		// handle the event here
+
+		libinput_event_destroy(event);
+		libinput_dispatch(li);
+	}
+
+	libinput_unref(li);
+
+	return 0;
+}
+
+@endcode
+
+@section building_against Building against libinput
+
+libinput provides a
+[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) file.
+Software that uses libinput should use pkg-config and the
+`PKG_CHECK_MODULES` autoconf macro.
+Otherwise, the most rudimentary way to compile and link a program against
+libinput is:
+
+@verbatim
+    gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput`
+@endverbatim
+
+For further information on using pkgconfig see the pkg-config documentation.
+
+@section stability Backwards-compatibility
+
+libinput promises backwards-compatibility across all the 1.x.y version. An
+application built against libinput 1.x.y will work with any future 1.*.*
+release.
+
+@section About
+
+Documentation generated from git commit [__GIT_VERSION__](https://gitlab.freedesktop.org/libinput/libinput/commit/__GIT_VERSION__)
+
+*/

doc/api/meson.build

@@ -0,0 +1,52 @@
+prg_install = find_program('install')
+
+doxygen = find_program('doxygen', required : false)
+if not doxygen.found()
+	error('Program "doxygen" not found or not executable. Try building with -Ddocumentation=false')
+endif
+dot = find_program('dot', required : false)
+if not dot.found()
+	error('Program "dot" not found or not executable. Try building with -Ddocumentation=false')
+endif
+
+mainpage = vcs_tag(command : ['git', 'log', '-1', '--format=%h'],
+		 fallback : 'unknown',
+		 input : 'mainpage.dox',
+		 output : 'mainpage.dox',
+		 replace_string: '__GIT_VERSION__')
+
+src_doxygen = files(
+	# source files
+	'../../src/libinput.h',
+	# style files
+	'style/header.html',
+	'style/footer.html',
+	'style/customdoxygen.css',
+	'style/bootstrap.css',
+	'style/libinputdoxygen.css',
+)
+
+doxyfiles = []
+foreach f : src_doxygen
+	df = configure_file(input: f,
+			    output: '@PLAINNAME@',
+			    copy : true)
+	doxyfiles += [ df ]
+endforeach
+
+doc_config = configuration_data()
+doc_config.set('PACKAGE_NAME', meson.project_name())
+doc_config.set('PACKAGE_VERSION', meson.project_version())
+doc_config.set('builddir', meson.current_build_dir())
+
+doxyfile = configure_file(input : 'libinput.doxygen.in',
+			  output : 'libinput.doxygen',
+			  configuration : doc_config)
+
+custom_target('doxygen',
+	      input : [ doxyfiles, doxyfile, mainpage ] + src_doxygen,
+	      output : [ 'html' ],
+	      command : [ doxygen, doxyfile ],
+	      install : false,
+	      depends: [ mainpage ],
+	      build_by_default : true)

doc/api/page-hierarchy.dox

@@ -0,0 +1,7 @@
+/**
+
+@page Tablets
+
+- @subpage tablet serial numbers
+
+*/

doc/api/style/customdoxygen.css

@@ -252,4 +252,3 @@ blockquote {
     margin: 0 24px 0 4px;
     padding: 0 12px 0 16px;
 }
-

doc/api/style/header.html

@@ -8,7 +8,7 @@
 
         <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
         <meta name="generator" content="Doxygen $doxygenversion"/>
-        
+
         <script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
 
         <!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->

doc/api/style/libinputdoxygen.css

@@ -0,0 +1,120 @@
+@import url("https://fonts.googleapis.com/css?family=Roboto+Mono");
+
+dd {
+    margin-left: 30px;
+}
+
+.title {
+	font-size: 200%;
+	font-weight: bold;
+}
+
+.title .ingroups {
+	font-size: 50%;
+}
+
+h1 {
+	font-size: 150%;
+	color: #354C7B;
+	background: none;
+	border-bottom: 1px solid #879ECB;
+	font-size: 150%;
+	font-weight: normal;
+	padding-top: 8px;
+	padding-bottom: 8px;
+	padding-left: 0px;
+	width: 100%;
+}
+
+h2 {
+	font-size: 120%;
+	color: #354C7B;
+	background: none;
+	border-bottom: 1px solid #879ECB;
+	font-size: 150%;
+	font-weight: normal;
+	padding-top: 8px;
+	padding-bottom: 8px;
+	padding-left: 0px;
+	width: 100%;
+}
+
+.sm-dox li {
+	float:left;
+	border-top: 0;
+	padding-right: 20px;
+}
+
+.sm li, .sm a {
+	position: relative;
+}
+
+.sm, .sm ul, .sm li {
+	list-style: none;
+	display: block;
+	line-height: normal;
+	direction: ltr;
+	text-align: left;
+}
+
+.sm, .sm *, .sm *::before, .sm *::after {
+	box-sizing: border-box;
+}
+
+#main-nav {
+	padding: 30px;
+}
+
+/* Main menu sub-items like file-list, etc */
+#main-menu li ul {
+	display: none;
+}
+
+.paramname {
+	padding-right: 10px;
+}
+
+.memtitle {
+	background-image: none;
+	background-color: #F0F0F0;
+}
+
+.memproto {
+	background-color: #F0F0F0;
+}
+
+.headertitle {
+	background-image: none;
+	background-color: #F0F0F0;
+}
+
+div.header {
+	border: none;
+}
+
+td.fieldname {
+	font-family: 'Roboto Mono', monospace;
+}
+
+.fieldtable th {
+	background-image: none;
+	background-color: #F0F0F0;
+}
+
+body {
+	letter-spacing: 0px;
+}
+
+.mdescLeft, .mdescRight, .memItemLeft, .memItemRight, .memTemplItemLeft, .memTemplItemRight, .memTemplParams {
+	background-color: #F0F0F0;
+}
+
+a {
+	color: #2873b0;
+
+}
+
+.navpath ul {
+	background-image: none;
+	background-color: #F0F0F0;
+}

doc/architecture.dox

@@ -1,282 +0,0 @@
-/**
-@page architecture libinput's internal architecture
-
-This page provides an outline of libinput's internal architecture. The goal
-here is to get the high-level picture across and point out the components
-and their interplay to new developers.
-
-The public facing API is in `libinput.c`, this file is thus the entry point
-for almost all API calls. General device handling is in `evdev.c` with the
-device-type-specific implementations in `evdev-<type>.c`. It is not
-necessary to understand all of libinput to contribute a patch.
-
-@ref architecture-contexts is the only user-visible implementation detail,
-everything else is purely internal implementation and may change when
-required.
-
-@section architecture-contexts The udev and path contexts
-
-The first building block is the "context" which can be one of
-two types, "path" and "udev". See libinput_path_create_context() and
-libinput_udev_create_context(). The path/udev specific bits are in
-`path-seat.c` and `udev-seat.c`. This includes the functions that add new
-devices to a context.
-
-@dot
-digraph context
-{
-  compound=true;
-  rankdir="LR";
-  node [
-    shape="box";
-  ]
-
-  libudev [label="libudev 'add' event"]
-  udev [label="libinput_udev_create_context()"];
-  udev_backend [label="udev-specific backend"];
-  context [label="libinput context"]
-  udev -> udev_backend;
-  libudev -> udev_backend;
-  udev_backend -> context;
-}
-@enddot
-
-The udev context provides automatic device hotplugging as udev's "add"
-events are handled directly by libinput. The path context requires that the
-caller adds devices.
-
-@dot
-digraph context
-{
-  compound=true;
-  rankdir="LR";
-  node [
-    shape="box";
-  ]
-
-  path [label="libinput_path_create_context()"];
-  path_backend [label="path-specific backend"];
-  xdriver [label="libinput_path_add_device()"]
-  context [label="libinput context"]
-  path -> path_backend;
-  xdriver -> path_backend;
-  path_backend -> context;
-}
-@enddot
-
-As a general rule: all Wayland compositors use a udev context, the X.org
-stack uses a path context.
-
-Which context was initialized only matters for creating/destroying a context
-and adding devices. The device handling itself is the same for both types of
-context.
-
-@section architecture-device Device initialization
-
-libinput only supports evdev devices, all the device initialization is done
-in `evdev.c`. Much of the libinput public API is also a thin wrapper around
-the matching implementation in the evdev device.
-
-There is a 1:1 mapping between libinput devices and `/dev/input/eventX`
-device nodes.
-
-
-@dot
-digraph context
-{
-  compound=true;
-  rankdir="LR";
-  node [
-    shape="box";
-  ]
-
-  devnode [label="/dev/input/event0"]
-
-  libudev [label="libudev 'add' event"]
-  xdriver [label="libinput_path_add_device()"]
-  context [label="libinput context"]
-
-  evdev [label="evdev_device_create()"]
-
-  devnode -> xdriver;
-  devnode -> libudev;
-  xdriver -> context;
-  libudev -> context;
-
-  context->evdev;
-
-}
-@enddot
-
-Entry point for all devices is `evdev_device_create()`, this function
-decides to create a `struct evdev_device` for the given device node.
-Based on the udev tags (e.g. `ID_INPUT_TOUCHPAD`), a @ref
-architecture-dispatch is initialized. All event handling is then in this
-dispatch. 
-
-Rejection of devices and the application of quirks is generally handled in 
-`evdev.c` as well. Common functionality shared across multiple device types
-(like button-scrolling) is also handled here.
-
-@section architecture-dispatch Device-type specific event dispatch
-
-Depending on the device type, `evdev_configure_device` creates the matching 
-`struct evdev_dispatch`. This dispatch interface contains the function
-pointers to handle events. Four such dispatch methods are currently
-implemented: touchpad, tablet, tablet pad, and the fallback dispatch which
-handles mice, keyboards and touchscreens.
-
-@dot
-digraph context
-{
-  compound=true;
-  rankdir="LR";
-  node [
-    shape="box";
-  ]
-
-  evdev [label="evdev_device_create()"]
-
-  fallback [label="evdev-fallback.c"]
-  touchpad [label="evdev-mt-touchpad.c"]
-  tablet [label="evdev-tablet.c"]
-  pad [label="evdev-tablet-pad.c"]
-
-  evdev -> fallback;
-  evdev -> touchpad;
-  evdev -> tablet;
-  evdev -> pad;
-
-}
-@enddot
-
-While `evdev.c` pulls the event out of libevdev, the actual handling of the
-events is performed within the dispatch method.
-
-@dot
-digraph context
-{
-  compound=true;
-  rankdir="LR";
-  node [
-    shape="box";
-  ]
-
-  evdev [label="evdev_device_dispatch()"]
-
-  fallback [label="fallback_interface_process()"];
-  touchpad [label="tp_interface_process()"]
-  tablet [label="tablet_process()"]
-  pad [label="pad_process()"]
-
-  evdev -> fallback;
-  evdev -> touchpad;
-  evdev -> tablet;
-  evdev -> pad;
-}
-@enddot
-
-The dispatch methods then look at the `struct input_event` and proceed to
-update the state. Note: the serialized nature of the kernel evdev protocol
-requires that the device updates the state with each event but to delay
-processing until the `SYN_REPORT` event is received.
-
-@section architecture-configuration Device configuration
-
-All device-specific configuration is handled through `struct
-libinput_device_config_FOO` instances. These are set up during device init
-and provide the function pointers for the `get`, `set`, `get_default`
-triplet of configuration queries (or more, where applicable).
-
-For example, the `struct tablet_dispatch` for tablet devices has a
-`struct libinput_device_config_accel`. This struct is set up with the
-required function pointers to change the profiles.
-
-@dot
-digraph context
-{
-  compound=true;
-  rankdir="LR";
-  node [
-    shape="box";
-  ]
-
-  tablet [label="struct tablet_dispatch"]
-  config [label="struct libinput_device_config_accel"];
-  tablet_config [label="tablet_accel_config_set_profile()"];
-  tablet->config;
-  config->tablet_config;
-}
-@enddot
-
-When the matching `libinput_device_config_set_FOO()` is called, this goes
-through to the config struct and invokes the function there. Thus, it is
-possible to have different configuration functions for a mouse vs a
-touchpad, even though the interface is the same.
-
-@dot
-digraph context
-{
-  compound=true;
-  rankdir="LR";
-  node [
-    shape="box";
-  ]
-
-  libinput [label="libinput_device_config_accel_set_profile()"];
-  tablet_config [label="tablet_accel_config_set_profile()"];
-  libinput->tablet_config;
-}
-@enddot
-
-@section architecture-filter Pointer acceleration filters
-
-All pointer acceleration is handled in the `filter.c` file and its
-associated files.
-
-The `struct motion_filter` is initialized during device init, whenever
-deltas are available they are passed to `filter_dispatch()`. This function
-returns a set of @ref motion_normalization_customization "normalized coordinates".
-
-All actual acceleration is handled within the filter, the device itself has
-no further knowledge. Thus it is possible to have different acceleration
-filters for the same device types (e.g. the Lenovo X230 touchpad has a
-custom filter).
-
-@dot
-digraph context
-{
-  compound=true;
-  rankdir="LR";
-  node [
-    shape="box";
-  ]
-
-  fallback [label="fallback deltas"];
-  touchpad [label="touchpad deltas"];
-  tablet [label="tablet deltas"];
-
-  filter [label="filter_dispatch"];
-
-  fallback->filter;
-  touchpad->filter;
-  tablet->filter;
-
-  flat [label="accelerator_interface_flat()"];
-  x230 [label="accelerator_filter_x230()"];
-  pen [label="tablet_accelerator_filter_flat_pen()"];
-  
-  filter->flat;
-  filter->x230;
-  filter->pen;
-
-}
-@enddot
-
-Most filters convert the deltas (incl. timestamps) to a motion speed and
-then apply a so-called profile function. This function returns a factor that
-is then applied to the current delta, converting it into an accelerated
-delta. See @ref pointer-acceleration for more details.
-the current
-
-*/

doc/building.dox

@@ -1,241 +0,0 @@
-/**
-@page building_libinput libinput build instructions
-
-@tableofcontents
-
-Instructions on how to build libinput and its tools and how to build against
-libinput.
-
-The build instruction on this page detail how to overwrite your
-system-provided libinput with one from the git repository, see
-see @ref reverting_install to revert to the previous state.
-
-@section building Building libinput
-
-libinput uses [meson](https://www.mesonbuild.com) and
-[ninja](https://www.ninja-build.org). A build is usually the three-step
-process below.  A successful build requires the @ref
-building_dependencies to be installed before running meson.
-
-@code
-$> git clone git://anongit.freedesktop.org/git/wayland/libinput
-$> cd libinput
-$> meson --prefix=/usr builddir/
-$> ninja -C builddir/
-$> sudo ninja -C builddir/ install
-$> sudo udevadm hwdb --update
-@endcode
-
-Additional options may also be specified. For example:
-@code
-$> meson --prefix=/usr -Ddocumentation=false builddir/
-@endcode
-
-We recommend that users disable the documentation, it's not usually required
-for testing and reduces the number of dependencies needed.
-
-The ```prefix``` or other options can be changed later with the
-```mesonconf``` command. For example:
-@code
-$> mesonconf builddir/ -Dprefix=/some/other/prefix -Ddocumentation=true
-$> ninja -C builddir
-$> sudo ninja -C builddir/ install
-@endcode
-
-Running ``mesonconf builddir/`` with no other arguments lists all
-configurable options meson provides.
-
-To rebuild from scratch, simply remove the build directory and run meson
-again:
-@code
-$> rm -r builddir/
-$> meson --prefix=....
-@endcode
-
-@subsection verifying_install Verifying the install
-
-To verify the install worked correctly, check that libinput.so.x.x.x is in
-the library path and that all symlinks point to the new library.
-<pre>
-$> ls -l /usr/lib64/libinput.*
--rwxr-xr-x 1 root root    946 Apr 28  2015 /usr/lib64/libinput.la
-lrwxrwxrwx 1 root root     19 Feb  1 15:12 /usr/lib64/libinput.so -> libinput.so.10.13.0
-lrwxrwxrwx 1 root root     19 Feb  1 15:12 /usr/lib64/libinput.so.10 -> libinput.so.10.13.0
--rwxr-xr-x 1 root root 204992 Feb  1 15:12 /usr/lib64/libinput.so.10.13.0
-</pre>
-
-@subsection reverting_install Reverting to the system-provided libinput package
-
-The recommended way to revert to the system install is to use the package
-manager to reinstall the libinput package. In some cases, this may leave
-files in the system (e.g. ```/usr/lib/libinput.la```) but these files are
-usually harmless. To definitely remove all files, run the following command
-from the libinput source directory:
-
-@code
-$> sudo ninja -C builddir/ uninstall
-# WARNING: Do not restart the computer/X/the Wayland compositor after
-# uninstall, reinstall the system package immediately!
-@endcode
-
-The following commands reinstall the current system package for libinput,
-overwriting manually installed files.
-
-<ul>
-<li><b>Debian/Ubuntu</b> based distributions: ```sudo apt-get install
---reinstall libinput```</li>
-<li><b>Fedora 22</b> and later: ```sudo dnf reinstall libinput```</li>
-<li><b>RHEL/CentOS/Fedora 21</b> and earlier: ```sudo yum reinstall libinput```</li>
-<li><b>openSUSE</b>: ```sudo zypper install --force libinput10```</li>
-<li><b>Arch</b>: ```sudo packman -S libinput```</li>
-</ul>
-
-@subsection building_selinux SELinux adjustments
-
-On systems with SELinux, overwriting the distribution-provided package with
-a manually built libinput may cause SELinux denials. This usually manifests
-when gdm does not start because it is denied access to libinput. The journal
-shows a log message in the form of:
-
-<pre>
-May 25 15:28:42 localhost.localdomain audit[23268]: AVC avc:  denied  { execute } for  pid=23268 comm="gnome-shell" path="/usr/lib64/libinput.so.10.12.2" dev="dm-0" ino=1709093 scontext=system_u:system_r:xdm_t:s0-s0:c0.c1023 tcontext=unconfined_u:object_r:user_home_t:s0 tclass=file permissive=0
-May 25 15:28:42 localhost.localdomain org.gnome.Shell.desktop[23270]: /usr/bin/gnome-shell: error while loading shared libraries: libinput.so.10: failed to map segment from shared object
-</pre>
-
-The summary of this error message is that gdm's gnome-shell runs in the
-```system_u:system_r:xdm_t``` context but libinput is installed with the
-context ```unconfined_u:object_r:user_home_t```.
-
-To avoid this issue, restore the SELinux context for any system files.
-
-<pre>
-$> sudo restorecon /usr/lib*/libinput.so.*
-</pre>
-
-This issue is tracked in https://github.com/mesonbuild/meson/issues/1967.
-
-@subsection building_dependencies Build dependencies
-
-libinput has a few build-time dependencies that must be installed prior to
-running configure. In most cases, it is sufficient to install the
-dependencies that your distribution uses to build the libinput package.
-These can be installed with one of the following commands:
-
-<ul>
-<li><b>Debian/Ubuntu</b> based distributions: ```sudo apt-get build-dep
-libinput```</li>
-<li><b>Fedora 22</b> and later: ```sudo dnf builddep libinput```</li>
-<li><b>RHEL/CentOS/Fedora 21</b> and earlier: ```sudo yum-builddep libinput```</li>
-<li><b>openSUSE</b>:
-<pre>
-$> sudo zypper modifyrepo --enable `zypper repos | grep source | awk '{print $5}'`
-$> sudo zypper source-install -d libinput10
-$> sudo zypper install autoconf automake libtool
-$> sudo zypper modifyrepo --disable `zypper repos | grep source | awk '{print $5}'`
-</pre>
-</li>
-<li><b>Arch</b>:
-<pre>
-$> sudo pacman -S asp
-$> cd $(mktemp -d)
-$> asp export libinput
-$> cd libinput
-$> makepkg --syncdeps --nobuild --noextract
-</pre>
-</li>
-</ul>
-
-If dependencies are missing, a message ```No package 'foo' found``` will be
-shown during the configure stage. See
-<a href="https://who-t.blogspot.com.au/2014/05/configure-fails-with-no-package-foo.html">this blog post here</a>.
-for instructions on how to fix it.
-
-@subsection building_libwacom Building without libwacom
-
-libwacom is required by libinput's tablet code to gather additional
-information about tablets that is not available from the kernel device
-itself. libwacom is required by default but can be skipped when @ref
-building.
-
-@code
-$> meson --prefix=/usr -Dlibwacom=false builddir
-@endcode
-
-It is not recommended to disable libwacom unless libinput is used in an
-environment where tablet support is not required. libinput provides tablet
-support even without libwacom, but some features may be missing or working
-differently.
-
-@subsection building_debug_gui Building without the graphical helper tool
-
-The @ref tools provide commandline features as well as graphical debugging
-features. To keep dependencies in check on some builds, the graphical
-features of the @ref tools can be disabled. By default, the `debug-gui`
-feature of the `libinput` tool is enabled and if the required libraries are
-not available, the build will fail. If the feature is not required, use the
-``--disable-debug-gui`` argument when @ref building.
-
-@code
-$> meson --prefix=/usr -Ddebug-gui=false builddir
-@endcode
-
-@subsection building_autotools Building with autotools
-
-<b>libinput no longer supports building with autotools.</b> These
-instructions are kept for users for libinput versions up to 1.8.x.
-
-A build with automake is usually the process below. A successful build
-requires the @ref building_dependencies to be installed at configure
-time.
-
-@code
-$> git clone git://anongit.freedesktop.org/git/wayland/libinput
-$> cd libinput
-$> ./autogen.sh --prefix=/usr --libdir=/usr/lib64
-$> make
-$> sudo make install
-$> sudo udevadm hwdb --update
-@endcode
-
-@note On Debian-based distributions including Ubuntu and its derivatives skip the
-```--libdir=/usr/lib64``` argument.
-
-To uninstall libinput as detailed in section @ref reverting_install, run
-
-@code
-$> sudo make uninstall
-# WARNING: Do not restart the computer/X/the Wayland compositor after make
-# uninstall, reinstall the system package immediately!
-@endcode
-
-To disable libwacom as detailed in section @ref building_libwacom, run
-
-@code
-$> ./autogen.sh --disable-libwacom --prefix=/usr --libdir=/usr/lib64
-@endcode
-
-To disable the graphical helper tool as detailed in section @ref
-building_debug_gui, run
-
-@code
-$> ./autogen.sh --disable-debug-gui --prefix=/usr --libdir=/usr/lib64
-@endcode
-
-
-@section building_against Building against libinput
-
-libinput provides a
-[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) file.
-Software that uses libinput should use pkg-config and the
-`PKG_CHECK_MODULES` autoconf macro.
-Otherwise, the most rudimentary way to compile and link a program against
-libinput is:
-
-@code
-    gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput`
-@endcode
-
-For further information on using pkgconfig see the pkg-config documentation.
-
-*/
-

doc/clickpad-softbuttons.dox

@@ -1,103 +0,0 @@
-/**
-@page clickpad_softbuttons Clickpad software button behavior
-
-Clickpad is the name given to touchpads without physical buttons below the
-touchpad. Instead, the whole touchpad acts as a button and left or right
-button clicks are distinguished by the location and/or number of fingers on
-the touchpad. <a href="http://www.synaptics.com/en/clickpad.php">"ClickPad" is
-a trademark by Synaptics Inc.</a> but for simplicity we refer to any
-touchpad with the above feature as Clickpad, regardless of the manufacturer.
-
-A clickpad is always marked with the <a
-href="https://www.kernel.org/doc/Documentation/input/event-codes.txt">INPUT_PROP_BUTTONPAD</a> property.
-To perform a right-click on a Clickpad, libinput provides @ref
-software_buttons and @ref clickfinger.
-
-In the page below, the term "click" shall refer to a physical button press
-and/or release of the touchpad, the term "button event" refers to the events
-generated by libinput and passed to the caller in response to a click.
-
-@section software_buttons Software button areas
-
-On most clickpads, this is the default behavior. The bottom of the touchpad
-is split into three distinct areas generate left, middle or right button
-events on click. The height of the button area depends on the hardware but
-is usually around 10mm.
-
-Left, right and middle button events can be triggered as follows:
-- if a finger is in the main area or the left button area, a click generates
-  left button events.
-- if a finger is in the right area, a click generates right button events.
-- if a finger is in the middle area, a click generates middle button events.
-
-The middle button is always centered on the touchpad and smaller in size
-than the left or right button. The actual size is device-dependent though as
-many touchpads do not have visible markings for the middle button the exact
-location of the button is not visibly obvious.
-
-@image html software-buttons.svg "Left, right and middle-button click with software button areas"
-
-@note If middle button emulation is enabled on a clickpad, only left and right
-button areas are available. For more details, see
-libinput_device_config_middle_emulation_set_enabled().
-
-If fingers are down in the main area in addition to fingers in the
-left or right button area, those fingers are are ignored.
-A release event always releases the buttons logically down, regardless of
-the current finger position
-
-The movement of a finger can alter the button area behavior:
-- if a finger starts in the main area and moves into the software button
-  area, the software buttons do not apply to that finger
-- a finger in the software button area does not move the pointer
-- if a finger moves out out of the button area it will control the pointer
-  if it's the first finger in the main area
-- once a finger has moved out of the button area, it cannot move back in and
-  trigger a right or middle button event
-
-On some touchpads, notably the 2015 Lenovo X1 Carbon 3rd series, the very
-bottom end of the touchpad is outside of the sensor range but it is possible
-to trigger a physical click there. To libinput, the click merely shows up as
-a left button click without any positional finger data and it is
-impossible to determine whether it is a left or a right click. libinput
-ignores such button clicks, this behavior is intentional.
-
-@section clickfinger Clickfinger behavior
-
-This is the default behavior on Apple touchpads.
-Here, a left, right, middle button event is generated when one, two, or
-three fingers are held down on the touchpad when a physical click is
-generated. The location of the fingers does not matter and there are no
-software-defined button areas.
-
-@image html clickfinger.svg "One, two and three-finger click with Clickfinger behavior"
-
-On some touchpads, libinput imposes a limit on how the fingers may be placed
-on the touchpad. In the most common use-case this allows for a user to
-trigger a click with the thumb while leaving the pointer-moving finger on
-the touchpad.
-
-@image html clickfinger-distance.svg "Illustration of the distance detection algorithm"
-
-In the illustration above the red area marks the proximity area around the
-first finger. Since the thumb is outside of that area libinput considers the
-click a single-finger click rather than a two-finger click.
-
-Clickfinger configuration can be enabled through the
-libinput_device_config_click_set_method() call. If clickfingers are
-enabled on a touchpad with top software buttons, the top area will keep
-acting as softbuttons for use with the trackpoint. Clickfingers will be used
-everywhere else on the touchpad.
-
-@section special_clickpads Special Clickpads
-
-The Lenovo *40 series laptops have a clickpad that provides two software button sections, one at
-the top and one at the bottom. See @ref t440_support "Lenovo *40 series touchpad support"
-for details on the top software button.
-
-Some Clickpads, notably some Cypress ones, perform right button detection in
-firmware and appear to userspace as if the touchpad had physical buttons.
-While physically clickpads, these are not handled by the software and
-treated like traditional touchpads.
-
-*/

doc/contributing.dox

@@ -1,18 +0,0 @@
-/**
-
-@page contributing Contributing to libinput
-
-Contributions to libinput are always welcome. Any patches should be sent to
-the
-[wayland-devel](https://lists.freedesktop.org/mailman/listinfo/wayland-devel)
-email list with a subject prefix of ````[PATCH libinput]````. The easiest
-way to achieve that is to run the following command in the libinput
-repository:
-
-	git config --add format.subjectprefix "PATCH libinput"
-
-Likewise, any new features should also be discussed publicly on the
-wayland-devel list.
-
-*/
-

doc/device-configuration-via-udev.dox

@@ -1,303 +0,0 @@
-/**
-@page udev_config Static device configuration via udev
-
-libinput supports some static configuration through udev properties.
-These properties are read when the device is initially added
-to libinput's device list, i.e. before the @ref
-LIBINPUT_EVENT_DEVICE_ADDED event is generated.
-
-The following udev properties are supported:
-<dl>
-<dt>LIBINPUT_CALIBRATION_MATRIX</dt>
-<dd>Sets the calibration matrix, see
-libinput_device_config_calibration_get_default_matrix(). If unset,
-defaults to the identity matrix.
-
-The udev property is parsed as 6 floating point numbers separated by a
-single space each (scanf(3) format "%f %f %f %f %f %f").
-The 6 values represent the first two rows of the calibration matrix as
-described in libinput_device_config_calibration_set_matrix().
-
-Example values are:
-@code
- ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
- ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
- ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
- ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
- ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 1 0" # reflect along y axis
-@endcode
-</dd>
-<dt>LIBINPUT_DEVICE_GROUP</dt>
-<dd>A string identifying the @ref libinput_device_group for this device. Two
-devices with the same property value are grouped into the same device group,
-the value itself is irrelevant otherwise.
-</dd>
-<dt>LIBINPUT_IGNORE_DEVICE</dt>
-<dd>If set to anything other than "0", the device is ignored by libinput.
-See @ref ignoring_devices for more details.
-</dd>
-<dt>ID_SEAT</dt>
-<dd>Assigns the physical @ref seats "seat" for this device. See
-libinput_seat_get_physical_name(). Defaults to "seat0".</dd>
-<dt>ID_INPUT</dt>
-<dd>If this property is set, the device is considered an input device. Any
-device with this property missing will be ignored, see @ref
-udev_device_type.</dt>
-</dd>
-<dt>ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
-ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
-ID_INPUT_ACCELEROMETER</dt>
-<dd>If any of the above is set, libinput initializes the device as the given
-type, see @ref udev_device_type. Note that for historical reasons more than
-one of these may be set at any time, libinput will select only one of these
-to determine the device type. To ensure libinput selects the correct device
-type, only set one of them.</dd>
-<dt>WL_SEAT</dt>
-<dd>Assigns the logical @ref seats "seat" for this device. See
-libinput_seat_get_logical_name()
-context. Defaults to "default".</dd>
-<dt>MOUSE_DPI</dt>
-<dd>HW resolution and sampling frequency of a relative pointer device.
-See @ref motion_normalization for details.
-</dd>
-<dt>MOUSE_WHEEL_CLICK_ANGLE</dt>
-<dd>The angle in degrees for each click on a mouse wheel. See
-libinput_pointer_get_axis_source() for details.
-</dd>
-<dt>LIBINPUT_MODEL_*</dt>
-<dd><b>This prefix is reserved as private API, do not use.</b> See @ref
-model_specific_configuration for details.
-</dd>
-<dt>LIBINPUT_ATTR_*</dt>
-<dd><b>This prefix is reserved as private API, do not use.</b> See @ref
-model_specific_configuration for details.
-</dd>
-</dl>
-
-Below is an example udev rule to assign "seat1" to a device from vendor
-0x012a with the model ID of 0x034b.
-@code
-ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
-ENV{ID_MODEL_ID}=="034b", ENV{ID_SEAT}="seat1"
-@endcode
-
-
-@section udev_device_type Device type assignment via udev
-
-libinput requires the <b>ID_INPUT</b> property to be set on a device,
-otherwise the device will be ignored. In addition, one of <b>
-ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
-ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
-ID_INPUT_ACCELEROMETER</b> must be set on the device to determine the
-device type. The usual error handling applies within libinput and a device
-type label does not guarantee that the device is initialized by libinput.
-If a device fails to meet the requirements for a device type (e.g. a keyboard
-labelled as touchpad) the device will not be available through libinput.
-
-Only one device type should be set per device at a type, though libinput can
-handle some combinations for historical reasons.
-
-Below is an example udev rule  to remove an <b>ID_INPUT_TOUCHPAD</b> setting
-and change it into an <b>ID_INPUT_TABLET</b> setting. This rule would apply
-for a device with the vendor/model ID of 012a/034b.
-
-@code
-ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \
-ENV{ID_MODEL_ID}=="034b", ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1"
-@endcode
-
-
-@section ignoring_devices Ignoring specific devices
-
-If a device has the <b>LIBINPUT_IGNORE_DEVICE</b> udev property set to any
-value but "0", that device is not initialized by libinput. For a context
-created with libinput_udev_create_context(), the device is silently ignored
-and never shows up. If the device is added with libinput_path_add_device()
-to a context created with libinput_path_create_context(), adding the device
-will fail and return NULL (see that function's documentation for more
-information).
-
-If the property value is exactly "0", then the property is considered unset
-and libinput initializes the device normally.
-
-This property should be used for devices that are correctly detected as
-input devices (see @ref udev_device_type) but that should not be used by
-libinput. It is recommended that devices that should not be handled as input
-devices at all unset the <b>ID_INPUT</b> and related properties instead. The
-<b>LIBINPUT_IGNORE_DEVICE</b> property signals that only libinput should
-ignore this property but other parts of the stack (if any) should continue
-treating this device normally.
-
-
-@section model_specific_configuration Model-specific configuration
-
-libinput reserves the property prefixes <b>LIBINPUT_MODEL_</b> and
-<b>LIBINPUT_ATTR_</b> for model-specific configuration. <b>These prefixes
-are reserved as private API, do not use.</b>
-
-The effect of these properties may be to enable or disable certain
-features on a specific device or set of devices, to change configuration
-defaults or any other reason. The effects of setting these properties, the
-format of the property and the value of the property are subject to change
-at any time.
-
-@subsection model_specific_configuration_x220fw81 Lenovo x220 with touchpad firmware v8.1
-
-The property <b>LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81</b> may be set by a
-user in a local hwdb file. This property designates the touchpad on a Lenovo
-x220 with a touchpad firmware version 8.1. When this firmware version is
-installed, the touchpad is imprecise. The touchpad device does not send
-continuos x/y axis position updates, a behavior also observed on its
-successor model, the Lenovo x230 which has the same firmware version. If the
-above property is set, libinput adjusts its behavior to better suit this
-particular model.
-
-The touchpad firmware version cannot be detected automatically by libinput,
-local configuration is required to set this property. Refer to the libinput
-model quirks hwdb for instructions.
-
-This property must not be used for any other purpose, no specific behavior
-is guaranteed.
-
-
-@section hwdb Configuring the hwdb
-
-This section outlines how to add an entry to the <a
-href="https://www.freedesktop.org/software/systemd/man/hwdb.html">udev
-hwdb</a> and reload properties so they are available to libinput.
-
-The hwdb contains a set of match rules that assign udev properties that are
-available to libinput when the device is connected and/or libinput is
-initialized. This section only describes the hwdb in relation to libinput,
-it is not a full documentation on how the hwdb works.
-
-@note **The use of the hwdb by libinput is not part of the public API. It may
-change at any time. Once tested, changes to the hwdb must be submitted
-upstream.**
-
-@subsection hwdb_querying Querying the hwdb
-
-libinput only uses device nodes in the form of `/dev/input/eventX` where X
-is the number of the specific device. Running `libinput debug-events` lists
-all devices currently available to libinput and their event node name:
-
-    $> sudo libinput debug-events
-    -event2   DEVICE_ADDED     Power Button                      seat0 default group1  cap:k
-    -event5   DEVICE_ADDED     Video Bus                         seat0 default group2  cap:k
-    -event0   DEVICE_ADDED     Lid Switch                        seat0 default group3  cap:S
-
-    ...
-
-Note the event node name for your device and translate it into a syspath in
-the form of `/sys/class/input/eventX`. This path can be supplied to `udevadm
-info`
-
-    $> udevadm info
-    P: /devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
-    N: input/event0
-    E: DEVNAME=/dev/input/event0
-    E: DEVPATH=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
-    E: ID_INPUT=1
-    E: ID_INPUT_SWITCH=1
-    E: MAJOR=13
-    E: MINOR=64
-    E: SUBSYSTEM=input
-    E: TAGS=:power-switch:
-    E: USEC_INITIALIZED=7167898
-
-Lines starting with `E:` are udev properties available to libinput. For
-example, the above device's `ID_INPUT_SWITCH` property will cause libinput
-to treat this device as switch device.
-
-
-@subsection hwdb_reloading Reloading the hwdb
-
-The actual hwdb is stored in binary file on-disk and must be updated
-manually whenever a `.hwdb` file changes. This is required both when a user
-manually edits the `.hwdb` file but also when the git tree is updated (and
-that update causes a hwdb change).
-
-To update the binary file on-disk, run:
-
-    sudo udevadm hwdb --update
-
-Then, to trigger a reload of all properties on your device, run:
-
-    sudo udevadm trigger /sys/class/input/eventX
-
-Then check with `udevadm info` whether the properties were updated, see @ref
-hwdb_querying. If a new property does not appear on the device, use `udevadm
-test` to check for error messages by udev and the hwdb (e.g. syntax errors
-in the udev rules files).
-
-    sudo udevadm test /sys/class/input/eventX
-
-@subsection hwdb_modifying Modifying the hwdb
-
-This section applies to users that need to add, change, or remove a hwdb
-entry for their device. Note that **the hwdb is not part of the public API
-and may change at any time**. Once a device has been made to work, the
-change must be submitted to the libinput bugzilla, see @ref reporting_bugs.
-
-hwdb entries are only applied if a udev rules calls out to the hwdb with the
-right match format. libinput ships with a set of rules to query the hwdb,
-the different rules are reflected by their prefix. Again, **this is not part
-of the public API**. libinput's matches are
-composed of a literal "libinput", then either the device name and dmi
-modalias, or the device types and the input modalias. Any part of the hwdb
-match line can be a glob by using a literal `*`. For example:
-
-    libinput:keyboard:input:b0011v*
-    libinput:touchpad:input:b0003v05ACp*
-    libinput:touchpad:input:b0003v05ACp021A*
-
-This type of matching is the preferred one for any removable device (USB,
-Bluetooth, ...) that can be uniquely identified by the bustype, vendor and
-product ID. The first line matches any keyboard device on the
-serial bus (0x0011). The second line matches any touchpad device
-with a vendor ID of 0x05AC. The third line matches any touchpad device
-with a vendor ID of 0x05AC and a product ID of 0x021A. The `input:b...`
-string is available in the device's modalias file
-`/sys/class/input/eventX/device/modalias`.
-
-In the case of built-in devices that do not have a unique id, we
-need to use the host system's dmi information. For example:
-
-    libinput:name:*Lid Switch*:dmi:*svnLENOVO:*pvrThinkPadT440*
-
-This match applies to any device with a name **containing** "Led Switch"
-that is on a Lenovo T440 system.  The dmi modalias is available in
-`/sys/class/dmi/id/modalias`. For example, on the T440 matched above, the
-modalias is
-
-    dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn3453453678:pvrThinkPadT440s:rvnLENOVO:rn2012345223:rvrABC123KKK123B:cvnLENOVO:ct10:cvrNotAvailable:
-
-The dmi should always be shortened to the sections that uniquely identify
-the type system, in this case the vendor (svn) and the product version (pvr).
-Failing to shorten the system may mean that the hwdb match rule only applies
-to your specific system, rather than all systems of that type, or that the
-rule no longer applies after a firmware update.
-
-The hwdb match string is the first portion of the hwdb entry. The second
-portion is the property to set. Each hwdb entry may match on multiple
-devices and may apply multiple properties. For example:
-
-
-    libinput:touchpad:input:b0003v05ACp*
-      THIS_IS_AN_APPLE_DEVICE=1
-
-    libinput:touchpad:input:b0003v05ACp*
-    libinput:name:*Lid Switch*:dmi:*svnLENOVO:*pvrThinkPadT440*
-      FOO=1
-      BAR=2
-
-In the example above, any matching touchpad device will have all three
-properties applied, the lid switch device only has FOO and BAR.
-
-The hwdb does not allow removing properties. Where a property must be unset,
-it should be set to 0.
-
-Any user-specific hwdb entries should be placed in a file
-`/etc/udev/hwdb.d/99-somename.hwdb`. See @ref hwdb_reloading for
-instructions on how to reload the hwdb once the file is in place.
-*/

doc/faqs.dox

@@ -1,223 +0,0 @@
-/**
-@page faq FAQs - Frequently Asked Questions
-
-Frequently asked questions about libinput.
-
-@tableofcontents
-
-@section faq_feature Why doesn't libinput support ...?
-
-First, read @ref what_is_libinput If you have a feature that you think
-libinput needs to support, please file a bug report. See @ref reporting_bugs
-for more details.
-
-@section faq_fast_mouse My mouse moves too fast, even at the slowest setting
-
-This is a symptom of high-dpi mice (greater than 1000dpi). These devices
-need a udev hwdb entry to normalize their motion. See @ref
-motion_normalization for a detailed explanation.
-
-@section faq_fast_trackpoint My trackpoint moves too slow or too fast
-
-This is a symptom of an invalid trackpoint range. These devices need a udev
-hwdb entry to specify the range available so libinput can adjust the pointer
-acceleration accordingly. See @ref trackpoint_range for a detailed explanation.
-
-@section faq_enable_tapping Why isn't touchpad tap-to-click enabled by default
-
-See @ref tapping_default
-
-@section faq_touchpad_pressure Why does my touchpad lose track of touches
-
-The most common cause for this is an incorrect pressure threshold range.
-See @ref touchpad_pressure for more info.
-
-@section faq_kinetic_scrolling Kinetic scrolling does not work
-
-The X.Org synaptics driver implemented kinetic scrolling in the driver. It
-measures the scroll speed and once the finger leaves the touchpad the driver
-keeps sending scroll events for a predetermined time. This effectively
-provides for kinetic scrolling without client support but triggers an
-unfixable [bug](https://bugs.freedesktop.org/show_bug.cgi?id=38909): the
-client cannot know that the events are from a kinetic scroll source. Scroll
-events in X are always sent to the current cursor position, a movement of the
-cursor after lifting the finger will send the kinetic scroll events to the
-new client, something the user does not usually expect. A key event during
-the kinetic scroll procedure causes side-effects such as triggering zoom.
-
-libinput does not implement kinetic scrolling for touchpads. Instead it
-provides the libinput_event_pointer_get_axis_source() function that enables
-callers to implement kinetic scrolling on a per-widget basis, see @ref
-scroll_sources.
-
-@section faq_gpl Is libinput GPL-licensed?
-
-No, libinput is MIT licensed. The Linux kernel header file linux/input.h in
-libinput's tree is provided to ensure the same behavior regardless of which
-kernel version libinput is built on. It does not make libinput GPL-licensed.
-
-@section faq_config_options Where is the configuration stored?
-
-libinput does not store configuration options, it is up to the caller to
-manage these and decide which configuration option to apply to each device.
-This must be done at startup, after a resume and whenever a new device is
-detected.
-
-One commonly used way to configure libinput is to have the Wayland
-compositor expose a compositor-specific configuration option. For example,
-in a GNOME stack, the gnome-control-center modifies dconf entries. These
-changes are read by mutter and applied to libinput. Changing these entries
-via the gsettings commandline tool has the same effect.
-
-Another commonly used way to configure libinput is to have xorg.conf.d
-snippets. When libinput is used with the xf86-input-libinput driver in an
-X.Org stack, these options are read on startup and apply to each device.
-Changing properties at runtime with the xinput commandline tool has the same
-effect.
-
-In both cases, the selection of available options and how they are exposed
-depends on the libinput caller (e.g. mutter or xf86-input-libinput).
-
-@dotfile libinput-stack-gnome.gv
-
-This has an effect on the availability of configuration options: if an
-option is not exposed by the intermediary, it cannot be configured by the
-client. Also some configuration options that are provided by the
-intermediary may not be libinput-specific configuration options.
-
-@section faq_configure_wayland How do I configure my device on Wayland?
-
-See @ref faq_config_options Use the configuration tool provided by your
-desktop environment (e.g. gnome-control-center) or direct access to your
-desktop environment's configuration storage (e.g. gsettings).
-
-@section faq_configure_xorg How do I configure my device on X?
-
-See @ref faq_config_options  If your desktop environment does not provide a
-graphical configuration tool you can use an
-<a href="https://www.x.org/archive/current/doc/man/man5/xorg.conf.5.xhtml">xorg.conf.d snippet</a>.
-Usually, such a snippet looks like this:
-<pre>
-$> cat /etc/X11/xorg.conf.d/99-libinput-custom-config.conf
-Section "InputClass"
-  Identifier "something to identify this snippet"
-  MatchDriver "libinput"
-  MatchProduct "substring of the device name"
-  Option "some option name" "the option value"
-EndSection
-</pre>
-
-The identifier is merely a human-readable string that shows up in the log
-file. The MatchProduct line should contain the device name or a substring of
-the device name that the snippet should apply to. For a full list of option
-names and permitted values, see the
-<a href="https://www.mankier.com/4/libinput">libinput man page</a>.
-xorg.conf.d snippets like the above apply to hotplugged devices but can be
-overwritten at runtime by desktop tools. Multiple snippets may be placed
-into the same file.
-
-For run-time configuration and testing, the
-<a href="https://www.x.org/archive/X11R7.5/doc/man/man1/xinput.1.html">xinput</a>
-debugging tool can modify a devices' properties. See the
-<a href="https://www.mankier.com/4/libinput">libinput man page</a>
-for supported property names and values. Usually, an invocation looks like
-this:
-<pre>
-$> xinput set-prop "the device name" "the property name" value [value2] [value3]
-</pre>
-
-@note
-Changes performed by xinput do not persist across device hotplugs. xinput is
-considered a debugging and testing tool only and should not be used for
-permanent configurations.
-
-@section faq_configuration Can you add a configuration option for $FEATURE?
-
-No. At least that's going to be the initial answer. Read <a
-href="http://who-t.blogspot.com/2016/04/why-libinput-doesnt-have-lot-of-config.html">Why
-libinput doesn't have a lot of configuration options</a> first.
-Configuration options for most features are a signal that we are incapable
-of handling it correctly. To get to that point, we want to be sure we're
-truly incapable of doing so. libinput has several features that
-are handled automatically (and correctly) that users wanted to have
-configuration options for initially.
-
-So the answer to this question will almost always be 'no'. A configuration
-option is, in most cases, a cop-out.
-
-@section faq_synclient Why don't synclient and syndaemon work with libinput?
-
-Synclient and syndaemon rely on X input device properties that are specific
-to the xf86-input-synaptics X.Org input driver. Both were written when the
-synaptics driver was the only commmon touchpad driver in existence. They
-assume that if the properties aren't available, no touchpad is available
-either. The xf86-input-libinput X.Org input driver does not export these
-driver-specific properties, synclient/syndaemon will thus not detect the
-touchpad and refuse to work. Other tools that rely on synclient/syndaemon or
-those same properties also do not work with xf86-input-libinput.
-
-Most of syndaemon's functionality is built into libinput, see @ref
-disable-while-typing. synclient is merely a configuration tool, see
-@ref faq_configure_xorg for similar functionality.
-
-See also the blog posts
-<a
-href="http://who-t.blogspot.com.au/2017/01/the-definitive-guide-to-synclient.html">The
-definitive guide to synclient</a> and
-<a href="http://who-t.blogspot.com.au/2016/12/the-future-of-xinput-xmodmap-setxkbmap.html">
-The future of xinput, xmodmap, setxkbmap, xsetwacom and other tools under
-Wayland</a>
-
-@section faq_tablets Does libinput support non-Wacom tablets?
-
-Yes, though unfortunately many non-Wacom tablets suffer from bad firmware
-and don't send the required events. But they should all work nonetheless. If
-you have a tablet that does not work with libinput, please @ref
-reporting_bugs "file a bug".
-
-@section faq_tablet_capabilities My tablet doesn't work
-
-If you see the message
-<pre>
-libinput bug: device does not meet tablet criteria. Ignoring this device.
-</pre>
-
-or the message
-<pre>
-missing tablet capabilities [...] Ignoring this device.
-</pre>
-
-your tablet device does not have the required capabilities to be treated as
-a tablet. This is usually a problem with the device and the kernel driver.
-See @ref tablet-capabilities for more details.
-
-@section faq_hwdb_changes How to apply hwdb changes
-
-Sometimes users are asked to test updates to the <a
-href="https://www.freedesktop.org/software/systemd/man/hwdb.html">udev
-hwdb</a> or patches that include a change to the hwdb. See @ref hwdb for
-details on the hwdb and how to modify it locally.
-
-@section faq_timer_offset What causes the "timer offset negative" warning?
-
-libinput relies on the caller to call libinput_dispatch() whenever data is
-available on the epoll-fd. Doing so will process the state of all devices
-and can trigger some timers to be set (e.g. palm detection, tap-to-click,
-disable-while-typing, etc.). Internally, libinput's time offsets are always
-based on the event time of the triggering event.
-
-For example, a touch event with time T may trigger a timer for the time T +
-180ms. When setting a timer, libinput checks the wall clock time to ensure
-that this time T + offset is still in the future. If not, the warning is
-logged.
-
-When this warning appears, it simply means that too much time has passed
-between the event occurring (and the epoll-fd triggering) and the current
-time. In almost all cases this is an indication of the caller being
-overloaded and not handling events as speedily as required.
-
-The warning has no immediate effect on libinput's behavior but some of the
-functionality that relies on the timer may be impeded (e.g. palms are not
-detected as they should be).
-
-*/

doc/gestures.dox

@@ -1,129 +0,0 @@
-/**
-@page gestures Gestures
-
-libinput supports basic gestures on touchpads and other indirect input
-devices. Two types of gestures are supported: @ref gestures_pinch and @ref
-gestures_swipe. Support for gestures depends on the hardware device, most
-touchpads support both gestures and any device that may send gesture events
-has the @ref LIBINPUT_DEVICE_CAP_GESTURE capability set.
-
-Note that libinput **does not** support gestures on touchscreens, see
-@ref gestures_touchscreens.
-
-@section gestures_lifetime Lifetime of a gesture
-
-A gesture's lifetime has three distinct stages: begin, update and end, each
-with their own event types. Begin is sent when the fingers are first set
-down or libinput decides that the gesture begins. For @ref gestures_pinch
-this sets the initial scale. Any events changing properties of the gesture
-are sent as update events. On termination of the gesture, an end event is
-sent.
-
-A gesture includes the finger count (see
-libinput_event_gesture_get_finger_count()) and that finger count remains the
-same for the lifetime of a gesture. Thus, if a user puts down a fourth
-finger during a three-finger swipe gesture, libinput will end
-the three-finger gesture and, if applicable, start a four-finger swipe
-gesture. A caller may decide that those gestures are semantically identical
-and continue the two gestures as one single gesture.
-
-@see LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
-@see LIBINPUT_EVENT_GESTURE_PINCH_UPDATE
-@see LIBINPUT_EVENT_GESTURE_PINCH_END
-@see LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
-@see LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE
-@see LIBINPUT_EVENT_GESTURE_SWIPE_END
-
-@section gestures_pinch Pinch gestures
-
-Pinch gestures are executed when two or more fingers are located on the
-touchpad and are either changing the relative distance to each other
-(pinching) or are changing the relative angle (rotate). Pinch gestures may
-change both rotation and distance at the same time. For such gestures,
-libinput calculates a logical center for the gestures and provides the
-caller with the delta x/y coordinates of that center, the relative angle of
-the fingers compared to the previous event, and the absolute scale compared
-to the initial finger position.
-
-@image html pinch-gestures.svg "The pinch and rotate gestures"
-
-The illustration above shows a basic pinch in the left image and a rotate in
-the right angle. Not shown is a movement of the logical center if the
-fingers move unevenly. Such a movement is supported by libinput, it is
-merely left out of the illustration.
-
-Note that while position and angle is relative to the previous event, the
-scale is always absolute and a multiplier of the initial finger position's
-scale.
-
-@section gestures_swipe Swipe gestures
-
-Swipe gestures are executed when three or more fingers are moved
-synchronously in the same direction. libinput provides x and y coordinates
-in the gesture and thus allows swipe gestures in any direction, including
-the tracing of complex paths. It is up to the caller to interpret the
-gesture into an action or limit a gesture to specific directions only.
-
-@image html swipe-gestures.svg "The swipe gestures"
-
-The illustration above shows a vertical three-finger swipe. The coordinates
-provided during the gesture are the movements of the logical center.
-
-@section gestures_touchscreens Touchscreen gestures
-
-Touchscreen gestures are **not** interpreted by libinput. Rather, any touch
-point is passed to the caller and any interpretation of gestures is up to
-the caller or, eventually, the X or Wayland client.
-
-Interpreting gestures on a touchscreen requires context that libinput does
-not have, such as the location of windows and other virtual objects on the
-screen as well as the context of those virtual objects:
-
-@image html touchscreen-gestures.svg "Context-sensitivity of touchscreen gestures"
-
-In this example, the finger movements are identical but in the left case
-both fingers are located within the same window, thus suggesting an attempt
-to zoom. In the right case  both fingers are located on a window border,
-thus suggesting a window movement. libinput only has knowledge of the finger
-coordinates (and even then only in device coordinates, not in screen
-coordinates) and thus cannot differentiate the two.
-
-@section gestures_softbuttons Gestures with enabled software buttons
-
-If the touchpad device is a @ref touchpads_buttons_clickpads "Clickpad", it
-is recommended that a caller switches to @ref clickfinger.
-Usually fingers placed in a @ref software_buttons "software button area" is not
-considered for gestures, resulting in some gestures to be interpreted as
-pointer motion or two-finger scroll events.
-
-@image html pinch-gestures-softbuttons.svg "Interference of software buttons and pinch gestures"
-
-In the example above, the software button area is highlighted in red. The
-user executes a three-finger pinch gesture, with the thumb remaining in the
-software button area. libinput ignores fingers within the software button
-areas, the movement of the remaining fingers is thus interpreted as a
-two-finger scroll motion.
-
-@section gestures_twofinger_touchpads Gestures on two-finger touchpads
-
-As of kernel 4.2, many @ref touchpads_touch_partial_mt provide only two
-slots. This affects how gestures can be interpreted. Touchpads with only two
-slots can identify two touches by position but can usually tell that there
-is a third (or fourth) finger down on the touchpad - without providing
-positional information for that finger.
-
-Touchpoints are assigned in sequential order and only the first two touch
-points are trackable. For libinput this produces an ambiguity where it is
-impossible to detect whether a gesture is a pinch gesture or a swipe gesture
-whenever a user puts the index and middle finger down first. Since the third
-finger does not have positional information, it's location cannot be
-determined.
-
-@image html gesture-2fg-ambiguity.svg "Ambiguity of three-finger gestures on two-finger touchpads"
-
-The image above illustrates this ambiguity. The index and middle finger are
-set down first, the data stream from both finger positions looks identical.
-In this case, libinput assumes the fingers are in a horizontal arrangement
-(the right image above) and use a swipe gesture.
-
-*/

doc/page-hierarchy.dox

@@ -1,57 +0,0 @@
-/**
-
-@page misc Users
-
-- @subpage what_is_libinput
-- @subpage faq
-- @subpage tools
-- @subpage reporting_bugs
-
-@page touchpads Touchpads
-
-- @subpage scrolling
-- @subpage clickpad_softbuttons
-- @subpage tapping
-- @subpage gestures
-- @subpage touchpad_pressure
-- @subpage palm_detection
-- @subpage t440_support
-- @subpage touchpad_jumping_cursor
-- @subpage absolute_coordinate_ranges
-- @subpage touchpad_jitter
-
-@page touchscreens Touchscreens
-
-- @subpage absolute_axes
-
-@page pointers Mice, Trackballs, etc.
-
-- @subpage motion_normalization
-- @subpage middle_button_emulation
-- @subpage button_debouncing
-- @subpage trackpoints
-
-@page tablets Graphics Tablets
-
-- @subpage tablet-support
-
-@page general General 
-
-- @subpage udev_config
-- @subpage seats
-- @subpage timestamps
-
-@page developers Developers
-
-Contributions to libinput are always welcome. See the links below for
-specific documentation.
-
-- @subpage what_is_libinput
-- @subpage contributing
-- @subpage architecture
-- @subpage building_libinput
-- @subpage test-suite
-- @subpage tools
-- @subpage pointer-acceleration
-
-*/

doc/pointer-acceleration.dox

@@ -1,156 +0,0 @@
-/**
-@page pointer-acceleration  Pointer acceleration
-
-libinput uses device-specific pointer acceleration methods, with the default
-being the @ref ptraccel-linear. The methods share common properties, such as
-@ref ptraccel-velocity.
-
-This page explains the high-level concepts used in the code. It aims to
-provide an overview for developers and is not necessarily useful for
-users.
-
-@section ptraccel-profiles Pointer acceleration profiles
-
-The profile decides the general method of pointer acceleration.
-libinput currently supports two profiles: "adaptive" and "flat". The aptive
-profile is the default profile for all devices and takes the current speed
-of the device into account when deciding on acceleration. The flat profile
-is simply a constant factor applied to all device deltas, regardless of the
-speed of motion (see @ref ptraccel-profile-flat). Most of this document
-describes the adaptive pointer acceleration.
-
-@section ptraccel-velocity Velocity calculation
-
-The device's speed of movement is measured across multiple input events
-through so-called "trackers". Each event prepends a the tracker item, each
-subsequent tracker contains the delta of that item to the current position,
-the timestamp of the event that created it and the cardinal direction of the
-movement at the time. If a device moves into the same direction, the
-velocity is calculated across multiple trackers. For example, if a device
-moves steadily for 10 events to the left, the velocity is calculated across
-all 10 events.
-
-Whenever the movement changes direction or significantly changes speed, the
-velocity is calculated from the direction/speed change only. For example, if
-a device moves steadily for 8 events to the left and then 2 events to the
-right, the velocity is only that of the last 2 events.
-
-An extra time limit prevents events that are too old to factor into the
-velocity calculation. For example, if a device moves steadily for 5 events
-to the left, then pauses, then moves again for 5 events to the left, only
-the last 5 events are used for velocity calculation.
-
-The velocity is then used to calculate the acceleration factor
-
-@section ptraccel-factor Acceleration factor
-
-The acceleration factor is the final outcome of the pointer acceleration
-calculations. It is a unitless factor that is applied to the current delta,
-a factor of 2 doubles the delta (i.e. speeds up the movement), a factor of
-less than 1 reduces the delta (i.e. slows the movement).
-
-Any factor less than 1 requires the user to move the device further to move
-the visible pointer. This is called deceleration and enables high precision
-target selection through subpixel movements. libinput's current maximum
-deceleration factor is 0.3 (i.e. slow down to 30% of the pointer speed).
-
-A factor higher than 1 moves the pointer further than the physical device
-moves. This is acceleration and allows a user to cross the screen quickly
-but effectively skips pixels. libinput's current maximum acceleration factor
-is 3.5.
-
-@section ptraccel-linear Linear pointer acceleration
-
-The linear pointer acceleration method is the default for most pointer
-devices. It provides deceleration at very slow movements, a 1:1 mapping for
-regular movements and a linear increase to the maximum acceleration factor
-for fast movements.
-
-Linear pointer acceleration applies to devices with above 1000dpi resolution
-and after @ref motion_normalization is applied.
-
-@image html ptraccel-linear.svg "Linear pointer acceleration"
-
-The image above shows the linear pointer acceleration settings at various
-speeds. The line for 0.0 is the default acceleration curve, speed settings
-above 0.0 accelerate sooner, faster and to a higher maximum acceleration.
-Speed settings below 0 delay when acceleration kicks in, how soon the
-maximum acceleration is reached and the maximum acceleration factor.
-
-Extremely low speed settings provide no acceleration and additionally
-decelerate all movement by a constant factor.
-
-@section ptraccel-low-dpi Pointer acceleration for low-dpi devices
-
-Low-dpi devices are those with a physical resolution of less than 1000 dots
-per inch (dpi). The pointer acceleration is adjusted to provide roughly the
-same feel for all devices at normal to high speeds. At slow speeds, the
-pointer acceleration works on device-units rather than normalized
-coordinates (see @ref motion_normalization).
-
-@image html ptraccel-low-dpi.svg "Pointer acceleration for low-dpi devices"
-
-The image above shows the default pointer acceleration curve for a speed of
-0.0 at different DPI settings. A device with low DPI has the acceleration
-applied sooner and with a stronger acceleration factor.
-
-@section ptraccel-touchpad Pointer acceleration on touchpads
-
-Touchpad pointer acceleration uses the same approach as the @ref
-ptraccel-linear profile, with a constant deceleration factor applied. The
-user expectation of how much a pointer should move in response to finger
-movement is different to that of a mouse device, hence the constant
-deceleration factor.
-
-@image html ptraccel-touchpad.svg "Pointer acceleration curve for touchpads"
-
-The image above shows the touchpad acceleration profile in comparison to the
-@ref ptraccel-linear. The shape of the curve is identical but vertically squashed.
-
-@section ptraccel-trackpoint Pointer acceleration on trackpoints
-
-The main difference between trackpoint hardware and mice or touchpads is
-that trackpoint speed is a function of pressure rather than moving speed.
-But trackpoint hardware is quite varied in how it reacts to user pressure
-and unlike other devices it cannot easily be normalized for physical
-properties. Measuring pressure objectively across a variety of hardware is
-nontrivial.
-
-libinput's pointer acceleration is a function of the total available
-pressure range on a device. See @ref trackpoint_range for details.
-
-libinput relies on some system-wide configured properties, specifically the
-@ref udev_config. The property that influences trackpoint acceleration is
-`LIBINPUT_ATTR_TRACKPOINT_RANGE` which specifies the total delta range for
-the trackpoint. See @ref trackpoint_range for details.
-
-Additionally, some trackpoints provide the ability to adjust the sensitivity in
-hardware by modifying a sysfs file on the serio node. The udev property
-`POINTINGSTICK_SENSITIVITY` indicates the desired value, a udev
-builtin is expected to apply this to the device, i.e.  libinput does not
-handle this property. Once applied, the sensitivity adjusts the deltas
-coming out of the hardware. When the sensitivity changes, the trackpoint
-range changes and thus the `LIBINPUT_ATTR_TRACKPOINT_RANGE` property
-becomes invalid.
-
-As of version 1.9, libinput does not parse the `POINTINGSTICK_CONST_ACCEL` property anymore.
-
-@image html ptraccel-trackpoint.svg "Pointer acceleration curves for trackpoints"
-
-The image above shows the trackpoint acceleration profile for each input
-delta.
-
-@section ptraccel-profile-flat The flat pointer acceleration profile
-
-In a flat profile, the acceleration factor is constant regardless of the
-velocity of the pointer and each delta (dx, dy) results in an accelerated delta
-(dx * factor, dy * factor). This provides 1:1 movement between the device
-and the pointer on-screen.
-
-@section ptraccel-tablet Pointer acceleration on tablets
-
-Pointer acceleration for relative motion on tablet devices is a flat
-acceleration, with the speed setting slowing down or speeding up the pointer
-motion by a constant factor. Tablets do not allow for switchable profiles.
-
-*/

doc/reporting-bugs.dox

@@ -1,295 +0,0 @@
-/**
-@page reporting_bugs Reporting bugs
-
-A new bug can be filed here:
-https://bugs.freedesktop.org/enter_bug.cgi?product=Wayland&component=libinput
-
-When reporting bugs against libinput, please follow the instructions below
-and provide the required data. You will need:
-
-- a reliable @ref reporting_bugs_reproducer "reproducer" for the bug
-- an @ref evemu "evemu recording" of the device while the bug is reproduced
-- device-specific information, see
-	- @ref reporting_bugs_touchpad
-	- @ref reporting_bugs_mouse
-	- @ref reporting_bugs_keyboard
-	- @ref reporting_bugs_trackpoint
-	- @ref reporting_bugs_other
-- the @ref reporting_bugs_version "libinput version" you are on.
-- the @ref reporting_bugs_options "configuration options" you have set
-- a bugzilla account
-
-If you don't have all of the above, provide a reason why not. Unless the
-reason is justified, the bug will have low priority. Remember, libinput has
-a lot of users but very few developers.
-
-Stay technical, on-topic, and keep the description concise.
-
-@section reporting_bugs_version Obtaining the libinput version
-
-If your libinput version is older than the current stable branch, you will
-get asked to try the latest version.
-
-If you run a distribution-provided libinput, use the package manager to get
-the **full** package name and version of libinput, e.g.
-- `rpm -q libinput`
-- `dpkg -s libinput10`
-
-If you run a self-compiled version of libinput provide the git commit you
-have built or the tarball name.
-
-As a last resort, use `libinput-list-devices --version`
-
-@section reporting_bugs_reproducer Reproducing bugs
-
-Try to identify the bug by reproducing it reliably. Bugs without a
-reliable reproducer will have lowest priority. The more specific a bug
-description and reproducer is, the easier it is to fix.
-
-Try to replicate the series of events that lead to the bug being triggered.
-Narrow it down until you have a reliable sequence that can trigger the bug.
-For the vast majority of bugs you should not take longer than 5 seconds or
-three interactions (clicks, touches, taps, ...) with the device to
-reproduce. If it takes longer than that, you can narrow it down further.
-
-Once you can reproduce it, use the @ref libinput-debug-events helper tool.
-The output is textual and can help identify whether the bug is in libinput
-at all. Note that any configuration options you have set must be specified
-on the commandline, see the @ref libinput-debug-events
-"libinput-debug-events" man page. Use the `--verbose` flag to get more
-information about how libinput processes events.
-
-If the bug cannot be reproduced with the @ref libinput-debug-events helper,
-even with the correct configuration options set, it is likely not a bug in
-libinput.
-
-@section reporting_bugs_options libinput configuration settings
-
-libinput has a number of device-specific default configuration settings that
-may differ from the ones your desktop environment picks by default. You may
-have changed some options in a settings panel or in an the xorg.conf snippet
-yourself.
-
-You must provide these options in the bug report, otherwise a developer
-reproducing the issue may not be able to do so.
-
-If you are on X11, the current settings can be can be obtained with
-`xinput list-props "your device name"`. Use `xinput list` to
-obtain the device name.
-
-If you are on Wayland, provide a manual summary of the options you have
-changed from the default (e.g. "I enabled tap-to-click").
-
-@section reporting_bugs_touchpad Reporting touchpad bugs
-
-When you file a bug, please attach the following information:
-
-- a virtual description of your input device, see @ref evemu. This is the
-  most important piece of information, do not forget it!
-- the output from udevadm info, see @ref udev_info.
-- the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s")
-- and the content of `/sys/class/dmi/id/modalias`.
-- run the `touchpad-edge-detectior` tool (provided by libevdev) and verify
-  that the ranges and sizes it prints match the touchpad (up to 5mm
-  difference is ok)
-
-If you are reporting a bug related to button event generation:
-
-- does your touchpad have (separate) physical hardware buttons or is the
-  whole touchpad clickable?
-- Are you using software buttons or clickfinger? See @ref
-  clickpad_softbuttons.
-- Do you have @ref tapping enabled?
-
-@section reporting_bugs_mouse Reporting mouse bugs
-
-When you file a bug, please attach the following information:
-
-- a virtual description of your input device, see @ref evemu. This is the
-  most important piece of information, do not forget it!
-- the vendor model number of the device (e.g. "Logitech M325")
-- the output from udevadm info, see @ref udev_info.
-
-If the bug is related to the @ref motion_normalization_customization "speed of the mouse":
-
-- the resolution of the mouse as specified by the vendor (in DPI)
-- the output of the `mouse-dpi-tool` (provided by libevdev)
-
-@section reporting_bugs_keyboard Reporting keyboard bugs
-
-Is your bug related to a keyboard layout? libinput does not handle keyboard
-layouts and merely forwards the physical key events. File the bug with your
-desktop environment instead (e.g. GNOME, KDE, ...), that's most likely where
-the issue is.
-
-When you file a bug, please attach the following information:
-
-- a virtual description of your input device, see @ref evemu. This is the
-  most important piece of information, do not forget it!
-
-@section reporting_bugs_trackpoint Reporting trackpoint bugs
-
-When you file a bug, please attach the following information:
-
-- a virtual description of your input device, see @ref evemu. This is the
-  most important piece of information, do not forget it!
-- the vendor model number of the device (e.g. "Logitech M325")
-- the output from udevadm info, see @ref udev_info.
-- the output of `libinput measure trackpoint-range`
-- the sensitivity of the trackpoint (adjust the event node number as needed):
-
-@verbatim
-$ cat /sys/class/input/event17/device/device/sensitivity
-@endverbatim
-
-@section reporting_bugs_other All other devices
-
-When you file a bug, please attach the following information:
-
-- a virtual description of your input device, see @ref evemu. This is the
-  most important piece of information, do not forget it!
-- the vendor model number of the device (e.g. "Sony Plastation3 controller")
-
-@section udev_info udev information for the device
-
-In many cases, we require the udev properties assigned to the device to
-verify whether device-specific quirks were applied. This can be obtained
-with ````udevadm info /sys/class/input/eventX```, with the correct event
-node for your device. An example output is below:
-
-@code
-$ udevadm info /sys/class/input/event4
-P: /devices/platform/i8042/serio1/input/input5/event4
-N: input/event4
-E: DEVNAME=/dev/input/event4
-E: DEVPATH=/devices/platform/i8042/serio1/input/input5/event4
-E: EVDEV_ABS_00=::41
-E: EVDEV_ABS_01=::37
-E: EVDEV_ABS_35=::41
-E: EVDEV_ABS_36=::37
-E: ID_INPUT=1
-E: ID_INPUT_HEIGHT_MM=66
-E: ID_INPUT_TOUCHPAD=1
-E: ID_INPUT_WIDTH_MM=97
-E: MAJOR=13
-E: MINOR=68
-E: SUBSYSTEM=input
-E: USEC_INITIALIZED=5463031
-@endcode
-
-@section evemu Recording devices with evemu
-
-@note Where available, the @ref libinput-record tools should be used instead
-of evemu
-
-<a href="http://www.freedesktop.org/wiki/Evemu/">evemu</a> records the
-device capabilities together with the event stream from the kernel. On our
-side, this allows us to recreate a virtual device identical to your device
-and re-play the event sequence, hopefully triggering the same bug.
-
-evemu-record takes a <tt>/dev/input/eventX</tt> event node, but without arguments
-it will simply show the list of devices and let you select:
-@code
-$ sudo evemu-record > scroll.evemu
-Available devices:
-/dev/input/event0:	Lid Switch
-/dev/input/event1:	Sleep Button
-/dev/input/event2:	Power Button
-/dev/input/event3:	AT Translated Set 2 keyboard
-/dev/input/event4:	SynPS/2 Synaptics TouchPad
-/dev/input/event5:	Video Bus
-/dev/input/event6:	ELAN Touchscreen
-/dev/input/event10:	ThinkPad Extra Buttons
-/dev/input/event11:	HDA Intel HDMI HDMI/DP,pcm=3
-/dev/input/event12:	HDA Intel HDMI HDMI/DP,pcm=7
-/dev/input/event13:	HDA Intel HDMI HDMI/DP,pcm=8
-/dev/input/event14:	HDA Intel PCH Dock Mic
-/dev/input/event15:	HDA Intel PCH Mic
-/dev/input/event16:	HDA Intel PCH Dock Headphone
-/dev/input/event17:	HDA Intel PCH Headphone
-/dev/input/event18:	Integrated Camera
-/dev/input/event19:	TPPS/2 IBM TrackPoint
-Select the device event number [0-19]:
-@endcode
-
-Select the device that triggers the issue, then reproduce the bug and Ctrl+C
-the process. The resulting recording, ("scroll.evemu" in this example) will
-contain the sequence required to reproduce the bug. If the bug fails to
-reproduce during recording, simply Ctrl+C and restart evemu-record.
-Always start the recording from a neutral state, i.e. without any buttons or
-keys down, with the position of the device in the neutral position, without
-touching the screen/touchpad.
-
-@note The longer the recording, the harder it is to identify the event
-sequence triggering the bug. Please keep the event sequence as short as possible.
-
-To verify that the recording contains the bug, you can replay it on your
-device. For example, to replay the sequence recorded in the example above:
-@code
-$ sudo evemu-play /dev/input/event4 < scroll.evemu
-@endcode
-
-If the bug is triggered by replaying on your device, attach the recording to
-the bug report.
-
-@note libinput does not affect the evemu recording. libinput and evemu talk
-directly to the kernel's device nodes. An evemu recording is not influenced
-by the libinput version or whether a libinput context is currently active.
-
-@dotfile evemu.gv
-
-@section fixed_bugs My bug was closed as fixed, what now?
-
-libinput's policy on closing bugs is: once the fix for a given bug is on git
-master, the bug is considered fixed and the bugzilla entry will be closed
-accordingly.
-
-Of course, unless you actually run git master, the bug will continue to
-affect you on your local machine. You are most likely running the
-distribution's package and you will need to wait until the distribution has
-updated its package accordingly.
-
-<b>Do not re-open a bug just because it hasn't trickled down to your
-distribution's package version yet.</b>
-
-Whether the bug fix ends up in your distribution depends on a number of
-things. Any given bug fix **may** be cherry-picked into the current stable
-branch, depending on its severity, impact, and likelyhood to cause
-regressions. Once cherry-picked it will land in the next stable branch
-release. These are usually a few weeks apart.
-
-<b>Do not re-open a bug because it wasn't picked into a stable branch
-release or because your distribution didn't update to the latest stable
-branch release.</b>
-
-Stable branches are usually discontinued when the next release comes out.
-
-Your distribution may pick a patch up immediately and ship the fix
-even before the next stable branch update is released. For example, Fedora
-does this frequently.
-
-<b>If a bug needs to be fixed urgently, file a bug in your distribution's
-bug tracker.</b>
-
-Patches on git master will end up in the next libinput release. Once your
-distribution updates to that release, your local libinput version will
-contain the fix.
-
-<b>Do not re-open a bug because your distribution didn't update to the
-release.</b>
-
-You can always run libinput from git master (see @ref building_libinput).
-Even while in development, libinput is very stable so this option isn't as
-scary as it may sounds.
-
-@subsection reporting_bugs_reopen When is it ok to re-open a fixed bug?
-
-Any time the bug was considered fixed but it turns out that the fix is
-insufficient and/or causes a regression.
-
-However, if the regression is in behavior unrelated to the fix itself it is
-usually better to file a new bug to reduce the noise. For example, if a fix
-to improve tapping breaks two-finger scrolling behavior, you should file a
-new bug but reference the original bug.
-
-*/

doc/scrolling.dox

@@ -1,106 +0,0 @@
-/**
-@page scrolling Scrolling
-
-libinput supports three different types of scrolling methods: @ref
-twofinger_scrolling, @ref edge_scrolling and @ref button_scrolling. Some
-devices support multiple methods, though only one can be enabled at a time.
-As a general overview:
-- touchpad devices with physical buttons below the touchpad support edge and
-  two-finger scrolling
-- touchpad devices without physical buttons (@ref clickpad_softbuttons
-  "clickpads") support two-finger scrolling only
-- pointing sticks provide on-button scrolling by default
-- mice and other pointing devices support on-button scrolling but it is not
-  enabled by default
-
-A device may differ from the above based on its capabilities. See
-libinput_device_config_scroll_set_method() for documentation on how to
-switch methods and libinput_device_config_scroll_get_methods() for
-documentation on how to query a device for available scroll methods.
-
-@section horizontal_scrolling Horizontal scrolling
-
-Scroll movements provide vertical and horizontal directions, each
-scroll event contains both directions where applicable, see
-libinput_event_pointer_get_axis_value(). libinput does not provide separate
-toggles to enable or disable horizontal scrolling. Instead, horizontal
-scrolling is always enabled. This is intentional, libinput does not have
-enough context to know when horizontal scrolling is appropriate for a given
-widget. The task of filtering horizontal movements is up to the caller.
-
-@section twofinger_scrolling Two-finger scrolling
-
-The default on two-finger capable touchpads (almost all modern touchpads are
-capable of detecting two fingers). Scrolling is triggered by two fingers
-being placed on the surface of the touchpad, then moving those fingers
-vertically or horizontally.
-
-@image html twofinger-scrolling.svg "Vertical and horizontal two-finger scrolling"
-
-For scrolling to trigger, a built-in distance threshold has to be met but once
-engaged any movement will scroll. In other words, to start scrolling a
-sufficiently large movement is required, once scrolling tiny amounts of
-movements will translate into tiny scroll movements.
-Scrolling in both directions at once is possible by meeting the required
-distance thresholds to enable each direction separately.
-
-Two-finger scrolling requires the touchpad to track both touch points with
-reasonable precision. Unfortunately, some so-called "semi-mt" touchpads can
-only track the bounding box of the two fingers rather than the actual
-position of each finger. In addition, that bounding box usually suffers from
-a low resolution, causing jumpy movement during two-finger scrolling.
-libinput does not provide two-finger scrolling on those touchpads.
-
-@section edge_scrolling Edge scrolling
-
-On some touchpads, edge scrolling is available, triggered by moving a single
-finger along the right edge (vertical scroll) or bottom edge (horizontal
-scroll).
-
-@image html edge-scrolling.svg "Vertical and horizontal edge scrolling"
-
-Due to the layout of the edges, diagonal scrolling is not possible. The
-behavior of edge scrolling using both edges at the same time is undefined.
-
-Edge scrolling overlaps with @ref clickpad_softbuttons. A physical click on
-a clickpad ends scrolling.
-
-@section button_scrolling On-Button scrolling
-
-On-button scrolling converts the motion of a device into scroll events while
-a designated button is held down. For example, Lenovo devices provide a
-<a href="http://en.wikipedia.org/wiki/Pointing_stick">pointing stick</a> that emulates
-scroll events when the trackstick's middle mouse button is held down.
-
-@note On-button scrolling is enabled by default for pointing sticks. This
-prevents middle-button dragging; all motion events while the middle button is
-down are converted to scroll events.
-
-@image html button-scrolling.svg "Button scrolling"
-
-The button may be changed with
-libinput_device_config_scroll_set_button() but must be on the same device as
-the motion events. Cross-device scrolling is not supported but
-for one exception: libinput's @ref t440_support enables the use of the middle
-button for button scrolling (even when the touchpad is disabled).
-
-@section scroll_sources Scroll sources
-
-libinput provides a pointer axis *source* for each scroll event. The
-source can be obtained with the libinput_event_pointer_get_axis_source()
-function and is one of **wheel**, **finger**, or **continuous**. The source
-information lets a caller decide when to implement kinetic scrolling.
-Usually, a caller will process events of source wheel as they come in.
-For events of source finger a caller should calculate the velocity of the
-scroll motion and upon finger release start a kinetic scrolling motion (i.e.
-continue executing a scroll according to some friction factor).
-libinput expects the caller to be in charge of widget handling, the source
-information is thus enough to provide kinetic scrolling on a per-widget
-basis. A caller should cancel kinetic scrolling when the pointer leaves the
-current widget or when a key is pressed.
-
-See the libinput_event_pointer_get_axis_source() for details on the
-behavior of each scroll source.
-
-See also http://who-t.blogspot.com.au/2015/03/libinput-scroll-sources.html
-*/

doc/style/libinputdoxygen.css

@@ -1,47 +0,0 @@
-dd {
-    margin-left: 30px;
-}
-
-.title {
-	font-size: 400%;
-	font-weight: 200;
-}
-
-h1 {
-	font-size: 300%;
-}
-
-h2 {
-	font-size: 200%;
-}
-
-.sm-dox li {
-	float:left;
-	border-top: 0;
-	padding-right: 20px;
-}
-
-.sm li, .sm a {
-	position: relative;
-}
-
-.sm, .sm ul, .sm li {
-	list-style: none;
-	display: block;
-	line-height: normal;
-	direction: ltr;
-	text-align: left;
-}
-
-.sm, .sm *, .sm *::before, .sm *::after {
-	box-sizing: border-box;
-}
-
-#main-nav {
-	padding: 30px;
-}
-
-/* Main menu sub-items like file-list, etc */
-#main-menu li ul {
-	display: none;
-}

doc/switches.dox

@@ -1,50 +0,0 @@
-/**
-@page switches Switches
-
-libinput supports a couple of switches. Unlike button events that come in
-press and release pairs, switches are usually toggled once and left at the
-setting for an extended period of time.
-
-Only some switches are handled by libinput, see @ref libinput_switch for a
-list of supported switches. Switch events are exposed to the caller, but
-libinput may handle some switch events internally and enable or disable
-specific features based on a switch state.
-
-The order of switch events is guaranteed to be correct, i.e., a switch will
-never send consecutive switch on, or switch off, events.
-
-@section switches_lid Lid switch handling
-
-Where available, libinput listens to devices providing a lid switch.
-The evdev event code `EV_SW` `SW_LID` is provided as @ref
-LIBINPUT_SWITCH_LID. If devices with a lid switch have a touchpad device,
-the device is disabled while the lid is logically closed. This is to avoid
-ghost touches that can be caused by interference with touchpads and the
-closed lid. The touchpad is automatically re-enabled whenever the lid is
-openend.
-
-This handling of lid switches is transparent to the user, no notifications
-are sent and the device appears as enabled at all times.
-
-On some devices, the device's lid state does not always reflect the physical
-state and the lid state may report as closed even when the lid is physicall
-open. libinput employs some heuristics to detect user input (specificially
-typing) to re-enable the touchpad on those devices.
-
-@section switches_tablet_mode Tablet mode switch handling
-
-Where available, libinput listens to devices providing a tablet mode switch.
-This switch is usually triggered on devices that can switch between a normal
-laptop layout and a tablet-like layout. One example for such a device is the
-Lenovo Yoga.
-
-The event sent by the kernel is `EV_SW` `SW_TABLET_MODE` and is provided as
-@ref LIBINPUT_SWITCH_TABLET_MODE. When the device switches to tablet mode,
-the touchpad and internal keyboard are disabled. If a trackpoint exists,
-it is disabled too. The input devices are automatically re-enabled whenever
-tablet mode is disengaged.
-
-This handling of tablet mode switches is transparent to the user, no
-notifications are sent and the device appears as enabled at all times.
-
-*/

doc/tapping.dox

@@ -1,76 +0,0 @@
-/**
-@page tapping Tap-to-click behaviour
-
-"Tapping" or "tap-to-click" is the name given to the behavior where a short
-finger touch down/up sequence maps into a button click. This is most
-commonly used on touchpads, but may be available on other devices.
-
-libinput implements tapping for one, two, and three fingers, where supported
-by the hardware, and maps those taps into a left, right, and middle button
-click, respectively. Not all devices support three fingers, libinput will
-support tapping up to whatever is supported by the hardware. libinput does
-not support four-finger taps or any tapping with more than four fingers,
-even though some hardware can distinguish between that many fingers.
-
-@section tapping_default Tap-to-click default setting
-
-Tapping is **disabled** by default on most devices, see [this
-commit](http://cgit.freedesktop.org/wayland/libinput/commit/?id=2219c12c3aa45b80f235e761e87c17fb9ec70eae)
-because:
-- if you don't know that tapping is a thing (or enabled by default), you get
-  spurious button events that make the desktop feel buggy.
-- if you do know what tapping is and you want it, you usually know where to
-  enable it, or at least you can search for it.
-
-Tapping is **enabled** by default on devices where tapping is the only
-method to trigger button clicks. This includes devices without physical
-buttons such as touch-capable graphics tablets.
-
-Tapping can be enabled/disabled on a per-device basis. See
-libinput_device_config_tap_set_enabled() for details.
-
-@section tapndrag Tap-and-drag 
-
-libinput also supports "tap-and-drag" where a tap immediately followed by a
-finger down and that finger being held down emulates a button press. Moving
-the finger around can thus drag the selected item on the screen.
-Tap-and-drag is optional and can be enabled or disabled with
-libinput_device_config_tap_set_drag_enabled(). Most devices have
-tap-and-drag enabled by default.
-
-Also optional is a feature called "drag lock". With drag lock disabled, lifting
-the finger will stop any drag process. When enabled, libinput will ignore a
-finger up event during a drag process, provided the finger is set down again
-within a implementation-specific timeout. Drag lock can be enabled and
-disabled with libinput_device_config_tap_set_drag_lock_enabled().
-Note that drag lock only applies if tap-and-drag is be enabled.
-
-@image html tap-n-drag.svg "Tap-and-drag process"
-
-The above diagram explains the process, a tap (a) followed by a finger held
-down (b) starts the drag process and logically holds the left mouse button
-down. A movement of the finger (c) will drag the selected item until the
-finger is released (e). If needed and drag lock is enabled, the finger's
-position can be reset by lifting and quickly setting it down again on the
-touchpad (d). This will be interpreted as continuing move and is especially
-useful on small touchpads or with slow pointer acceleration.
-If drag lock is enabled, the release of the mouse buttons after the finger
-release (e) is triggered by a timeout. To release the button immediately,
-simply tap again (f).
-
-If two fingers are supported by the hardware, a second finger can be used to
-drag while the first is held in-place.
-
-@section tap_constraints Constraints while tapping
-
-A couple of constraints apply to the contact to be converted into a press, the most common ones are:
-- the touch down and touch up must happen within an implementation-defined timeout
-- if a finger moves more than an implementation-defined distance while in contact, it's not a tap
-- tapping within @ref clickpad_softbuttons "clickpad software buttons" may not trigger an event
-- a tap not meeting required pressure thresholds can be ignored as accidental touch
-- a tap exceeding certain pressure thresholds can be ignored (see @ref
-  palm_detection)
-- a tap on the edges of the touchpad can usually be ignored (see @ref
-  palm_detection)
-
-*/

doc/test-suite.dox

@@ -1,134 +0,0 @@
-/**
-@page test-suite libinput test suite
-
-libinput ships with a number of tests all run automatically on `ninja test`.
-The primary test suite is the `libinput-test-suite-runner`. When testing,
-the `libinput-test-suite-runner` should always be invoked to check for
-behavior changes.
-
-The test suite runner uses
-[Check](http://check.sourceforge.net/doc/check_html/) underneath the hood
-but most of the functionality is abstracted into *litest* wrappers.
-
-The test suite runner has a make-like job control enabled by the `-j` or
-`--jobs` flag and will fork off as many parallel processes as given by this
-flag. The default if unspecified is 8. When debugging a specific test case
-failure it is recommended to employ test filtures (see @ref test-filtering)
-and disable parallel tests. The test suite automatically disables parallel
-make when run in gdb.
-
-@section test-config X.Org config to avoid interference
-
-uinput devices created by the test suite are usually recognised by X as
-input devices. All events sent through these devices will generate X events
-and interfere with your desktop.
-
-Copy the file `$srcdir/test/50-litest.conf` into your `/etc/X11/xorg.conf.d`
-and restart X. This will ignore any litest devices and thus not interfere
-with your desktop.
-
-@section test-root Permissions required to run tests
-
-Most tests require the creation of uinput devices and access to the
-resulting `/dev/input/eventX` nodes. Some tests require temporary udev rules.
-<b>This usually requires the tests to be run as root</b>. If not run as
-root, the test suite runner will exit with status 77, interpreted as
-"skipped" by ninja.
-
-@section test-filtering Selective running of tests
-
-litest's tests are grouped into test groups, test names and devices. A test
-group is e.g.  "touchpad:tap" and incorporates all tapping-related tests for
-touchpads. Each test function is (usually) run with one or more specific
-devices. The `--list` commandline argument shows the list of suites and
-tests. This is useful when trying to figure out if a specific test is
-run for a device.
-
-@code
-$ ./test/libinput-test-suite-runner --list
-...
-pointer:left-handed:
-	pointer_left_handed_during_click_multiple_buttons:
-		trackpoint
-		ms-surface-cover
-		mouse-wheelclickcount
-		mouse-wheelclickangle
-		low-dpi-mouse
-		mouse-roccat
-		mouse-wheel-tilt
-		mouse
-		logitech-trackball
-		cyborg-rat
-		magicmouse
-	pointer_left_handed_during_click:
-		trackpoint
-		ms-surface-cover
-		mouse-wheelclickcount
-		mouse-wheelclickangle
-		low-dpi-mouse
-		mouse-roccat
-		mouse-wheel-tilt
-		mouse
-		logitech-trackball
-		cyborg-rat
-		litest-magicmouse-device
-	pointer_left_handed:
-		trackpoint
-		ms-surface-cover
-		mouse-wheelclickcount
-		mouse-wheelclickangle
-		low-dpi-mouse
-		mouse-roccat
-		mouse-wheel-tilt
-		mouse
-...
-@endcode
-
-In the above example, the "pointer:left-handed" suite contains multiple
-tests, e.g. "pointer_left_handed_during_click" (this is also the function
-name of the test, making it easy to grep for). This particular test is run
-for various devices including the trackpoint device and the magic mouse
-device.
-
-The "no device" entry signals that litest does not instantiate a uinput
-device for a specific test (though the test itself may
-instantiate one).
-
-The `--filter-test` argument enables selective running of tests through
-basic shell-style function name matching. For example:
-
-@code
-$ ./test/libinput-test-suite-runner --filter-test="*1fg_tap*"
-@endcode
-
-The `--filter-device` argument enables selective running of tests through
-basic shell-style device name matching. The device names matched are the
-litest-specific shortnames, see the output of `--list`. For example:
-
-@code
-$ ./test/libinput-test-suite-runner --filter-device="synaptics*"
-@endcode
-
-The `--filter-group` argument enables selective running of test groups
-through basic shell-style test group matching. The test groups matched are
-litest-specific test groups, see the output of `--list`. For example:
-
-@code
-$ ./test/libinput-test-suite-runner --filter-group="touchpad:*hover*"
-@endcode
-
-The `--filter-device` and `--filter-group` arguments can be combined with
-`--list` to show which groups and devices will be affected.
-
-@section test-verbosity Controlling test output
-
-Each test supports the `--verbose` commandline option to enable debugging
-output, see libinput_log_set_priority() for details. The `LITEST_VERBOSE`
-environment variable, if set, also enables verbose mode.
-
-@code
-$ ./test/libinput-test-suite-runner --verbose
-$ LITEST_VERBOSE=1 ninja test
-@endcode
-
-*/

doc/timestamps.dox

@@ -1,36 +0,0 @@
-/**
-
-@page timestamps Timestamps
-
-@section event_timestamps Event timestamps
-
-Most libinput events provide a timestamp in millisecond and/or microsecond
-resolution. These timestamp usually increase monotonically, but libinput
-does not guarantee that this always the case. In other words, it is possible
-to receive an event with a timestamp earlier than the previous event. 
-
-For example, if a touchpad has @ref tapping enabled, a button event may have a
-lower timestamp than an event from a different device. Tapping requires the
-use of timeouts to detect multi-finger taps and/or @ref tapndrag.
-
-Consider the following event sequences from a touchpad and a mouse:
-
-<pre>
-Time      Touchpad      Mouse
----------------------------------
-t1       finger down
-t2        finger up
-t3                     movement
-t4       tap timeout
-</pre>
-
-For this event sequence, the first event to be sent to a caller is in
-response to the mouse movement: an event of type @ref
-LIBINPUT_EVENT_POINTER_MOTION with the timestamp t3.
-Once the timeout expires at t4, libinput generates an event of 
-@ref LIBINPUT_EVENT_POINTER_BUTTON (press) with a timestamp t1 and an event
-@ref LIBINPUT_EVENT_POINTER_BUTTON (release) with a timestamp t2.
-
-Thus, the caller gets events with timestamps in the order t3, t1, t2,
-despite t3 > t2 > t1.
-*/

doc/tools.dox

@@ -1,237 +0,0 @@
-/**
-@page tools Helper tools
-
-libinput provides a `libinput` tool to query state and events. This tool
-takes a subcommand as argument, similar to the **git** command. A full
-explanation of the various commands available in the libinput tool is
-available in the **libinput(1)** man page. 
-
-The most common tools used are:
-- `libinput list-devices`: to list locally available devices, see @ref
-  libinput-list-devices "here"
-- `libinput debug-events`: to monitor and debug events, see @ref
-  libinput-debug-events "here"
-- `libinput debug-gui`: to visualize events, see @ref libinput-debug-gui
-  "here"
-- `libinput record`: to record an event sequence for replaying, see @ref
-  libinput-record "here"
-- `libinput measure`: measure properties on a kernel device, see @ref
-  libinput-measure "here"
-
-Most the tools must be run as root to have access to the kernel's @c
-/dev/input/event* device files.
-
-@section libinput-list-devices libinput list-devices
-
-The `libinput list-devices` command shows information about devices
-recognized by libinput and can help identifying why a device behaves
-different than expected. For example, if a device does not show up in the
-output, it is not a supported input device.
-
-@note This tool does **not** show your desktop's configuration, just the
-libinput built-in defaults.
-
-@verbatim
-$ sudo libinput list-devices
-[...]
-Device:           SynPS/2 Synaptics TouchPad
-Kernel:           /dev/input/event4
-Group:            9
-Seat:             seat0, default
-Size:             97.33x66.86mm
-Capabilities:     pointer 
-Tap-to-click:     disabled
-Tap drag lock:    disabled
-Left-handed:      disabled
-Nat.scrolling:    disabled
-Middle emulation: n/a
-Calibration:      n/a
-Scroll methods:   *two-finger 
-Click methods:    *button-areas clickfinger 
-[...]
-@endverbatim
-
-The above listing shows example output for a touchpad. The
-`libinput list-devices` command lists general information about the device
-(the kernel event node) but also the configuration options. If an option is
-"n/a" it does not exist on this device. Otherwise, the tool will show the
-default configuration for this device, for options that have more than a
-binary state all available options are listed, with the default one prefixed
-with an asterisk (*). In the example above, the default click method is
-button-areas but clickinger is available.
-
-@note This tool is intended to be human-readable and may change its output
-at any time.
-
-@section libinput-debug-events libinput debug-events
-The `libinput debug-events` command prints events from devices and can help
-to identify why a device behaves different than expected.
-
-@verbatim
-$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
-@endverbatim
-
-All configuration options (enable/disable tapping,
-etc.) are available as commandline arguments. To reproduce the event
-sequence as your desktop session sees it, ensure that all options are turned
-on or off as required. See the **libinput-debug-events(1)** man page or the 
-`--help` output for information about the available options. 
-
-@note When submitting a bug report, always use the `--verbose` flag to get
-additional information: `libinput debug-events --verbose <other options>`
-
-An example output from this tool may look like the snippet below. 
-
-@verbatim
-$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
--event2   DEVICE_ADDED     Power Button                      seat0 default group1  cap:k
--event5   DEVICE_ADDED     Video Bus                         seat0 default group2  cap:k
--event0   DEVICE_ADDED     Lid Switch                        seat0 default group3  cap:S
--event1   DEVICE_ADDED     Sleep Button                      seat0 default group4  cap:k
--event4   DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=3      seat0 default group5  cap:
--event11  DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=7      seat0 default group6  cap:
--event12  DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=8      seat0 default group7  cap:
--event13  DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=9      seat0 default group8  cap:
--event14  DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=10     seat0 default group9  cap:
--event19  DEVICE_ADDED     Integrated Camera: Integrated C   seat0 default group10 cap:k
--event15  DEVICE_ADDED     HDA Intel PCH Dock Mic            seat0 default group11 cap:
--event16  DEVICE_ADDED     HDA Intel PCH Mic                 seat0 default group12 cap:
--event17  DEVICE_ADDED     HDA Intel PCH Dock Headphone      seat0 default group13 cap:
--event18  DEVICE_ADDED     HDA Intel PCH Headphone           seat0 default group14 cap:
--event6   DEVICE_ADDED     ELAN Touchscreen                  seat0 default group15 cap:t  size 305x172mm ntouches 10 calib
--event3   DEVICE_ADDED     AT Translated Set 2 keyboard      seat0 default group16 cap:k
--event20  DEVICE_ADDED     SynPS/2 Synaptics TouchPad        seat0 default group17 cap:pg  size 100x76mm tap(dl off) left scroll-nat scroll-2fg-edge click-buttonareas-clickfinger dwt-on
--event21  DEVICE_ADDED     TPPS/2 IBM TrackPoint             seat0 default group18 cap:p left scroll-nat scroll-button
--event7   DEVICE_ADDED     ThinkPad Extra Buttons            seat0 default group19 cap:k
--event20  POINTER_MOTION    +3.62s	  2.72/ -0.93
- event20  POINTER_MOTION    +3.63s	  1.80/ -1.42
- event20  POINTER_MOTION    +3.65s	  6.16/ -2.28
- event20  POINTER_MOTION    +3.66s	  6.42/ -1.99
- event20  POINTER_MOTION    +3.67s	  8.99/ -1.42
- event20  POINTER_MOTION    +3.68s	 11.30/  0.00
- event20  POINTER_MOTION    +3.69s	 21.32/  1.42
-@endverbatim
-
-@section libinput-debug-gui libinput debug-gui
-
-A simple GTK-based graphical tool that shows the behavior and location of
-touch events, pointer motion, scroll axes and gestures. Since this tool
-gathers data directly from libinput, it is thus suitable for
-pointer-acceleration testing.
-
-@note This tool does **not** use your desktop's configuration, just the
-libinput built-in defaults.
-
-@verbatim
-$ sudo libinput debug-gui --enable-tapping
-@endverbatim
-
-As with @ref libinput-debug-events, all options must be specified on the
-commandline to emulate the correct behavior.
-See the **libinput-debug-gui(1)** man page or the `--help` output for information about
-the available options.
-
-@section libinput-record libinput record and libinput replay
-
-The `libinput record` command records the **kernel** events from a specific
-device node. The recorded sequence can be replayed with the `libinput
-replay` command. This pair of tools is crucial to capturing bugs and
-reproducing them on a developer's machine.
-
-@note These tools are shipped with libinput, but the recorded events
-are **kernel events** and independent of the libinput context. libinput does not
-need to be running, it does not matter whether a user is running X.Org or
-Wayland or even what version of libinput is currently running.
-
-The use of the tools is straightforward, just run without arguments, piping
-the output into a file:
-@verbatim
-$ sudo libinput record > touchpad.log
-Available devices:
-/dev/input/event0:	Lid Switch
-/dev/input/event1:	Sleep Button
-/dev/input/event2:	Power Button
-/dev/input/event3:	AT Translated Set 2 keyboard
-/dev/input/event4:	ThinkPad Extra Buttons
-/dev/input/event5:	ELAN Touchscreen
-/dev/input/event6:	Video Bus
-/dev/input/event7:	HDA Intel HDMI HDMI/DP,pcm=3
-/dev/input/event8:	HDA Intel HDMI HDMI/DP,pcm=7
-/dev/input/event9:	HDA Intel HDMI HDMI/DP,pcm=8
-/dev/input/event10:	HDA Intel HDMI HDMI/DP,pcm=9
-/dev/input/event11:	HDA Intel HDMI HDMI/DP,pcm=10
-/dev/input/event12:	HDA Intel PCH Dock Mic
-/dev/input/event13:	HDA Intel PCH Mic
-/dev/input/event14:	HDA Intel PCH Dock Headphone
-/dev/input/event15:	HDA Intel PCH Headphone
-/dev/input/event16:	Integrated Camera: Integrated C
-/dev/input/event17:	SynPS/2 Synaptics TouchPad
-/dev/input/event18:	TPPS/2 IBM TrackPoint
-Select the device event number: 17
-/dev/input/event17 recording to stdout
-@endverbatim
-
-Without arguments, `libinput record` displays the available devices and lets
-the user select one. Supply the number (17 in this case for
-`/dev/input/event17`) and the tool will print the device information and
-events to the file it is redirected to. More arguments are available, see
-the **libinput-record(1)** man page.
-
-Reproduce the bug, ctrl+c and attach the output file to a bug report.
-For data protection, `libinput record` obscures key codes by default, any
-alphanumeric key shows up as letter "a".
-
-@note When reproducing a bug that crashes libinput, run inside `screen` or
-`tmux`.
-
-The recording can be replayed with the `libinput replay` command:
-@verbatim
-$ sudo libinput replay touchpad.log
-SynPS/2 Synaptics TouchPad: /dev/input/event19
-Hit enter to start replaying
-@endverbatim
-
-`libinput replay` creates a new virtual device based on the description in
-the log file. Hitting enter replays the event sequence once and the tool
-stops once all events have been replayed. Hitting enter again replays the
-sequence again, Ctrl+C stops it and removes the virtual device.
-
-Users are advised to always replay a recorded event sequence to ensure they
-have captured the bug.
-
-More arguments are available, see the **libinput-record(1)** and
-**libinput-replay(1)** man pages.
-
-@subsection libinput-record-multiple Recording multiple devices at once
-
-In some cases, an interaction between multiple devices is the cause for a
-specific bug. For example, a touchpad may not work in response to keyboard
-events. To accurately reproduce this sequence, the timing between multiple
-devices must be correct and we need to record the events in one go.
-
-`libinput record` has a `--multiple` argument to record multiple devices at
-once. Unlike the normal invocation, this one requires a number of arguments:
-
-@verbatim
-$ sudo libinput record --multiple --output-file=touchpad-bug.log /dev/input/event17 /dev/input/event3
-recording to 'touchpad-bug.log'
-@endverbatim
-
-As seen above, a user must specify `--multiple` and the `--output-file`.
-Finally, all devices to be recorded must be specified on the commandline as
-well.
-
-Replaying events is the same as for a single recording:
-@verbatim
-$ sudo libinput replay touchpad-bug.log
-@endverbatim
-
-@subsection libinput-measure Measuring device properties with libinput measure
-
-The `libinput measure` tool is a multiplexer for various sub-tools that can
-measure specific properties on the device. These tools generally measure one
-thing and one thing only and their usage is highly specific to the tool.
-Please see the **libinput-measure(1)** man page for information about what
-tools are available and the man page for each respective tool.
-
-*/

doc/touchpad-jitter.dox

@@ -1,90 +0,0 @@
-/**
-@page touchpad_jitter Touchpad jitter
-
-Touchpad jitter describes random movement by a few pixels even when the
-user's finger is unmoving.
-
-libinput has a mechanism called a **hysteresis** to avoid that jitter. When
-active, movement with in the **hysteresis margin** is discarded. If the
-movement delta is larger than the margin, the movement is passed on as
-pointer movement. This is a simplified summary, developers should
-read the implementation of the hysteresis in `src/evdev.c`.
-
-libinput uses the kernel `fuzz` value to determine the size of the
-hysteresis. Users should override this with a udev hwdb entry where the
-device itself does not provide the correct value.
-
-@section touchpad_jitter_fuzz_override Overriding the hysteresis margins
-
-libinput provides the debugging tool `libinput measure fuzz` to help edit or
-test a fuzz value. This tool is interactive and provides a udev hwdb entry
-that matches the device. To check if a fuzz is currently present, simply run
-without arguments or with the touchpad's device node:
-
-@verbatim
-$ sudo libinput measure fuzz
-Using Synaptics TM2668-002: /dev/input/event17
-  Checking udev property... not set
-  Checking axes... x=16 y=16
-@endverbatim
-
-In the above output, the axis fuzz is set to 16. To set a specific fuzz, run
-with the `--fuzz=<value>` argument.
-
-@verbatim
-$ sudo libinput measure fuzz --fuzz=8
-@endverbatim
-
-The tool will attempt to construct a hwdb file that matches your touchpad
-device. Follow the printed prompts.
-
-In the ideal case, the tool will provide you with a file that can be
-submitted to the systemd repo for inclusion.
-
-However, hwdb entry creation is difficult to automate and it's likely
-that the tools fails in doing so, especially if an existing entry is already
-present.
-
-Below is the outline of what a user needs to do to override a device's fuzz
-value in case the `libinput measure fuzz` tool fails.
-
-Check with `udevadm info /sys/class/input/eventX` (replace your device node
-number) whether an existing hwdb override exists. If the `EVDEV_ABS_`
-properties are present, the hwdb overried exists. Find the file that
-contains that entry, most likely in `/etc/udev/hwdb.d` or
-`/usr/lib/udev/hwdb.d`.
-
-The content of the property is a set of values in the format
-`EVDEV_ABS_00=min:max:resolution:fuzz`. You need to set the `fuzz` part,
-leaving the remainder of the property as-is. Values may be empty, e.g. a
-property that only sets resolution and fuzz reads as `EVDEV_ABS_00=::32:8`.
-
-If no properties exist, your hwdb.entry should look approximately like this:
-@verbatim
-evdev:name:Synaptics TM2668-002:dmi:*:svnLENOVO*:pvrThinkPadT440s*:
- EVDEV_ABS_00=:::8
- EVDEV_ABS_01=:::8
- EVDEV_ABS_35=:::8
- EVDEV_ABS_36=:::8
-@endverbatim
-
-Substitute the `name` field with the device name (see the output of
-`libinput measure fuzz` and the DMI match content with your hardware. See
-@ref hwdb_modifying for details.
-
-Once the hwdb entry has been modified, added, or created, @ref
-hwdb_reloading "reload the hwdb". Once reloaded, @ref libinput-record
-"libinput record" should show the new fuzz value for the axes.
-
-Restart the host and libinput should pick up the revised fuzz values.
-
-@section kernel_fuzz Kernel fuzz
-
-A fuzz set on an absolute axis in the kernel causes the kernel to apply
-hysteresis-like behavior to the axis. Unfortunately, this behavior leads to
-inconsistent deltas. To avoid this, libinput sets the kernel fuzz on the
-device to 0 to disable this kernel behavior but remembers what the fuzz was
-on startup. The fuzz is stored in the `LIBINPUT_FUZZ_XX` udev property, on
-startup libinput will check that property as well as the axis itself.
-
-*/

doc/touchpad-jumping-cursors.dox

@@ -1,54 +0,0 @@
-/**
-@page touchpad_jumping_cursor Touchpad jumping cursor bugs
-
-A common bug encountered on touchpads is a cursor jump when alternating
-between fingers on a multi-touch-capable touchpad. For example, after moving
-the cursor a user may use a second finger in the software button area to
-physically click the touchpad. Upon setting the finger down, the cursor
-exhibits a jump towards the bottom left or right, depending on the finger
-position.
-
-When libinput detects a cursor jump it prints a bug warning to the log with
-the text <b>"Touch jump detected and discarded."</b> and a link to this page.
-
-In most cases, this is a bug in the kernel driver and to libinput it appears
-that the touch point moves from its previous position. The pointer jump can
-usually be seen in the evemu-record output for the device:
-
-<pre>
- E: 249.206319 0000 0000 0000    # ------------ SYN_REPORT (0) ----------
- E: 249.218008 0003 0035 3764    # EV_ABS / ABS_MT_POSITION_X    3764
- E: 249.218008 0003 0036 2221    # EV_ABS / ABS_MT_POSITION_Y    2221
- E: 249.218008 0003 003a 0065    # EV_ABS / ABS_MT_PRESSURE      65
- E: 249.218008 0003 0000 3764    # EV_ABS / ABS_X                3764
- E: 249.218008 0003 0001 2216    # EV_ABS / ABS_Y                2216
- E: 249.218008 0003 0018 0065    # EV_ABS / ABS_PRESSURE         65
- E: 249.218008 0000 0000 0000    # ------------ SYN_REPORT (0) ----------
- E: 249.230881 0003 0035 3752    # EV_ABS / ABS_MT_POSITION_X    3752
- E: 249.230881 0003 003a 0046    # EV_ABS / ABS_MT_PRESSURE      46
- E: 249.230881 0003 0000 3758    # EV_ABS / ABS_X                3758
- E: 249.230881 0003 0018 0046    # EV_ABS / ABS_PRESSURE         46
- E: 249.230881 0000 0000 0000    # ------------ SYN_REPORT (0) ----------
- E: 249.242648 0003 0035 1640    # EV_ABS / ABS_MT_POSITION_X    1640
- E: 249.242648 0003 0036 4681    # EV_ABS / ABS_MT_POSITION_Y    4681
- E: 249.242648 0003 003a 0025    # EV_ABS / ABS_MT_PRESSURE      25
- E: 249.242648 0003 0000 1640    # EV_ABS / ABS_X                1640
- E: 249.242648 0003 0001 4681    # EV_ABS / ABS_Y                4681
- E: 249.242648 0003 0018 0025    # EV_ABS / ABS_PRESSURE         25
- E: 249.242648 0000 0000 0000    # ------------ SYN_REPORT (0) ----------
- E: 249.254568 0003 0035 1648    # EV_ABS / ABS_MT_POSITION_X    1648
- E: 249.254568 0003 003a 0027    # EV_ABS / ABS_MT_PRESSURE      27
- E: 249.254568 0003 0000 1644    # EV_ABS / ABS_X                1644
- E: 249.254568 0003 0018 0027    # EV_ABS / ABS_PRESSURE         27
-</pre>
-
-In this recording, the pointer jumps from its position 3752/2216 to
-1640/4681 within a single frame. On this particular touchpad, this would
-represent a physical move of almost 50mm. libinput detects some of these
-jumps and discards the movement but otherwise continues as usual. However,
-the bug should be fixed at the kernel level.
-
-When you encounter the warning in the log, please generate an evemu
-recording of your touchpad and file a bug. See @ref reporting_bugs for more
-details.
-*/

doc/touchpad-pressure.dox

@@ -1,217 +0,0 @@
-/**
-@page touchpad_pressure Touchpad pressure-based touch detection
-
-libinput uses the touchpad pressure values and/or touch size values to
-detect wether a finger has been placed on the touchpad. This is @ref
-kernel_pressure_information and combines with a libinput-specific hardware
-database to adjust the thresholds on a per-device basis. libinput uses
-these thresholds primarily to filter out accidental light touches but
-the information is also used for some @ref palm_detection.
-
-Pressure and touch size thresholds are **not** directly configurable by the
-user. Instead, libinput provides these thresholds for each device where
-necessary. See @ref touchpad_pressure_hwdb for instructions on how to adjust
-the pressure ranges and @ref touchpad_touch_size_hwdb for instructions on
-how to adjust the touch size ranges.
-
-@section kernel_pressure_information Information provided by the kernel
-
-The kernel sends multiple values to inform userspace about a finger touching
-the touchpad. The most basic is the ```EV_KEY/BTN_TOUCH``` boolean event
-that simply announces physical contact with the touchpad. The decision when
-this event is sent is usually made by the kernel driver and may depend on
-device-specific thresholds. These thresholds are transparent to userspace
-and cannot be modified. On touchpads where pressure or touch size is not
-available, libinput uses ```BTN_TOUCH``` to determine when a finger is
-logically down.
-
-Many contemporary touchpad devices provide an absolute pressure axis in
-addition to ```BTN_TOUCH```. This pressure generally increases as the pressure
-increases, however few touchpads are capable of detecting true pressure. The
-pressure value is usually related to the covered area - as the pressure
-increases a finger flattens and thus covers a larger area. The range
-provided by the kernel is not mapped to a specific physical range and
-often requires adjustment. Pressure is sent by the ```ABS_PRESSURE``` axis
-for single-touch touchpads or ```ABS_MT_PRESSURE``` on multi-touch capable
-touchpads. Some devices can detect multiple fingers but only provide
-```ABS_PRESSURE```.
-
-Some devices provide additional touch size information through
-the ```ABS_MT_TOUCH_MAJOR/ABS_MT_TOUCH_MINOR``` axes and/or
-the ```ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR``` axes. These axes specifcy
-the size of the touch ellipse. While the kernel documentation specifies how
-these axes are supposed to be mapped, few devices forward reliable
-information. libinput uses these values together with a device-specific hwdb
-entry. In other words, touch size detection does not work unless a hwdb
-entry is present for the device.
-
-@section touchpad_pressure_hwdb Debugging touchpad pressure ranges
-
-This section describes how to determine the touchpad pressure ranges
-required for a touchpad device and how to add the required hwdb entry
-locally. Note that the hwdb entry is **not public API** and **may change at
-any time**. Users are advised to @ref reporting_bugs "report a bug" with the
-updated pressure ranges when testing has completed.
-
-Use the ```libinput measure touchpad-pressure``` tool provided by libinput.
-This tool will search for your touchpad device and print some pressure
-statistics, including whether a touch is/was considered logically down.
-
-@note This tool will only work on touchpads with pressure.
-
-Example output of the tool is below:
-
-<pre>
-$ sudo libinput measure touchpad-pressure
-Ready for recording data.
-Pressure range used: 8:10
-Palm pressure range used: 65535
-Place a single finger on the touchpad to measure pressure values.
-Ctrl+C to exit
-&nbsp;
-Sequence 1190 pressure: min:  39 max:  48 avg:  43 median:  44 tags: down
-Sequence 1191 pressure: min:  49 max:  65 avg:  62 median:  64 tags: down
-Sequence 1192 pressure: min:  40 max:  78 avg:  64 median:  66 tags: down
-Sequence 1193 pressure: min:  36 max:  83 avg:  70 median:  73 tags: down
-Sequence 1194 pressure: min:  43 max:  76 avg:  72 median:  74 tags: down
-Touchpad pressure:  47 min:  47 max:  86 tags: down
-</pre>
-
-The example output shows five completed touch sequences and one ongoing one.
-For each, the respective minimum and maximum pressure values are printed as
-well as some statistics. The ```tags``` show that sequence was considered
-logically down at some point. This is an interactive tool and its output may
-change frequently. Refer to the <i>libinput-measure-touchpad-pressure(1)</i> man
-page for more details.
-
-By default, this tool uses the udev hwdb entries for the pressure range. To
-narrow down on the best values for your device, specify the 'logically down'
-and 'logically up' pressure thresholds with the  ```--touch-thresholds``
-argument:
-<pre>
-$ sudo libinput measure touchpad-pressure --touch-thresholds=10:8 --palm-threshold=20
-</pre>
-
-Interact with the touchpad and check if the output of this tool matches your
-expectations.
-
-@note **This is an interactive process. You will need to re-run the
-tool with varying thresholds until you find the right range for your
-touchpad. Attaching output logs to a bug will not help, only you with access
-to the hardware can figure out the correct ranges.**
-
-Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
-the following hwdb file:
-
-<pre>
-$> cat /etc/udev/hwdb.d/99-touchpad-pressure.hwdb
-libinput:name:*SynPS/2 Synaptics TouchPad:dmi:*svnHewlett-Packard:*pnHPCompaq6910p*
- LIBINPUT_ATTR_PRESSURE_RANGE=10:8
-</pre>
-
-The first line is the match line and should be adjusted for the device name
-(see evemu-record's output) and for the local system, based on the
-information in ```/sys/class/dmi/id/modalias```. The modalias should be
-shortened to the specific system's information, usually system vendor (svn)
-and product name (pn).
-
-Once in place, you need to run the following to commands, adjusted for your
-device's event node (see @ref faq_hwdb_changes):
-<pre>
-    sudo udevadm hwdb --update
-    sudo udevadm test /sys/class/input/eventX
-</pre>
-
-If the pressure range property shows up correctly, restart X or the
-Wayland compositor and libinput should now use the correct pressure
-thresholds. The @ref tools can be used to verify the correct
-functionality first without the need for a restart.
-
-Once the pressure ranges are deemed correct,
-@ref reporting_bugs "report a bug" to get the pressure ranges into the
-repository.
-
-@section touchpad_touch_size_hwdb Debugging touch size ranges
-
-This section describes how to determine the touchpad touch size ranges
-required for a touchpad device and how to add the required hwdb entry
-locally. Note that the hwdb entry is **not public API** and **may change at
-any time**. Users are advised to @ref reporting_bugs "report a bug" with the
-updated pressure ranges when testing has completed.
-
-Use the ```libinput measure touch-size``` tool provided by libinput.
-This tool will search for your touchpad device and print some touch size
-statistics, including whether a touch is/was considered logically down.
-
-@note This tool will only work on touchpads with the ```ABS_MT_MAJOR``` axis.
-
-Example output of the tool is below:
-
-<pre>
-$ sudo libinput measure touch-size --touch-thresholds 10:8 --palm-threshold 14
-Using ELAN Touchscreen: /dev/input/event5
-&nbsp;
-Ready for recording data.
-Touch sizes used: 10:8
-Palm size used: 14
-Place a single finger on the device to measure touch size.
-Ctrl+C to exit
-&nbsp;
-Sequence: major: [  9.. 11] minor: [  7..  9]
-Sequence: major: [  9.. 10] minor: [  7..  7]
-Sequence: major: [  9.. 14] minor: [  6..  9]  down
-Sequence: major: [ 11.. 11] minor: [  9..  9]  down
-Sequence: major: [  4.. 33] minor: [  1..  5]  down palm
-</pre>
-
-The example output shows five completed touch sequences. For each, the
-respective minimum and maximum pressure values are printed as well as some
-statistics. The ```down``` and ```palm``` tags show that sequence was considered
-logically down or a palm at some point. This is an interactive tool and its
-output may change frequently. Refer to the <i>libinput-measure-touch-size(1)</i> man
-page for more details.
-
-By default, this tool uses the udev hwdb entries for the touch size range. To
-narrow down on the best values for your device, specify the 'logically down'
-and 'logically up' pressure thresholds with the  ```--touch-thresholds``
-arguments as in the example above.
-
-Interact with the touchpad and check if the output of this tool matches your
-expectations.
-
-@note **This is an interactive process. You will need to re-run the
-tool with varying thresholds until you find the right range for your
-touchpad. Attaching output logs to a bug will not help, only you with access
-to the hardware can figure out the correct ranges.**
-
-Once the thresholds are decided on (e.g. 10 and 8), they can be enabled with
-the following hwdb file:
-
-<pre>
-$> cat /etc/udev/hwdb.d/99-touchpad-pressure.hwdb
-libinput:name:*SynPS/2 Synaptics TouchPad:dmi:*svnHewlett-Packard:*pnHPCompaq6910p*
- LIBINPUT_ATTR_TOUCH_SIZE_RANGE=10:8
-</pre>
-
-The first line is the match line and should be adjusted for the device name
-(see evemu-record's output) and for the local system, based on the
-information in ```/sys/class/dmi/id/modalias```. The modalias should be
-shortened to the specific system's information, usually system vendor (svn)
-and product name (pn).
-
-Once in place, you need to run the following to commands, adjusted for your
-device's event node (see @ref faq_hwdb_changes):
-<pre>
-    sudo udevadm hwdb --update
-    sudo udevadm test /sys/class/input/eventX
-</pre>
-
-If the touch size range property shows up correctly, restart X or the
-Wayland compositor and libinput should now use the correct thresholds.
-The @ref tools can be used to verify the correct functionality first without
-the need for a restart.
-
-Once the touch size ranges are deemed correct, @ref reporting_bugs "report a
-bug" to get the thresholds into the repository.
-
-*/

doc/touchpads.dox

@@ -1,162 +0,0 @@
-/**
-@page touchpads Touchpads
-
-This page provides an outline of touchpad devices. Touchpads aren't simply
-categorised into a single type, instead they have a set of properties, a
-combination of number of physical buttons, multitouch support abilities and
-other properties.
-
-@section touchpads_buttons Number of buttons
-
-@subsection touchapds_buttons_phys Physically separate buttons
-
-Touchpads with physical buttons usually provide two buttons, left and right.
-A few touchpads with three buttons exist, and Apple used to have touchpads
-with a single physical buttons until ca 2008. Touchpads with only two
-buttons require the software stack to emulate a middle button. libinput does
-this when both buttons are pressed simultaneously.
-
-Note that many Lenovo laptops provide a pointing stick above the touchpad.
-This pointing stick has a set of physical buttons just above the touchpad.
-While many users use those as substitute touchpad buttons, they logically
-belong to the pointing stick. The *40 and *50 series are an exception here,
-the former had no physical buttons on the touchpad and required the top
-section of the pad to emulate pointing stick buttons, the *50 series has
-physical buttons but they are wired to the touchpads. The kernel re-routes
-those buttons through the trackstick device. See @ref t440_support for more
-information.
-
-@subsection touchpads_buttons_clickpads Clickpads
-
-Clickpads are the most common type of touchpads these days. A Clickpad has
-no separate physical buttons, instead the touchpad itself is clickable as a
-whole, i.e. a user presses down on the touch area and triggers a physical
-click. Clickpads thus only provide a single button, everything else needs to
-be software-emulated. See @ref clickpad_softbuttons for more information.
-
-Clickpads are labelled by the kernel with the @c INPUT_PROP_BUTTONPAD input
-property.
-
-@subsection touchpads_buttons_forcepads Forcepads
-
-Forcepads are Clickpads without a physical button underneath the hardware.
-They provide pressure and may have a vibration element that is
-software-controlled. This element can simulate the feel of a physical
-click or be co-opted for other tasks.
-
-
-@section touchpads_touch Touch capabilities
-
-Virtually all touchpads available now can <b>detect</b> multiple fingers on
-the touchpad, i.e. provide information on how many fingers are on the
-touchpad. The touch capabilities described here specify how many fingers a
-device can <b>track</b>, i.e. provide reliable positional information for. 
-In the kernel each finger is tracked in a so-called "slot", the number of
-slots thus equals the number of simultaneous touches a device can track.
-
-@subsection touchapds_touch_st Single-touch touchpads
-
-Single-finger touchpads can track a single touchpoint. Most single-touch
-touchpads can also detect three fingers on the touchpad, but no positional
-information is provided for those. In libinput, these touches are termed
-"fake touches". The kernel sends @c BTN_TOOL_DOUBLETAP, @c
-BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events when
-multiple fingers are detected.
-
-@subsection touchpads_touch_mt Pure multi-touch touchpads
-
-Pure multi-touch touchpads are those that can track, i.e. identify the
-location of all fingers on the touchpad. Apple's touchpads support 16
-touches, others support 5 touches like the Synaptics touchpads when using
-SMBus.
-
-These touchpads usually also provide extra information. Apple touchpads
-provide an ellipse and the orientation of the ellipse for each touch point.
-Other touchpads provide a pressure value for each touch point (see @ref
-touchpads_pressure_handling).
-
-Note that the kernel sends @c BTN_TOOL_DOUBLETAP, @c
-BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events for
-all touches for backwards compatibility. libinput ignores these events if
-the touchpad can track touches correctly.
-
-@subsection touchpads_touch_partial_mt Partial multi-touch touchpads
-
-The vast majority of touchpads fall into this category, the half-way
-point between single-touch and pure multi-touch. These devices can track N
-fingers, but detect more than N. For example, when using the serial
-protocol, Synaptics touchpads can track two fingers but may detect up to
-five.
-
-The number of slots may limit which features are available in libinput.
-Any device with two slots can support two-finger scrolling, but @ref
-thumb-detection or @ref palm_detection may be limited if only two slots are
-available.
-
-@subsection touchpads_touch_semi_mt Semi-mt touchpads
-
-A sub-class of partial multi-touch touchpads. These touchpads can
-technically detect two fingers but the location of both is limited to the
-bounding box, i.e. the first touch is always the top-left one and the second
-touch is the bottom-right one. Coordinates jump around as fingers move past
-each other.
-
-Many semi-mt touchpads also have a lower resolution for the second touch, or
-both touches. This may limit some features such as @ref gestures or
-@ref scrolling.
-
-Semi-mt are labelled by the kernel with the @c INPUT_PROP_SEMI_MT input
-property.
-
-@section touchpads_mis Other touchpad properties
-
-@subsection touchpads_external External touchpads
-
-External touchpads are USB or Bluetooth touchpads not in a laptop chassis,
-e.g. Apple Magic Trackpad or the Logitech T650. These are usually @ref
-touchpads_buttons_clickpads the biggest difference is that they can be
-removed or added at runtime. 
-
-One interaction method that is only possible on external touchpads is a
-thumb resting on the very edge/immediately next to the touchpad. On the far
-edge, touchpads don't always detect the finger location so clicking with a
-thumb barely touching the edge makes it hard or impossible to figure out
-which software button area the finger is on.
-
-These touchpads also don't need @ref palm_detection - since they're not
-located underneath the keyboard, accidental palm touches are a non-issue.
-
-@subsection touchpads_pressure_handling Touchpads pressure handling
-
-Pressure is usually directly related to contact area. Human fingers flatten
-out as the pressure on the pad increases, resulting in a bigger contact area
-and the firmware then calculates that back into a pressure reading.
-
-libinput uses pressure to detect accidental palm contact and thumbs, though
-pressure data is often device-specific and unreliable.
-
-@subsection touchpads_circular Circular touchpads
-
-Only listed for completeness, circular touchpads have not been used in
-laptops for a number of years. These touchpad shaped in an ellipse or
-straight.
-
-@subsection touchpads_tablets Graphics tablets
-
-Touch-capable graphics tablets are effectively external touchpads, with two
-differentiators: they are larger than normal touchpads and they have no
-regular touchpad buttons. They either work like a @ref
-touchpads_buttons_forcepads Forcepad, or rely on interaction methods that
-don't require buttons (like @ref tapping). Since the physical device is
-shared with the pen input, some touch arbitration is required to avoid touch
-input interfering when the pen is in use.  
-
-@subsection touchpads_edge_zone Dedicated edge scroll area
-
-Before @ref twofinger_scrolling became the default scroll method, some
-touchpads provided a marking on the touch area that designates the
-edge to be used for scrolling. A finger movement in that edge zone should
-trigger vertical motions. Some touchpads had markers for a horizontal
-scroll area too at the bottom of the touchpad.
-*/
-

doc/trackpoints.dox

@@ -1,153 +0,0 @@
-/**
-@page trackpoints Trackpoints and Pointing Sticks
-
-This page provides an overview of trackpoint handling in libinput, also
-refered to as Pointing Stick or Trackstick. The device itself is usually a
-round plastic stick between the G, H and B keys with a set of buttons below
-the space bar.
-
-@image html button-scrolling.svg "A trackpoint"
-
-libinput always treats the buttons below the space bar as the buttons that
-belong to the trackpoint even on the few laptops where the buttons are not
-physically wired to the trackpoint device anyway, see @ref t440_support.
-
-Trackpoint devices have @ref button_scrolling enabled by default. This may
-interfer with middle-button dragging, if middle-button dragging is required
-by a user then button scrolling must be disabled.
-
-@section trackpoint_range Motion range on trackpoints
-
-It is difficult to associate motion on a trackpoint with a physical
-reference. Unlike mice or touchpads where the motion can be
-measured in mm, the trackpoint only responds to pressure. Without special
-equipment it is impossible to measure identical pressure values across
-multiple laptops.
-
-The values provided by a trackpoint are motion deltas, usually corresponding
-to the pressure applied to the trackstick. For example, pressure towards the
-screen on a laptop provides negative y deltas at a fixed rate (e.g. every
-10ms). As the pressure increases, the delta increases too. As the pressure
-decreases, the delta decreases until it hits the neutral state.
-
-The delta range itself can vary greatly between laptops, some devices send a
-maximum delta value of 30, others can go beyond 100. To normalize the motion
-trackpoint, libinput uses the available delta range and fits its
-acceleration curve into this range. This requires calibration by the user,
-see @ref trackpoint_range_measure.
-
-@section trackpoint_range_measure Measuring the trackpoint range
-
-This section describes how to measure the trackpoint range and apply a hwdb
-entry to make this range known to libinput. libinput provides the tool
-`libinput measure trackpoint-range` for this task. This is an interactive
-tool and prints its instructions on the commandline. Example output from
-this tool is below:
-
-@code
-$ sudo libinput measure trackpoint-range
-This tool measures the commonly used pressure range of the
-trackpoint. Push the trackpoint:
-- Four times around the screen edges
-- From the top left to the bottom right and back, twice
-- From the top right to the bottom left and back, twice
-A minimum of 1000 events for each axis is required
-
-Movements should emulate fast pointer movement on the screen
-but not use excessive pressure that would not be used
-during day-to-day movement. For best results, run this tool
-several times to get an idea of the common range.
-
-Trackpoint sends: max x: 19, max y: 23 samples [121, 121]
-@endcode
-
-Once sufficient samples have been collected, the tool prints a simplified
-histogram for x and y axis deltas. This histogram should be used to
-<b>estimate</b> the appropriate trackpoint range. For example, let's look at
-the histogram below:
-
-@code
-Histogram for x axis deltas, in counts of 5
- -30:
- -29:
- -28: +
- -27: +
- -26: ++
- -25: ++++
- -24: +++++
- -23: ++
- -22: ++++++
- -21: +++
- -20: ++++
- -19: +++++++
- -18: ++++++++++++
- -17: ++++++++++++
- -16: ++++++++++++
- -15: ++++
- -14: +++++
- -13: +++++
- -12: ++++++
- -11: +++++
- -10: +++
-  -9: ++++
-  -8: +++++++
-  -7: +++++++
-  -6: ++++++++++++
-  -5: ++++++++++++
-  -4: ++++++++++++
-  -3: +++++++++
-  -2: +++++++++
-  -1: ++++++++
-   0: +++++++
-   1: +++++
-   2: +++++
-   3: ++++++
-   4: ++++++
-   5: +++++++
-   6: ++++
-   7: ++
-   8: +++
-   9: +++
-  10: +++
-  11: +++
-  12: +++
-  13: ++++
-  14: ++++++
-  15: ++++
-  16: ++++
-  17: ++++
-  18: ++++++
-  19: +++++++
-  20: ++++
-  21: ++++++
-  22: ++++++
-  23: ++++++
-  24: ++++++
-  25: +++++++++
-  26: +++++++
-  27: ++++++++
-  28: +++++
-  29: ++
-  30: ++
-  31: +
-  32:
-  33:
-  34:
-@endcode
-
-The 0 delta is the neutral state, each + represents 5 events with that
-delta value. Note how the curve is distributed, it's not a classic bell
-curve. That can be a factor of the input provided or the firmware-based
-pointer acceleration.
-
-Overall, the majority of events appear to be in the 0-25 range with a few
-outliers. So the trackpoint range libinput should use for this particular
-device would be 25. Note how there is a fair bit of guesswork involved, a
-trackpoint's data is never clean enough to get a definitive value. It is
-generally better to take a (slightly) smaller range than one too large.
-
-The udev property to set is `LIBINPUT_ATTR_TRACKPOINT_RANGE=25`. See @ref
-hwdb_modifying for details on how to apply this property.
-
-*/
-

doc/user/404.rst

@@ -0,0 +1,9 @@
+:orphan:
+
+===
+404
+===
+
+This page has permanently moved, probably to `<@TARGET@>`_
+
+This placeholder page will be removed soon.

doc/user/absolute-axes.rst

@@ -1,5 +1,8 @@
-/**
-@page absolute_axes Absolute axes
+.. _absolute_axes:
+
+==============================================================================
+Absolute axes
+==============================================================================
 
 Devices with absolute axes are those that send positioning data for an axis in
 a device-specific coordinate range, defined by a minimum and a maximum value.
@@ -10,7 +13,7 @@ libinput supports three types of devices with absolute axes:
 
  - multi-touch screens
  - single-touch screens
- - @ref tablet-support "graphics tablets"
+ - :ref:`graphics tablets <tablet-support>`
 
 Touchpads are technically absolute devices but libinput converts the axis values
 to directional motion and posts events as relative events. Touchpads do not count
@@ -19,11 +22,15 @@ as absolute devices in libinput.
 For all absolute devices in libinput, the default unit for x/y coordinates is
 in mm off the top left corner on the device, or more specifically off the
 device's sensor. If the device is physically rotated from its natural
-position and this rotation was communicated to libinput (e.g.
-@ref libinput_device_config_left_handed_set "by setting the device left-handed"),
-the coordinate origin is the top left corner of in the current rotation.
+position and this rotation was communicated to libinput (e.g. by setting
+the device left-handed),
+the coordinate origin is the top left corner in the current rotation.
 
-@section absolute_axes_handling Handling of absolute coordinates
+.. _absolute_axes_handling:
+
+------------------------------------------------------------------------------
+Handling of absolute coordinates
+------------------------------------------------------------------------------
 
 In most use-cases, absolute input devices are mapped to a single screen. For
 direct input devices such as touchscreens the aspect ratio of the screen and
@@ -31,8 +38,8 @@ the device match. Mapping the input device position to the output position is
 thus a simple mapping between two coordinates. libinput provides the API for
 this with
 
-- libinput_event_pointer_get_absolute_x_transformed() for pointer events
-- libinput_event_touch_get_x_transformed() for touch events
+- **libinput_event_pointer_get_absolute_x_transformed()** for pointer events
+- **libinput_event_touch_get_x_transformed()** for touch events
 
 libinput's API only provides the call to map into a single coordinate range.
 If the coordinate range has an offset, the compositor is responsible for
@@ -40,97 +47,98 @@ applying that offset after the mapping. For example, if the device is mapped
 to the right of two outputs, add the output offset to the transformed
 coordinate.
 
-@section absolute_axes_nores Devices without x/y resolution
+.. _absolute_axes_nores:
+
+------------------------------------------------------------------------------
+Devices without x/y resolution
+------------------------------------------------------------------------------
 
 An absolute device that does not provide a valid resolution is considered
 buggy and must be fixed in the kernel. Some touchpad devices do not
 provide resolution, those devices are correctly handled within libinput
 (touchpads are not absolute devices, as mentioned above).
 
-@section calibration Calibration of absolute devices
+.. _calibration:
+
+------------------------------------------------------------------------------
+Calibration of absolute devices
+------------------------------------------------------------------------------
 
 Absolute devices may require calibration to map precisely into the output
 range required. This is done by setting a transformation matrix, see
-libinput_device_config_calibration_set_matrix() which is applied to
+**libinput_device_config_calibration_set_matrix()** which is applied to
 each input coordinate.
 
-@f[
-\begin{pmatrix}
- cos\theta & -sin\theta & xoff \\
- sin\theta &  cos\theta & yoff \\
- 0   & 0    & 1
-\end{pmatrix} \begin{pmatrix}
-x \\ y \\ 1
-\end{pmatrix}
-@f]
+.. math::
+    \begin{pmatrix}
+     cos\theta & -sin\theta & xoff \\
+     sin\theta &  cos\theta & yoff \\
+     0   & 0    & 1
+    \end{pmatrix} \begin{pmatrix}
+    x \\ y \\ 1
+    \end{pmatrix}
 
-@f$\theta@f$ is the rotation angle. The offsets @f$xoff@f$ and @f$yoff@f$ are
-specified in device dimensions, i.e. a value of 1 equals one device width
-or height. Note that rotation applies to the device's origin, rotation
-usually requires an offset to move the coordinates back into the original
-range.
+:math:`\theta` is the rotation angle. The offsets :math:`xoff` and :math:`yoff` are
+specified in device dimensions, i.e. a value of 1 equals one device width or
+height. Note that rotation applies to the device's origin, rotation usually
+requires an offset to move the coordinates back into the original range.
 
 The most common matrices are:
 
 - 90 degree clockwise:
-@f$
-\begin{pmatrix}
- 0 & -1 & 1 \\
- 1 & 0 & 0 \\
- 0 & 0 & 1
-\end{pmatrix}
-@f$
-
+     .. math::
+         \begin{pmatrix}
+          0 & -1 & 1 \\
+          1 & 0 & 0 \\
+          0 & 0 & 1
+         \end{pmatrix}
 - 180 degree clockwise:
-@f$
-\begin{pmatrix}
- -1 & 0 & 1 \\
- 0 & -1 & 1 \\
- 0 & 0 & 1
-\end{pmatrix}
-@f$
-
+     .. math::
+         \begin{pmatrix}
+          -1 & 0 & 1 \\
+          0 & -1 & 1 \\
+          0 & 0 & 1
+         \end{pmatrix}
 - 270 degree clockwise:
-@f$
-\begin{pmatrix}
- 0 & 1 & 0 \\
- -1 & 0 & 1 \\
- 0 & 0 & 1
-\end{pmatrix}
-@f$
-
+     .. math::
+         \begin{pmatrix}
+          0 & 1 & 0 \\
+          -1 & 0 & 1 \\
+          0 & 0 & 1
+         \end{pmatrix}
 - reflection along y axis:
-@f$
-\begin{pmatrix}
- -1 & 0 & 1 \\
- 1 & 0 & 0 \\
- 0 & 0 & 1
-\end{pmatrix}
-@f$
+     .. math::
+         \begin{pmatrix}
+          -1 & 0 & 1 \\
+          1 & 0 & 0 \\
+          0 & 0 & 1
+         \end{pmatrix}
 
 See Wikipedia's
-<a href="http://en.wikipedia.org/wiki/Transformation_matrix">Transformation
-Matrix article</a> for more information on the matrix maths. See
-libinput_device_config_calibration_get_default_matrix() for how these
+`Transformation Matrix article <http://en.wikipedia.org/wiki/Transformation_matrix>`_
+for more information on the matrix maths. See
+**libinput_device_config_calibration_get_default_matrix()** for how these
 matrices must be supplied to libinput.
 
 Once applied, any x and y axis value has the calibration applied before it
 is made available to the caller. libinput does not provide access to the
 raw coordinates before the calibration is applied.
 
-@section absolute_axes_nonorm Why x/y coordinates are not normalized
+.. _absolute_axes_nonorm:
 
-x/y are not given in @ref motion_normalization "normalized coordinates"
+------------------------------------------------------------------------------
+Why x/y coordinates are not normalized
+------------------------------------------------------------------------------
+
+x/y are not given in :ref:`normalized coordinates <motion_normalization>`
 ([0..1]) for one simple reason: the aspect ratio of virtually all current
 devices is something other than 1:1. A normalized axes thus is only useful to
 determine that the stylus is e.g. at 78% from the left, 34% from the top of
 the device. Without knowing the per-axis resolution, these numbers are
 meaningless. Worse, calculation based on previous coordinates is simply wrong:
-a movement from 0/0 to 50%/50% is not a 45% degree line.
+a movement from 0/0 to 50%/50% is not a 45-degree line.
 
 This could be alleviated by providing resolution and information about the
 aspect ratio to the caller. Which shifts processing and likely errors into the
 caller for little benefit. Providing the x/y axes in mm from the outset
 removes these errors.
-
-*/

doc/user/absolute-coordinate-ranges.rst

@@ -0,0 +1,153 @@
+.. _absolute_coordinate_ranges:
+
+==============================================================================
+Coordinate ranges for absolute axes
+==============================================================================
+
+libinput requires that all touchpads provide a correct axis range and
+resolution. These are used to enable or disable certain features or adapt
+the interaction with the touchpad. For example, the software button area is
+narrower on small touchpads to avoid reducing the interactive surface too
+much. Likewise, palm detection works differently on small touchpads as palm
+interference is less likely to happen.
+
+Touchpads with incorrect axis ranges generate error messages
+in the form:
+<blockquote>
+Axis 0x35 value 4000 is outside expected range [0, 3000]
+</blockquote>
+
+This error message indicates that the ABS_MT_POSITION_X axis (i.e. the x
+axis) generated an event outside the expected range of 0-3000. In this case
+the value was 4000.
+This discrepancy between the coordinate range the kernels advertises vs.
+what the touchpad sends can be the source of a number of perceived
+bugs in libinput.
+
+.. _absolute_coordinate_ranges_fix:
+
+------------------------------------------------------------------------------
+Measuring and fixing touchpad ranges
+------------------------------------------------------------------------------
+
+To fix the touchpad you need to:
+
+#. measure the physical size of your touchpad in mm
+#. run the ``libinput measure touchpad-size`` tool
+#. verify the hwdb entry provided by this tool
+#. test locally
+#. send a patch to the `systemd project <https://github.com/systemd/systemd>`_.
+
+Detailed explanations are below.
+
+The ``libinput measure touchpad-size`` tool is an interactive tool. It must
+be called with the physical dimensions of the touchpad in mm. In the example
+below, we use 100mm wide and 55mm high. The tool will find the touchpad device
+automatically.
+
+::
+
+     $> sudo libinput measure touchpad-size 100x55
+     Using "Touchpad SynPS/2 Synaptics TouchPad": /dev/input/event4
+
+     Kernel specified touchpad size: 99.7x75.9mm
+     User specified touchpad size:   100.0x55.0mm
+
+     Kernel axis range:   x [1024..5112], y [2024..4832]
+     Detected axis range: x [   0..   0], y [   0..   0]
+
+     Move one finger along all edges of the touchpad
+     until the detected axis range stops changing.
+
+     ...
+
+Move the finger around until the detected axis range matches the data sent
+by the device. ``Ctrl+C`` terminates the tool and prints a
+suggested hwdb entry. ::
+
+    ...
+    Kernel axis range:   x [1024..5112], y [2024..4832]
+    ^C
+    Detected axis range: x [2072..4880], y [2159..4832]
+    Resolutions calculated based on user-specified size: x 28, y 49 units/mm
+
+    Suggested hwdb entry:
+    Note: the dmi modalias match is a guess based on your machine's modalias:
+      dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn20ARS25701:pvrThinkPadT440s:rvnLENOVO:rn20ARS25701:rvrSDK0E50512STD:cvnLENOVO:ct10:cvrNotAvailable:
+    Please verify that this is the most sensible match and adjust if necessary.
+    -8<--------------------------
+    # Laptop model description (e.g. Lenovo X1 Carbon 5th)
+    evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s*
+     EVDEV_ABS_00=2072:4880:28
+     EVDEV_ABS_01=2159:4832:49
+     EVDEV_ABS_35=2072:4880:28
+     EVDEV_ABS_36=2159:4832:49
+    -8<--------------------------
+    Instructions on what to do with this snippet are in /usr/lib/udev/hwdb.d/60-evdev.hwdb
+
+
+If there are discrepancies between the coordinate range the kernels
+advertises and what what the touchpad sends, the hwdb entry should be added to the
+``60-evdev.hwdb`` file provided by the `systemd project <https://github.com/systemd/systemd>`_.
+An example commit can be found
+`here <https://github.com/systemd/systemd/commit/26f667eac1c5e89b689aa0a1daef6a80f473e045>`_.
+
+The ``libinput measure touchpad-size`` tool attempts to provide the correct
+dmi match but it does require user verification.
+
+In most cases the dmi match can and should be trimmed to the system vendor (``svn``)
+and the product version (``pvr``) or product name (``pn``), with everything else
+replaced by a wildcard (``*``). In the above case, the match string is:
+
+::
+
+     evdev:name:SynPS/2 Synaptics TouchPad:dmi:*svnLENOVO:*pvrThinkPadT440s*
+
+As a general rule: for Lenovo devices use ``pvr`` and for all others use
+``pn``.
+
+.. note:: hwdb match strings only allow for alphanumeric ascii characters. Use a
+	wildcard (* or ?, whichever appropriate) for special characters.
+
+The actual axis overrides are in the form:
+
+::
+
+     # axis number=min:max:resolution
+      EVDEV_ABS_00=2072:4880:28
+
+or, if the range is correct but the resolution is wrong
+
+::
+
+     # axis number=::resolution
+      EVDEV_ABS_00=::28
+
+
+Note the leading single space. The axis numbers are in hex and can be found
+in ``linux/input-event-codes.h``. For touchpads ``ABS_X``, ``ABS_Y``,
+``ABS_MT_POSITION_X`` and ``ABS_MT_POSITION_Y`` are required.
+
+.. note:: The touchpad's ranges and/or resolution should only be fixed when
+	there is a significant discrepancy. A few units do not make a
+	difference and a resolution that is off by 2 or less usually does
+	not matter either.
+
+Once a match and override rule has been found, follow the instructions at
+the top of the
+`60-evdev.hwdb <https://github.com/systemd/systemd/blob/main/hwdb.d/60-evdev.hwdb>`_
+file to save it locally and trigger the udev hwdb reload. Rebooting is
+always a good idea. If the match string is correct, the new properties will
+show up in the
+output of
+
+::
+
+        udevadm info /sys/class/input/event4
+
+
+Adjust the command for the event node of your touchpad.
+A udev builtin will apply the new axis ranges automatically.
+
+When the axis override is confirmed to work, please submit it as a pull
+request to the `systemd project <https://github.com/systemd/systemd>`_.

doc/user/architecture.rst

@@ -0,0 +1,416 @@
+.. _architecture:
+
+==============================================================================
+libinput's internal architecture
+==============================================================================
+
+This page provides an outline of libinput's internal architecture. The goal
+here is to get the high-level picture across and point out the components
+and their interplay to new developers.
+
+The public facing API is in ``libinput.c``, this file is thus the entry point
+for almost all API calls. General device handling is in ``evdev.c`` with the
+device-type-specific implementations in ``evdev-<type>.c``. It is not
+necessary to understand all of libinput to contribute a patch.
+
+As of libinput 1.29 libinput has an internal plugin pipeline that modifies
+the event stream before libinput proper sees it, see
+:ref:`architecture-plugins`.
+
+:ref:`architecture-contexts` is the only user-visible implementation detail,
+everything else is purely internal implementation and may change when
+required.
+
+.. _architecture-contexts:
+
+------------------------------------------------------------------------------
+The udev and path contexts
+------------------------------------------------------------------------------
+
+The first building block is the "context" which can be one of
+two types, "path" and "udev". See **libinput_path_create_context()** and
+**libinput_udev_create_context()**. The path/udev specific bits are in
+``path-seat.c`` and ``udev-seat.c``. This includes the functions that add new
+devices to a context.
+
+
+.. graphviz::
+
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      libudev [label="libudev 'add' event"]
+      udev [label="**libinput_udev_create_context()**"];
+      udev_backend [label="udev-specific backend"];
+      context [label="libinput context"]
+      udev -> udev_backend;
+      libudev -> udev_backend;
+      udev_backend -> context;
+    }
+
+
+The udev context provides automatic device hotplugging as udev's "add"
+events are handled directly by libinput. The path context requires that the
+caller adds devices.
+
+
+.. graphviz::
+
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      path [label="**libinput_path_create_context()**"];
+      path_backend [label="path-specific backend"];
+      xdriver [label="**libinput_path_add_device()**"]
+      context [label="libinput context"]
+      path -> path_backend;
+      xdriver -> path_backend;
+      path_backend -> context;
+    }
+
+
+As a general rule: all Wayland compositors use a udev context, the X.org
+stack uses a path context.
+
+Which context was initialized only matters for creating/destroying a context
+and adding devices. The device handling itself is the same for both types of
+context.
+
+.. _architecture-device:
+
+------------------------------------------------------------------------------
+Device initialization
+------------------------------------------------------------------------------
+
+libinput only supports evdev devices, all the device initialization is done
+in ``evdev.c``. Much of the libinput public API is also a thin wrapper around
+the matching implementation in the evdev device.
+
+There is a 1:1 mapping between libinput devices and ``/dev/input/eventX``
+device nodes.
+
+
+
+.. graphviz::
+
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      devnode [label="/dev/input/event0"]
+
+      libudev [label="libudev 'add' event"]
+      xdriver [label="**libinput_path_add_device()**"]
+      context [label="libinput context"]
+
+      evdev [label="evdev_device_create()"]
+
+      devnode -> xdriver;
+      devnode -> libudev;
+      xdriver -> context;
+      libudev -> context;
+
+      context->evdev;
+
+    }
+
+
+Entry point for all devices is ``evdev_device_create()``, this function
+decides to create a ``struct evdev_device`` for the given device node.
+Based on the udev tags (e.g. ``ID_INPUT_TOUCHPAD``), a
+:ref:`architecture-dispatch` is initialized. All event handling is then in this
+dispatch.
+
+Rejection of devices and the application of quirks is generally handled in
+``evdev.c`` as well. Common functionality shared across multiple device types
+(like button-scrolling) is also handled here.
+
+.. _architecture-dispatch:
+
+------------------------------------------------------------------------------
+Device-type specific event dispatch
+------------------------------------------------------------------------------
+
+Depending on the device type, ``evdev_configure_device`` creates the matching
+``struct evdev_dispatch``. This dispatch interface contains the function
+pointers to handle events. Four such dispatch methods are currently
+implemented: touchpad, tablet, tablet pad, and the fallback dispatch which
+handles mice, keyboards and touchscreens.
+
+.. graphviz::
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      evdev [label="evdev_device_create()"]
+
+      fallback [label="evdev-fallback.c"]
+      touchpad [label="evdev-mt-touchpad.c"]
+      tablet [label="evdev-tablet.c"]
+      pad [label="evdev-tablet-pad.c"]
+
+      evdev -> fallback;
+      evdev -> touchpad;
+      evdev -> tablet;
+      evdev -> pad;
+
+    }
+
+
+Event dispatch is done per "evdev frame", a collection of events up until including
+the ``SYN_REPORT``. One such ``struct evdev_frame`` represents all state **updates**
+to the previous frame.
+
+While ``evdev.c`` pulls the event out of libevdev, the actual handling of the
+events is performed within the dispatch method.
+
+.. graphviz::
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      evdev [label="evdev_device_dispatch()"]
+
+      plugins [label="plugin pipline"]
+
+      fallback [label="fallback_interface_process()"];
+      touchpad [label="tp_interface_process()"]
+      tablet [label="tablet_process()"]
+      pad [label="pad_process()"]
+
+      evdev -> plugins;
+      plugins -> fallback;
+      plugins -> touchpad;
+      plugins -> tablet;
+      plugins -> pad;
+    }
+
+
+The dispatch methods then look at the ``struct evdev_frame`` and proceed to
+update the state.
+
+.. _architecture-plugins:
+
+------------------------------------------------------------------------------
+The Plugin Pipeline
+------------------------------------------------------------------------------
+
+As of libinput 1.29 libinput has an **internal** plugin pipeline. These plugins
+logically sit between libevdev and the :ref:`architecture-dispatch` and modify
+the device and/or event stream. The primary motivation of such plugins is that
+modifying the event stream is often simpler than analyzing the state later.
+
+Plugins are loaded on libinput context startup and are executed in-order. The last
+plugin is the hardcoded `evdev-plugin.c` which takes the modified event stream and
+passes the events to the dispatch.
+
+.. graphviz::
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      evdev [label="evdev_device_dispatch()"]
+
+      p1 [label="P1"]
+      p2 [label="P2"]
+      p3 [label="P3"]
+      ep [label="evdev-plugin"]
+
+      fallback [label="fallback_interface_process()"];
+      touchpad [label="tp_interface_process()"]
+      tablet [label="tablet_process()"]
+      pad [label="pad_process()"]
+
+      evdev -> p1;
+      p1 -> p2;
+      p2 -> p3;
+      p3 -> ep;
+      ep -> fallback;
+      ep -> touchpad;
+      ep -> tablet;
+      ep -> pad;
+    }
+
+Each plugin may not only modify the current event frame (this includes adding/removing events
+from the frame), it may also append or prepend additional event frames. For
+example the tablet proximity-timer plugin adds proximity in/out events to the
+event stream.
+
+.. graphviz::
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+      n0 [label= "", shape=none,height=.0,width=.0]
+      n1 [label= "", shape=none,height=.0,width=.0]
+
+      p1 [label="P1"]
+      p2 [label="P2"]
+      p3 [label="P3"]
+      ep [label="evdev-plugin"]
+
+      n0 -> p1 [label="F1"];
+      p1 -> p2 [label="F1"];
+      p2 -> p3 [label="F1,F2"];
+      p3 -> ep [label="F3,F1,F2"];
+      ep -> n1 [label="F3,F1,F2"];
+    }
+
+In the diagram above, the plugin ``P2`` *appends* a new frame (``F2``), the plugin ``P3``
+*prepends* a new frame (``F3``). The original event frame ``F1`` thus becomes the event frame
+sequence ``F3``, ``F1``, ``F2`` by the time it reaches the :ref:`architecture-dispatch`.
+
+Note that each plugin only sees one event frame at a time, so ``P3`` would see ``F1`` first,
+decides to prepend ``F3`` and passes ``F1`` through. It then sees ``F2`` but does nothing with
+it (optionally modified in-place).
+
+.. _architecture-configuration:
+
+------------------------------------------------------------------------------
+Device configuration
+------------------------------------------------------------------------------
+
+All device-specific configuration is handled through ``struct
+libinput_device_config_FOO`` instances. These are set up during device init
+and provide the function pointers for the ``get``, ``set``, ``get_default``
+triplet of configuration queries (or more, where applicable).
+
+For example, the ``struct tablet_dispatch`` for tablet devices has a
+``struct libinput_device_config_accel``. This struct is set up with the
+required function pointers to change the profiles.
+
+
+.. graphviz::
+
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      tablet [label="struct tablet_dispatch"]
+      config [label="struct libinput_device_config_accel"];
+      tablet_config [label="tablet_accel_config_set_profile()"];
+      tablet->config;
+      config->tablet_config;
+    }
+
+
+When the matching ``**libinput_device_config_set_FOO()**`` is called, this goes
+through to the config struct and invokes the function there. Thus, it is
+possible to have different configuration functions for a mouse vs a
+touchpad, even though the interface is the same.
+
+
+.. graphviz::
+
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      libinput [label="**libinput_device_config_accel_set_profile()**"];
+      tablet_config [label="tablet_accel_config_set_profile()"];
+      libinput->tablet_config;
+    }
+
+
+.. _architecture-filter:
+
+------------------------------------------------------------------------------
+Pointer acceleration filters
+------------------------------------------------------------------------------
+
+All pointer acceleration is handled in the ``filter.c`` file and its
+associated files.
+
+The ``struct motion_filter`` is initialized during device init, whenever
+deltas are available they are passed to ``filter_dispatch()``. This function
+returns a set of :ref:`normalized coordinates <motion_normalization_customization>`.
+
+All actual acceleration is handled within the filter, the device itself has
+no further knowledge. Thus it is possible to have different acceleration
+filters for the same device types (e.g. the Lenovo X230 touchpad has a
+custom filter).
+
+
+.. graphviz::
+
+
+    digraph context
+    {
+      compound=true;
+      rankdir="LR";
+      node [
+        shape="box";
+      ]
+
+      fallback [label="fallback deltas"];
+      touchpad [label="touchpad deltas"];
+      tablet [label="tablet deltas"];
+
+      filter [label="filter_dispatch"];
+
+      fallback->filter;
+      touchpad->filter;
+      tablet->filter;
+
+      flat [label="accelerator_interface_flat()"];
+      x230 [label="accelerator_filter_x230()"];
+      pen [label="tablet_accelerator_filter_flat_pen()"];
+
+      filter->flat;
+      filter->x230;
+      filter->pen;
+
+    }
+
+
+Most filters convert the deltas (incl. timestamps) to a motion speed and
+then apply a so-called profile function. This function returns a factor that
+is then applied to the current delta, converting it into an accelerated
+delta. See :ref:`pointer-acceleration` for more details.
+the current

doc/user/building.rst

@@ -0,0 +1,299 @@
+.. _building_libinput:
+
+==============================================================================
+libinput build instructions
+==============================================================================
+
+
+.. contents::
+    :local:
+    :backlinks: entry
+
+Instructions on how to build libinput and its tools and how to build against
+libinput.
+
+The build instruction on this page detail how to overwrite your
+system-provided libinput with one from the git repository, see
+see :ref:`reverting_install` to revert to the previous state.
+
+.. _distribution_repos:
+
+------------------------------------------------------------------------------
+Distribution repositories for libinput from git
+------------------------------------------------------------------------------
+
+Some distributions provide package repositories for users that want to test
+the latest libinput without building it manually.
+
+.. note:: The list below is provided for convenience. The libinput community
+   cannot provide any guarantees that the packages in those repositories are
+   correct, up-to-date and/or unmodified from the git branch. Due dilligence
+   is recommended.
+
+The following repositories provide an up-to-date package for libinput:
+
+- **Arch:** https://aur.archlinux.org/packages/libinput-git/
+- **Fedora:** https://copr.fedorainfracloud.org/coprs/whot/libinput-git/
+
+Please follow the respective repositories for instructions on how to enable
+the repository and install libinput.
+
+
+.. _building:
+
+------------------------------------------------------------------------------
+Building libinput
+------------------------------------------------------------------------------
+
+libinput uses `meson <https://www.mesonbuild.com>`_ and
+`ninja <https://www.ninja-build.org>`_. A build is usually the three-step
+process below.  A successful build requires the
+:ref:`building_dependencies` to be installed before running meson.
+
+
+::
+
+     $> git clone https://gitlab.freedesktop.org/libinput/libinput
+     $> cd libinput
+     $> meson setup --prefix=/usr builddir/
+     $> ninja -C builddir/
+     $> sudo ninja -C builddir/ install
+
+
+When running libinput versions 1.11.x or earlier, you must run
+
+::
+
+     $> sudo systemd-hwdb update
+
+
+Additional options may also be specified. For example:
+
+::
+
+     $> meson setup --prefix=/usr -Ddocumentation=false builddir/
+
+
+We recommend that users disable the documentation, it's not usually required
+for testing and reduces the number of dependencies needed.
+
+The ``prefix`` or other options can be changed later with the
+``meson configure`` command. For example:
+
+::
+
+     $> meson configure builddir/ -Dprefix=/some/other/prefix -Ddocumentation=true
+     $> ninja -C builddir
+     $> sudo ninja -C builddir/ install
+
+
+Running ``meson configure builddir/`` with no other arguments lists all
+configurable options meson provides.
+
+To rebuild from scratch, simply remove the build directory and run meson
+again:
+
+::
+
+     $> rm -r builddir/
+     $> meson setup --prefix=....
+
+
+.. _verifying_install:
+
+..............................................................................
+Verifying the install
+..............................................................................
+
+To verify the install worked correctly, check that libinput.so.x.x.x is in
+the library path and that all symlinks point to the new library.
+
+::
+
+     $> ldconfig -p | grep libinput | awk '{print $NF}' | xargs ls -l
+     lrwxrwxrwx 1 root root      14 lug 22 13:06 /usr/lib/x86_64-linux-gnu/libinput.so -> libinput.so.10
+     lrwxrwxrwx 1 root root      19 lug 22 13:06 /usr/lib/x86_64-linux-gnu/libinput.so.10 -> libinput.so.10.13.0
+     -rwxr-xr-x 1 root root 1064144 lug 22 13:06 /usr/lib/x86_64-linux-gnu/libinput.so.10.13.0
+
+.. _reverting_install:
+
+..............................................................................
+Reverting to the system-provided libinput package
+..............................................................................
+
+The recommended way to revert to the system install is to use the package
+manager to reinstall the libinput package. In some cases, this may leave
+files in the system (e.g. ``/usr/lib/libinput.la``) but these files are
+usually harmless. To definitely remove all files, run the following command
+from the libinput source directory:
+
+
+::
+
+     $> sudo ninja -C builddir/ uninstall
+     # WARNING: Do not restart the computer/X/the Wayland compositor after
+     # uninstall, reinstall the system package immediately!
+
+
+The following commands reinstall the current system package for libinput,
+overwriting manually installed files.
+
+- **Debian/Ubuntu** based distributions: ``sudo apt-get install --reinstall libinput``
+- **Fedora 22** and later: ``sudo dnf reinstall libinput``
+- **RHEL/CentOS/Fedora 21** and earlier: ``sudo yum reinstall libinput``
+- **openSUSE**: ``sudo zypper install --force libinput10``
+- **Arch**: ``sudo pacman -S libinput``
+
+.. _building_selinux:
+
+..............................................................................
+SELinux adjustments
+..............................................................................
+
+.. note:: This section only applies to meson version < 0.42.0
+
+On systems with SELinux, overwriting the distribution-provided package with
+a manually built libinput may cause SELinux denials. This usually manifests
+when gdm does not start because it is denied access to libinput. The journal
+shows a log message in the form of:
+
+
+::
+
+     May 25 15:28:42 localhost.localdomain audit[23268]: AVC avc:  denied  { execute } for  pid=23268 comm="gnome-shell" path="/usr/lib64/libinput.so.10.12.2" dev="dm-0" ino=1709093 scontext=system_u:system_r:xdm_t:s0-s0:c0.c1023 tcontext=unconfined_u:object_r:user_home_t:s0 tclass=file permissive=0
+     May 25 15:28:42 localhost.localdomain org.gnome.Shell.desktop[23270]: /usr/bin/gnome-shell: error while loading shared libraries: libinput.so.10: failed to map segment from shared object
+
+
+The summary of this error message is that gdm's gnome-shell runs in the
+``system_u:system_r:xdm_t`` context but libinput is installed with the
+context ``unconfined_u:object_r:user_home_t``.
+
+To avoid this issue, restore the SELinux context for any system files.
+
+
+::
+
+     $> sudo restorecon /usr/lib*/libinput.so.*
+
+
+This issue is tracked in https://github.com/mesonbuild/meson/issues/1967.
+
+.. _building_dependencies:
+
+------------------------------------------------------------------------------
+Build dependencies
+------------------------------------------------------------------------------
+
+libinput has a few build-time dependencies that must be installed prior to
+running meson.
+
+.. hint:: The build dependencies for some distributions can be found in the
+	`GitLab Continuous Integration file <https://gitlab.freedesktop.org/libinput/libinput/blob/main/.gitlab-ci.yml>`_.
+	Search for **FEDORA_PACKAGES** in the **variables:** definition
+	and check the list for an entry for your distribution.
+
+In most cases, it is sufficient to install the dependencies that your
+distribution uses to build the libinput package.  These can be installed
+with one of the following commands:
+
+- **Debian/Ubuntu** based distributions: ``sudo apt-get build-dep libinput``
+- **Fedora 22** and later: ``sudo dnf builddep libinput``
+- **RHEL/CentOS/Fedora 21** and earlier: ``sudo yum-builddep libinput``
+- **openSUSE**: ::
+
+     $> sudo zypper modifyrepo --enable ``zypper repos | grep source | awk '{print $5}'``
+     $> sudo zypper source-install -d libinput10
+     $> sudo zypper install autoconf automake libtool
+     $> sudo zypper modifyrepo --disable ``zypper repos | grep source | awk '{print $5}'``
+
+
+- **Arch**: ::
+
+     $> sudo pacman -S asp
+     $> cd $(mktemp -d)
+     $> asp export libinput
+     $> cd libinput
+     $> makepkg --syncdeps --nobuild --noextract
+
+
+
+If dependencies are missing, meson shows a message ``No package 'foo'
+found``.  See
+`this blog post here <https://who-t.blogspot.com/2018/07/meson-fails-with-native-dependency-not-found.html>`_
+for instructions on how to fix it.
+
+..............................................................................
+Build dependencies per distribution
+..............................................................................
+
+
+.. include:: dependencies.rst
+
+
+.. _building_conditional:
+
+------------------------------------------------------------------------------
+Conditional builds
+------------------------------------------------------------------------------
+
+libinput supports several meson options to disable parts of the build. See
+the ``meson_options.txt`` file in the source tree for a full list of
+available options. The default build enables most options and thus requires
+more build dependencies. On systems where build dependencies are an issue,
+options may be disabled with this meson command: ::
+
+    meson setup --prefix=/usr -Dsomefeature=false builddir
+
+Where ``-Dsomefeature=false`` may be one of:
+
+- ``-Ddocumentation=false``
+    Disables the documentation build (this website). Building the
+    documentation is only needed on the maintainer machine.
+- ``-Dtests=false``
+    Disables the test suite. The test suite is only needed on developer
+    systems.
+- ``-Ddebug-gui=false``
+    Disables the ``libinput debug-gui`` helper tool (see :ref:`tools`),
+    dropping GTK and other build dependencies. The debug-gui is only
+    required for troubleshooting.
+- ``-Dlibwacom=false``
+    libwacom is required by libinput's tablet code to gather additional
+    information about tablets that is not available from the kernel device.
+    It is not recommended to disable libwacom unless libinput is used in an
+    environment where tablet support is not required. libinput provides tablet
+    support even without libwacom, but some features may be missing or working
+    differently.
+
+.. _building_against:
+
+------------------------------------------------------------------------------
+Building against libinput
+------------------------------------------------------------------------------
+
+libinput provides a
+`pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ file.
+Software that uses autotools should use the ``PKG_CHECK_MODULES`` autoconf
+macro: ::
+
+    PKG_CHECK_MODULES(LIBINPUT, "libinput")
+
+Software that uses meson should use the ``dependency()`` function: ::
+
+    pkgconfig = import('pkgconfig')
+    dep_libinput = dependency('libinput')
+
+Software that uses CMake should use: ::
+
+    find_package(Libinput)
+    target_link_libraries(myprogram PRIVATE Libinput::Libinput)
+
+Otherwise, the most rudimentary way to compile and link a program against
+libinput is:
+
+
+::
+
+         gcc -o myprogram myprogram.c ``pkg-config --cflags --libs libinput``
+
+
+For further information on using pkgconfig see the pkg-config documentation.

doc/user/button-debouncing.rst

@@ -1,6 +1,9 @@
-/**
 
-@page button_debouncing Button debouncing
+.. _button_debouncing:
+
+==============================================================================
+Button debouncing
+==============================================================================
 
 Physical buttons experience wear-and-tear with usage. On some devices this
 can result in an effect called "contact bouncing" or "chatter". This effect
@@ -29,8 +32,8 @@ immediately and most release events are delivered immediately. The
 does not enable this method unless a faulty event sequence is detected. A
 message is printed to the log when spurious deboucing was detected.
 
-Note that libinput's debouncing intended to correct hardware damage or
-substandard hardware. Debouncing is also used as an accessibility feature
+libinput's debouncing is supposed to correct hardware damage or
+substandard hardware. Debouncing also exists as an accessibility feature
 but the requirements are different. In the accessibility feature, multiple
 physical key presses, usually caused by involuntary muscle movement, must be
 filtered to only one key press. This feature must be implemented higher in
@@ -42,6 +45,12 @@ extra line is added to show the timeouts used by libinput that
 affect the button state handling. The waveform's high and low states
 correspond to the buttons 'pressed' and 'released' states, respectively.
 
-@image html button-debouncing-wave-diagram.svg "Diagram illustrating button debouncing"
+.. figure:: button-debouncing-wave-diagram.svg
+    :align: center
 
-*/
+    Diagram illustrating button debouncing
+
+
+Some devices send events in bursts, erroneously triggering the button
+debouncing detection. Please :ref:`file a bug <reporting_bugs>` if that
+occurs for your device.

doc/user/clickpad-softbuttons.rst

@@ -0,0 +1,144 @@
+.. _clickpad_softbuttons:
+
+==============================================================================
+Clickpad software button behavior
+==============================================================================
+
+"Clickpads" are touchpads without separate physical buttons. Instead, the
+whole touchpad acts as a button and left or right button clicks are
+distinguished by :ref:`the location of the fingers <software_buttons>` or
+the :ref:`number of fingers on the touchpad <clickfinger>`.
+"ClickPad" is a trademark by `Synaptics Inc. <http://www.synaptics.com/en/clickpad.php>`_
+but for simplicity we refer to any touchpad with the above feature as Clickpad,
+regardless of the manufacturer.
+
+The kernel marks clickpads with the
+`INPUT_PROP_BUTTONPAD <https://www.kernel.org/doc/Documentation/input/event-codes.txt>`_
+property. Without this property, libinput would not know whether a touchpad
+is a clickpad or not. To perform a right-click on a Clickpad, libinput
+provides :ref:`software_buttons` and :ref:`clickfinger`.
+
+.. note:: The term "click" refers refer to a physical button press
+	  and/or release of the touchpad, the term "button event" refers to
+	  the events generated by libinput in response to a click.
+
+.. _software_buttons:
+
+------------------------------------------------------------------------------
+Software button areas
+------------------------------------------------------------------------------
+
+The bottom of the touchpad is split into three distinct areas generate left,
+middle or right button events on click. The height of the button area
+depends on the hardware but is usually around 10mm.
+
+.. figure :: software-buttons-visualized.svg
+     :align: center
+
+     The locations of the virtual button areas.
+
+
+Left, right and middle button events can be triggered as follows:
+
+- if a finger is in the main area or the left button area, a click generates
+  left button events.
+- if a finger is in the right area, a click generates right button events.
+- if a finger is in the middle area, a click generates middle button events.
+
+.. figure:: software-buttons.svg
+    :align: center
+
+    Left, right and middle-button click with software button areas
+
+The middle button is always centered on the touchpad and smaller in size
+than the left or right button. The actual size is device-dependent. Many
+touchpads do not have visible markings so the exact location of the button
+is unfortunately not visibly obvious.
+
+.. note:: If :ref:`middle button emulation <middle_button_emulation>` is
+	  enabled on a clickpad, only left and right button areas are
+	  available.
+
+If fingers are down in the main area in addition to fingers in the
+left or right button area, those fingers are are ignored.
+A release event always releases the buttons logically down, regardless of
+the current finger position
+
+.. figure:: software-buttons-thumbpress.svg
+    :align: center
+
+    Only the location of the thumb determines whether it is a left, right or
+    middle click.
+
+The movement of a finger can alter the button area behavior:
+
+- if a finger starts in the main area and moves into the software button
+  area, the software buttons do not apply to that finger
+- once a finger has moved out of the button area, it cannot move back in and
+  trigger a right or middle button event
+- a finger moving within the software button area does not move the pointer
+- once a finger moves out out of the button area it will control the
+  pointer (this only applies if there is no other finger down on the
+  touchpad)
+
+.. figure:: software-buttons-conditions.svg
+    :align: center
+
+    **Left:** moving a finger into the right button area does not trigger a
+    right-button click.
+    **Right:** moving within the button areas does not generate pointer
+    motion.
+
+On some touchpads, notably the 2015 Lenovo X1 Carbon 3rd series, the very
+bottom end of the touchpad is outside of the sensor range but it is possible
+to trigger a physical click there. To libinput, the click merely shows up as
+a left button click without any positional finger data and it is
+impossible to determine whether it is a left or a right click. libinput
+ignores such button clicks, this behavior is intentional.
+
+.. _clickfinger:
+
+------------------------------------------------------------------------------
+Clickfinger behavior
+------------------------------------------------------------------------------
+
+This is the default behavior on Apple touchpads. Here, a left, right, middle
+button event is generated when one, two, or three fingers are held down on the
+touchpad when a physical click is generated, given the default mapping. The
+location of the fingers does not matter and there are no software-defined
+button areas. It is possible to swap right and middle buttons, the same way as
+with :ref:`tapping <tapping>`.
+
+.. figure:: clickfinger.svg
+    :align: center
+
+    One, two and three-finger click with Clickfinger behavior
+
+On some touchpads, libinput imposes a limit on how the fingers may be placed
+on the touchpad. In the most common use-case this allows for a user to
+trigger a click with the thumb while leaving the pointer-moving finger on
+the touchpad.
+
+.. figure:: clickfinger-distance.svg
+    :align: center
+
+    Illustration of the distance detection algorithm
+
+In the illustration above the red area marks the proximity area around the
+first finger. Since the thumb is outside of that area libinput considers the
+click a single-finger click rather than a two-finger click.
+
+.. _special_clickpads:
+
+------------------------------------------------------------------------------
+Special Clickpads
+------------------------------------------------------------------------------
+
+The Lenovo \*40 series laptops have a clickpad that provides two software button sections, one at
+the top and one at the bottom. See :ref:`Lenovo \*40 series touchpad support <t440_support>`
+for details on the top software button.
+
+Some Clickpads, notably some Cypress ones, perform right button detection in
+firmware and appear to userspace as if the touchpad had physical buttons.
+While physically clickpads, these are not handled by the software and
+treated like traditional touchpads.

doc/user/clickpad-with-right-button.rst

@@ -0,0 +1,46 @@
+.. _clickpads_with_right_buttons:
+
+==============================================================================
+Clickpads with a fake right button
+==============================================================================
+
+libinput relies on the kernel to label :ref:`Clickpads <touchpads_buttons_clickpads>`
+with the ``INPUT_PROP_BUTTONPAD`` property so it can enable the correct
+:ref:`clickpad_softbuttons`. Clickpads are not expected to have a right button
+since the whole surface can be depressed.
+
+A common bug encountered with :ref:`Clickpads <touchpads_buttons_clickpads>`
+is that the device advertises a physical right button where no such button
+exists. This is usually a bug in the firmware of the device and causes the
+following warning to be emitted by libinput::
+
+    "<device name> clickpad advertising right button"
+
+The user-visible effect of this is usually negligible since these devices
+cannot actually trigger a right click and libinput's default behaviors for
+clickpads work as expected.
+
+However, we should nonetheless correct the device to get rid of this warning
+and avoid potential issues with future features. The :ref:`device-quirks`
+provide a simple way to disable the fake right button on the device. The
+following quirk disables the right button on the MyModel laptop from the
+MyVendor OEM::
+
+    [MyVendor MyModel Touchpad]
+    MatchName=Foo Bar Touchpad
+    MatchUdevtype=touchpad
+    MatchDMIModAlias=dmi:*:svnMyVendor:pnMyModel:*
+    AttrEventCode=-BTN_RIGHT
+
+The name of the device can be obtained using :ref:`libinput record <libinput-record>`,
+the modalias match is a shell-style glob against the value of ``/sys/class/dmi/id/modalias``.
+In most cases, matching should be against ``svn`` (system vendor) and one of
+``pn`` (product name) or ``pvr`` (product version), whichever provides a
+useful description of the individual laptop model. See the
+:ref:`device-quirks` documentation for details on testing local quirks.
+
+For reference, some example commits that add such a quirk are:
+
+ - `bf61ab9bb0694d0ac3d60a7f815779abfe4886e6 <https://gitlab.freedesktop.org/libinput/libinput/-/commit/bf61ab9bb0694d0ac3d60a7f815779abfe4886e6>`__
+ - `74fac6d040ac62048882dfb6f73da567ace6a6f5 <https://gitlab.freedesktop.org/libinput/libinput/-/commit/74fac6d040ac62048882dfb6f73da567ace6a6f5>`__
+ - `89cd0f990e3bee9906754d6ca8484ed5aa392249 <https://gitlab.freedesktop.org/libinput/libinput/-/commit/89cd0f990e3bee9906754d6ca8484ed5aa392249>`__

doc/user/conf.py.in

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/stable/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# sys.path.insert(0, os.path.abspath('.'))
+
+import sys
+import os
+sys.path.insert(0, os.path.abspath('@BUILDDIR@'))
+
+# -- Project information -----------------------------------------------------
+
+project = '@PROJECT_NAME@'
+copyright = '2019, the libinput authors'
+author = 'the libinput authors'
+
+# The short X.Y version
+version = '@PROJECT_VERSION@'
+# The full version, including alpha/beta/rc tags
+release = '@PROJECT_VERSION@'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.mathjax',
+    'sphinx.ext.graphviz',
+    'sphinx.ext.extlinks',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+highlight_language = 'none'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    'collapse_navigation': False,
+    'navigation_depth': 3,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '@PROJECT_NAME@doc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, '@PROJECT_NAME@.tex', '@PROJECT_NAME@ Documentation',
+     'Peter Hutterer', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, '@PROJECT_NAME@', '@PROJECT_NAME@ Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, '@PROJECT_NAME@', '@PROJECT_NAME@ Documentation',
+     author, '@PROJECT_NAME@', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Extension configuration -------------------------------------------------
+
+from recommonmark.parser import CommonMarkParser
+
+extlinks = { 'commit' :
+		('https://gitlab.freedesktop.org/libinput/libinput/commit/%s',
+			'git commit %s')
+}
+
+# -- git version hack -------------------------------------------------
+#
+# meson doesn't take configuration_data() for vcs_tag, so we cannot replace
+# two substrings in the same file.
+#
+# sphinx cannot do ..include:: without linebreaks, so in-line replacements
+# are a no-go.
+#
+# Work around this by generating a mini python module in meson through
+# vcs_tag, then use that to generate the replacements in rst_prolog.
+
+import git_version
+
+rst_prolog = """
+   .. |git_version| replace:: :commit:`{}`
+   .. |git_version_full| replace:: :commit:`{}`
+
+""".format(git_version.get_git_version(),
+	   git_version.get_git_version_full)

doc/user/configuration.rst

@@ -0,0 +1,237 @@
+.. _config_options:
+
+==============================================================================
+Configuration options
+==============================================================================
+
+Below is a list of configurable options exposed to the users.
+
+.. contents::
+   :depth: 1
+   :local:
+
+
+.. hint:: Not all configuration options are available on all devices. Use
+	  :ref:`libinput list-devices <libinput-list-devices>` to show the
+	  configuration options for local devices.
+
+libinput's configuration interface is available to the caller only, not
+directly to the user. Thus it is the responsibility of the caller to expose
+the various options and how these options are exposed. For example, the
+`xf86-input-libinput driver <https://gitlab.freedesktop.org/xorg/driver/xf86-input-libinput/>`_
+exposes the options through X Input device properties and `xorg.conf.d
+<https://linux.die.net/man/5/xorg.conf.d>`_ options.  See the `libinput(4)
+<https://www.mankier.com/4/libinput>`_ man page for more details.
+
+
+------------------------------------------------------------------------------
+Tap-to-click
+------------------------------------------------------------------------------
+
+See :ref:`tapping` for details on how this feature works. Configuration
+options exposed by libinput are:
+
+- how many tapping fingers are supported by this device
+- a toggle to enable/disable tapping
+- a toggle to enable/disable tap-and-drag, see :ref:`tapndrag`.
+- a toggle to enable/disable tap-and-drag drag lock, see :ref:`tapndrag`
+- The default order is 1, 2, 3 finger tap mapping to left, right, middle
+  click, respectively. This order can be changed to left, middle, right click,
+  respectively.
+
+Tapping is usually available on touchpads and the touchpad part of external
+graphics tablets. Tapping is usually **not** available on touch screens,
+for those devices it is expected to be implemented by the toolkit.
+
+------------------------------------------------------------------------------
+Three-finger drag
+------------------------------------------------------------------------------
+
+Three-finger drag allows emulates the mouse button down while three fingers
+are down on a touchpad without the need to press a physical button or use
+:ref:`tapndrag`. See :ref:`drag_3fg` for details on how this feature works.
+
+Three-finger drag is usually available on touchpads and the touchpad part of
+external graphics tablets. Three-finger drag is usually **not** available on
+touch screens, for those devices it is expected to be implemented by the
+toolkit.
+
+------------------------------------------------------------------------------
+Send Events Mode
+------------------------------------------------------------------------------
+
+The Send Events Mode is libinput's terminology for disabling a device. It is
+more precise in that the device only stops sending events but may not get
+fully disabled. For example, disabling the touchpad on a
+:ref:`Lenovo T440 and similar <t440_support>` leaves the top software
+buttons enabled for the trackpoint. Available options are
+**enabled** (send events normally), **disabled** ( do not send events),
+**disabled on external mouse** (disable the device while an external mouse
+is plugged in).
+
+
+.. _config_pointer_acceleration:
+
+------------------------------------------------------------------------------
+Pointer acceleration
+------------------------------------------------------------------------------
+
+Pointer acceleration is a function to convert input deltas to output deltas,
+usually based on the movement speed of the device, see
+:ref:`pointer-acceleration` for details.
+
+Pointer acceleration is normalized into a [-1, 1] range, where -1 is
+"slowest" and 1 is "fastest". Most devices use a default speed of 0.
+
+The pointer acceleration profile defines **how** the input deltas are
+converted, see :ref:`ptraccel-profiles`. Most devices have their default
+profile (usually called "adaptive") and a "flat" profile. The flat profile
+does not apply any acceleration.
+
+------------------------------------------------------------------------------
+Scrolling
+------------------------------------------------------------------------------
+
+"Natural scrolling" is the terminology for moving the content in the
+direction of scrolling, i.e. moving the wheel or fingers down moves the page
+down. Traditional scrolling moves the content in the opposite direction.
+Natural scrolling can be turned on or off, it is usually off by default.
+
+The scroll method defines how to trigger scroll events. On touchpads
+libinput provides two-finger scrolling and edge scrolling. Two-finger
+scrolling converts a movement with two fingers to a series of scroll events.
+Edge scrolling converts a movement with one finger along the right or bottom
+edge of the touchpad into a series of scroll events.
+
+On other libinput provides button-scrolling - movement of the device while
+the designated scroll button is down is converted to scroll events. The
+button used for scrolling is configurable.
+
+The scroll method can be chosen or disabled altogether but most devices only
+support a subset of available scroll methods. libinput's default is
+two-finger scrolling for multi-touch touchpads, edge scrolling for
+single-touch touchpads. On tracksticks, button scrolling is enabled by
+default.
+
+See :ref:`scrolling` for more details on how the scroll methods work.
+
+------------------------------------------------------------------------------
+Left-handed Mode
+------------------------------------------------------------------------------
+
+Left-handed mode switches the device's functionality to be more
+accommodating for left-handed users. On mice this usually means swapping the
+left and right mouse button, on tablets this allows the tablet to be used
+upside-down to present the pad buttons for the non-dominant right hand. Not
+all devices have left-handed mode.
+
+Left-handed mode can be enabled or disabled and is disabled by default.
+
+------------------------------------------------------------------------------
+Middle Button Emulation
+------------------------------------------------------------------------------
+
+Middle button emulation converts a simultaneous left and right button click
+into a middle button. The emulation can be enabled or disabled. Middle
+button emulation is usually enabled when the device does not provide a
+middle button.
+
+------------------------------------------------------------------------------
+Click method
+------------------------------------------------------------------------------
+
+The click method defines how button events are triggered on a :ref:`clickpad
+<clickpad_softbuttons>`. When set to button areas, the bottom area of the
+touchpad is divided into a left, middle and right button area. When set to
+clickfinger, the number of fingers on the touchpad decide the button type.
+Clicking with 1, 2, 3 fingers triggers a left, right, or middle click,
+respectively. The default click method is software button areas. Click
+methods are usually only available on :ref:`clickpads
+<clickpad_softbuttons>`.
+
+------------------------------------------------------------------------------
+Disable while typing
+------------------------------------------------------------------------------
+
+DWT is the most generic form of palm detection on touchpad. While the user
+is typing on an internal keyboard the touchpad is disabled, the touchpad
+is enabled again after a timeout.  See :ref:`disable-while-typing` for more
+info.
+
+Disable-while-typing can be enabled or disabled, it is enabled by default on
+most touchpads.
+
+------------------------------------------------------------------------------
+Disable while trackpointing
+------------------------------------------------------------------------------
+
+DWTP is a form of palm detecion for devices that have a trackpoint (like
+Thinkpads). While the user is using the trackpoint, the touchpad is disabled,
+being enabled again after a timeout. See :ref:`disable-while-trackpointing` for
+more info.
+
+Disable-while-trackpointing can be enabled or disabled, it is enabled by
+default.
+
+------------------------------------------------------------------------------
+Calibration
+------------------------------------------------------------------------------
+
+Calibration is available for some direct-input devices (touch screens,
+graphics tablets, etc.). The purpose of calibration is to ensure the input
+lines up with the output and the configuration data is a transformation
+matrix. It is thus not expected that the user sets this option. The desktop
+environment should provide an interface for this.
+
+------------------------------------------------------------------------------
+Rotation
+------------------------------------------------------------------------------
+
+The device rotation applies a corrective angle to relative input events,
+allowing the device to be used e.g. sideways or upside-down. For example, a
+trackball may be used in a 90° rotated position for accessibility reasons -
+such a rotated position allows triggering the buttons with the thumb or
+the non-dominant hand.
+
+Note that where a device rotation is higher than 160 but less than 200 degrees,
+the direction of wheels is also inverted. For all other angles, the wheel
+direction is left as-is.
+
+.. _config-tablet-pressure-range:
+
+------------------------------------------------------------------------------
+Tablet tool pressure range
+------------------------------------------------------------------------------
+
+The pressure range on a :ref:`Tablet tool <tablet-tools>` can be reduced
+from the full available hardware range to a subset of that range. The effect
+of this is that the tablet will not register pressure below the given
+the given threshold is met, and will reach the maximum logical pressure
+before the maximum hardware-supported pressure is reached.
+
+See :ref:`tablet-pressure-range` for more info.
+
+.. _config-tablet-eraser-buttons:
+
+------------------------------------------------------------------------------
+Tablet tool eraser buttons
+------------------------------------------------------------------------------
+
+On many contemporary :ref:`Tablet tools <tablet-tools>` one button is hardcoded
+in firmware to emulate an eraser. This button can be remapped to provide
+a normal stylus button instead.
+
+See :ref:`tablet-eraser-button` for more info.
+
+------------------------------------------------------------------------------
+Area configuration
+------------------------------------------------------------------------------
+
+Area configuration is available for some indirect input devices such as
+graphics tablets. This configuration allows reducing the active area of
+such a device to a subset of the physically possible area.
+
+An example use-case for this is to match the aspect ratio of the device to that
+of the screen.
+
+See :ref:`tablet-area` for more info.

doc/user/contributing.rst

@@ -0,0 +1,421 @@
+
+.. _contributing:
+
+==============================================================================
+Contributing to libinput
+==============================================================================
+
+
+So you want to contribute to libinput? Great! We'd love to help you be a part
+of our community. Here is some important information to help you.
+
+.. contents::
+    :local:
+
+------------------------------------------------------------------------------
+Code of Conduct
+------------------------------------------------------------------------------
+
+As a freedesktop.org project, libinput follows the `freedesktop.org
+Contributor Covenant <https://www.freedesktop.org/wiki/CodeOfConduct>`_.
+
+Please conduct yourself in a respectful and civilised manner when
+interacting with community members on mailing lists, IRC, or bug trackers.
+The community represents the project as a whole, and abusive or bullying
+behaviour is not tolerated by the project.
+
+------------------------------------------------------------------------------
+Contact
+------------------------------------------------------------------------------
+
+Questions can be asked on ``#wayland`` on oftc or on the
+`wayland-devel@lists.freedesktop.org
+<https://lists.freedesktop.org/mailman/listinfo/wayland-devel>`_ mailing
+list.
+
+For IRC, ping user ``whot`` (Peter Hutterer, the libinput maintainer) though
+note that he lives on UTC+10 and thus the rest of the world is out of sync
+by default ;)
+
+For anything that appears to be device specific and/or related to a new
+feature, just file `an issue in our issue tracker
+<https://gitlab.freedesktop.org/libinput/libinput/issues>`_. It's usually the
+most efficient way to get answers.
+
+------------------------------------------------------------------------------
+What to work on?
+------------------------------------------------------------------------------
+
+If you don't already know what you want to improve or fix with libinput,
+then a good way of finding something is to search for the ``help needed``
+tag in our `issue tracker <https://gitlab.freedesktop.org/libinput/libinput/issues?label_name%5B%5D=help+needed>`_.
+These are issues that have been triaged to some degree and deemed to be a
+possible future feature to libinput.
+
+.. note:: Some of these issue may require specific hardware to reproduce.
+
+Another good place to help out with is the documentation. For anything you
+find in these pages that isn't clear enough please feel free to reword it
+and add what is missing.
+
+------------------------------------------------------------------------------
+Getting the code
+------------------------------------------------------------------------------
+
+The :ref:`building_libinput` have all the details but the short solution
+will be:
+
+::
+
+     $> git clone https://gitlab.freedesktop.org/libinput/libinput
+     $> cd libinput
+     $> meson setup --prefix=/usr builddir/
+     $> ninja -C builddir/
+     $> sudo ninja -C builddir/ install
+
+You can omit the last step if you only want to test locally.
+
+------------------------------------------------------------------------------
+Working on the code
+------------------------------------------------------------------------------
+
+If you are planning to send patches, it's a good idea to set up
+`pre-commit <https://pre-commit.com/>`_ with these commands::
+
+     $> pre-commit install
+     $> pre-commit install --hook-type pre-push
+
+This will check a few things before you commit and/or push to your repos to
+reduce the turnaround time for some common mistakes.
+
+libinput has a roughly three-parts architecture:
+
+-  the front-end code which handles the ``libinput_some_function()`` API calls in ``libinput.c``
+-  the generic evdev interface handling which maps those API calls to the
+   backend calls (``evdev.c``).
+- there are device-specific backends which do most of the actual work -
+  ``evdev-mt-touchpad.c`` is the one for touchpads for example.
+
+In general, things that only affect the internal workings of a device only
+get implemented in the device-specific backend. You only need to touch the
+API when you are adding configuration options. For more details, please read
+the :ref:`architecture` document. There's also a `blog post describing the
+building blocks
+<https://who-t.blogspot.com/2019/03/libinputs-internal-building-blocks.html>`_
+that may help to understand how it all fits together.
+
+Documentation is in ``/doc/api`` for the doxygen-generated API documentation.
+These are extracted from the libinput source code directly. The
+documentation you're reading right now is in ``/doc/user`` and generated with
+sphinx. Simply running ``ninja -C builddir`` will rebuild it and the final
+product ends up in ``builddir/Documentation``.
+
+------------------------------------------------------------------------------
+Testing the code
+------------------------------------------------------------------------------
+
+libinput provides a bunch of :ref:`tools` to debug any changes - without
+having to install libinput.
+
+The two most useful ones are :ref:`libinput debug-events
+<libinput-debug-events>` and :ref:`libinput debug-gui <libinput-debug-gui>`.
+Both tools can be run from the build directory directly and are great for
+quick test iterations::
+
+  $> sudo ./builddir/libinput-debug-events --verbose
+  $> sudo ./builddir/libinput-debug-gui --verbose
+
+The former provides purely textual output and is useful for verifying event
+streams from buttons, etc. The latter is particularly useful when you are
+trying to debug pointer movement or placement. ``libinput debug-gui`` will
+also visualize the raw data from the device so you can compare pointer
+behavior with what comes from the kernel.
+
+These tools create a new libinput context and will not affect your session's
+behavior. Only once you've installed libinput and restarted your session
+will your changes affect the X server/Wayland compositor.
+
+Once everything seems to be correct, it's time to run the
+:ref:`test-suite`::
+
+  $> sudo ./builddir/libinput-test-suite
+
+This test suite can take test names etc. as arguments, have a look at
+:ref:`test-suite` for more info. There are a bunch of other tests that are
+run by the CI on merge requests, you can run those locally with ::
+
+  $> sudo ninja -C builddir check
+
+So it always pays to run that before submitting. This will also run the code
+through valgrind and pick up any memory leaks.
+
+.. _contributing_submitting_code:
+
+------------------------------------------------------------------------------
+Submitting Code
+------------------------------------------------------------------------------
+
+Any patches should be sent via a Merge Request (see the `GitLab docs
+<https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.htm>`_)
+in the `libinput GitLab instance hosted by freedesktop.org
+<https://gitlab.freedesktop.org/libinput/libinput>`_.
+
+.. note:: freedesktop.org's GitLab instance has restrictions to prevent Spam
+          and you cannot fork libinput until you have successfully
+          `applied for fork permissions <https://gitlab.freedesktop.org/freedesktop/freedesktop/-/wikis/home>`_.
+
+Below are the steps required to submit a merge request. They do not
+replace `learning git <https://git-scm.com/doc>`__ but they should be
+sufficient to make some of the more confusing steps obvious.
+
+- `Register an account <https://gitlab.freedesktop.org/users/sign_in>`_ in
+  the freedesktop.org GitLab instance and
+  `apply for fork permissions <https://gitlab.freedesktop.org/freedesktop/freedesktop/-/wikis/home>`_.
+- `Fork libinput <https://gitlab.freedesktop.org/libinput/libinput/-/forks/new>`_
+  into your username's namespace. Select public visibility.
+- Get libinput's main repository. git will call this repository ``origin``. ::
+
+    git clone https://gitlab.freedesktop.org/libinput/libinput.git
+
+- Add the forked git repository to your remotes (replace ``USERNAME``
+  with your username). git will call this repository ``gitlab``. ::
+
+    cd /path/to/libinput.git
+    git remote add gitlab git@ssh.gitlab.freedesktop.org:USERNAME/libinput.git
+    git fetch gitlab
+
+- Create a new branch and commit your changes to that branch. ::
+
+    git switch -C mynewbranch
+    # edit files, make changes
+    git add file1 file2
+    git commit -s
+    # edit commit message in the editor
+
+  Replace ``mynewbranch`` (here and in the commands below) with a meaningful
+  name. See :ref:`contributing_commit_messages` for details on the commit
+  message format.
+
+- Push your changes to your fork and submit a merge request ::
+
+    git push gitlab mynewbranch
+
+  This command will print the URL to file a merge request, you then only
+  have to click through. Alternatively you can go to:
+
+    https://gitlab.freedesktop.org/USERNAME/libinput/merge_requests
+
+  Select your branch name to merge and ``libinput/libinput`` ``main`` as target branch.
+
+- Verify that the CI completes successfully by visiting the merge request
+  page. A successful pipeline shows only green ticks, failure is indicated
+  by a red cross or a yellow exclamation mark (see
+  the `GitLab Docs
+  <https://docs.gitlab.com/ee/ci/pipelines/#pipeline-mini-graphs>`__). For
+  details about the failures, click on the failed jobs in the pipelines
+  and/or click the ``Expand`` button in the box for the test summaries.
+
+  A merge request without a successful pipeline may never be looked at by a
+  maintainer.
+
+- If changes are requested by the maintainers, please **amend** the
+  commit(s) and **force-push** the updated branch. ::
+
+    # edits in file foo.c
+    git add foo.c
+    git commit --amend
+    git push -f gitlab mynewbranch
+
+  A force-push will re-trigger the CI and notify the merge request that new
+  changes are available.
+
+  If the branch contains more than one commit, please look at
+  `git interactive rebases
+  <https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History>`__
+  to learn how to change multiple commits, or squash new changes into older
+  commits.
+
+------------------------------------------------------------------------------
+Commit History
+------------------------------------------------------------------------------
+
+libinput strives to have a
+`linear, 'recipe' style history <http://www.bitsnbites.eu/git-history-work-log-vs-recipe/>`_
+This means that every commit should be small, digestible, stand-alone, and
+functional. Rather than a purely chronological commit history like this: ::
+
+	doc: final docs for view transforms
+	fix tests when disabled, redo broken doc formatting
+	better transformed-view iteration (thanks Hannah!)
+	try to catch more cases in tests
+	tests: add new spline test
+	fix compilation on splines
+	doc: notes on reticulating splines
+	compositor: add spline reticulation for view transforms
+
+We aim to have a clean history which only reflects the final state, broken up
+into functional groupings: ::
+
+	compositor: add spline reticulation for view transforms
+	compositor: new iterator for view transforms
+	tests: add view-transform correctness tests
+	doc: fix Doxygen formatting for view transforms
+
+This ensures that the final patch series only contains the final state,
+without the changes and missteps taken along the development process.
+
+The first line of a commit message should contain a prefix indicating
+what part is affected by the patch followed by one sentence that
+describes the change. For example: ::
+
+	touchpad: add software button behavior
+	fallback: disable button debouncing on device foo
+
+If in doubt what prefix to use, look at other commits that change the
+same file(s) as the patch being sent.
+
+.. _contributing_commit_messages:
+
+------------------------------------------------------------------------------
+Commit Messages
+------------------------------------------------------------------------------
+
+When you re-send patches, revised or not, it would be very good to document the
+changes compared to the previous revision in the commit message and/or the
+merge request. If you have already received Reviewed-by or Acked-by tags, you
+should evaluate whether they still apply and include them in the respective
+commit messages. Otherwise the tags may be lost, reviewers miss the credit they
+deserve, and the patches may cause redundant review effort.
+
+If your commit solves a GitLab issue, add a ``Closes:`` tag followed by the
+issue number at the end of your commit message. For example: ::
+
+  Closes: #974
+
+If your commit fixes an issue introduced by another commit, use a ``Fixes`` tag
+followed by the first 12 characters of the SHA-1 ID and the commit one line
+summary at the end of your commit message. For example: ::
+
+  Fixes: 123456789012 ("The commit that caused the issue")
+
+For further reading, please see
+`'on commit messages' <http://who-t.blogspot.de/2009/12/on-commit-messages.html>`_
+as a general guideline on what commit messages should contain.
+
+------------------------------------------------------------------------------
+Coding Style
+------------------------------------------------------------------------------
+
+Please see the `CODING_STYLE.md
+<https://gitlab.freedesktop.org/libinput/libinput/blob/main/CODING_STYLE.md>`_
+document in the source tree.
+
+------------------------------------------------------------------------------
+Tracking patches and follow-ups
+------------------------------------------------------------------------------
+
+Once submitted to GitLab, your patches will be reviewed by the libinput
+development team on GitLab. Review may be entirely positive and result in your
+code landing instantly, in which case, great! You're done. However, we may ask
+you to make some revisions: fixing some bugs we've noticed, working to a
+slightly different design, or adding documentation and tests.
+
+If you do get asked to revise the patches, please bear in mind the notes above.
+You should use ``git rebase -i`` to make revisions, so that your patches
+follow the clear linear split documented above. Following that split makes
+it easier for reviewers to understand your work, and to verify that the code
+you're submitting is correct.
+
+A common request is to split single large patch into multiple patches. This can
+happen, for example, if when adding a new feature you notice a bug in
+libinput's core which you need to fix to progress. Separating these changes
+into separate commits will allow us to verify and land the bugfix quickly,
+pushing part of your work for the good of everyone, whilst revision and
+discussion continues on the larger feature part. It also allows us to direct
+you towards reviewers who best understand the different areas you are
+working on.
+
+When you have made any requested changes, please rebase the commits, verify
+that they still individually look good, then force-push your new branch to
+GitLab. This will update the merge request and notify everyone subscribed to
+your merge request, so they can review it again.
+
+There are also many GitLab CLI clients, if you prefer to avoid the web
+interface. It may be difficult to follow review comments without using the
+web interface though, so we do recommend using this to go through the review
+process, even if you use other clients to track the list of available
+patches.
+
+------------------------------------------------------------------------------
+Failed pipeline errors
+------------------------------------------------------------------------------
+
+After submitting your merge request to GitLab, you might receive an email
+informing you that your pipeline failed.
+
+Visit your merge request page and check the `pipeline mini graph
+<https://docs.gitlab.com/ee/ci/pipelines/#pipeline-mini-graphs>`_ to know which
+step failed.
+
+Follow the appropriate section to fix the errors.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Committed gitlab-ci.yml differs from generated gitlab-ci.yml. Please verify
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When your merge request modifies the CI templates, you might see this error
+mainly due two reasons: the wrong file was modified and/or
+``ci-fairy generate-template`` wasn't run.
+
+``.gitlab-ci.yaml`` is auto generated, changes should be made in:
+
+- ``.gitlab-ci/ci.template``
+
+- ``.gitlab-ci/config.yaml``
+
+Once the changes are ready, run
+`ci-fairy <https://freedesktop.pages.freedesktop.org/ci-templates/ci-fairy.html#templating-gitlab-ci-yml>`_
+to update ``.gitlab-ci.yaml``: ::
+
+  ci-fairy generate-template
+
+Finally, force-push you changes. See :ref:`contributing_submitting_code` for
+more details.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Build errors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Usually, checking the CI log is enough to catch this errors. However, your merge
+request is built using different configurations you might have not tested.
+
+In order to fix this kind of problems, you can compile libinput using the same
+flags used by the CI.
+
+For example, if an error is found in the ``build-no-libwacom`` step, open the
+log and search the build options: ::
+
+  [...]
+  + rm -rf 'build dir'
+  + meson 'build dir' -Dlibwacom=false
+  The Meson build system
+  [...]
+
+Use the same flags to fix the issue and force-push you changes. See
+:ref:`contributing_submitting_code` for more details.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Test errors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The test suite is run for your merge request to check for bugs, regressions and
+memory leaks among other issues.
+
+Open the CI error log and search for a message similar to: ::
+
+  :: Failure: ../test/test-touchpad.c:465: touchpad_2fg_scroll_slow_distance(synaptics-t440)
+
+See :ref:`test-suite` to learn how to run the failing tests.
+
+Once the tests are fixed, force-push you changes. See
+:ref:`contributing_submitting_code` for more details.

doc/user/dependencies.rst

@@ -0,0 +1,21 @@
+.. warning:: The package lists are autogenerated from the `CI <https://gitlab.freedesktop.org/libinput/libinput/-/tree/master/.gitlab-ci.yml>`_.
+
+- Fedora: ::
+
+    dnf install @FEDORA_PACKAGES@
+
+- Ubuntu: ::
+
+    apt install @UBUNTU_PACKAGES@
+
+- Debian: ::
+
+    apt install @DEBIAN_PACKAGES@
+
+- Arch: ::
+
+    pacman -S @ARCH_PACKAGES@
+
+- Alpine: ::
+
+    apk add @ALPINE_PACKAGES@

doc/user/development.rst

@@ -0,0 +1,53 @@
+.. _development:
+
+==============================================================================
+Information for developers
+==============================================================================
+
+Below is a list of topics of interest to developers, divided into
+information for those :ref:`using_libinput_as_library` in a Wayland compositor
+or other project. The :ref:`hacking_on_libinput` section applies to developers working on
+libinput itself.
+
+.. note:: If you use or work on libinput you should get in touch with the
+          libinput developers on the wayland-devel@lists.freedesktop.org
+          mailing lists
+
+.. _using_libinput_as_library:
+
+------------------------------------------------------------------------------
+Using libinput as library
+------------------------------------------------------------------------------
+
+See :ref:`building_against` for information on how to integrate libinput
+with your project's build system.
+
+.. note:: **libinput's API documentation is available here:**
+           http://wayland.freedesktop.org/libinput/doc/latest/api/
+
+
+Topics below explain some behaviors of libinput.
+
+.. toctree::
+   :maxdepth: 1
+
+   absolute-axes.rst
+   absolute-coordinate-ranges.rst
+   normalization-of-relative-motion.rst
+   seats.rst
+   timestamps.rst
+   wheel-api.rst
+
+.. _hacking_on_libinput:
+
+------------------------------------------------------------------------------
+Hacking on libinput
+------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   architecture
+   test-suite.rst
+   pointer-acceleration.rst
+   device-configuration-via-udev.rst

doc/user/device-configuration-via-udev.rst

@@ -0,0 +1,245 @@
+.. _udev_config:
+
+==============================================================================
+Static device configuration via udev
+==============================================================================
+
+libinput supports some static configuration through udev properties.
+These properties are read when the device is initially added
+to libinput's device list, i.e. before the
+**LIBINPUT_EVENT_DEVICE_ADDED** event is generated.
+
+The following udev properties are supported:
+
+LIBINPUT_CALIBRATION_MATRIX
+    Sets the calibration matrix, see
+    **libinput_device_config_calibration_get_default_matrix()**. If unset,
+    defaults to the identity matrix.
+
+    The udev property is parsed as 6 floating point numbers separated by a
+    single space each (scanf(3) format ``"%f %f %f %f %f %f"``).
+    The 6 values represent the first two rows of the calibration matrix as
+    described in **libinput_device_config_calibration_set_matrix()**.
+
+    Example values are: ::
+
+          ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
+          ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
+          ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
+          ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
+          ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 1 0" # reflect along y axis
+
+
+LIBINPUT_DEVICE_GROUP
+    A string identifying the **libinput_device_group** for this device. Two
+    devices with the same property value are grouped into the same device group,
+    the value itself is irrelevant otherwise.
+
+LIBINPUT_IGNORE_DEVICE
+    If set to anything other than "0", the device is ignored by libinput.
+    See :ref:`ignoring_devices` for more details.
+
+ID_SEAT
+    Assigns the physical :ref:`seat <seats>` for this device. See
+    **libinput_seat_get_physical_name()**. Defaults to "seat0".
+
+ID_INPUT
+    If this property is set, the device is considered an input device. Any
+    device with this property missing will be ignored, see :ref:`udev_device_type`.
+
+ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD, ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK, ID_INPUT_ACCELEROMETER
+    If any of the above is set, libinput initializes the device as the given
+    type, see :ref:`udev_device_type`. Note that for historical reasons more than
+    one of these may be set at any time, libinput will select only one of these
+    to determine the device type. To ensure libinput selects the correct device
+    type, only set one of them.
+
+WL_SEAT
+    Assigns the logical :ref:`seat <seats>` for this device. See
+    **libinput_seat_get_logical_name()** context. Defaults to "default".
+
+MOUSE_DPI
+    HW resolution and sampling frequency of a relative pointer device.
+    See :ref:`motion_normalization` for details.
+
+MOUSE_WHEEL_CLICK_ANGLE
+    The angle in degrees for each click on a mouse wheel. See
+    **libinput_pointer_get_axis_source()** for details.
+
+
+Below is an example udev rule to assign "seat1" to a device from vendor
+``0x012a`` with the model ID of ``0x034b``. ::
+
+   $ cat /etc/udev/rules.d/99-my-device-is-on-seat1.rules
+     ACTION!="remove", KERNEL=="event[0-9]*", \
+     ENV{ID_VENDOR_ID}=="012a", \
+     ENV{ID_MODEL_ID}=="034b", \
+     ENV{ID_SEAT}="seat1"
+
+
+
+.. _udev_device_type:
+
+------------------------------------------------------------------------------
+Device type assignment via udev
+------------------------------------------------------------------------------
+
+libinput requires the **ID_INPUT** property to be set on a device,
+otherwise the device will be ignored. In addition, one of
+**ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD,
+ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK,
+ID_INPUT_ACCELEROMETER** must be set on the device to determine the
+device type. The usual error handling applies within libinput and a device
+type label does not guarantee that the device is initialized by libinput.
+If a device fails to meet the requirements for a device type (e.g. a keyboard
+labelled as touchpad) the device will not be available through libinput.
+
+Only one device type should be set per device at a type, though libinput can
+handle some combinations for historical reasons.
+
+Below is an example udev rule  to remove an **ID_INPUT_TOUCHPAD** setting
+and change it into an **ID_INPUT_TABLET** setting. This rule would apply
+for a device with the vendor/model ID of ``012a``/``034b``. ::
+
+   $ cat /etc/udev/rules.d/99-my-device-is-a-tablet.rules
+     ACTION!="remove", KERNEL=="event[0-9]*", \
+     ENV{ID_VENDOR_ID}=="012a", \
+     ENV{ID_MODEL_ID}=="034b", \
+     ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1"
+
+
+.. _model_specific_configuration:
+
+------------------------------------------------------------------------------
+Model-specific configuration
+------------------------------------------------------------------------------
+
+As of libinput 1.12, model-specific configuration is stored in the
+:ref:`device-quirks` and not in the hwdb anymore. Please see
+:ref:`device-quirks` for
+details.
+
+.. _model_specific_configuration_x220fw81:
+
+..............................................................................
+Lenovo x220 with touchpad firmware v8.1
+..............................................................................
+
+The property **LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81** may be set by a
+user in a local hwdb file. This property designates the touchpad on a Lenovo
+x220 with a touchpad firmware version 8.1. When this firmware version is
+installed, the touchpad is imprecise. The touchpad device does not send
+continuous x/y axis position updates, a behavior also observed on its
+successor model, the Lenovo x230 which has the same firmware version. If the
+above property is set, libinput adjusts its behavior to better suit this
+particular model.
+
+The touchpad firmware version cannot be detected automatically by libinput,
+local configuration is required to set this property. Refer to the libinput
+model quirks hwdb for instructions.
+
+This property must not be used for any other purpose, no specific behavior
+is guaranteed.
+
+
+.. _hwdb:
+
+------------------------------------------------------------------------------
+Configuring the hwdb
+------------------------------------------------------------------------------
+
+This section outlines how to query the
+`udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_
+and reload properties so they are available to libinput.
+
+The hwdb contains a set of match rules that assign udev properties that are
+available to libinput when the device is connected and/or libinput is
+initialized. This section only describes the hwdb in relation to libinput,
+it is not a full documentation on how the hwdb works.
+
+libinput's use of the hwdb is limited to properties systemd and custom
+rules files (where available) provide. Hardware-specific quirks as used by
+libinput are in the :ref:`device-quirks` system.
+
+.. _hwdb_querying:
+
+..............................................................................
+Querying the hwdb
+..............................................................................
+
+libinput only uses device nodes in the form of ``/dev/input/eventX`` where X
+is the number of the specific device. Running ``libinput debug-events`` lists
+all devices currently available to libinput and their event node name: ::
+
+    $> sudo libinput debug-events
+    -event2   DEVICE_ADDED     Power Button                      seat0 default group1  cap:k
+    -event5   DEVICE_ADDED     Video Bus                         seat0 default group2  cap:k
+    -event0   DEVICE_ADDED     Lid Switch                        seat0 default group3  cap:S
+
+    ...
+
+Note the event node name for your device and translate it into a syspath in
+the form of ``/sys/class/input/eventX``. This path can be supplied to ``udevadm
+info`` ::
+
+    $> udevadm info
+    P: /devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
+    N: input/event0
+    E: DEVNAME=/dev/input/event0
+    E: DEVPATH=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
+    E: ID_INPUT=1
+    E: ID_INPUT_SWITCH=1
+    E: MAJOR=13
+    E: MINOR=64
+    E: SUBSYSTEM=input
+    E: TAGS=:power-switch:
+    E: USEC_INITIALIZED=7167898
+
+Lines starting with ``E:`` are udev properties available to libinput. For
+example, the above device's ``ID_INPUT_SWITCH`` property will cause libinput
+to treat this device as switch device.
+
+
+.. _hwdb_reloading:
+
+..............................................................................
+Reloading the hwdb
+..............................................................................
+
+The actual hwdb is stored in binary file on-disk and must be updated
+manually whenever a ``.hwdb`` file changes. This is required both when a user
+manually edits the ``.hwdb`` file but also when the git tree is updated (and
+that update causes a hwdb change).
+
+To update the binary file on-disk, run: ::
+
+    sudo systemd-hwdb update
+
+Then, to trigger a reload of all properties on your device, run: ::
+
+    sudo udevadm trigger /sys/class/input/eventX
+
+Then check with ``udevadm info`` whether the properties were updated, see
+:ref:`hwdb_querying`. If a new property does not appear on the device, use ``udevadm
+test`` to check for error messages by udev and the hwdb (e.g. syntax errors
+in the udev rules files). ::
+
+    sudo udevadm test /sys/class/input/eventX
+
+.. warning::  ``udevadm test`` does not run commands specified in ``RUN``
+	      directives. This affects the udev properties relying on e.g.
+	      the udev keyboard builtin such as the :ref:`touchpad_jitter`
+	      workarounds.
+
+.. _hwdb_modifying:
+
+..............................................................................
+Modifying the hwdb
+..............................................................................
+
+.. warning:: This section has been removed as it no longer applies in libinput 1.12
+             and later. libinput users should not need to modify the hwdb, any
+             device-specific quirks must go in to the :ref:`device-quirks` system.
+
+For information about older libinput versions, please see the documentation
+for your version available in: https://wayland.freedesktop.org/libinput/doc/

doc/user/device-quirks.rst

@@ -0,0 +1,244 @@
+.. _device-quirks:
+
+==============================================================================
+Device quirks
+==============================================================================
+
+libinput requires extra information from devices that is not always readily
+available. For example, some touchpads are known to have jumping cursors
+under specific conditions. libinput ships a set of files containing the
+so-called model quirks to provide that information. Model quirks are usually
+installed under ``/usr/share/libinput/<filename>.quirks`` and are standard
+``.ini`` files. A file may contain multiple section headers (``[some
+identifier]``) followed by one or more :ref:`MatchFoo=Bar <device-quirks-matches>`
+directives, followed by at least one of ``ModelFoo=1`` or ``AttrFoo=bar`` directive.
+See the ``quirks/README.md`` file in the libinput source repository for more
+details on their contents.
+
+.. warning:: Model quirks are internal API and may change at any time. No
+             backwards-compatibility is guaranteed.
+
+For example, a quirks file may have this content to label all keyboards on
+the serial bus (PS/2) as internal keyboards: ::
+
+     [Serial Keyboards]
+     MatchUdevType=keyboard
+     MatchBus=serial
+     AttrKeyboardIntegration=internal
+
+
+The model quirks are part of the source distribution and should never be
+modified locally. Updates to libinput may overwrite modifications or even
+stop parsing any property. For temporary local workarounds, see
+:ref:`device-quirks-local`.
+
+Device quirks are parsed on libinput initialization. A parsing error in the
+device quirks disables **all** device quirks and may negatively impact
+device behavior on the host. If the quirks cannot be loaded, an error
+message is posted to the log and users should use the information in
+:ref:`device-quirks-debugging` to verify their quirks files.
+
+.. _device-quirks-local:
+
+------------------------------------------------------------------------------
+Installing temporary local device quirks
+------------------------------------------------------------------------------
+
+The model quirks are part of the source distribution and should never be
+modified. For temporary local workarounds, libinput reads the
+``/etc/libinput/local-overrides.quirks`` file. Users may add a sections to
+this file to add a device quirk for a local device but beware that **any
+modification must be upstreamed** or it may cease to work at any time.
+
+.. warning:: Model quirks are internal API and may change at any time. No
+             backwards-compatibility is guaranteed. Local overrides should only
+             be used until the distribution updates the libinput packages.
+
+The ``local-overrides.quirks`` file usually needs to be created by the user.
+Once the required section has been added, use the information from section
+:ref:`device-quirks-debugging` to validate and test the quirks.
+
+.. _device-quirks-debugging:
+
+------------------------------------------------------------------------------
+Debugging device quirks
+------------------------------------------------------------------------------
+
+libinput provides the ``libinput quirks`` tool to debug the quirks database.
+This tool takes an action as first argument, the most common invocation is
+``libinput quirks list`` to list model quirks that apply to one or more local
+devices. ::
+
+     $ libinput quirks list /dev/input/event19
+     $ libinput quirks list /dev/input/event0
+     AttrLidSwitchReliability=unreliable
+
+The device `event19` does not have any quirks assigned.
+
+When called with the ``--verbose`` argument, ``libinput quirks list`` prints
+information about all files and its attempts to match the device: ::
+
+     $ libinput quirks list --verbose /dev/input/event0
+     quirks debug: /usr/share/share/libinput is data root
+     quirks debug: /usr/share/share/libinput/10-generic-keyboard.quirks
+     quirks debug: /usr/share/share/libinput/10-generic-lid.quirks
+     [...]
+     quirks debug: /usr/share/etc/libinput/local-overrides.quirks
+     quirks debug: /dev/input/event0: fetching quirks
+     quirks debug: [Serial Keyboards] (10-generic-keyboard.quirks) wants MatchBus but we don't have that
+     quirks debug: [Lid Switch Ct9] (10-generic-lid.quirks) matches for MatchName
+     quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchName
+     quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) matches for MatchDMIModalias
+     quirks debug: [Lid Switch Ct10] (10-generic-lid.quirks) is full match
+     quirks debug: property added: AttrLidSwitchReliability from [Lid Switch Ct10] (10-generic-lid.quirks)
+     quirks debug: [Aiptek No Tilt Tablet] (30-vendor-aiptek.quirks) wants MatchBus but we don't have that
+     [...]
+     quirks debug: [HUION PenTablet] (30-vendor-huion.quirks) wants MatchBus but we don't have that
+     quirks debug: [Logitech Marble Mouse Trackball] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
+     quirks debug: [Logitech K400] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
+     quirks debug: [Logitech K400r] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
+     quirks debug: [Logitech K830] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
+     quirks debug: [Logitech K400Plus] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
+     quirks debug: [Logitech Wireless Touchpad] (30-vendor-logitech.quirks) wants MatchBus but we don't have that
+     quirks debug: [Microsoft Surface 3 Lid Switch] (30-vendor-microsoft.quirks) matches for MatchName
+     [...]
+     AttrLidSwitchReliability
+
+
+Note that this is an example only, the output may change over time. The tool
+uses the same parser as libinput and any parsing errors will show up in the
+output.
+
+.. _device-quirks-list:
+
+------------------------------------------------------------------------------
+List of currently available device quirks
+------------------------------------------------------------------------------
+
+This list is a guide for developers to ease the process of submitting
+patches upstream. This section shows device quirks currently available in
+|git_version|.
+
+.. warning:: Quirks are internal API and may change at any time for any reason.
+             No guarantee is given that any quirk below works on your version of
+             libinput.
+
+In the documentation below, the letters N, M, O, P refer to arbitrary integer
+values.
+
+Quirks starting with **Model*** triggers implementation-defined behaviour
+for this device not needed for any other device. Only the more
+general-purpose **Model*** flags are listed here.
+
+ModelALPSTouchpad, ModelAppleTouchpad, ModelWacomTouchpad, ModelChromebook
+    Reserved for touchpads made by the respective vendors
+ModelTouchpadVisibleMarker
+    Indicates the touchpad has a drawn-on visible marker between the software
+    buttons.
+ModelTabletModeNoSuspend
+    Indicates that the device does not need to be
+    suspended in :ref:`switches_tablet_mode`.
+ModelTabletModeSwitchUnreliable
+    Indicates that this tablet mode switch's state cannot be relied upon.
+ModelTrackball
+    Reserved for trackballs
+ModelBouncingKeys
+    Indicates that the device may send fake bouncing key events and
+    timestamps can not be relied upon.
+ModelSynapticsSerialTouchpad
+    Reserved for touchpads made by Synaptics on the serial bus
+ModelPressurePad
+    .. warning:: This quirk is no longer in use. Use
+                 ``AttrInputProp=+INPUT_PROP_PRESSUREPAD`` instead.
+
+    Unlike in traditional touchpads, whose pressure value equals contact size,
+    on pressure pads pressure is a real physical axis.
+    Indicates that the device is a pressure pad.
+ModelTouchpadPhantomClicks
+    Some laptops are prone to registering touchpad clicks when the case is
+    bent. Indicates that clicks should be ignored if no fingers are on the
+    touchpad.
+ModelScrollOnMiddleClick
+    Some mice can generate unwanted high-resolution scroll events when the wheel
+    is pressed. Increases the scroll threshold required to start scrolling to
+    avoid accidentally scrolling when middle clicking.
+AttrSizeHint=NxM, AttrResolutionHint=N
+    Hints at the width x height of the device in mm, or the resolution
+    of the x/y axis in units/mm. These may only be used where they apply to
+    a large proportion of matching devices. They should not be used for any
+    specific device, override ``EVDEV_ABS_*`` instead, see
+    :ref:`absolute_coordinate_ranges_fix`.
+AttrTouchSizeRange=N:M, AttrPalmSizeThreshold=O
+    Specifies the touch size required to trigger a press (N) and to trigger
+    a release (M). O > N > M. See :ref:`touchpad_touch_size_hwdb` for more
+    details.
+    An AttrPalmSizeThreshold of zero unsets any threshold that has been
+    inherited from another quirk.
+AttrPressureRange=N:M, AttrPalmPressureThreshold=O, AttrThumbPressureThreshold=P
+    Specifies the touch pressure required to trigger a press (N) and to
+    trigger a release (M), when a palm touch is triggered (O) and when a
+    thumb touch is triggered (P). O > P > N > M. See
+    :ref:`touchpad_pressure_hwdb` for more details.
+    An AttrPalmPressureThreshold of zero unsets any threshold that has been
+    inherited from another quirk.
+AttrLidSwitchReliability=reliable|unreliable|write_open
+    Indicates the reliability of the lid switch. This is a string enum.
+    Very few devices need this, if in doubt do not set. See :ref:`switches_lid`
+    for details. libinput 1.21.0 changed the default from unreliable to
+    reliable, which may be removed from local overrides.
+AttrKeyboardIntegration=internal|external
+    Indicates the integration of the keyboard. This is a string enum.
+    Generally only needed for USB keyboards.
+AttrTPKComboLayout=below
+    Indicates the position of the touchpad on an external touchpad+keyboard
+    combination device. This is a string enum. Don't specify it unless the
+    touchpad is below.
+AttrEventCode=+EV_ABS;-BTN_STYLUS;+EV_KEY:0x123;
+    Enables or disables the evdev event type/code tuples on the device. The prefix
+    for each entry is either '+' (enable) or '-' (disable). Entries may be
+    a named event type, or a named event code, or a named event type with a
+    hexadecimal event code, separated by a single colon.
+AttrInputProp=+INPUT_PROP_BUTTONPAD;-INPUT_PROP_POINTER;
+    Enables or disables the evdev input property on the device. The prefix
+    for each entry is either '+' (enable) or '-' (disable). Entries may be
+    a named input property or the hexadecimal value of that property.
+
+    The most common use of this is ``AttrInputProp=+INPUT_PROP_PRESSUREPAD``
+    which marks a touchpad as a :ref:`forcepad or pressurepad <touchpads_buttons_forcepads>`.
+AttrPointingStickIntegration=internal|external
+    Indicates the integration of the pointing stick. This is a string enum.
+    Only needed for external pointing sticks. These are rare.
+AttrTabletSmoothing=1|0
+    Enables (1) or disables (0) input smoothing for tablet devices. Smoothing is enabled
+    by default, except on AES devices.
+
+.. _device-quirks-matches:
+
+------------------------------------------------------------------------------
+List of currently available matches
+------------------------------------------------------------------------------
+
+``Match*`` statements are how quirks are assigned to a device. Quirks with multiple
+match statements must match all of those to apply.
+
+.. warning:: Quirks are internal API and may change at any time for any reason.
+             No guarantee is given that any ``Match`` statement below works on
+             your version of libinput.
+
+MatchName, MatchUniq
+    Match on the ``NAME`` or ``UNIQ`` udev property on this device. These properties
+    are typically derived from the device's kernel name or uniq but may be overridden
+    by a udev rule. These matches use ``fnmatch()`` globs.
+MatchBus
+    A lower-case bus name. Currently supported are ``usb``, ``bluetooth``, ``ps2``,
+    ``rmi``, ``i2c``, and ``spi``.
+MatchVendor, MatchProduct, MatchVersion
+    The hexadecimal 4-digit vendor ID, product ID or driver version as
+    exported, uppercase with a ``0x`` prefix, e.g. ``0x12AB```.
+MatchDMIModalias, MatchDeviceTree
+    An ``fnmatch()`` glob for the DMI modalias or the DeviceTree ``compatible`` string.
+    See ``/sys/class/dmi/id/modalias`` and ``/sys/firmware/devicetree/base/compatible``.
+MatchUdevType
+    One of ``touchpad``, ``mouse``, ``pointingstick``, ``keyboard``, ``joystick``,
+    ``tablet``, ``tablet-pad``. Matches the corresponding ``ID_INPUT_*`` udev
+    property.

doc/user/dot/libinput-contexts.gv

@@ -0,0 +1,36 @@
+digraph stack
+{
+  compound=true;
+  splines=line;
+  rankdir="LR";
+  node [
+    shape="box";
+  ]
+
+  subgraph cluster_2 {
+	  label="Kernel";
+	  event0 [label="/dev/input/event0"];
+	  event1 [label="/dev/input/event1"];
+  }
+
+  subgraph cluster_0 {
+	  label="Compositor process";
+	  libinput [label="libinput context 1"];
+  }
+
+  subgraph cluster_1 {
+	  label="libinput debug-events";
+	  libinput2 [label="libinput context 2"];
+  }
+
+  stdout;
+
+  client [label="Wayland client"];
+
+  event0:e -> libinput:w;
+  event1:e -> libinput:w;
+  event0:e -> libinput2:w;
+  event1:e -> libinput2:w;
+  libinput -> client [ltail=cluster_0 label="Wayland protocol"];
+  libinput2 -> stdout [ltail=cluster_1];
+}

doc/user/dot/libinput-record.gv

@@ -0,0 +1,20 @@
+digraph stack
+{
+  compound=true;
+  rankdir="LR";
+  node [
+    shape="box";
+  ]
+
+  kernel [label="Kernel"];
+
+  libinput;
+  xserver [label="X Server"];
+  record [label="libinput record"];
+
+  kernel -> libinput
+  libinput -> xserver
+
+  kernel -> record;
+  record -> stdout
+}

doc/user/dot/plugin-stack.gv

@@ -0,0 +1,31 @@
+digraph stack
+{
+  compound=true;
+  rankdir="LR";
+  node [
+    shape="box";
+  ]
+
+  subgraph cluster_2 {
+	  label="Kernel";
+	  event0 [label="/dev/input/event0"]
+  }
+
+  subgraph cluster_1 {
+	  label="libinput";
+    subgraph cluster_0 {
+	    label="Plugin pipeline";
+	    p1 [label="00-foo.lua"];
+	    p2 [label="10-bar.lua"];
+    }
+	  libinput [label="libinput core"];
+  }
+
+
+  compositor [label="Compositor"];
+
+  event0 -> p1;
+  p1 -> p2;
+  p2 -> libinput;
+  libinput -> compositor [ltail=cluster_1 label="libinput API"];
+}

doc/user/drag-3fg.rst

@@ -0,0 +1,40 @@
+.. _drag_3fg:
+
+==============================================================================
+Three-finger drag
+==============================================================================
+
+Three-finger drag is a feature available on touchpads that emulates logical
+button presses if three fingers are moving on the touchpad.
+
+Three-finger drag is independent from :ref:`tapping` though some specific
+behaviors may change when both features are enabled. For example, with
+tapping *disabled* a three-finger gesture will virtually always be a three-finger
+drag. With tapping *enabled* a three finger gesture may be a three finger drag
+and a short delay is required to disambiguate between the two.
+
+
+The exact behavior of three-finger drag is implementation defined and may
+subtly change. As a general rule, the following constraints can be expected:
+
+- three fingers down and movement trigger a button down and subsequent motion
+  events (i.e. a drag)
+- releasing one finger while keeping two fingers down will keep the drag
+  and *not* switch to :ref:`twofinger_scrolling`.
+- releasing two fingers while keeping one finger down will end the drag
+  (and thus release the button) and switch to normal pointer motion
+- releasing all three fingers and putting three fingers back on the touchpad
+  immediately will keep the drag (i.e. behave as if the fingers were
+  never lifted)
+
+  - if tapping is enabled: a three finger tap immediately after a three-finger
+    drag will *not* tap, the user needs to wait past the timeout to
+    three-finger tap
+
+- releasing all three fingers and putting one or two fingers back on
+  the touchpad will end the drag (and thus release the button)
+  and proceed with pointer motion or two-finger scrolling, if applicable
+
+  - if tapping is enabled: a one or two finger tap immediately after a
+    three-finger drag will trigger a one or two finger tap. The user does
+    not have to wait past the drag release timeout

doc/user/faqs.rst

@@ -0,0 +1,390 @@
+.. _faq:
+
+==============================================================================
+FAQs - Frequently Asked Questions
+==============================================================================
+
+Frequently asked questions about libinput.
+
+
+.. contents::
+    :local:
+    :backlinks: entry
+
+.. _faq_feature:
+
+------------------------------------------------------------------------------
+Why doesn't libinput support ...?
+------------------------------------------------------------------------------
+
+First, read :ref:`what_is_libinput` If you have a feature that you think
+libinput needs to support, please file a bug report. See :ref:`reporting_bugs`
+for more details.
+
+.. _faq_fast_mouse:
+
+------------------------------------------------------------------------------
+My mouse moves too fast, even at the slowest setting
+------------------------------------------------------------------------------
+
+This is a symptom of high-dpi mice (greater than 1000dpi). These devices
+need a udev hwdb entry to normalize their motion. See
+:ref:`motion_normalization` for a detailed explanation.
+
+.. _faq_fast_trackpoint:
+
+------------------------------------------------------------------------------
+My trackpoint moves too slow or too fast
+------------------------------------------------------------------------------
+
+This is a symptom of an invalid trackpoint multiplier. These devices need
+:ref:`device-quirks` to specify the range available so libinput can adjust the
+pointer acceleration accordingly. See :ref:`trackpoint_range` for a detailed
+explanation.
+
+.. _faq_pointer_acceleration:
+
+------------------------------------------------------------------------------
+Why is libinput's pointer acceleration worse than synaptics/evdev
+------------------------------------------------------------------------------
+
+This is a known problem affecting some devices and/or use-case but the exact
+cause is still unknown. It may be a device-specific issue, it may be a bug
+in libinput's acceleration code, it may be a disagreement about how pointer
+acceleration should feel. Unfortunately this is something that affected
+users need to investigate and analyze.
+
+.. _faq_enable_tapping:
+
+------------------------------------------------------------------------------
+Why isn't touchpad tap-to-click enabled by default
+------------------------------------------------------------------------------
+
+See :ref:`tapping_default`
+
+.. _faq_touchpad_pressure:
+
+------------------------------------------------------------------------------
+Why does my touchpad lose track of touches
+------------------------------------------------------------------------------
+
+The most common cause for this is an incorrect pressure threshold range.
+See :ref:`touchpad_pressure` for more info.
+
+.. _faq_kinetic_scrolling:
+
+------------------------------------------------------------------------------
+Kinetic scrolling does not work
+------------------------------------------------------------------------------
+
+The X.Org synaptics driver implemented kinetic scrolling in the driver. It
+measures the scroll speed and once the finger leaves the touchpad the driver
+keeps sending scroll events for a predetermined time. This effectively
+provides for kinetic scrolling without client support but triggers an
+unfixable `bug <https://bugs.freedesktop.org/show_bug.cgi?id=38909>`_: the
+client cannot know that the events are from a kinetic scroll source. Scroll
+events in X are always sent to the current cursor position, a movement of the
+cursor after lifting the finger will send the kinetic scroll events to the
+new client, something the user does not usually expect. A key event during
+the kinetic scroll procedure causes side-effects such as triggering zoom.
+
+libinput does not implement kinetic scrolling for touchpads. Instead it
+provides the **libinput_event_pointer_get_axis_source()** function that enables
+callers to implement kinetic scrolling on a per-widget basis, see
+:ref:`scroll_sources`.
+
+.. _faq_gpl:
+
+------------------------------------------------------------------------------
+Is libinput GPL-licensed?
+------------------------------------------------------------------------------
+
+No, libinput is MIT licensed. The Linux kernel header file linux/input.h in
+libinput's tree is provided to ensure the same behavior regardless of which
+kernel version libinput is built on. It does not make libinput GPL-licensed.
+
+.. _faq_config_options:
+
+------------------------------------------------------------------------------
+Where is the configuration stored?
+------------------------------------------------------------------------------
+
+libinput does not store configuration options, it is up to the caller to
+manage these and decide which configuration option to apply to each device.
+This must be done at startup, after a resume and whenever a new device is
+detected.
+
+One commonly used way to configure libinput is to have the Wayland
+compositor expose a compositor-specific configuration option. For example,
+in a GNOME stack, the gnome-control-center modifies dconf entries. These
+changes are read by mutter and applied to libinput. Changing these entries
+via the gsettings commandline tool has the same effect.
+
+Another commonly used way to configure libinput is to have xorg.conf.d
+snippets. When libinput is used with the xf86-input-libinput driver in an
+X.Org stack, these options are read on startup and apply to each device.
+Changing properties at runtime with the xinput commandline tool has the same
+effect.
+
+In both cases, the selection of available options and how they are exposed
+depends on the libinput caller (e.g. mutter or xf86-input-libinput).
+
+.. graphviz:: libinput-stack-gnome.gv
+
+This has an effect on the availability of configuration options: if an
+option is not exposed by the intermediary, it cannot be configured by the
+client. Also some configuration options that are provided by the
+intermediary may not be libinput-specific configuration options.
+
+.. _faq_configure_wayland:
+
+------------------------------------------------------------------------------
+How do I configure my device on Wayland?
+------------------------------------------------------------------------------
+
+See :ref:`faq_config_options` Use the configuration tool provided by your
+desktop environment (e.g. gnome-control-center) or direct access to your
+desktop environment's configuration storage (e.g. gsettings).
+
+.. _faq_configure_xorg:
+
+------------------------------------------------------------------------------
+How do I configure my device on X?
+------------------------------------------------------------------------------
+
+See :ref:`faq_config_options`  If your desktop environment does not provide a
+graphical configuration tool you can use an
+`xorg.conf.d snippet <https://www.x.org/archive/current/doc/man/man5/xorg.conf.5.xhtml>`_.
+Usually, such a snippet looks like this:
+
+::
+
+     $> cat /etc/X11/xorg.conf.d/99-libinput-custom-config.conf
+     Section "InputClass"
+       Identifier "something to identify this snippet"
+       MatchDriver "libinput"
+       MatchProduct "substring of the device name"
+       Option "some option name" "the option value"
+     EndSection
+
+
+The identifier is merely a human-readable string that shows up in the log
+file. The MatchProduct line should contain the device name or a substring of
+the device name that the snippet should apply to. For a full list of option
+names and permitted values, see the
+`libinput man page <https://www.mankier.com/4/libinput>`_.
+xorg.conf.d snippets like the above apply to hotplugged devices but can be
+overwritten at runtime by desktop tools. Multiple snippets may be placed
+into the same file.
+
+For run-time configuration and testing, the
+`xinput <https://www.x.org/archive/X11R7.5/doc/man/man1/xinput.1.html>`_
+debugging tool can modify a devices' properties. See the
+`libinput man page <https://www.mankier.com/4/libinput>`_
+for supported property names and values. Usually, an invocation looks like
+this:
+
+::
+
+     $> xinput set-prop "the device name" "the property name" value [value2] [value3]
+
+
+.. note:: Changes performed by xinput do not persist across device hotplugs. xinput
+	is considered a debugging and testing tool only and should not be used
+	for permanent configurations.
+
+.. _faq_configuration:
+
+------------------------------------------------------------------------------
+Can you add a configuration option for $FEATURE?
+------------------------------------------------------------------------------
+
+No. At least that's going to be the initial answer. Read
+`Why libinput doesn't have a lot of configuration options <http://who-t.blogspot.com/2016/04/why-libinput-doesnt-have-lot-of-config.html>`_
+first. Configuration options for most features are a signal that we are incapable
+of handling it correctly. To get to that point, we want to be sure we're
+truly incapable of doing so. libinput has several features that
+are handled automatically (and correctly) that users wanted to have
+configuration options for initially.
+
+So the answer to this question will almost always be 'no'. A configuration
+option is, in most cases, a cop-out.
+
+.. _faq_synclient:
+
+------------------------------------------------------------------------------
+Why don't synclient and syndaemon work with libinput?
+------------------------------------------------------------------------------
+
+Synclient and syndaemon rely on X input device properties that are specific
+to the xf86-input-synaptics X.Org input driver. Both were written when the
+synaptics driver was the only common touchpad driver in existence. They
+assume that if the properties aren't available, no touchpad is available
+either. The xf86-input-libinput X.Org input driver does not export these
+driver-specific properties, synclient/syndaemon will thus not detect the
+touchpad and refuse to work. Other tools that rely on synclient/syndaemon or
+those same properties also do not work with xf86-input-libinput.
+
+Most of syndaemon's functionality is built into libinput, see
+:ref:`disable-while-typing`. synclient is merely a configuration tool, see
+:ref:`faq_configure_xorg` for similar functionality.
+
+See also the blog posts
+`The definitive guide to synclient <http://who-t.blogspot.com.au/2017/01/the-definitive-guide-to-synclient.html>`_ and
+`The future of xinput, xmodmap, setxkbmap, xsetwacom and other tools under Wayland <http://who-t.blogspot.com.au/2016/12/the-future-of-xinput-xmodmap-setxkbmap.html>`_
+
+.. _faq_tablets:
+
+------------------------------------------------------------------------------
+Does libinput support non-Wacom tablets?
+------------------------------------------------------------------------------
+
+Yes, though unfortunately many non-Wacom tablets suffer from bad firmware
+and don't send the required events. But they should all work nonetheless. If
+you have a tablet that does not work with libinput, please
+:ref:`file a bug <reporting_bugs>`.
+
+.. _faq_tablet_capabilities:
+
+------------------------------------------------------------------------------
+My tablet doesn't work
+------------------------------------------------------------------------------
+
+If you see the message
+
+::
+
+     libinput bug: device does not meet tablet criteria. Ignoring this device.
+
+
+or the message
+
+::
+
+     missing tablet capabilities [...] Ignoring this device.
+
+
+your tablet device does not have the required capabilities to be treated as
+a tablet. This is usually a problem with the device and the kernel driver.
+See :ref:`tablet-capabilities` for more details.
+
+.. _faq_hwdb_changes:
+
+------------------------------------------------------------------------------
+How to apply hwdb changes
+------------------------------------------------------------------------------
+
+Sometimes users are asked to test updates to the
+`udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_
+or patches that include a change to the hwdb. See :ref:`hwdb` for
+details on the hwdb and how to modify it locally.
+
+.. note:: As of libinput 1.12, libinput-specific properties are now stored in
+	the :ref:`device-quirks` system. There are no libinput-specific hwdb
+	entries anymore and any changes to the hwdb must be merged into the
+	systemd repository.
+
+.. _faq_timer_offset:
+
+------------------------------------------------------------------------------
+What causes the "your system is too slow" warning?
+------------------------------------------------------------------------------
+
+libinput relies on the caller to call **libinput_dispatch()** whenever data is
+available. **libinput_dispatch()** will process the state of all devices,
+including some time-sensitive features (e.g. palm detection, tap-to-click,
+disable-while-typing, etc.).
+
+If the time between the event and the call to **libinput_dispatch()**
+is excessive, those features may not work correctly. For example, a delay in
+touch event processing may cause wrong or missing tap-to-click events or
+a palm may not be detected correctly.
+
+When this warning appears, it simply means that too much time has passed
+between the event occurring and the current time. In almost all cases this
+is an indication of the caller being overloaded and not handling events as
+speedily as required.
+
+The warning has no immediate effect on libinput's behavior but some of the
+functionality that relies on the timer may be impeded. This is not a bug in
+libinput. libinput does not control how quickly **libinput_dispatch()** is
+called.
+
+.. _faq_wayland:
+
+------------------------------------------------------------------------------
+Is libinput required for Wayland?
+------------------------------------------------------------------------------
+
+Technically - no. But for your use-case - probably.
+
+Wayland is a display server communication protocol. libinput is a low-level
+library to simplify handling input devices and their events. They have no
+direct connection. As a technical analogy, the question is similar to "is
+glibc required for HTTP", or (stretching the analogy a bit further) "Is a
+pen required to write English". No, it isn't.
+
+You can use libinput without a Wayland compositor, you can write a Wayland
+compositor without libinput. On most major distributions, libinput is the
+standard input stack used with the X.Org X server through the
+xf86-input-libinput driver.
+
+So why "for your use-case - probably"?  All general-purpose Wayland
+compositors use libinput for their input stack. Wayland compositors that
+are more specialized (e.g. in-vehicle infotainment or IVI) can handle input
+devices directly but the compositor you want to use
+on your desktop needs an input stack that is more complex. And right now,
+libinput is the only input stack that exists for this use-case.
+
+.. _faq_separate_contexts:
+
+------------------------------------------------------------------------------
+Can I write a program to make libinput do $FOO
+------------------------------------------------------------------------------
+
+A common question is whether it's possible to write a program that can change
+libinput's behavior - specifically the libinput that is used inside the
+compositor. This indicates a misunderstanding of how libinput works:
+libinput is a library that converts kernel events into libinput events, much
+like ``sed`` reads data in, modifies it, and provides it to stdout.
+
+.. graphviz:: libinput-contexts.gv
+
+A libinput context is private to the process and cannot be modified from the
+outside. To use the ``sed`` analogy again: if ``sed`` is used by a
+shell-script, that script has full control over how ``sed`` processes data. In
+this analogy, ``sed`` is libinput and the shell script is the compositor. It is
+not possible to write a program to modify the behavior of the ``sed`` instance
+used inside that shell script.
+
+Writing a program that uses libinput is akin to writing a new script that
+invoke ``sed``. It will not have any effect on the original ``sed`` instance.
+
+The only way to modify libinput's behavior is to use the configuration options
+exposed by the respective compositor. Those affect the libinput context inside
+the compositor and thus have an effect on the input device behavior.
+
+.. _faq_debug_events_not_showing_configuration:
+
+------------------------------------------------------------------------------
+Why doesn't libinput debug-events show my configuration
+------------------------------------------------------------------------------
+
+See :ref:`faq_separate_contexts`.
+
+------------------------------------------------------------------------------
+Can I configure scroll speed?
+------------------------------------------------------------------------------
+
+No, or at least, not as a libinput option.
+
+When using a mouse, libinput notifies callers about physical scroll wheel
+movement. When using another device, libinput notifies scroll in scroll units.
+
+It is up to the caller to transform those events into a number of pixels to
+scroll and, if desired, provide a way to adjust scroll speed.
+
+This transformation cannot be done in libinput because it may depend on context
+only known by the caller. For example, a caller may want to scroll faster
+depending on how many pages a document has or depending on the widget that
+receives the scroll events.

doc/user/features.rst

@@ -0,0 +1,29 @@
+.. _features:
+
+==============================================================================
+libinput Features
+==============================================================================
+
+Below is a list of features supported by libinput. The availability of
+features usually depends on the device type and a device's capabilities.
+Not all features are user-configurable, some rely on :ref:`device-quirks`
+to be useful.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   button-debouncing.rst
+   clickpad-softbuttons.rst
+   gestures.rst
+   middle-button-emulation.rst
+   palm-detection.rst
+   touchpad-thumb-detection.rst
+   scrolling.rst
+   t440-support.rst
+   tapping.rst
+   drag-3fg.rst
+   tablet-support.rst
+   switches.rst
+   touchpad-pressure.rst
+   trackpoints.rst

doc/user/gestures.rst

@@ -0,0 +1,373 @@
+.. _gestures:
+
+==============================================================================
+Gestures
+==============================================================================
+
+libinput supports :ref:`gestures_pinch` and :ref:`gestures_swipe` on most
+modern touchpads and other indirect touch devices. Note that libinput **does
+not** support gestures on touchscreens, see :ref:`gestures_touchscreens`.
+
+.. _gestures_lifetime:
+
+-----------------------------------------------------------------------------
+Lifetime of a gesture
+-----------------------------------------------------------------------------
+
+A gesture starts when the finger position and/or finger motion is
+unambiguous as to what gesture to trigger and continues until the first
+finger belonging to this gesture is lifted.
+
+A single gesture cannot change the finger count. For example, if a user
+puts down a fourth finger during a three-finger swipe gesture, libinput will
+end (cancel) the three-finger gesture and, if applicable, start a
+four-finger swipe gesture. A caller may however decide that those gestures
+are semantically identical and continue the two gestures as one single
+gesture.
+
+.. _gestures_pinch:
+
+------------------------------------------------------------------------------
+Pinch gestures
+------------------------------------------------------------------------------
+
+Pinch gestures are executed when two or more fingers are located on the
+touchpad and are either changing the relative distance to each other
+(pinching) or are changing the relative angle (rotate). Pinch gestures may
+change both rotation and distance at the same time. For such gestures,
+libinput calculates a logical center for the gestures and provides the
+caller with the delta x/y coordinates of that center, the relative angle of
+the fingers compared to the previous event, and the absolute scale compared
+to the initial finger position.
+
+.. figure:: pinch-gestures.svg
+    :align: center
+
+    The pinch and rotate gestures
+
+The illustration above shows a basic pinch in the left image and a rotate in
+the right angle. Not shown is a movement of the logical center if the
+fingers move unevenly. Such a movement is supported by libinput, it is
+merely left out of the illustration.
+
+Note that while position and angle is relative to the previous event, the
+scale is always absolute and a multiplier of the initial finger position's
+scale.
+
+.. _gestures_swipe:
+
+------------------------------------------------------------------------------
+Swipe gestures
+------------------------------------------------------------------------------
+
+Swipe gestures are executed when three or more fingers are moved
+synchronously in the same direction. libinput provides x and y coordinates
+in the gesture and thus allows swipe gestures in any direction, including
+the tracing of complex paths. It is up to the caller to interpret the
+gesture into an action or limit a gesture to specific directions only.
+
+.. figure:: swipe-gestures.svg
+    :align: center
+
+    The swipe gestures
+
+The illustration above shows a vertical three-finger swipe. The coordinates
+provided during the gesture are the movements of the logical center.
+
+.. _gestures_hold:
+
+------------------------------------------------------------------------------
+Hold gestures
+------------------------------------------------------------------------------
+
+A hold gesture is one where the user places one or more fingers on the
+device without significant movement. The exact conditions when a hold gesture
+transitions to pointer motion, scrolling or other gestures
+are implementation-defined.
+
+The hold gesture is intended to allow for the implementation of two specific
+features:
+
+- where a two-finger scrolling starts kinetic scrolling in the caller, a
+  subsequent hold gesture can be used to stop that kinetic scroll motion,
+  and
+- hold-to-trigger interactions where the interaction could be a click, a
+  context menu, or some other context-specific interaction.
+
+Hold gestures have three potential logical states:
+
+- **begin**: one or more fingers are placed on the device at the same time
+- **end**: all fingers are removed and the device enters a neutral logical state
+- **end(cancelled)**: all fingers are part of a known interaction and the
+  currenthold gesture is no longer active. This may also occurs when
+  switching between hold gestures with different finger counts.
+
+.. note:: By definition, a hold gesture does not move and thus no coordinate
+          updates are available.
+
+For example, a user that puts one finger, then a second finger down and
+releases them later may trigger the following event sequence:
+
+=============  ============  ============
+Action         Event         Finger count
+=============  ============  ============
+Finger 1 down  <no event>
+Finger 2 down  **begin**     2
+Finger 2 up    **end**       2
+Finger 1 up    <no event>
+=============  ============  ============
+
+A hold gesture may by be **cancelled**. This occurs
+when the hold gesture changes into some other interaction and should no
+longer be considered the current hold gesture. A **end(cancelled)** event
+applies to the whole gesture (all fingers). For example, a pointer motion on
+a touchpad may trigger this sequence:
+
++-------------------+-----------------------+
+| Action            |  Event                |
++===================+=======================+
+| | Finger 1 down   | | **hold begin**      |
++-------------------+-----------------------+
+| | Finger 1 motion | | **hold cancel**     |
+| |                 | | **pointer motion**  |
++-------------------+-----------------------+
+| | Finger 1 motion | | **pointer motion**  |
++-------------------+-----------------------+
+| | Finger 1 up     | | *no event*          |
++-------------------+-----------------------+
+
+.. note:: Many interactions with a touchpad will start with a hold
+          gesture that is then cancelled as that gesture turns into e.g.
+          pointer motion. A caller **must** handle hold gesture
+          cancellations correctly.
+
+A two-finger scroll motion on a touchpad may trigger this sequence:
+
++------------------------+---------------------+--------------+
+| Action                 |  Event              | Finger count |
++========================+=====================+==============+
+| | Finger 1 down        | | **hold begin**    | | 1          |
++------------------------+---------------------+--------------+
+| | Finger 2 down        | | **hold cancel**   | | 1          |
+| |                      | | **hold begin**    | | 2          |
++------------------------+---------------------+--------------+
+| | Finger 1+2 motion    | | **hold cancel**   | | 2          |
+| |                      | | **pointer axis**  | |            |
++------------------------+---------------------+--------------+
+| | Finger 1+2 motion    | | **pointer axis**  |              |
++------------------------+---------------------+--------------+
+| | Finger 1 up          | | **pointer axis**  |              |
+| | Finger 2 up          | | (scroll stop)     |              |
++------------------------+---------------------+--------------+
+
+A three-finger-swipe on a touchpad may trigger this sequence:
+
++---------------------+---------------------+--------------+
+| Action              |  Event              | Finger count |
++=====================+=====================+==============+
+| | Finger 1 down     |  | **hold begin**   | | 1          |
++---------------------+---------------------+--------------+
+| | Finger 2 down     | | **hold cancel**   | | 1          |
+| |                   | | **hold begin**    | | 2          |
++---------------------+---------------------+--------------+
+| | Finger 3 down     | | **hold cancel**   | | 2          |
+| |                   | | **hold begin**    | | 3          |
++---------------------+---------------------+--------------+
+| | Finger motion     | | **hold cancel**   | | 3          |
+| |                   | | **swipe begin**   | | 3          |
++---------------------+---------------------+--------------+
+| | Finger motion     | | **swipe update**  | | 3          |
++---------------------+---------------------+--------------+
+| | Finger 1 up       | | **swipe end**     | | 3          |
+| | Finger 2 up       | |                   | |            |
+| | Finger 3 up       | |                   | |            |
++---------------------+---------------------+--------------+
+
+Single-finger hold gestures
+...........................
+
+libinput uses implementation-defined timeouts based on other interactions
+to determine whether a single-finger hold gestures should start. In other
+words, a caller **must not** rely on a hold gesture always being triggered
+as soon as a single finger is placed on the touchpad. This is true for any
+hold gesture but especially so for single-finger hold gestures.
+
+Hold gestures with a single finger are prone to being extremely short-lived.
+On many devices it is impossible to hold a finger still enough for there to
+be no pointer motion events, even if those deltas are miniscule. Changing
+movement thresholds to rely on hold gestures would reduce device
+responsiveness.
+
+It is thus the responsibility of the caller to determine where hold gestures
+transition in and out of other interactions. For example, a two-finger hold
+may produce a cancelled single-finger hold gesture first:
+
++--------------------+----------------------+--------------+--------------+
+| Action             |  Event               | Finger count | Notes        |
++====================+======================+==============+==============+
+| | Finger 1 down    | | **hold begin**     | | 1          |              |
++--------------------+----------------------+--------------+--------------+
+| | Finger 1 motion  | | **hold cancel**    | | 1          | | tiny deltas|
+| |                  | | **pointer motion** | |            | |            |
++--------------------+----------------------+--------------+--------------+
+| | Finger 2 down    | | **hold begin**     | | 2          |              |
++--------------------+----------------------+--------------+--------------+
+| | Finger 1 up      | | **hold end**       | |            |              |
+| | Finger 2 up      | |                    | |            |              |
++--------------------+----------------------+--------------+--------------+
+
+Note how the second hold gesture started with a finger count of 2 - without
+the user ever lifting the first finger. Cancellation of hold gesture does
+not imply the user has lifted a finger.
+
+A hold gesture may start after a previous gesture completed. For example, a
+single finger move-and-hold may trigger different sequences for the same
+user interaction:
+
++--------------------+---------------------+-------------------+--------------+
+| Action             |  Device 1           | Device 2          | Notes        |
++====================+=====================+===================+==============+
+| | Finger 1 down    | | **hold begin**    |  | **hold begin** |              |
++--------------------+---------------------+-------------------+--------------+
+| | Finger 1 motion  | | **hold cancel**   |                   | | tiny deltas|
+|                    | | **pointer motion**|                   | |            |
++--------------------+---------------------+-------------------+--------------+
+|                    | |  **hold begin**   |                   |              |
++--------------------+---------------------+-------------------+--------------+
+| |  Finger 1 up     | |  **hold end**     | |  **hold end**   |              |
++--------------------+---------------------+-------------------+--------------+
+
+A caller that wants to use hold gestures must thus be able to infer the same
+interaction based on a stream of pointer motion events with small deltas.
+
+libinput may start a new hold begin gesture once the pointer stops moving.
+The time between the last pointer motion event and the hold begin event is
+implementation-defined.
+
+
+Hold gestures and thumb/palm detection
+......................................
+
+Thumb and palm detection effectively remove touches from being counted
+towards an interaction, see :ref:`thumb_detection` and
+:ref:`palm_detection` for details.
+
+In the context of hold gestures, thumbs and palms are treated by libinput as
+if the finger was removed from the device. Where other non-thumb/non-palm
+fingers remain on the device, an **hold update** event is sent. Otherwise,
+the hold gesture terminates with a **hold cancel** event.
+
+Notably, libinput's thumb and palm detection is not a simple boolean per
+touch but specific to the state of that touch in the overall context. For
+example, a touch may be a thumb for tapping but not for clickfinger
+interactions. A caller must not infer the number of physical fingers from
+the hold gesture.
+
+Likewise, libinput may classify a finger as thumb in the same hardware event
+as a new finger is placed on the touchpad. In that case, the hold gesture
+**may** continue as one-finger gesture despite there being two physical
+touch points.
+
+Information to determine whether a touch is a thumb or a palm may not be
+available until some time into an interaction. Thus very short brushes
+of the touchpad by a palm may trigger a **hold begin** followed by an
+immediate **hold end** as libinput lacks sufficient information to identify
+the touch as thumb/palm and send the corresponding **hold cancel**
+event. A caller must not assume that a hold gesture always represents a
+valid finger down.
+
+Hold gestures and tap-to-click
+..............................
+
+:ref:`tapping` is the feature that enables short-lived touches to trigger
+button presses.
+
+.. warning:: Summary: do not use hold gestures to do your own tap-to-click
+             implementation
+
+In the context of hold gestures, tap-to-click cancels current hold gestures
+and a finger dragging (see :ref:`tapndrag`) does not begin a hold
+gesture. Where tap-to-click is disabled a tap-like gesture may create
+**hold begin** followed by a **hold end** event. Callers **must not** use
+hold gestures for their own tap-to-click implementation as the data is not
+reliable enough. libinput may change internal timeouts and thresholds
+depending on whether tap-to-click is enabled and the hold gesture event may
+not match touch sequences that a user would expect to be a tap-to-click
+interaction.
+
+.. _gestures_touchscreens:
+
+------------------------------------------------------------------------------
+Touchscreen gestures
+------------------------------------------------------------------------------
+
+Touchscreen gestures are **not** interpreted by libinput. Rather, any touch
+point is passed to the caller and any interpretation of gestures is up to
+the caller or, eventually, the X or Wayland client.
+
+Interpreting gestures on a touchscreen requires context that libinput does
+not have, such as the location of windows and other virtual objects on the
+screen as well as the context of those virtual objects:
+
+.. figure:: touchscreen-gestures.svg
+    :align: center
+
+    Context-sensitivity of touchscreen gestures
+
+In the above example, the finger movements are identical but in the left
+case both fingers are located within the same window, thus suggesting an
+attempt to zoom. In the right case  both fingers are located on a window
+border, thus suggesting a window movement. libinput has no knowledge of the
+window coordinates and thus cannot differentiate the two.
+
+.. _gestures_softbuttons:
+
+------------------------------------------------------------------------------
+Gestures with enabled software buttons
+------------------------------------------------------------------------------
+
+If the touchpad device is a :ref:`Clickpad <touchpads_buttons_clickpads>`, it
+is recommended that a caller switches to :ref:`clickfinger`.
+Usually fingers placed in a :ref:`software button area <software_buttons>`
+are not considered for gestures, resulting in some gestures to be
+interpreted as pointer motion or two-finger scroll events.
+
+.. figure:: pinch-gestures-softbuttons.svg
+    :align: center
+
+    Interference of software buttons and pinch gestures
+
+In the example above, the software button area is highlighted in red. The
+user executes a three-finger pinch gesture, with the thumb remaining in the
+software button area. libinput ignores fingers within the software button
+areas, the movement of the remaining fingers is thus interpreted as a
+two-finger scroll motion.
+
+.. _gestures_twofinger_touchpads:
+
+------------------------------------------------------------------------------
+Gestures on two-finger touchpads
+------------------------------------------------------------------------------
+
+As of kernel 4.2, many :ref:`touchpads_touch_partial_mt` provide only two
+slots. This affects how gestures can be interpreted. Touchpads with only two
+slots can identify two touches by position but can usually tell that there
+is a third (or fourth) finger down on the touchpad - without providing
+positional information for that finger.
+
+Touchpoints are assigned in sequential order and only the first two touch
+points are trackable. For libinput this produces an ambiguity where it is
+impossible to detect whether a gesture is a pinch gesture or a swipe gesture
+whenever a user puts the index and middle finger down first. Since the third
+finger does not have positional information, it's location cannot be
+determined.
+
+.. figure:: gesture-2fg-ambiguity.svg
+    :align: center
+
+    Ambiguity of three-finger gestures on two-finger touchpads
+
+The image above illustrates this ambiguity. The index and middle finger are
+set down first, the data stream from both finger positions looks identical.
+In this case, libinput assumes the fingers are in a horizontal arrangement
+(the right image above) and use a swipe gesture.

doc/user/git_version.py.in

@@ -0,0 +1,5 @@
+def get_git_version():
+	return "__GIT_VERSION__"[:7]
+
+def get_git_version_full():
+	return "__GIT_VERSION__"

doc/user/ignoring-devices.rst

@@ -0,0 +1,36 @@
+.. _ignoring_devices:
+
+==============================================================================
+Ignoring specific devices
+==============================================================================
+
+If a device has the **LIBINPUT_IGNORE_DEVICE** udev property set to any
+value but "0", that device is not initialized by libinput.
+For a context created with **libinput_udev_create_context()**, the device is
+silently ignored and never shows up. If the device is added with
+**libinput_path_add_device()** to a context created with
+**libinput_path_create_context()**, adding the device will fail and return NULL
+(see that function's documentation for more
+information).
+
+If the property value is exactly "0", then the property is considered unset
+and libinput initializes the device normally.
+
+This property should be used for devices that are correctly detected as
+input devices (see :ref:`udev_device_type`) but that should not be used by
+libinput. It is recommended that devices that should not be handled as input
+devices at all unset the **ID_INPUT** and related properties instead. The
+**LIBINPUT_IGNORE_DEVICE** property signals that only libinput should
+ignore this property but other parts of the stack (if any) should continue
+treating this device normally.
+
+Below is an example udev rule  to assign **LIBINPUT_IGNORE_DEVICE** to the
+device with the vendor/model ID of ``012a``/``034b``. ::
+
+  $ cat /etc/udev/rules.d/99-ignore-my-device.rules
+  ACTION!="remove", KERNEL=="event[0-9]*", \
+     ENV{ID_VENDOR_ID}=="012a", \
+     ENV{ID_MODEL_ID}=="034b", \
+     ENV{LIBINPUT_IGNORE_DEVICE}="1"
+
+See :ref:`udev_config` for more details on libinput's udev properties.

doc/user/incorrectly-enabled-hires.rst

@@ -0,0 +1,62 @@
+.. _incorrectly_enabled_hires:
+
+==============================================================================
+Incorrectly enabled high-resolution scroll
+==============================================================================
+
+Some devices might announce support for high-resolution scroll wheel by enabling
+``REL_WHEEL_HI_RES`` and/or ``REL_HWHEEL_HI_RES`` but never send a
+high-resolution scroll event.
+
+When the first low-resolution scroll event is received without any previous
+high-resolution event, libinput prints a bug warning with the text **"device
+supports high-resolution scroll but only low-resolution events have been
+received"** and a link to this page.
+
+.. note:: This warning will be printed only once
+
+In most cases this is a bug on the device firmware, the kernel driver or in a
+software used to create user-space devices through uinput.
+
+Once the bug is detected, libinput will start emulating high-resolution scroll
+events.
+
+------------------------------------------------------------------------------
+Detecting and fixing the issue
+------------------------------------------------------------------------------
+
+Events sent by a buggy device can be shown in the
+:ref:`libinput record <libinput-record>` output for the device. Notice that
+``REL_WHEEL_HI_RES`` and ``REL_HWHEEL_HI_RES`` are set but only ``REL_WHEEL``
+events are sent: ::
+
+    # Supported Events:
+    # Event type 0 (EV_SYN)
+    # Event type 1 (EV_KEY)
+    #   Event code 272 (BTN_LEFT)
+    # Event type 2 (EV_REL)
+    #   Event code 0 (REL_X)
+    #   Event code 1 (REL_Y)
+    #   Event code 6 (REL_HWHEEL)
+    #   Event code 8 (REL_WHEEL)
+    #   Event code 11 (REL_WHEEL_HI_RES)
+    #   Event code 12 (REL_HWHEEL_HI_RES)
+    [...]
+    quirks:
+    events:
+    - evdev:
+        - [  0,      0,   2,   8,       1] # EV_REL / REL_WHEEL                 1
+        - [  0,      0,   0,   0,       0] # ------------ SYN_REPORT (0) ---------- +0ms
+    - evdev:
+        - [  0,  15126,   2,   8,       1] # EV_REL / REL_WHEEL                 1
+        - [  0,  15126,   0,   0,       0] # ------------ SYN_REPORT (0) ---------- +15ms
+    - evdev:
+        - [  0,  30250,   2,   8,       1] # EV_REL / REL_WHEEL                 1
+        - [  0,  30250,   0,   0,       0] # ------------ SYN_REPORT (0) ---------- +15ms
+
+The issue can be fixed by adding a quirk to unset the ``REL_WHEEL_HI_RES`` and
+``REL_HWHEEL_HI_RES`` event codes: ::
+
+    AttrEventCode=-REL_WHEEL_HI_RES;-REL_HWHEEL_HI_RES;
+
+Please see :ref:`device-quirks` for details.

doc/user/index.rst

@@ -0,0 +1,74 @@
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  what-is-libinput
+  features
+  configuration
+  building
+  faqs
+  reporting-bugs
+  troubleshooting
+  contributing
+  development
+  lua-plugins
+  API documentation <@HTTP_DOC_LINK@/api/>
+
+
+++++++++++++++++++++++++++++++
+libinput
+++++++++++++++++++++++++++++++
+
+libinput is a library that provides a full input stack for display servers
+and other applications that need to handle input devices provided by the
+kernel.
+
+libinput provides device detection, event handling and abstraction to
+minimize the amount of custom input code the user of libinput need to
+provide the common set of functionality that users expect. Input event
+processing includes scaling touch coordinates, generating
+relative pointer events from touchpads, pointer acceleration, etc.
+
+libinput is not used directly by applications. Think of it more as a device
+driver than an application library. See :ref:`what_is_libinput` for more details.
+
+--------------------
+Users and Developers
+--------------------
+
+Please use the side-bar to navigate through the various documentation items.
+
+-----------------
+API documentation
+-----------------
+
+The API documentation is available here:
+    https://wayland.freedesktop.org/libinput/doc/latest/api/
+
+.. note:: This documentation is generally only needed by authors of Wayland
+	  compositors or other developers dealing with input events directly.
+
+-------
+License
+-------
+
+libinput is licensed under the MIT license
+
+.. code-block:: none
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions: [...]
+
+See the
+`COPYING <https://gitlab.freedesktop.org/libinput/libinput/tree/master/COPYING>`_
+file for the full license information.
+
+.....
+About
+.....
+Documentation generated from |git_version|

doc/user/lua-plugins.rst

@@ -0,0 +1,661 @@
+.. _lua_plugins:
+
+==============================================================================
+Lua Plugins
+==============================================================================
+
+libinput provides a plugin system that allows users to modify the behavior
+of devices. For example, a plugin may add or remove axes and/or buttons on a
+device and/or modify the event stream seen by this device before it is passed
+to libinput.
+
+Plugins are implemented in `Lua <https://www.lua.org/>`_ (version 5.4)
+and are typically loaded from the following paths:
+
+- ``/etc/libinput/plugins/*.lua``, and
+- ``/usr/lib{64}/libinput/plugins/*.lua``
+
+Plugins are loaded in alphabetical order and where
+multiple plugins share the same file name, the one in the highest precedence
+directory is used. Plugins in ``/etc`` take precedence over
+plugins in ``/usr``.
+
+.. note:: Plugins lookup paths and their order are decided by the compositor.
+          Some compositors may support more/fewer/other lookup paths than the
+          above defaults.
+
+Plugins are run sequentially in ascending sort-order (i.e. ``00-foo.lua`` runs
+before ``10-bar.lua``) and each plugin sees the state left by any previous
+plugins. For example if ``00-foo.lua`` changes all left button events to right
+button events, ``10-bar.lua`` only ever sees right button events.
+
+See the `Lua Reference manual <https://www.lua.org/manual/5.4/manual.html>`_ for
+details on the Lua language.
+
+.. note:: Plugins are **not** loaded by default, it is up to the compositor
+          whether to allow plugins. An explicit call to
+          ``libinput_plugin_system_load_plugins()`` is required.
+
+------------------------------------------------------------------------------
+Limitations
+------------------------------------------------------------------------------
+
+Each script runs in its own sandbox and cannot communicate or share state with
+other scripts.
+
+Tables that hold API methods are not writable, i.e. it is not possible
+to overwrite the default functionality of those APIs.
+
+The Lua API available to plugins is limited to the following calls::
+
+    assert  error   ipairs  next     pairs  tonumber
+    pcall   select  print   tostring type   xpcall
+    table   string  math    _VERSION
+
+It is not possible to e.g. use the ``io`` module from a script.
+
+To use methods on instantiated objects, the ``object:method`` method call
+syntax must be used. For example:
+
+.. code-block:: lua
+
+    libinput:register()
+    libinput.register() -- this will fail
+
+------------------------------------------------------------------------------
+When to use plugins
+------------------------------------------------------------------------------
+
+libinput plugins are a relatively niche use-case that typically need to
+address either once-off issues (e.g. those caused by worn-out hardware) or
+user preferences that libinput does not and will not cater for.
+
+Plugins should not be used for issues that can be fixed generically, for
+example via :ref:`device-quirks`.
+
+As a rule of thumb: a plugin should be a once-off that only works for one
+user's hardware. If a plugin can be shared with many users then the plugin
+implements functionality that should be integrated into libinput proper.
+
+------------------------------------------------------------------------------
+Testing plugins
+------------------------------------------------------------------------------
+
+Our :ref:`tools` support plugins if passed the ``--enable-plugins`` commandline
+option. For implementing and testing plugins the easiest commands to test are
+
+- ``libinput debug-events --enable-plugins`` (see :ref:`libinput-debug-events` docs)
+- ``libinput debug-gui --enable-plugins`` (see :ref:`libinput-debug-gui` docs)
+
+Where libinput is built and run from git, the tools will also look for plugins
+in the meson build directory. See the ``plugins/meson.build`` file for details.
+
+.. _plugins_api_lua:
+
+--------------------------------------------------------------------------------
+Lua Plugin API
+--------------------------------------------------------------------------------
+
+Lua plugins sit effectively below libinput and the API is not a
+representation of the libinput API. Plugins modify the evdev event stream
+received from the kernel.
+
+.. graphviz:: plugin-stack.gv
+
+The API revolves around two types: ``libinput`` and ``EvdevDevice``. The
+``libinput`` type is used to register a plugin from a script, the
+``EvdevDevice`` represents one device that is present in the system (but may
+not have yet been added by libinput).
+
+Typically a script does the following steps:
+
+- register with libinput via ``libinput:register({versions})``
+- connect to the ``"new-evdev-device"`` event
+- receive an ``EvdevDevice`` object in the ``"new-evdev-device"`` callback
+
+  - check and/or modify the evdev event codes on the device
+  - connect to the device's ``"evdev-frame"`` event
+
+- receive an :ref:`evdev frame <plugins_api_evdev_frame>` in the device's
+  ``"evdev-frame"`` callback
+
+  - check and/or modify the events in that frame
+
+Where multiple plugins are active, the evdev frame passed to the callback is
+the combined frame as processed by all previous plugins in ascending sort order.
+For example, if one plugin discards all button events subsequent plugins will
+never see those button events in the frame.
+
+.. _plugins_api_version_stability:
+
+..............................................................................
+Plugin version stability
+..............................................................................
+
+Plugin API version stability is provided on a best effort basis. We aim to provide
+stable plugin versions for as long as feasible but may need to retire some older
+versions over time. For this reason a plugin can select multiple versions it
+implements, libinput will pick one supported version and adjust the plugin
+behavior to match that version. See the ``libinput:register()`` call for details.
+
+--------------------------------------------------------------------------------
+Lua Plugin API Reference
+--------------------------------------------------------------------------------
+
+
+libinput provides the following globals and types:
+
+.. _plugins_api_evdev_usage:
+
+................................................................................
+Evdev Usages
+................................................................................
+
+Evdev usages are a libinput-specific wrapper around the ``linux/input-event-codes.h``
+evdev types and codes. They are used by libinput internally and are a 32-bit
+combination of ``type << 16 | code``. Each usage carries the type and code and
+is thus simpler to pass around and less prone to type confusion.
+
+The :ref:`evdev global <plugins_api_evdev_global>` attempts to provide all
+available usages but for the niche cases where it does not provide a named constant
+the value can be crafted manually:
+
+.. code-block:: lua
+
+   evdev_type = 0x3  -- EV_REL
+   evdev_code = 0x1  -- REL_Y
+   evdev_usage = (evdev_type << 16) | evdev_code
+
+   assert(usage == evdev.REL_Y)
+
+.. _plugins_api_evdev_global:
+
+................................................................................
+The ``evdev`` global
+................................................................................
+
+The ``evdev`` global represents all known :ref:`plugins_api_evdev_usage`,
+effectively in the form:
+
+.. code-block:: lua
+
+   evdev = {
+      ABS_X = (3 << 16) | 0,
+      ABS_Y = (3 << 16) | 1,
+      ...
+      REL_X = (2 << 16) | 0,
+      REL_Y = (2 << 16) | 1,
+      ...
+   }
+
+
+This global is provided for convenience to improve readability in the code.
+Note that the name uses the event code name only (e.g. ``evdev.ABS_Y``) but the
+value is an :ref:`Evdev Usage <plugins_api_evdev_usage>` (type and code).
+
+See the ``linux/input-event-codes.h`` header file provided by your kernel
+for a list of all evdev types and codes.
+
+The evdev global also provides the bus type constants, e.g. ``evdev.BUS_USB``.
+See the ``linux/input.h`` header file provided by your kernel
+for a list of bus types.
+
+
+.. _plugins_api_evdev_frame:
+
+................................................................................
+Evdev frames
+................................................................................
+
+Evdev frames represent a single frame of evdev events for a device. A frame
+is a group of events that occurred at the same time. The frame usually only
+contains state that has changed compared to the previous frame.
+
+In our API a frame is exposed as a nested table with the following structure:
+
+.. code-block:: lua
+
+    frame1 = {
+         { usage = evdev.ABS_X, value = 123 },
+         { usage = evdev.ABS_Y, value = 456 },
+         { usage = evdev.BTN_LEFT, value = 1 },
+    }
+    frame2 = {
+         { usage = evdev.ABS_Y, value = 457 },
+    }
+    frame3 = {
+         { usage = evdev.ABS_X, value = 124 },
+         { usage = evdev.BTN_LEFT, value = 0 },
+    }
+
+.. note:: This API does not use ``SYN_REPORT`` events, it is implied at the
+          end of the table. Where a plugin writes a ``SYN_REPORT`` into the
+          list of events, that ``SYN_REPORT`` terminates the event frame
+          (similar to writing a ``\0`` into the middle of a C string).
+          A frame containing only a ``SYN_REPORT`` is functionally equivalent
+          to an empty frame.
+
+Events or frames do not have a timestamp. Where a timestamp is required, that
+timestamp is passed as additional argument to the function or return value.
+
+See :ref:`plugins_api_evdev_global` for a list of known usages.
+
+.. warning:: Evdev frames have an implementation-defined size limit of how many
+             events can be added to a single frame. This limit should never be
+             hit by valid plugins.
+
+.. _plugins_api_libinputglobal:
+
+................................................................................
+The ``libinput`` global object
+................................................................................
+
+The core of our plugin API is the ``libinput`` global object. A script must
+immediately ``register()`` to be active, otherwise it is unloaded immediately.
+
+All libinput-specific APIs can be accessed through the ``libinput`` object.
+
+.. function:: libinput:register({1, 2, ...})
+
+   Register this plugin with the given table of supported version numbers and
+   returns the version number selected by libinput for this plugin. See
+   :ref:`plugins_api_version_stability` for details.
+
+   .. code-block:: lua
+
+       -- this plugin can support versions 1, 4 and 5
+       version = libinput:register({1, 4, 5})
+       if version == 1 then
+           ...
+
+   This function must be the first function called.
+   If the plugin calls any other functions before ``register()``, those functions
+   return the default zero value for the return type (``nil``, ``0``, an empty
+   table, etc.).
+
+   If the plugin does not call ``register()`` it will be removed immediately.
+   Once registered, any connected callbacks will be invoked whenever libinput
+   detects new devices, removes devices, etc.
+
+   This function must only be called once.
+
+.. function:: libinput:unregister()
+
+   Unregister this plugin. This removes the plugin from libinput and releases
+   any resources associated with this plugin. This call must be the last call
+   in your plugin, it is effectively equivalent to Lua's
+   `os.exit() <https://www.lua.org/manual/5.4/manual.html#pdf-os.exit>`_.
+
+.. function:: libinput:log_debug(message)
+
+   Log a message at the libinput debug log priority. See
+   ``libinput:log_error()`` for details.
+
+.. function:: libinput:log_info(message)
+
+   Log a message at the libinput info log priority. See
+   ``libinput:log_error()`` for details.
+
+.. function:: libinput:log_error(message)
+
+   Log a message at the libinput error log priority. Whether a message is
+   displayed in the log depends on libinput's log priority, set by the caller.
+
+   A compositor may disable stdout and stderr. Log messages should be preferred
+   over Lua's ``print()`` function to ensure the messages end up in the same
+   location as other libinput log messages and are not discarded.
+
+.. function:: libinput:now()
+
+   Returns the current time in microseconds in ``CLOCK_MONOTONIC``. This is
+   the timestamp libinput uses internally. This timestamp cannot be mapped
+   to any particular time of day, see the
+   `clock_gettime() man page <https://man7.org/linux/man-pages/man3/clock_gettime.3.html>`_
+   for details.
+
+.. function:: libinput:version()
+
+   Returns the agreed-on version of the plugin, see ``libinput:register()``.
+   If called before ``libinput:register()`` this function returns ``0``.
+
+.. function:: libinput:connect(name, function)
+
+   Set the callback to the given event name. Only one callback
+   may be set for an event name at any time, subsequent callbacks
+   will replace any earlier callbacks for the same name.
+
+   Version 1 of the plugin API supports the following events and callback arguments:
+
+   - ``"new-evdev-device"``: A new :ref:`EvdevDevice <plugins_api_evdevdevice>`
+     has been seen by libinput but not yet added.
+
+     .. code-block:: lua
+
+      libinput:connect("new-evdev-device", function (device) ... end)
+
+   - ``"timer-expired"``: The timer for this plugin has expired. This event is
+     only sent if the plugin has set a timer with ``timer_set()``.
+
+     .. code-block:: lua
+
+      libinput:connect("timer-expired", function (now) ... end)
+
+     The ``now`` argument is the current time in microseconds in
+     ``CLOCK_MONOTONIC`` (see ``libinput:now()``).
+
+.. function:: libinput:timer_cancel()
+
+   Cancel the timer for this plugin. This is a no-op if the timer
+   has not been set or has already expired.
+
+.. function:: libinput:timer_set_absolute(time)
+
+   Set a timer for this plugin, with the given time in microseconds.
+   The timeout specifies an absolute time in microseconds (see
+   ``libinput:now()``) The timer will expire once and then call the
+   ``"timer-expired"`` event handler (if any).
+
+   See ``libinput:timer_set_relative()`` for a relative timer.
+
+   The following two lines of code are equivalent:
+
+   .. code-block:: lua
+
+      libinput:timer_set_relative(1000000) -- 1 second from now
+      libinput:timer_set_absolute(libinput:now() + 1000000) -- 1 second from now
+
+   Calling this function will cancel any existing (relative or absolute) timer.
+
+.. function:: libinput:timer_set_relative(timeout)
+
+   Set a timer for this plugin, with the given timeout in microseconds from
+   the current time. The timer will expire once and then call the
+   ``"timer-expired"`` event handler (if any).
+
+   See ``libinput:timer_set_absolute()`` for an absolute timer.
+
+   The following two lines of code are equivalent:
+
+   .. code-block:: lua
+
+      libinput:timer_set_relative(1000000) -- 1 second from now
+      libinput:timer_set_absolute(libinput:now() + 1000000) -- 1 second from now
+
+   Calling this function will cancel any existing (relative or absolute) timer.
+
+.. _plugins_api_evdevdevice:
+
+................................................................................
+The ``EvdevDevice`` type
+................................................................................
+
+The ``EvdevDevice`` type represents a device available in the system
+but not (yet) added by libinput. This device may be used to modify
+a device's capabilities before the device is processed by libinput.
+
+A plugin should always ``connect()`` to the ``"device-removed"`` callback
+to be notified when a device is removed. If the plugin keeps a reference
+to this device but the device is discarded by libinput, the device's query
+methods will return zero values (e.g. ``nil``, ``0``, an empty table) and
+methods will be noops.
+
+.. function:: EvdevDevice:info()
+
+   A table containing static information about the device, e.g.
+
+   .. code-block:: lua
+
+      {
+         bustype = evdev.BUS_USB,
+         vid = 0x1234,
+         pid = 0x5678,
+      }
+
+   A plugin must ignore keys it does not know about.
+
+   Version 1 of the plugin API supports the following keys and values:
+
+   - ``bustype``: The numeric bustype of the device. See the
+     ``BUS_*`` defines in ``linux/input.h`` for the list of possible values.
+   - ``vid``: The 16-bit vendor ID of the device
+   - ``pid``: The 16-bit product ID of the device
+
+   If the device has since been discarded by libinput, this function returns an
+   empty table.
+
+.. function:: EvdevDevice:name()
+
+   The device name as set by the kernel
+
+.. function:: EvdevDevice:usages()
+
+   Returns a table of all usages that are currently enabled for this
+   device. Any type that exists on the device has a table assigned and in this
+   table any code that exists on the device is a boolean true.
+   For example:
+
+   .. code-block:: lua
+
+      {
+         evdev.REL_X = true,
+         evdev.REL_Y = true,
+         evdev.BTN_LEFT = true,
+      }
+
+   All other usages are ``nil``, so that the following code is possible:
+
+   .. code-block:: lua
+
+      local usages = device:usages()
+      if usages[evdev.REL_X] then
+         -- do something
+      end
+
+
+   If the device has since been discarded by libinput, this function returns an
+   empty table.
+
+.. function:: EvdevDevice:absinfos()
+
+   Returns a table of all ``EV_ABS`` codes that are currently enabled for this device.
+   The event code is the key, each value is a table containing the following keys:
+   ``minimum``, ``maximum``, ``fuzz``, ``flat``, ``resolution``.
+
+   .. code-block:: lua
+
+      {
+         evdev.ABS_X = {
+            minimum = 0,
+            maximum = 1234,
+            fuzz = 0,
+            flat = 0,
+            resolution = 45,
+         },
+      }
+
+   If the device has since been discarded by libinput, this function returns an
+   empty table.
+
+.. function:: EvdevDevice:udev_properties()
+
+   Returns a table containing a filtered list of udev properties available on this device
+   in the form ``{ property_name = property_value, ... }``.
+   udev properties used as a boolean (e.g. ``ID_INPUT``) are only present if their
+   value is a logical true.
+
+   Version 1 of the plugin API supports the following udev properties:
+
+   - ``ID_INPUT`` and all of ``ID_INPUT_*`` that denote the device type as assigned
+     by udev. This information is usually used by libinput to determine a
+     device type. Note that for historical reasons these properties have
+     varying rules - some properties may be mutually exclusive, others are
+     independent, others may only be set if another property is set. Refer to
+     the udev documentation (if any) for details. ``ID_INPUT_WIDTH_MM`` and
+     ``ID_INPUT_HEIGHT_MM`` are excluded from this set.
+
+   If the device has since been discarded by libinput, this function returns an
+   empty table.
+
+.. function:: EvdevDevice:enable_evdev_usage(usage)
+
+   Enable the given :ref:`evdev usage <plugins_api_evdev_usage>` for this device.
+   Use :ref:`plugins_api_evdev_global` for better readability,
+   e.g. ``device:enable_evdev_usage(evdev.REL_X)``.
+   This function must not be used for ``ABS_*`` events, use ``set_absinfo()``
+   instead.
+
+   Once a usage is enabled, events for that usage may be added to a device's
+   frame.
+
+   If the device has since been discarded by libinput, this function does nothing.
+
+.. function:: EvdevDevice:disable_evdev_usage(usage)
+
+   Disable the given :ref:`evdev usage <plugins_api_evdev_usage>` for this device.
+   Use :ref:`plugins_api_evdev_global` for better readability,
+   e.g. ``device:disable_evdev_usage(evdev.REL_X)``.
+
+   Once a usage is disabled, events for that usage are discarded from any
+   device frame.
+
+   If the device has since been discarded by libinput, this function does nothing.
+
+.. function:: EvdevDevice:set_absinfo(usage, absinfo)
+
+   Set the absolute axis information for the given :ref:`evdev usage <plugins_api_evdev_usage>`
+   and enable it if it does not yet exist on the device. The ``absinfo`` argument is a table
+   containing zero or more of the following keys: ``minimum``, ``maximum``, ``fuzz``,
+   ``flat``, ``resolution``. Any missing key defaults the corresponding
+   value from the device if the device already has this event usage or zero otherwise.
+   For example, the following code changes the resolution but leaves everything
+   else as-is:
+
+   .. code-block:: lua
+
+      local absinfo = {
+         resolution = 40,
+      }
+      device:set_absinfo(evdev.ABS_X, absinfo)
+      device:set_absinfo(evdev.ABS_Y, absinfo)
+
+   Use :ref:`plugins_api_evdev_global` for better readability as shown in the
+   example above.
+
+   If the device has since been discarded by libinput, this function does nothing.
+
+   .. note:: Overriding the absinfo values often indicates buggy firmware. This should
+             typically be fixed with an entry in the
+             `60-evdev.hwdb <https://github.com/systemd/systemd/blob/main/hwdb.d/60-evdev.hwdb>`_
+             or :ref:`device-quirks` instead of a plugin so all users of that
+             device can benefit from the fix.
+
+.. function:: EvdevDevice:connect(name, function)
+
+   Set the callback to the given event name. Only one callback
+   may be set for an event name at any time, subsequent callbacks
+   will overwrite any earlier callbacks for the same name.
+
+   If the device has since been discarded by libinput, this function does nothing.
+
+   Version 1 of the plugin API supports the following events and callback arguments:
+
+   - ``"evdev-frame"``: A new :ref:`evdev frame <plugins_api_evdev_frame>` has
+     started for this device. If the callback returns a value other than
+     ``nil``, that value is the frame with any modified events.
+     An empty frame (``{}``) causes libinput to drop the current event frame.
+
+     .. code-block:: lua
+
+        device:connect("evdev-frame", function (device, frame, timestamp)
+            -- change any event into a movement left by 1 pixel
+            move_left = {
+                  { usage = evdev.REL_X, value = -1, },
+            }
+            return move_left
+        end
+
+     The timestamp of an event frame is in microseconds in ``CLOCK_MONOTONIC``, see
+     ``libinput:now()`` for details.
+
+     For performance reasons plugins that do not modify the event frame should
+     return ``nil`` (or nothing) instead of the event frame that was passed
+     as argument.
+
+   - ``"device-removed"``: This device was removed by libinput. This may happen
+     without the device ever becoming a libinput device as seen by libinput's
+     public API (e.g. if the device does not meet the requirements to be
+     added). Once this callback is invoked, the plugin should remove any
+     references to this device and stop using it.
+
+     .. code-block:: lua
+
+      device:connect("device-removed", function (device) ... end)
+
+     Functions to query the device's capabilities (e.g. ``usages()``) will
+     return an empty table.
+
+.. function:: EvdevDevice:disconnect(name)
+
+   Disconnect the existing callback (if any) for the given event name. See
+   ``EvdevDevice:connect()`` for a list of supported names.
+
+.. function:: EvdevDevice:prepend_frame(frame)
+
+   Prepend an :ref:`evdev frame <plugins_api_evdev_frame>` for this device
+   **before** the current frame (if any). The **next** plugin will see the
+   prepended frame first followed by the current frame.
+
+   This function can only be called from within a device's ``"evdev-frame"``
+   handler or from within the plugin's timer callback function.
+
+   For example, to change a single event into a drag, prepend a button
+   down and append a button up before each event:
+
+   .. code:: lua
+
+      function frame_handler(device, frame, timestamp)
+          device:prepend_frame({
+              { usage = evdev.BTN_LEFT, value = 1}
+          })
+          device:append_frame({
+              { usage = evdev.BTN_LEFT, value = 0}
+          })
+          return nil  -- return the current frame unmodified
+
+          -- The next plugin sees the event sequence:
+          --    button down, frame, button up
+      end
+
+   If called from within the plugin's timer there is no current frame and this
+   function is identical to ``append_frame()``.
+
+.. function:: EvdevDevice:append_frame(frame)
+
+   Appends an :ref:`evdev frame <plugins_api_evdev_frame>` for this device
+   **after** the current frame (if any). This function can only be called from
+   within a device's ``"evdev-frame"`` handler or from within the plugin's timer
+   callback function.
+
+   If called from within the plugin's timer there is no current frame and this
+   function is identical to ``prepend_frame()``.
+
+   See ``prepend_frame()`` for more details.
+
+.. function:: EvdevDevice:disable_feature(feature_name)
+
+   Disable the given libinput-internal feature for this device. This should be used
+   by plugins that replace that feature with a custom implementation for this device.
+
+   libinput may have multiple internal implementations for any given feature, disabling
+   it via this API disables any and all of those implementations, causing the feature to
+   no longer work at all. It is up to the plugin implementation to re-implement that
+   feature to match the user's expectation.
+
+   Version 1 of the plugin API supports the following features:
+
+   - ``"button-debouncing"``: see :ref:`button_debouncing`
+   - ``"touchpad-hysteresis"``: see :ref:`touchpad_jitter`
+   - ``"touchpad-jump-detection"``: see :ref:`touchpad_jumping_cursor`
+   - ``"touchpad-palm-detection"``: see :ref:`palm_detection`
+   - ``"wheel-debouncing"``: some high-resolution mouse wheel movements inside libinput
+     are delayed and/or modified

doc/user/meson.build

@@ -0,0 +1,224 @@
+# Sphinx build
+sphinx = find_program('sphinx-build-3', 'sphinx-build', required : false)
+if not sphinx.found()
+	error('Program "sphinx-build" not found or not executable. Try building with -Ddocumentation=false')
+endif
+
+yq = find_program('yq', required : false)
+if not yq.found()
+	warning('Program "yq" not found or not executable. Dependency list will not be built.')
+endif
+
+sphinx_config = configuration_data()
+sphinx_config.set('PROJECT_NAME', meson.project_name())
+sphinx_config.set('PROJECT_VERSION', meson.project_version())
+sphinx_config.set('BUILDDIR', meson.current_build_dir())
+sphinx_config.set('HTTP_DOC_LINK', doc_url)
+
+git_version_page = vcs_tag(command : ['git', 'log', '-1', '--format=%H'],
+			   fallback : 'unknown',
+			   input : 'git_version.py.in',
+			   output : 'git_version.py',
+			   replace_string: '__GIT_VERSION__')
+
+sphinx_conf_py = configure_file(input : 'conf.py.in',
+				output : 'conf.py',
+				configuration : sphinx_config)
+
+# 404 replacements for old URLs
+# The switch to sphinx caused a few pages to be renamed, sphinx uses
+# filename.html whereas doxygen used whatever the @page foo was. So old docs
+# *mostly* used underscores, now we're consistent with dashes.
+# We can't use htaccess on the server, so let's auto-generate a 404 list
+# with a basic page telling users that the link has moved. This can be
+# removed in a few months, towards the end of 2018.
+#
+# File list is: [current-sphinx-input-file, old-generated-page]
+# If they're the same they'll be ignored.
+src_404s = [
+	[ 'absolute-axes.rst', 'absolute_axes.html'],
+	[ 'absolute-coordinate-ranges.rst', 'absolute_coordinate_ranges.html'],
+	[ 'architecture.rst', 'architecture.html'],
+	[ 'building.rst', 'building_libinput.html'],
+	[ 'button-debouncing.rst', 'button_debouncing.html'],
+	[ 'clickpad-softbuttons.rst', 'clickpad_softbuttons.html'],
+	[ 'configuration.rst', 'config_options.html'],
+	[ 'contributing.rst', 'contributing.html'],
+	[ 'development.rst', 'development.html'],
+	[ 'device-configuration-via-udev.rst', 'udev_config.html'],
+	[ 'device-quirks.rst', 'device-quirks.html'],
+	[ 'faqs.rst', 'faq.html'],
+	[ 'features.rst', 'features.html'],
+	[ 'gestures.rst', 'gestures.html'],
+	[ 'incorrectly-enabled-hires.rst', 'incorrectly-enabled-hires.html'],
+	[ 'middle-button-emulation.rst', 'middle_button_emulation.html'],
+	[ 'normalization-of-relative-motion.rst', 'motion_normalization.html'],
+	[ 'palm-detection.rst', 'palm_detection.html'],
+	[ 'pointer-acceleration.rst', 'pointer-acceleration.html'],
+	[ 'reporting-bugs.rst', 'reporting_bugs.html'],
+	[ 'scrolling.rst', 'scrolling.html'],
+	[ 'seats.rst', 'seats.html'],
+	[ 'switches.rst', 'switches.html'],
+	[ 't440-support.rst', 't440_support.html'],
+	[ 'tablet-support.rst', 'tablet-support.html'],
+	[ 'tapping.rst', 'tapping.html'],
+	[ 'test-suite.rst', 'test-suite.html'],
+	[ 'timestamps.rst', 'timestamps.html'],
+	[ 'tools.rst', 'tools.html'],
+	[ 'touchpad-jitter.rst', 'touchpad_jitter.html'],
+	[ 'touchpad-jumping-cursors.rst', 'touchpad_jumping_cursor.html'],
+	[ 'touchpad-pressure.rst', 'touchpad_pressure.html'],
+	[ 'touchpads.rst', 'touchpads.html'],
+	[ 'trackpoints.rst', 'trackpoints.html'],
+	[ 'troubleshooting.rst', 'troubleshooting.html'],
+	[ 'what-is-libinput.rst', 'what_is_libinput.html'],
+]
+
+dst_404s = []
+foreach s404 : src_404s
+	target = s404[0]
+	oldpage = s404[1]
+	tname = target.split('.rst')[0]
+	oname = oldpage.split('.html')[0]
+
+	if tname != oname
+		config_404 = configuration_data()
+		config_404.set('TARGET', '@0@.html'.format(tname))
+		c = configure_file(input : '404.rst',
+				   output : '@0@.rst'.format(oname),
+				   configuration : config_404)
+		dst_404s += [c]
+	endif
+endforeach
+
+src_rst = files(
+	# dot drawings
+	'dot/seats-sketch.gv',
+	'dot/seats-sketch-libinput.gv',
+	'dot/libinput-contexts.gv',
+	'dot/libinput-stack-wayland.gv',
+	'dot/libinput-stack-xorg.gv',
+	'dot/libinput-stack-gnome.gv',
+	'dot/evemu.gv',
+	'dot/libinput-record.gv',
+	'dot/plugin-stack.gv',
+	# svgs
+	'svg/button-debouncing-wave-diagram.svg',
+	'svg/button-scrolling.svg',
+	'svg/clickfinger.svg',
+	'svg/clickfinger-distance.svg',
+	'svg/edge-scrolling.svg',
+	'svg/gesture-2fg-ambiguity.svg',
+	'svg/palm-detection.svg',
+	'svg/pinch-gestures.svg',
+	'svg/pinch-gestures-softbuttons.svg',
+	'svg/ptraccel-custom.svg',
+	'svg/ptraccel-linear.svg',
+	'svg/ptraccel-low-dpi.svg',
+	'svg/ptraccel-touchpad.svg',
+	'svg/ptraccel-trackpoint.svg',
+	'svg/software-buttons.svg',
+	'svg/software-buttons-conditions.svg',
+	'svg/software-buttons-thumbpress.svg',
+	'svg/software-buttons-visualized.svg',
+	'svg/swipe-gestures.svg',
+	'svg/tablet-area.svg',
+	'svg/tablet-axes.svg',
+	'svg/tablet-cintiq24hd-modes.svg',
+	'svg/tablet-eraser-invert.svg',
+	'svg/tablet-eraser-button.svg',
+	'svg/tablet-interfaces.svg',
+	'svg/tablet-intuos-modes.svg',
+	'svg/tablet-left-handed.svg',
+	'svg/tablet-out-of-bounds.svg',
+	'svg/tablet.svg',
+	'svg/tap-n-drag.svg',
+	'svg/thumb-detection.svg',
+	'svg/top-software-buttons.svg',
+	'svg/touchscreen-gestures.svg',
+	'svg/trackpoint-delta-illustration.svg',
+	'svg/twofinger-scrolling.svg',
+	# rst files
+	'absolute-axes.rst',
+	'absolute-coordinate-ranges.rst',
+	'architecture.rst',
+	'building.rst',
+	'button-debouncing.rst',
+	'clickpad-softbuttons.rst',
+	'clickpad-with-right-button.rst',
+	'contributing.rst',
+	'device-configuration-via-udev.rst',
+	'device-quirks.rst',
+	'drag-3fg.rst',
+	'faqs.rst',
+	'gestures.rst',
+	'incorrectly-enabled-hires.rst',
+	'ignoring-devices.rst',
+	'middle-button-emulation.rst',
+	'normalization-of-relative-motion.rst',
+	'palm-detection.rst',
+	'lua-plugins.rst',
+	'pointer-acceleration.rst',
+	'reporting-bugs.rst',
+	'scrolling.rst',
+	'seats.rst',
+	'switches.rst',
+	't440-support.rst',
+	'tablet-support.rst',
+	'tapping.rst',
+	'test-suite.rst',
+	'timestamps.rst',
+	'tablet-debugging.rst',
+	'tools.rst',
+	'touchpad-jumping-cursors.rst',
+	'touchpad-pressure.rst',
+	'touchpad-pressure-debugging.rst',
+	'touchpad-jitter.rst',
+	'touchpad-thumb-detection.rst',
+	'touchpads.rst',
+	'trackpoints.rst',
+	'trackpoint-configuration.rst',
+	'what-is-libinput.rst',
+	'wheel-api.rst',
+	'features.rst',
+	'development.rst',
+	'troubleshooting.rst',
+	'configuration.rst',
+)
+
+src_sphinx = []
+foreach f : src_rst
+	sf = configure_file(input: f,
+			    output: '@PLAINNAME@',
+			    copy : true)
+	src_sphinx += [ sf ]
+endforeach
+
+configure_file(input: 'index.rst',
+	       output: 'index.rst',
+	       configuration: sphinx_config)
+
+dependencies_config = configuration_data()
+if yq.found()
+	distributions = ['fedora', 'ubuntu', 'debian', 'arch', 'alpine']
+	foreach distro : distributions
+		yq_filter = '.distributions[] | select(.name == "@0@") | .packages | join(" ")'.format(distro)
+		deps = run_command(yq, '-r', yq_filter,
+				   dir_gitlab_ci / 'config.yml',
+				   check: true).stdout()
+		dependencies_config.set('@0@_PACKAGES'.format(distro.to_upper()), deps)
+endforeach
+endif
+configure_file(input: 'dependencies.rst',
+	       output: 'dependencies.rst',
+	       configuration: dependencies_config)
+
+# do not use -j, it breaks on Ubuntu
+sphinx_output_dir = 'Documentation'
+custom_target('sphinx',
+	      input : [ sphinx_conf_py, git_version_page ] + src_sphinx + dst_404s,
+	      output : [ sphinx_output_dir ],
+	      command : [ sphinx, '-q', '-b', 'html',
+			  '-d', meson.current_build_dir() / 'doctrees',
+			  meson.current_build_dir(), sphinx_output_dir],
+	      build_by_default : true)

doc/user/middle-button-emulation.rst

@@ -1,5 +1,8 @@
-/**
-@page middle_button_emulation Middle button emulation
+.. _middle_button_emulation:
+
+==============================================================================
+Middle button emulation
+==============================================================================
 
 Middle button emulation provides users with the ability to generate a middle
 click even when the device does not have a physical middle button available.
@@ -16,7 +19,7 @@ appropriate to the physical device.
 
 The middle button emulation behavior when combined with other device
 buttons, including a physical middle button is device-dependent.
-For example, @ref clickpad_softbuttons provides a middle button area when
+For example, :ref:`clickpad_softbuttons` provides a middle button area when
 middle button emulation is disabled. That middle button area disappears
 when middle button emulation is enabled - a middle click can then only be
 triggered by a simultaneous left + right click.
@@ -26,9 +29,7 @@ enabling/disabling that emulation. Likewise, some devices may allow middle
 button emulation but have it disabled by default. This is the case for most
 mouse-like devices where a middle button is detected.
 
-libinput provides libinput_device_config_middle_emulation_set_enabled() to
-enable or disable middle button emulation. See @ref faq_configure_wayland
-and @ref faq_configure_xorg for info on how to enable or disable middle
+libinput provides **libinput_device_config_middle_emulation_set_enabled()** to
+enable or disable middle button emulation. See :ref:`faq_configure_wayland`
+and :ref:`faq_configure_xorg` for info on how to enable or disable middle
 button emulation in the Wayland compositor or the X stack.
- 
-*/

doc/user/normalization-of-relative-motion.rst

@@ -1,5 +1,8 @@
-/**
-@page motion_normalization Normalization of relative motion
+.. _motion_normalization:
+
+==============================================================================
+Normalization of relative motion
+==============================================================================
 
 Most relative input devices generate input in so-called "mickeys". A
 mickey is in device-specific units that depend on the resolution
@@ -24,11 +27,20 @@ libinput applies a dpi-dependent acceleration function. At low speeds, a
 movement speed increases, acceleration is applied - at high speeds a low-dpi
 device will roughly feel the same as a higher-dpi mouse.
 
+The reason for the normalization is convenience: a caller can assume that a
+delta of 1 should result in a movement of 1 pixel on a traditional
+(low-dpi) screen. On screens with high resolutions, the caller must scale
+according to the UI scale factors.
+
 This normalization only applies to accelerated coordinates, unaccelerated
 coordinates are left in device-units. It is up to the caller to interpret
 those coordinates correctly.
 
-@section motion_normalization_touchpad Normalization of touchpad coordinates
+.. _motion_normalization_touchpad:
+
+------------------------------------------------------------------------------
+Normalization of touchpad coordinates
+------------------------------------------------------------------------------
 
 Touchpads may have a different resolution for the horizontal and vertical
 axis. Interpreting coordinates from the touchpad without taking resolution
@@ -36,49 +48,50 @@ into account results in uneven motion.
 
 libinput scales unaccelerated touchpad motion to the resolution of the
 touchpad's x axis, i.e. the unaccelerated value for the y axis is:
-     y = (x / resolution_x) * resolution_y
+``y = (x / resolution_x) * resolution_y``.
 
-@section motion_normalization_tablet Normalization of tablet coordinates
+.. _motion_normalization_tablet:
 
-See @ref tablet-relative-motion
+------------------------------------------------------------------------------
+Normalization of tablet coordinates
+------------------------------------------------------------------------------
 
-@section motion_normalization_customization Setting custom DPI settings
+See :ref:`tablet-relative-motion`
+
+.. _motion_normalization_customization:
+
+------------------------------------------------------------------------------
+Setting custom DPI settings
+------------------------------------------------------------------------------
 
 Devices usually do not advertise their resolution and libinput relies on
-the udev property <b>MOUSE_DPI</b> for this information. This property is usually
-set via the <a
-href="http://cgit.freedesktop.org/systemd/systemd/tree/hwdb/70-mouse.hwdb">udev hwdb</a>.
-The "mouse-dpi-tool" utility provided by <a
-href="http://freedesktop.org/wiki/Software/libevdev/">libevdev</a> should be
+the udev property **MOUSE_DPI** for this information. This property is usually
+set via the
+`udev hwdb <http://cgit.freedesktop.org/systemd/systemd/tree/hwdb/70-mouse.hwdb>`_.
+The ``mouse-dpi-tool`` utility provided by
+`libevdev <https://freedesktop.org/wiki/Software/libevdev/>`_ should be
 used to measure a device's resolution.
 
-The format of the property for single-resolution mice is:
-@code
-     MOUSE_DPI=resolution@frequency
-@endcode
+The format of the property for single-resolution mice is: ::
+
+          MOUSE_DPI=resolution@frequency
 
 The resolution is in dots per inch, the frequency in Hz.
 The format of the property for multi-resolution mice may list multiple
-resolutions and frequencies:
-@code
-     MOUSE_DPI=r1@f1 *r2@f2 r3@f3
-@endcode
+resolutions and frequencies: ::
+
+          MOUSE_DPI=r1@f1 *r2@f2 r3@f3
 
 The default frequency must be pre-fixed with an asterisk.
 
-For example, these two properties are valid:
-@code
-     MOUSE_DPI=800@125
-     MOUSE_DPI=400@125 800@125 *1000@500 5500@500
-@endcode
+For example, these two properties are valid: ::
 
-The behavior for a malformed property is undefined.
+          MOUSE_DPI=800@125
+          MOUSE_DPI=400@125 800@125 *1000@500 5500@500
 
-If the property is unset, libinput assumes the resolution is 1000dpi.
+The behavior for a malformed property is undefined. If the property is
+unset, libinput assumes the resolution is 1000dpi.
 
 Note that HW does not usually provide information about run-time
 resolution changes, libinput will thus not detect when a resolution
 changes to the non-default value.
-
-*/
-

doc/user/palm-detection.rst

@@ -1,5 +1,8 @@
-/**
-@page palm_detection Palm detection
+.. _palm_detection:
+
+==============================================================================
+Palm detection
+==============================================================================
 
 Palm detection tries to identify accidental touches while typing, while
 using the trackpoint and/or during general use of the touchpad area.
@@ -18,25 +21,34 @@ touchpads are less affected by palm touches.
 libinput has multiple ways of detecting a palm, each of which depends on
 hardware-specific capabilities.
 
-- @ref palm_tool
-- @ref palm_pressure
-- @ref palm_touch_size
-- @ref palm_exclusion_zones
-- @ref trackpoint-disabling
-- @ref disable-while-typing
-- @ref stylus-touch-arbitration
+- :ref:`palm_tool`
+- :ref:`palm_pressure`
+- :ref:`palm_touch_size`
+- :ref:`palm_exclusion_zones`
+- :ref:`trackpoint-disabling`
+- :ref:`disable-while-typing`
+- :ref:`disable-while-trackpointing`
+- :ref:`stylus-touch-arbitration`
 
 Palm detection is always enabled, with the exception of
 disable-while-typing.
 
-@section palm_tool Palm detection based on firmware labelling
+.. _palm_tool:
+
+------------------------------------------------------------------------------
+Palm detection based on firmware labelling
+------------------------------------------------------------------------------
 
 Some devices provide palm detection in the firmware, forwarded by the kernel
-as the ```EV_ABS/ABS_MT_TOOL``` axis with a value of ```MT_TOOL_PALM```
+as the ``EV_ABS/ABS_MT_TOOL`` axis with a value of ``MT_TOOL_PALM``
 (whenever a palm is detected). libinput honors that value and switches that
 touch to a palm.
 
-@section palm_pressure Palm detection based on pressure
+.. _palm_pressure:
+
+------------------------------------------------------------------------------
+Palm detection based on pressure
+------------------------------------------------------------------------------
 
 The simplest form of palm detection labels a touch as palm when the pressure
 value goes above a certain threshold. This threshold is usually high enough
@@ -46,19 +58,27 @@ the threshold again. This ensures that a palm remains a palm even when the
 pressure changes as the user is typing.
 
 For some information on how to detect pressure on a touch and debug the
-pressure ranges, see @ref touchpad_pressure.
+pressure ranges, see :ref:`touchpad_pressure`.
 
-@section palm_touch_size Palm detection based on touch size
+.. _palm_touch_size:
 
-On touchads that support the `ABS_MT_TOUCH_MAJOR` axes, libinput can perform
+------------------------------------------------------------------------------
+Palm detection based on touch size
+------------------------------------------------------------------------------
+
+On touchpads that support the ``ABS_MT_TOUCH_MAJOR`` axes, libinput can perform
 palm detection based on the size of the touch ellipse. This works similar to
 the pressure-based palm detection in that a touch is labelled as palm when
 it exceeds the (device-specific) touch size threshold.
 
 For some information on how to detect the size of a touch and debug the
-touch size ranges, see @ref touchpad_pressure.
+touch size ranges, see :ref:`touchpad_pressure`.
 
-@section palm_exclusion_zones Palm exclusion zones
+.. _palm_exclusion_zones:
+
+------------------------------------------------------------------------------
+Palm exclusion zones
+------------------------------------------------------------------------------
 
 libinput enables palm detection on the left, right and top edges of the
 touchpad. Two exclusion zones are defined  on the left and right edge of the
@@ -72,9 +92,8 @@ Another exclusion zone is defined on the top edge of the touchpad. As with
 the edge zones, libinput detects vertical movements out of the edge zone and
 avoids palm detection on such touch sequences.
 
-Each side edge exclusion zone is divided into a top part and a bottom part.
-A touch starting in the top part of the exclusion zone does not trigger a
-tap (see @ref tapping).
+A touch starting in the exclusion zone does not trigger a tap (see
+:ref:`tapping`).
 
 In the diagram below, the exclusion zones are painted red.
 Touch 'A' starts inside the exclusion zone and moves
@@ -84,17 +103,20 @@ despite moving out of the exclusion zone.
 Touch 'B' starts inside the exclusion zone but moves horizontally out of the
 zone. It is considered a valid touch and controls the cursor.
 
-Touch 'C' occurs in the top part of the exclusion zone. Despite being a
-tapping motion, it does not generate an emulated button event. Touch 'D'
-likewise occurs within the exclusion zone but in the bottom half. libinput
-will generate a button event for this touch.
+Touch 'C' occurs in the exclusion zone. Despite being a tapping motion, it does
+not generate an emulated button event.
 
-@image html palm-detection.svg
+.. figure:: palm-detection.svg
+    :align: center
 
-@section trackpoint-disabling Palm detection during trackpoint use
+.. _trackpoint-disabling:
 
-If a device provides a <a
-href="http://en.wikipedia.org/wiki/Pointing_stick">trackpoint</a>, it is
+------------------------------------------------------------------------------
+Palm detection during trackpoint use
+------------------------------------------------------------------------------
+
+If a device provides a
+`trackpoint <http://en.wikipedia.org/wiki/Pointing_stick>`_, it is
 usually located above the touchpad. This increases the likelihood of
 accidental touches whenever the trackpoint is used.
 
@@ -103,36 +125,64 @@ certain timeout until after trackpoint activity stops. Touches generated
 during this timeout will not move the pointer, and touches started during
 this timeout will likewise not move the pointer (allowing for a user to rest
 the palm on the touchpad while using the trackstick).
-If the touchpad is disabled, the @ref t440_support "top software buttons"
+If the touchpad is disabled, the :ref:`top software buttons <t440_support>`
 remain enabled.
 
-@section disable-while-typing Disable-while-typing
+.. _disable-while-typing:
+
+------------------------------------------------------------------------------
+Disable-while-typing
+------------------------------------------------------------------------------
 
 libinput automatically disables the touchpad for a timeout after a key
 press, a feature traditionally referred to as "disable while typing" and
 previously available through the
-[syndaemon(1)](http://linux.die.net/man/1/syndaemon) command. libinput does
+`syndaemon(1) <http://linux.die.net/man/1/syndaemon>`_ command. libinput does
 not require an external command and the feature is currently enabled for all
 touchpads but will be reduced in the future to only apply to touchpads where
 finger width or pressure data is unreliable.
 
 Notable behaviors of libinput's disable-while-typing feature:
+
 - Two different timeouts are used, after a single key press the timeout is
   short to ensure responsiveness. After multiple key events, the timeout is
   longer to avoid accidental pointer manipulation while typing.
-- Some keys do not trigger the timeout, specifically some modifier keys 
+- Some keys do not trigger the timeout, specifically some modifier keys
   (Ctrl, Alt, Shift, and Fn). Actions such as Ctrl + click thus stay
   responsive.
 - Touches started while typing do not control the cursor even after typing
   has stopped, it is thus possible to rest the palm on the touchpad while
   typing.
 - Physical buttons work even while the touchpad is disabled. This includes
-  @ref t440_support "software-emulated buttons".
+  :ref:`software-emulated buttons <t440_support>`.
+- libinput pairs touchpads and keyboards for the disable-while-typing
+  feature. In the most common case, the internal touchpad is paired only
+  with the internal keyboard. Typing on an external keyboard will thus not
+  disable the touchpad. Some devices require a :ref:`quirk <device-quirks>`
+  to be correctly paired.
 
 Disable-while-typing can be enabled and disabled by calling
-libinput_device_config_dwt_set_enabled().
+**libinput_device_config_dwt_set_enabled()**.
 
-@section stylus-touch-arbitration Stylus-touch arbitration
+.. _disable-while-trackpointing:
+
+------------------------------------------------------------------------------
+Disable-while-trackpointing
+------------------------------------------------------------------------------
+
+libinput automatically disables the touchpad for a timeout after the trackpoint
+is moved, a feature referred to as "disable while trackpointing". libinput does
+not require an external command and the feature is currently enabled for all
+touchpads.
+
+Disable-while-trackpointing can be enabled and disabled by calling
+**libinput_device_config_dwtp_set_enabled()**.
+
+.. _stylus-touch-arbitration:
+
+------------------------------------------------------------------------------
+Stylus-touch arbitration
+------------------------------------------------------------------------------
 
 A special case of palm detection is touch arbitration on devices that
 support styli. When interacting with a stylus on the screen, parts of the
@@ -140,35 +190,38 @@ hand may touch the surface and trigger touches. As the user is currently
 interacting with the stylus, these touches would interfer with the correct
 working of the stylus.
 
-libinput employs a method similar to @ref disable-while-typing to detect
+libinput employs a method similar to :ref:`disable-while-typing` to detect
 these touches and disables the touchpad accordingly.
 
-@section thumb-detection Thumb detection
+.. _thumb-detection:
+
+------------------------------------------------------------------------------
+Thumb detection
+------------------------------------------------------------------------------
 
 Many users rest their thumb on the touchpad while using the index finger to
 move the finger around. For clicks, often the thumb is used rather than the
 finger. The thumb should otherwise be ignored as a touch, i.e. it should not
-count towards @ref clickfinger and it should not cause a single-finger
-movement to trigger @ref twofinger_scrolling.
+count towards :ref:`clickfinger` and it should not cause a single-finger
+movement to trigger :ref:`twofinger_scrolling`.
 
 libinput uses two triggers for thumb detection: pressure and
 location. A touch exceeding a pressure threshold is considered a thumb if it
 is within the thumb detection zone.
 
-@note "Pressure" on touchpads is synonymous with "contact area", a large
-touch surface area has a higher pressure and thus hints at a thumb or palm
-touching the surface.
+.. note:: "Pressure" on touchpads is synonymous with "contact area." A large touch
+	surface area has a higher pressure and thus hints at a thumb or palm
+	touching the surface.
 
 Pressure readings are unreliable at the far bottom of the touchpad as a
 thumb hanging mostly off the touchpad will have a small surface area.
 libinput has a definitive thumb zone where any touch is considered a resting
 thumb.
 
-@image html thumb-detection.svg
+.. figure:: thumb-detection.svg
+    :align: center
 
 The picture above shows the two detection areas. In the larger (light red)
 area, a touch is labelled as thumb when it exceeds a device-specific
 pressure threshold. In the lower (dark red) area, a touch is labelled as
 thumb if it remains in that area for a time without moving outside.
-
-*/

doc/user/pointer-acceleration.rst

@@ -0,0 +1,296 @@
+.. _pointer-acceleration:
+
+==============================================================================
+ Pointer acceleration
+==============================================================================
+
+libinput uses device-specific pointer acceleration methods, with the default
+being the :ref:`ptraccel-linear`. The methods share common properties, such as
+:ref:`ptraccel-velocity`.
+
+This page explains the high-level concepts used in the code. It aims to
+provide an overview for developers and is not necessarily useful for
+users.
+
+.. _ptraccel-profiles:
+
+------------------------------------------------------------------------------
+Pointer acceleration profiles
+------------------------------------------------------------------------------
+
+The profile decides the general method of pointer acceleration.
+libinput currently supports three profiles: **"adaptive"**, **"flat"** and
+**"custom"**.
+
+- The **adaptive** profile is the default profile for all devices and takes the
+  current speed of the device into account when deciding on acceleration.
+- The **flat** profile is simply a constant factor applied to all device deltas,
+  regardless of the speed of motion (see :ref:`ptraccel-profile-flat`).
+- The **custom** profile allows the user to define a custom acceleration
+  function, giving full control over accelerations behavior at different speed
+  (see :ref:`ptraccel-profile-custom`).
+
+Most of this document describes the adaptive pointer acceleration.
+
+.. _ptraccel-velocity:
+
+------------------------------------------------------------------------------
+Velocity calculation
+------------------------------------------------------------------------------
+
+The device's speed of movement is measured across multiple input events
+through so-called "trackers". Each event prepends a the tracker item, each
+subsequent tracker contains the delta of that item to the current position,
+the timestamp of the event that created it and the cardinal direction of the
+movement at the time. If a device moves into the same direction, the
+velocity is calculated across multiple trackers. For example, if a device
+moves steadily for 10 events to the left, the velocity is calculated across
+all 10 events.
+
+Whenever the movement changes direction or significantly changes speed, the
+velocity is calculated from the direction/speed change only. For example, if
+a device moves steadily for 8 events to the left and then 2 events to the
+right, the velocity is only that of the last 2 events.
+
+An extra time limit prevents events that are too old to factor into the
+velocity calculation. For example, if a device moves steadily for 5 events
+to the left, then pauses, then moves again for 5 events to the left, only
+the last 5 events are used for velocity calculation.
+
+The velocity is then used to calculate the acceleration factor
+
+.. _ptraccel-factor:
+
+------------------------------------------------------------------------------
+Acceleration factor
+------------------------------------------------------------------------------
+
+The acceleration factor is the final outcome of the pointer acceleration
+calculations. It is a unitless factor that is applied to the current delta,
+a factor of 2 doubles the delta (i.e. speeds up the movement), a factor of
+less than 1 reduces the delta (i.e. slows the movement).
+
+Any factor less than 1 requires the user to move the device further to move
+the visible pointer. This is called deceleration and enables high precision
+target selection through subpixel movements. libinput's current maximum
+deceleration factor is 0.3 (i.e. slow down to 30% of the pointer speed).
+
+A factor higher than 1 moves the pointer further than the physical device
+moves. This is acceleration and allows a user to cross the screen quickly
+but effectively skips pixels. libinput's current maximum acceleration factor
+is 3.5.
+
+.. _ptraccel-linear:
+
+------------------------------------------------------------------------------
+Linear pointer acceleration
+------------------------------------------------------------------------------
+
+The linear pointer acceleration method is the default for most pointer
+devices. It provides deceleration at very slow movements, a 1:1 mapping for
+regular movements and a linear increase to the maximum acceleration factor
+for fast movements.
+
+Linear pointer acceleration applies to devices with above 1000dpi resolution
+and after :ref:`motion_normalization` is applied.
+
+.. figure:: ptraccel-linear.svg
+    :align: center
+
+    Linear pointer acceleration
+
+The image above shows the linear pointer acceleration settings at various
+speeds. The line for 0.0 is the default acceleration curve, speed settings
+above 0.0 accelerate sooner, faster and to a higher maximum acceleration.
+Speed settings below 0 delay when acceleration kicks in, how soon the
+maximum acceleration is reached and the maximum acceleration factor.
+
+Extremely low speed settings provide no acceleration and additionally
+decelerate all movement by a constant factor.
+
+.. _ptraccel-low-dpi:
+
+------------------------------------------------------------------------------
+Pointer acceleration for low-dpi devices
+------------------------------------------------------------------------------
+
+Low-dpi devices are those with a physical resolution of less than 1000 dots
+per inch (dpi). The pointer acceleration is adjusted to provide roughly the
+same feel for all devices at normal to high speeds. At slow speeds, the
+pointer acceleration works on device-units rather than normalized
+coordinates (see :ref:`motion_normalization`).
+
+.. figure:: ptraccel-low-dpi.svg
+    :align: center
+
+    Pointer acceleration for low-dpi devices
+
+The image above shows the default pointer acceleration curve for a speed of
+0.0 at different DPI settings. A device with low DPI has the acceleration
+applied sooner and with a stronger acceleration factor.
+
+.. _ptraccel-touchpad:
+
+------------------------------------------------------------------------------
+Pointer acceleration on touchpads
+------------------------------------------------------------------------------
+
+Touchpad pointer acceleration uses the same approach as the
+:ref:`ptraccel-linear` profile, with a constant deceleration factor applied. The
+user expectation of how much a pointer should move in response to finger
+movement is different to that of a mouse device, hence the constant
+deceleration factor.
+
+.. figure:: ptraccel-touchpad.svg
+    :align: center
+
+    Pointer acceleration curve for touchpads
+
+The image above shows the touchpad acceleration profile in comparison to the
+:ref:`ptraccel-linear`. The shape of the curve is identical but vertically squashed.
+
+.. _ptraccel-trackpoint:
+
+------------------------------------------------------------------------------
+Pointer acceleration on trackpoints
+------------------------------------------------------------------------------
+
+The main difference between trackpoint hardware and mice or touchpads is
+that trackpoint speed is a function of pressure rather than moving speed.
+But trackpoint hardware is quite varied in how it reacts to user pressure
+and unlike other devices it cannot easily be normalized for physical
+properties. Measuring pressure objectively across a variety of hardware is
+nontrivial. See :ref:`trackpoints` for more details.
+
+The deltas for trackpoints are converted units/ms but there is no common
+physical reference point for a unit. Thus, the same pressure on different
+trackpoints will generate different speeds and thus different acceleration
+behaviors. Additionally, some trackpoints provide the ability to adjust the
+sensitivity in hardware by modifying a sysfs file on the serio node. A
+higher sensitivity results in higher deltas, thus changing the definition of
+what is a unit again.
+
+libinput attempts to normalize unit data to the best of its abilities, see
+:ref:`trackpoint_multiplier`. Beyond this, it is not possible to have
+consistent behavior across different trackpoint devices.
+
+.. figure:: ptraccel-trackpoint.svg
+    :align: center
+
+    Pointer acceleration curves for trackpoints
+
+The image above shows the trackpoint acceleration profile for the speed in
+units/ms.
+
+.. _ptraccel-profile-flat:
+
+------------------------------------------------------------------------------
+The flat pointer acceleration profile
+------------------------------------------------------------------------------
+
+In a flat profile, the acceleration factor is constant regardless of the
+velocity of the pointer and each delta (dx, dy) results in an accelerated delta
+(dx * factor, dy * factor). This provides 1:1 movement between the device
+and the pointer on-screen.
+
+.. _ptraccel-tablet:
+
+------------------------------------------------------------------------------
+Pointer acceleration on tablets
+------------------------------------------------------------------------------
+
+Pointer acceleration for relative motion on tablet devices is a flat
+acceleration, with the speed setting slowing down or speeding up the pointer
+motion by a constant factor. Tablets do not allow for switchable profiles.
+
+.. _ptraccel-profile-custom:
+
+------------------------------------------------------------------------------
+The custom acceleration profile
+------------------------------------------------------------------------------
+
+libinput supports a user-defined custom acceleration profile, which can be
+adjusted for different movement types supported by a device. Movement types
+include pointer movement, scrolling, etc. but the set of supported
+movement types depends on the device.
+
+The custom pointer acceleration profile gives users full control over the
+acceleration behavior at different speeds. libinput exposes
+an acceleration function ``f(x)`` where the x axis is the device speed in
+device units per millisecond and the y axis is the pointer speed. By
+supplying the y axis values for this function, users can control the
+behavior of the device.
+
+The user should take into account the native device dpi and screen dpi in
+order to achieve the desired behavior/feel.
+
+The custom acceleration function is defined using ``n`` points which are spaced
+uniformly along the x axis, starting from 0 and continuing in constant steps.
+At least two points must be defined and there is an implementation-defined
+limit on how many points may be added.
+
+Thus the points defining the custom function are:
+``(0 * step, f[0]), (1 * step, f[1]), ..., ((n-1) * step, f[n-1])``
+where ``f`` is a list of ``n`` values defining the output velocity for each
+input velocity.
+The acceleration factor is defined by the ratio of the output velocity to the
+input velocity.
+When a velocity value does not lie exactly on those points, a linear
+interpolation of the two closest points will be calculated.
+When a velocity value is greater than the max point defined, a linear
+extrapolation of the two biggest points will be calculated.
+
+the calculation made by libinput: ::
+
+    input_delta = device delta units
+    delta_time = time in ms since last input_delta
+    input_speed = hypot(input_delta) / delta_time
+    output_speed = user_custom_function(input_speed)
+    acceleration_factor = output_speed / input_speed
+    output_delta = input_delta * acceleration_factor
+
+An example is the curve of ``0.0, 1.0`` with a step of ``1.0``. This curve
+is the equivalent of the flat acceleration profile with any input speed ``N``
+mapped to the same pointer speed ``N``. The curve ``1.0, 1.0`` neutralizes
+any input speed differences and results in a fixed pointer speed.
+
+Another example is the custom acceleration function ``x**2``,
+sampling the function at ``4`` points up to
+a maximum input speed of ``9`` will give us a custom function with
+a step of ``3`` and points ``[0.0, 9.0, 36.0, 81.0]``:
+
+.. figure:: ptraccel-custom.svg
+    :align: center
+
+More sampled points can be added to improve the accuracy of the user custom
+function.
+
+Supported Movement types:
+
++---------------+---------------------------------+----------------------+
+| Movement type | Uses                            | supported by         |
++===============+=================================+======================+
+| Fallback      | Catch-all default movement type | All devices          |
++---------------+---------------------------------+----------------------+
+| Motion        | Used for pointer motion         | All devices          |
++---------------+---------------------------------+----------------------+
+| Scroll        | Used for scroll movement        | Mouse, Touchpad      |
++---------------+---------------------------------+----------------------+
+
+If a user does not provide the fallback custom acceleration function, a
+flat acceleration function is used, i.e. no acceleration.
+
+The fallback acceleration may be used for different types of movements, it is
+strongly recommended that this acceleration function is a constant function.
+
+For example, a touchpad has multiple movement types: pointer
+movement, scroll movement, zoom movement (pinch), etc. As there is no separate
+movement type for zoom yet, zoom movement is accelerated using the Fallback
+acceleration function. Pointer movement is accelerated using the Motion
+acceleration function, and Scroll movement is accelerated using the Scroll
+acceleration function. If no Motion/Scroll acceleration function is set, the
+Fallback acceleration function is used.
+
+When using custom acceleration profile, any calls to set the speed have no
+effect on the behavior of the custom acceleration function, but any future calls to
+get the speed will reflect the requested speed setting.

doc/user/reporting-bugs.rst

@@ -0,0 +1,395 @@
+.. _reporting_bugs:
+
+==============================================================================
+Reporting bugs
+==============================================================================
+
+A new bug can be filed here:
+https://gitlab.freedesktop.org/libinput/libinput/issues/new
+
+.. hint:: libinput has lots of users but very few developers. It is in your
+	   own interest to follow the steps here precisely to ensure your bug can be
+	   dealt with efficiently.
+
+When reporting bugs against libinput, you will need:
+
+- a reliable :ref:`reproducer <reporting_bugs_reproducer>` for the bug
+- a :ref:`recording <libinput-record>` of the device while the bug is reproduced
+- device-specific information, see
+
+     - :ref:`reporting_bugs_touchpad`
+     - :ref:`reporting_bugs_mouse`
+     - :ref:`reporting_bugs_keyboard`
+     - :ref:`reporting_bugs_trackpoint`
+     - :ref:`reporting_bugs_other`
+
+- the :ref:`libinput version <reporting_bugs_version>` you are on.
+- the :ref:`configuration options <reporting_bugs_options>` you have set
+- a `gitlab account <https://gitlab.freedesktop.org/users/sign_in>`_
+
+Stay technical, on-topic, and keep the description concise.
+
+.. _reporting_bugs_version:
+
+------------------------------------------------------------------------------
+Obtaining the libinput version
+------------------------------------------------------------------------------
+
+If your libinput version is older than the current stable branch, please try
+the latest version. If you run a distribution-provided
+libinput, use the package manager to get the **full** package name and
+version of libinput, e.g.
+
+- ``rpm -q libinput``
+- ``dpkg -s libinput10``
+
+If you run a self-compiled version of libinput provide the git commit you
+have built or the tarball name.
+
+As a last resort, use ``libinput --version``
+
+.. _reporting_bugs_reproducer:
+
+------------------------------------------------------------------------------
+Reproducing bugs
+------------------------------------------------------------------------------
+
+Try to identify the bug by reproducing it reliably. Bugs without a
+reliable reproducer will have lowest priority. The more specific a bug
+description and reproducer is, the easier it is to fix.
+
+Try to replicate the series of events that lead to the bug being triggered.
+Narrow it down until you have a reliable sequence that can trigger the bug.
+For the vast majority of bugs you should not take longer than 5 seconds or
+three interactions (clicks, touches, taps, ...) with the device to
+reproduce. If it takes longer than that, you can narrow it down further.
+
+Once you can reproduce it, use the :ref:`libinput-debug-events` helper
+tool::
+
+ $> libinput debug-events --verbose
+
+The output is textual and can help identify whether the bug is in libinput
+at all. Note that any configuration options you have set must be specified
+on the commandline, see the :ref:`libinput-debug-events`
+man page. Use the ``--verbose`` flag to get more information about how
+libinput processes events.
+
+If the bug cannot be reproduced with the :ref:`libinput-debug-events` helper,
+even with the correct configuration options set, it is likely not a bug in
+libinput.
+
+.. _reporting_bugs_options:
+
+------------------------------------------------------------------------------
+libinput configuration settings
+------------------------------------------------------------------------------
+
+libinput has a number of device-specific default configuration settings that
+may differ from the ones your desktop environment picks by default. You may
+have changed some options in a settings panel or in an the xorg.conf snippet
+yourself.
+
+You must provide these options in the bug report, otherwise a developer
+reproducing the issue may not be able to do so.
+
+If you are on X11, the current settings can be can be obtained with
+``xinput list-props "your device name"``. Use ``xinput list`` to
+obtain the device name.
+
+If you are on Wayland, provide a manual summary of the options you have
+changed from the default (e.g. "I enabled tap-to-click").
+
+.. _reporting_bugs_touchpad:
+
+------------------------------------------------------------------------------
+Reporting touchpad bugs
+------------------------------------------------------------------------------
+
+When you file a bug, please attach the following information:
+
+- a virtual description of your input device, see :ref:`libinput-record`.
+  This is the most important piece of information, do not forget it!
+- the output from udevadm info, see :ref:`udev_info`.
+- the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s")
+- and the content of ``/sys/class/dmi/id/modalias``.
+- run ``libinput measure touchpad-size`` tool (see :ref:`absolute_coordinate_ranges_fix`)
+  and verify that the ranges and sizes it prints match the touchpad (up to 5mm
+  difference is ok)
+
+If you are reporting a bug related to button event generation:
+
+- does your touchpad have (separate) physical hardware buttons or is the
+  whole touchpad clickable?
+- Are you using software buttons or clickfinger? See :ref:`clickpad_softbuttons`.
+- Do you have :ref:`tapping` enabled?
+
+.. _reporting_bugs_mouse:
+
+------------------------------------------------------------------------------
+Reporting mouse bugs
+------------------------------------------------------------------------------
+
+When you file a bug, please attach the following information:
+
+- a virtual description of your input device, see :ref:`libinput-record`.
+  This is the most important piece of information, do not forget it!
+- the vendor model number of the device (e.g. "Logitech M325")
+- the output from udevadm info, see :ref:`udev_info`.
+
+If the bug is related to the :ref:`speed of the mouse <motion_normalization_customization>`:
+
+- the resolution of the mouse as specified by the vendor (in DPI)
+- the output of the ``mouse-dpi-tool`` (provided by libevdev)
+
+.. _reporting_bugs_keyboard:
+
+------------------------------------------------------------------------------
+Reporting keyboard bugs
+------------------------------------------------------------------------------
+
+Is your bug related to a keyboard layout? libinput does not handle keyboard
+layouts and merely forwards the physical key events. File the bug with your
+desktop environment instead (e.g. GNOME, KDE, ...), that's most likely where
+the issue is.
+
+When you file a bug, please attach the following information:
+
+- a virtual description of your input device, see :ref:`libinput-record`.
+  This is the most important piece of information, do not forget it!
+
+.. _reporting_bugs_trackpoint:
+
+------------------------------------------------------------------------------
+Reporting trackpoint bugs
+------------------------------------------------------------------------------
+
+When you file a bug, please attach the following information:
+
+- a virtual description of your input device, see :ref:`libinput-record`.
+  This is the most important piece of information, do not forget it!
+- the vendor model number of the device (e.g. "Logitech M325")
+- the output from udevadm info, see :ref:`udev_info`.
+- the sensitivity of the trackpoint if it exists (adjust the event node number as needed): ::
+
+     $ cat /sys/class/input/event17/device/device/sensitivity
+
+
+.. _reporting_bugs_other:
+
+------------------------------------------------------------------------------
+All other devices
+------------------------------------------------------------------------------
+
+When you file a bug, please attach the following information:
+
+- a virtual description of your input device, see :ref:`libinput-record`.
+  This is the most important piece of information, do not forget it!
+- the vendor model number of the device (e.g. "Sony Plastation3 controller")
+
+.. _udev_info:
+
+------------------------------------------------------------------------------
+udev information for the device
+------------------------------------------------------------------------------
+
+In many cases, we require the udev properties assigned to the device to
+verify whether device-specific quirks were applied. This can be obtained
+with ``udevadm info /sys/class/input/eventX``, with the correct event
+node for your device. An example output is below: ::
+
+     $ udevadm info /sys/class/input/event4
+     P: /devices/platform/i8042/serio1/input/input5/event4
+     N: input/event4
+     E: DEVNAME=/dev/input/event4
+     E: DEVPATH=/devices/platform/i8042/serio1/input/input5/event4
+     E: EVDEV_ABS_00=::41
+     E: EVDEV_ABS_01=::37
+     E: EVDEV_ABS_35=::41
+     E: EVDEV_ABS_36=::37
+     E: ID_INPUT=1
+     E: ID_INPUT_HEIGHT_MM=66
+     E: ID_INPUT_TOUCHPAD=1
+     E: ID_INPUT_WIDTH_MM=97
+     E: MAJOR=13
+     E: MINOR=68
+     E: SUBSYSTEM=input
+     E: USEC_INITIALIZED=5463031
+
+
+.. _evemu:
+
+------------------------------------------------------------------------------
+Recording devices with evemu
+------------------------------------------------------------------------------
+
+.. warning:: Where available, the :ref:`libinput-record` tools should be used instead
+             of evemu
+
+`evemu-record <https://www.freedesktop.org/wiki/Evemu/>`_ records the
+device capabilities together with the event stream from the kernel. On our
+side, this allows us to recreate a virtual device identical to your device
+and re-play the event sequence, hopefully triggering the same bug.
+
+evemu-record takes a ``/dev/input/eventX`` event node, but without arguments
+it will simply show the list of devices and let you select: ::
+
+     $ sudo evemu-record > scroll.evemu
+     Available devices:
+     /dev/input/event0:	Lid Switch
+     /dev/input/event1:	Sleep Button
+     /dev/input/event2:	Power Button
+     /dev/input/event3:	AT Translated Set 2 keyboard
+     /dev/input/event4:	SynPS/2 Synaptics TouchPad
+     /dev/input/event5:	Video Bus
+     /dev/input/event6:	ELAN Touchscreen
+     /dev/input/event10:	ThinkPad Extra Buttons
+     /dev/input/event11:	HDA Intel HDMI HDMI/DP,pcm=3
+     /dev/input/event12:	HDA Intel HDMI HDMI/DP,pcm=7
+     /dev/input/event13:	HDA Intel HDMI HDMI/DP,pcm=8
+     /dev/input/event14:	HDA Intel PCH Dock Mic
+     /dev/input/event15:	HDA Intel PCH Mic
+     /dev/input/event16:	HDA Intel PCH Dock Headphone
+     /dev/input/event17:	HDA Intel PCH Headphone
+     /dev/input/event18:	Integrated Camera
+     /dev/input/event19:	TPPS/2 IBM TrackPoint
+     Select the device event number [0-19]:
+
+
+Select the device that triggers the issue, then reproduce the bug and Ctrl+C
+the process. The resulting recording, ("scroll.evemu" in this example) will
+contain the sequence required to reproduce the bug. If the bug fails to
+reproduce during recording, simply Ctrl+C and restart evemu-record.
+Always start the recording from a neutral state, i.e. without any buttons or
+keys down, with the position of the device in the neutral position, without
+touching the screen/touchpad.
+
+.. note:: The longer the recording, the harder it is to identify the event
+          sequence triggering the bug. Please keep the event sequence as short
+          as possible.
+
+To verify that the recording contains the bug, you can replay it on your
+device. For example, to replay the sequence recorded in the example above: ::
+
+     $ sudo evemu-play /dev/input/event4 < scroll.evemu
+
+
+If the bug is triggered by replaying on your device, attach the recording to
+the bug report.
+
+libinput does not affect the evemu recording. libinput and evemu talk
+directly to the kernel's device nodes. An evemu recording is not
+influenced by the libinput version or whether a libinput context is
+currently active.
+
+.. graphviz:: evemu.gv
+
+.. _fixed_bugs:
+
+------------------------------------------------------------------------------
+My bug was closed as fixed, what now?
+------------------------------------------------------------------------------
+
+libinput's policy on closing bugs is: once the fix for a given bug is on git
+master, the bug is considered fixed and the gitlab issue will be closed
+accordingly.
+
+Of course, unless you actually run git master, the bug will continue to
+affect you on your local machine. You are most likely running the
+distribution's package and you will need to wait until the distribution has
+updated its package accordingly.
+
+.. warning:: Do not re-open a bug just because it hasn't trickled down to
+             your distribution's package version yet.
+
+Whether the bug fix ends up in your distribution depends on a number of
+things. Any given bug fix **may** be cherry-picked into the current stable
+branch, depending on its severity, impact, and likelihood to cause
+regressions. Once cherry-picked it will land in the next stable branch
+release. These are usually a few weeks apart.
+
+.. warning:: Do not re-open a bug because it wasn't picked into a stable branch
+             release or because your distribution didn't update to the latest stable
+             branch release.
+
+Stable branches are usually discontinued when the next release comes out.
+
+Your distribution may pick a patch up immediately and ship the fix
+even before the next stable branch update is released. For example, Fedora
+does this frequently.
+
+.. hint:: If a bug needs to be fixed urgently, file a bug in your
+          distribution's bug tracker.
+
+Patches on git master will end up in the next libinput release. Once your
+distribution updates to that release, your local libinput version will
+contain the fix.
+
+.. warning:: Do not re-open a bug because your distribution didn't update to
+             the release.
+
+You can always run libinput from git master (see :ref:`building_libinput`).
+Even while in development, libinput is very stable so this option isn't as
+scary as it may sounds.
+
+.. _reporting_bugs_reopen:
+
+..............................................................................
+When is it ok to re-open a fixed bug?
+..............................................................................
+
+Any time the bug was considered fixed but it turns out that the fix is
+insufficient and/or causes a regression.
+
+However, if the regression is in behavior unrelated to the fix itself it is
+usually better to file a new bug to reduce the noise. For example, if a fix
+to improve tapping breaks two-finger scrolling behavior, you should file a
+new bug but reference the original bug.
+
+.. _reporting_bugs_tags:
+
+------------------------------------------------------------------------------
+Gitlab issue tracker tags
+------------------------------------------------------------------------------
+
+The gitlab issue tracker allows developers to add tags to bugs to classify
+them.
+
+- **being worked on**: someone is currently working on this feature. This
+  tag is used for features that will take a long time to implement fully and
+  prevents others from having to duplicate the work. Do reach out and ask if
+  help and/or further testing is needed.
+- **bug**: issue is confirmed to be a bug
+- **cantfix**: for technical reasons, this bug cannot be fixed, or at least
+  it cannot be fixed in libinput.
+- **enhancement**: this issue describes a future feature, not a bug.
+- **help needed**: this issue requires someone outside the libinput core
+  developer team to implement it. It is unlikely to be implemented
+  without someone stepping up to do the work. If you do see this tag, do ask
+  for guidance on how to implement it.
+- **hw issue**: an issue that affects a specific device and is a hardware
+  bug, not a software bug. Often these needs to be worked around in libinput
+  but there are cases where a hw issue ends up as *cantfix*.
+- **janitor**: a cleanup task that does not substantially affect how
+  libinput works. These are usually good bugs for newcomers to start on.
+- **kernel**: this issue is a kernel bug, not a libinput bug. Often closed
+  as *cantfix* of *wontfix* as we wait for the kernel to address the issue
+  instead.
+- **needs triage**: bug has not yet been confirmed by a core developer.
+- **not our bug**: the issue is in some other component of the stack and
+  needs to be addressed there.
+- **please test**: a fix is available but not yet merged and should be
+  tested by the reporter or others affected by the issue.
+- **quirk**: this is issue needs :ref:`device-quirks` to be fixed
+- **regression**: the issue is a regression to previous versions of
+  libinput. These issues get priorities.
+- **waiting on reporter**: some more information is required from the
+  reporter and the issue cannot be fixed until the issue has been provided.
+  Where a bug is left in this state for too long, the bug will be closed as
+  *cantfix*.
+- **wontfix**: this issue will not get fixed. This tag is usually assigned
+  to feature requests that are outside the scope of libinput or would put an
+  unreasonable maintenance burdern on the maintainers.
+
+These tags are high-level categories only, always look for the comments in
+the issue to get further details.