From patchwork Tue Apr 4 12:22:12 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 9661611 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 166A560352 for ; Tue, 4 Apr 2017 12:23:46 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0D25C27D0E for ; Tue, 4 Apr 2017 12:23:46 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 0212F28504; Tue, 4 Apr 2017 12:23:45 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 25B5D27D0E for ; Tue, 4 Apr 2017 12:23:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753145AbdDDMXP (ORCPT ); Tue, 4 Apr 2017 08:23:15 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:34557 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752133AbdDDMXC (ORCPT ); Tue, 4 Apr 2017 08:23:02 -0400 Received: from localhost (localhost [127.0.0.1]) by osg.samsung.com (Postfix) with ESMTP id 3664DA05EE; Tue, 4 Apr 2017 12:23:26 +0000 (UTC) X-Virus-Scanned: amavisd-new at osg.samsung.com X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" Received: from osg.samsung.com ([127.0.0.1]) by localhost (s-opensource.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id n4GS0aDBVigO; Tue, 4 Apr 2017 12:23:24 +0000 (UTC) Received: from smtp.s-opensource.com (177.133.87.34.dynamic.adsl.gvt.net.br [177.133.87.34]) by osg.samsung.com (Postfix) with ESMTPSA id 413E3A05FB; Tue, 4 Apr 2017 12:23:19 +0000 (UTC) Received: from mchehab by smtp.s-opensource.com with local (Exim 4.87) (envelope-from ) id 1cvNTr-0004Zq-Jt; Tue, 04 Apr 2017 09:22:39 -0300 From: Mauro Carvalho Chehab To: linux-input@vger.kernel.org, Dmitry Torokhov Cc: Mauro Carvalho Chehab , Linux Doc Mailing List , Jonathan Corbet Subject: [PATCH v2 12/37] docs: input/ff: convert it to ReST format Date: Tue, 4 Apr 2017 09:22:12 -0300 Message-Id: <95dd0d035385dac833029e1db56846f02b3ae69c.1491308444.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.9.3 In-Reply-To: References: <67ed7b07043e6fac94528044ebaf541d5deb7c82.1491308444.git.mchehab@s-opensource.com> <8e64d13bfc6952bc9370593ddc556a539f589654.1491308444.git.mchehab@s-opensource.com> <781a89b410f25a2fb39d081d1ebd696317b6d2c2.1491308444.git.mchehab@s-opensource.com> <6800b2c4e8f67b699c22533f7574d380b37cb6d6.1491308444.git.mchehab@s-opensource.com> <9f6ae6ca543f4aa294afd000b7c8a8f49b2e8382.1491308444.git.mchehab@s-opensource.com> <00ec4ed3ae000ee03c3fd725a5fadf33c1353d16.1491308444.git.mchehab@s-opensource.com> <9794ec8a2147f66e9e183f612fa7e834c9245dd9.1491308444.git.mchehab@s-opensource.com> <3bb792c867ec11d1e5b998b2d44e99fbd654ff95.1491308444.git.mchehab@s-opensource.com> In-Reply-To: <67ed7b07043e6fac94528044ebaf541d5deb7c82.1491308444.git.mchehab@s-opensource.com> References: <67ed7b07043e6fac94528044ebaf541d5deb7c82.1491308444.git.mchehab@s-opensource.com> Sender: linux-input-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-input@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This file require minimum adjustments to be a valid ReST file. Do it, in order to be able to parse it with Sphinx. Signed-off-by: Mauro Carvalho Chehab --- Documentation/input/ff.txt | 188 +++++++++++++++++++++++++++------------------ 1 file changed, 112 insertions(+), 76 deletions(-) diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt index b3867bf49f8f..6d6688a63dd8 100644 --- a/Documentation/input/ff.txt +++ b/Documentation/input/ff.txt @@ -1,12 +1,16 @@ -Force feedback for Linux. -By Johann Deneux on 2001/04/22. -Updated by Anssi Hannula on 2006/04/09. +======================== +Force feedback for Linux +======================== + +:Author: Johann Deneux on 2001/04/22. +:Updated: Anssi Hannula on 2006/04/09. + You may redistribute this file. Please remember to include shape.fig and interactive.fig as well. ----------------------------------------------------------------------------- -1. Introduction -~~~~~~~~~~~~~~~ +Introduction +~~~~~~~~~~~~ + This document describes how to use force feedback devices under Linux. The goal is not to support these devices as if they were simple input-only devices (as it is already the case), but to really enable the rendering of force @@ -15,8 +19,9 @@ This document only describes the force feedback part of the Linux input interface. Please read joystick.txt and input.txt before reading further this document. -2. Instructions to the user -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Instructions to the user +~~~~~~~~~~~~~~~~~~~~~~~~ + To enable force feedback, you have to: 1. have your kernel configured with evdev and a driver that supports your @@ -33,39 +38,48 @@ something goes wrong. If you have a serial iforce device, you need to start inputattach. See joystick.txt for details. -2.1 Does it work ? -~~~~~~~~~~~~~~~~~~ -There is an utility called fftest that will allow you to test the driver. -% fftest /dev/input/eventXX +Does it work ? +-------------- + +There is an utility called fftest that will allow you to test the driver:: + + % fftest /dev/input/eventXX + +Instructions to the developer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -3. Instructions to the developer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All interactions are done using the event API. That is, you can use ioctl() and write() on /dev/input/eventXX. This information is subject to change. -3.1 Querying device capabilities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#include -#include +Querying device capabilities +---------------------------- -#define BITS_TO_LONGS(x) \ - (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) -unsigned long features[BITS_TO_LONGS(FF_CNT)]; -int ioctl(int file_descriptor, int request, unsigned long *features); +:: + + #include + #include + + #define BITS_TO_LONGS(x) \ + (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) + unsigned long features[BITS_TO_LONGS(FF_CNT)]; + int ioctl(int file_descriptor, int request, unsigned long *features); "request" must be EVIOCGBIT(EV_FF, size of features array in bytes ) Returns the features supported by the device. features is a bitfield with the following bits: + - FF_CONSTANT can render constant force effects - FF_PERIODIC can render periodic effects with the following waveforms: + - FF_SQUARE square waveform - FF_TRIANGLE triangle waveform - FF_SINE sine waveform - FF_SAW_UP sawtooth up waveform - FF_SAW_DOWN sawtooth down waveform - FF_CUSTOM custom waveform + - FF_RAMP can render ramp effects - FF_SPRING can simulate the presence of a spring - FF_FRICTION can simulate friction @@ -75,24 +89,30 @@ following bits: - FF_GAIN gain is adjustable - FF_AUTOCENTER autocenter is adjustable -Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All +.. note:: + + - In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All devices that support FF_RUMBLE support FF_PERIODIC (square, triangle, sine) and the other way around. -Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver + - The exact syntax FF_CUSTOM is undefined for the time being as no driver supports it yet. +:: -int ioctl(int fd, EVIOCGEFFECTS, int *n); + int ioctl(int fd, EVIOCGEFFECTS, int *n); Returns the number of effects the device can keep in its memory. -3.2 Uploading effects to the device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#include -#include +Uploading effects to the device +------------------------------- -int ioctl(int file_descriptor, int request, struct ff_effect *effect); +:: + + #include + #include + + int ioctl(int file_descriptor, int request, struct ff_effect *effect); "request" must be EVIOCSFF. @@ -110,34 +130,41 @@ See for a description of the ff_effect struct. You should also find help in a few sketches, contained in files shape.fig and interactive.fig. You need xfig to visualize these files. -3.3 Removing an effect from the device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -int ioctl(int fd, EVIOCRMFF, effect.id); + +Removing an effect from the device +---------------------------------- + +:: + + int ioctl(int fd, EVIOCRMFF, effect.id); This makes room for new effects in the device's memory. Note that this also stops the effect if it was playing. -3.4 Controlling the playback of effects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Controlling the playback of effects +----------------------------------- + Control of playing is done with write(). Below is an example: -#include -#include +:: + + #include + #include struct input_event play; struct input_event stop; struct ff_effect effect; int fd; -... + ... fd = open("/dev/input/eventXX", O_RDWR); -... + ... /* Play three times */ play.type = EV_FF; play.code = effect.id; play.value = 3; write(fd, (const void*) &play, sizeof(play)); -... + ... /* Stop an effect */ stop.type = EV_FF; stop.code = effect.id; @@ -145,43 +172,50 @@ Control of playing is done with write(). Below is an example: write(fd, (const void*) &play, sizeof(stop)); -3.5 Setting the gain -~~~~~~~~~~~~~~~~~~~~ +Setting the gain +---------------- + Not all devices have the same strength. Therefore, users should set a gain factor depending on how strong they want effects to be. This setting is persistent across access to the driver. -/* Set the gain of the device -int gain; /* between 0 and 100 */ -struct input_event ie; /* structure used to communicate with the driver */ +:: -ie.type = EV_FF; -ie.code = FF_GAIN; -ie.value = 0xFFFFUL * gain / 100; + /* Set the gain of the device + int gain; /* between 0 and 100 */ + struct input_event ie; /* structure used to communicate with the driver */ -if (write(fd, &ie, sizeof(ie)) == -1) + ie.type = EV_FF; + ie.code = FF_GAIN; + ie.value = 0xFFFFUL * gain / 100; + + if (write(fd, &ie, sizeof(ie)) == -1) perror("set gain"); -3.6 Enabling/Disabling autocenter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Enabling/Disabling autocenter +----------------------------- + The autocenter feature quite disturbs the rendering of effects in my opinion, and I think it should be an effect, which computation depends on the game type. But you can enable it if you want. -int autocenter; /* between 0 and 100 */ -struct input_event ie; +:: -ie.type = EV_FF; -ie.code = FF_AUTOCENTER; -ie.value = 0xFFFFUL * autocenter / 100; + int autocenter; /* between 0 and 100 */ + struct input_event ie; -if (write(fd, &ie, sizeof(ie)) == -1) + ie.type = EV_FF; + ie.code = FF_AUTOCENTER; + ie.value = 0xFFFFUL * autocenter / 100; + + if (write(fd, &ie, sizeof(ie)) == -1) perror("set auto-center"); A value of 0 means "no auto-center". -3.7 Dynamic update of an effect -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Dynamic update of an effect +--------------------------- + Proceed as if you wanted to upload a new effect, except that instead of setting the id field to -1, you set it to the wanted effect id. Normally, the effect is not stopped and restarted. However, depending on the @@ -192,30 +226,32 @@ case, the driver stops the effect, up-load it, and restart it. Therefore it is recommended to dynamically change direction while the effect is playing only when it is ok to restart the effect with a replay count of 1. -3.8 Information about the status of effects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Information about the status of effects +--------------------------------------- + Every time the status of an effect is changed, an event is sent. The values -and meanings of the fields of the event are as follows: +and meanings of the fields of the event are as follows:: -struct input_event { -/* When the status of the effect changed */ - struct timeval time; + struct input_event { + /* When the status of the effect changed */ + struct timeval time; -/* Set to EV_FF_STATUS */ - unsigned short type; + /* Set to EV_FF_STATUS */ + unsigned short type; -/* Contains the id of the effect */ - unsigned short code; + /* Contains the id of the effect */ + unsigned short code; -/* Indicates the status */ - unsigned int value; -}; + /* Indicates the status */ + unsigned int value; + }; -FF_STATUS_STOPPED The effect stopped playing -FF_STATUS_PLAYING The effect started to play + FF_STATUS_STOPPED The effect stopped playing + FF_STATUS_PLAYING The effect started to play -NOTE: Status feedback is only supported by iforce driver. If you have +.. note:: + + - Status feedback is only supported by iforce driver. If you have a really good reason to use this, please contact linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com so that support for it can be added to the rest of the drivers. -