diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2020-08-06 14:36:13 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2020-08-06 14:36:13 -0700 |
commit | c0c419c04557117258d184876d94091d29bbd9a6 (patch) | |
tree | b363d085bc6c715d9513f0cd06ac37d6a0378e8d /Documentation | |
parent | 3f9df56480fc8ce492fc9e988d67bdea884ed15c (diff) | |
parent | 5bbd90550da8f7bdac769b5825597e67183c9411 (diff) | |
download | lwn-c0c419c04557117258d184876d94091d29bbd9a6.tar.gz lwn-c0c419c04557117258d184876d94091d29bbd9a6.zip |
Merge tag 'staging-5.9-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
Pull staging/IIO driver updates from Greg KH:
"Here is the large set of Staging and IIO driver patches for 5.9-rc1.
Lots of churn here, but overall the size increase in lines added is
small, while adding a load of new IIO drivers.
Major things in here:
- lots and lots of IIO new drivers and frameworks added
- IIO driver fixes and updates
- lots of tiny coding style cleanups for staging drivers
- vc04_services major reworks and cleanups
We had 3 set of drivers move out of staging in this round as well:
- wilc1000 wireless driver moved out of staging
- speakup moved out of staging
- most USB driver moved out of staging
Full details are in the shortlog.
All of these have been in linux-next with no reported issues. The last
few changes here were to resolve reported linux-next issues, and they
seem to have resolved the problems"
* tag 'staging-5.9-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging: (428 commits)
staging: most: fix up movement of USB driver
staging: rts5208: clear alignment style issues
staging: r8188eu: replace rtw_netdev_priv define with inline function
staging: netlogic: clear alignment style issues
staging: android: ashmem: Fix lockdep warning for write operation
drivers: most: add USB adapter driver
staging: most: Use %pM format specifier for MAC addresses
staging: ks7010: Use %pM format specifier for MAC addresses
staging: qlge: qlge_dbg: removed comment repition
staging: wfx: Use flex_array_size() helper in memcpy()
staging: rtl8723bs: Align macro definitions
staging: rtl8723bs: Clean up function declations
staging: rtl8723bs: Fix coding style errors
drivers: staging: audio: Fix the missing header file for helper file
staging: greybus: audio: Enable GB codec, audio module compilation.
staging: greybus: audio: Add helper APIs for dynamic audio modules
staging: greybus: audio: Resolve compilation error in topology parser
staging: greybus: audio: Resolve compilation errors for GB codec module
staging: greybus: audio: Maintain jack list within GB Audio module
staging: greybus: audio: Update snd_jack FW usage as per new APIs
...
Diffstat (limited to 'Documentation')
33 files changed, 2770 insertions, 315 deletions
diff --git a/Documentation/ABI/stable/sysfs-driver-speakup b/Documentation/ABI/stable/sysfs-driver-speakup new file mode 100644 index 000000000000..c6a32c434ce9 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-speakup @@ -0,0 +1,375 @@ +What: /sys/accessibility/speakup/attrib_bleep +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Beeps the PC speaker when there is an attribute change such as + foreground or background color when using speakup review + commands. One = on, zero = off. + +What: /sys/accessibility/speakup/bell_pos +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This works much like a typewriter bell. If for example 72 is + echoed to bell_pos, it will beep the PC speaker when typing on + a line past character 72. + +What: /sys/accessibility/speakup/bleeps +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls whether one hears beeps through the PC speaker + when using speakup's review commands. + TODO: what values does it accept? + +What: /sys/accessibility/speakup/bleep_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls the duration of the PC speaker beeps speakup + produces. + TODO: What are the units? Jiffies? + +What: /sys/accessibility/speakup/cursor_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls cursor delay when using arrow keys. When a + connection is very slow, with the default setting, when moving + with the arrows, or backspacing etc. speakup says the incorrect + characters. Set this to a higher value to adjust for the delay + and better synchronisation between cursor position and speech. + +What: /sys/accessibility/speakup/delimiters +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Delimit a word from speakup. + TODO: add more info + +What: /sys/accessibility/speakup/ex_num +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/key_echo +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Controls if speakup speaks keys when they are typed. One = on, + zero = off or don't echo keys. + +What: /sys/accessibility/speakup/keymap +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Speakup keymap remaps keys to Speakup functions. + It uses a binary + format. A special program called genmap is needed to compile a + textual keymap into the binary format which is then loaded into + /sys/accessibility/speakup/keymap. + +What: /sys/accessibility/speakup/no_interrupt +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Controls if typing interrupts output from speakup. With + no_interrupt set to zero, typing on the keyboard will interrupt + speakup if for example + the say screen command is used before the + entire screen is read. + With no_interrupt set to one, if the say + screen command is used, and one then types on the keyboard, + speakup will continue to say the whole screen regardless until + it finishes. + +What: /sys/accessibility/speakup/punc_all +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is a list of all the punctuation speakup should speak when + punc_level is set to four. + +What: /sys/accessibility/speakup/punc_level +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Controls the level of punctuation spoken as the screen is + displayed, not reviewed. Levels range from zero no punctuation, + to four, all punctuation. One corresponds to punc_some, two + corresponds to punc_most, and three as well as four both + correspond to punc_all. Some hardware synthesizers may have + different levels each corresponding to three and four for + punc_level. Also note that if punc_level is set to zero, and + key_echo is set to one, typed punctuation is still spoken as it + is typed. + +What: /sys/accessibility/speakup/punc_most +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is a list of all the punctuation speakup should speak when + punc_level is set to two. + +What: /sys/accessibility/speakup/punc_some +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is a list of all the punctuation speakup should speak when + punc_level is set to one. + +What: /sys/accessibility/speakup/reading_punc +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Almost the same as punc_level, the differences being that + reading_punc controls the level of punctuation when reviewing + the screen with speakup's screen review commands. The other + difference is that reading_punc set to three speaks punc_all, + and reading_punc set to four speaks all punctuation, including + spaces. + +What: /sys/accessibility/speakup/repeats +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: A list of characters speakup repeats. Normally, when there are + more than three characters in a row, speakup + just reads three of + those characters. For example, "......" would be read as dot, + dot, dot. If a . is added to the list of characters in repeats, + "......" would be read as dot, dot, dot, times six. + +What: /sys/accessibility/speakup/say_control +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: If set to one, speakup speaks shift, alt and control when those + keys are pressed. If say_control is set to zero, shift, ctrl, + and alt are not spoken when they are pressed. + +What: /sys/accessibility/speakup/say_word_ctl +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/silent +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/spell_delay +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls how fast a word is spelled + when speakup's say word + review command is pressed twice quickly to speak the current + word being reviewed. Zero just speaks the letters one after + another, while values one through four + seem to introduce more of + a pause between the spelling of each letter by speakup. + +What: /sys/accessibility/speakup/synth +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the synthesizer driver currently in use. Reading + synth returns the synthesizer driver currently in use. Writing + synth switches to the given synthesizer driver, provided it is + either built into the kernel, or already loaded as a module. + +What: /sys/accessibility/speakup/synth_direct +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Sends whatever is written to synth_direct + directly to the speech synthesizer in use, bypassing speakup. + This could be used to make the synthesizer speak + a string, or to + send control sequences to the synthesizer to change how the + synthesizer behaves. + +What: /sys/accessibility/speakup/version +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Reading version returns the version of speakup, and the version + of the synthesizer driver currently in use. + +What: /sys/accessibility/speakup/i18n/announcements +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This file contains various general announcements, most of which + cannot be categorized. You will find messages such as "You + killed Speakup", "I'm alive", "leaving help", "parked", + "unparked", and others. You will also find the names of the + screen edges and cursor tracking modes here. + +What: /sys/accessibility/speakup/i18n/chartab +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO + +What: /sys/accessibility/speakup/i18n/ctl_keys +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Here, you will find names of control keys. These are used with + Speakup's say_control feature. + +What: /sys/accessibility/speakup/i18n/function_names +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Here, you will find a list of names for Speakup functions. + These are used by the help system. For example, suppose that + you have activated help mode, and you pressed + keypad 3. Speakup + says: "keypad 3 is character, say next." + The message "character, say next" names a Speakup function, and + it comes from this function_names file. + +What: /sys/accessibility/speakup/i18n/states +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This file contains names for key states. + Again, these are part of the help system. For instance, if you + had pressed speakup + keypad 3, you would hear: + "speakup keypad 3 is go to bottom edge." + The speakup key is depressed, so the name of the key state is + speakup. + This part of the message comes from the states collection. + +What: /sys/accessibility/speakup/i18n/characters +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Through this sys entry, Speakup gives you the ability to change + how Speakup pronounces a given character. You could, for + example, change how some punctuation characters are spoken. You + can even change how Speakup will pronounce certain letters. For + further details see '12. Changing the Pronunciation of + Characters' in Speakup User's Guide (file spkguide.txt in + source). + +What: /sys/accessibility/speakup/i18n/colors +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: When you use the "say attributes" function, Speakup says the + name of the foreground and background colors. These names come + from the i18n/colors file. + +What: /sys/accessibility/speakup/i18n/formatted +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This group of messages contains embedded formatting codes, to + specify the type and width of displayed data. If you change + these, you must preserve all of the formatting codes, and they + must appear in the order used by the default messages. + +What: /sys/accessibility/speakup/i18n/key_names +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Again, key_names is used by Speakup's help system. In the + previous example, Speakup said that you pressed "keypad 3." + This name came from the key_names file. + +What: /sys/accessibility/speakup/<synth-name>/ +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: In `/sys/accessibility/speakup` is a directory corresponding to + the synthesizer driver currently in use (E.G) `soft` for the + soft driver. This directory contains files which control the + speech synthesizer itself, + as opposed to controlling the speakup + screen reader. The parameters in this directory have the same + names and functions across all + supported synthesizers. The range + of values for freq, pitch, rate, and vol is the same for all + supported synthesizers, with the given range being internally + mapped by the driver to more or less fit the range of values + supported for a given parameter by the individual synthesizer. + Below is a description of values and parameters for soft + synthesizer, which is currently the most commonly used. + +What: /sys/accessibility/speakup/soft/caps_start +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is the string that is sent to the synthesizer to cause it + to start speaking uppercase letters. For the soft synthesizer + and most others, this causes the pitch of the voice to rise + above the currently set pitch. + +What: /sys/accessibility/speakup/soft/caps_stop +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This is the string sent to the synthesizer to cause it to stop + speaking uppercase letters. In the case of the soft synthesizer + and most others, this returns the pitch of the voice + down to the + currently set pitch. + +What: /sys/accessibility/speakup/soft/delay_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/soft/direct +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Controls if punctuation is spoken by speakup, or by the + synthesizer. + For example, speakup speaks ">" as "greater", while + the espeak synthesizer used by the soft driver speaks "greater + than". Zero lets speakup speak the punctuation. One lets the + synthesizer itself speak punctuation. + +What: /sys/accessibility/speakup/soft/freq +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the frequency of the speech synthesizer. Range is + 0-9. + +What: /sys/accessibility/speakup/soft/full_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/soft/jiffy_delta +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: This controls how many jiffys the kernel gives to the + synthesizer. Setting this too high can make a system unstable, + or even crash it. + +What: /sys/accessibility/speakup/soft/pitch +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the pitch of the synthesizer. The range is 0-9. + +What: /sys/accessibility/speakup/soft/inflection +KernelVersion: 5.8 +Contact: speakup@linux-speakup.org +Description: Gets or sets the inflection of the synthesizer, i.e. the pitch + range. The range is 0-9. + +What: /sys/accessibility/speakup/soft/punct +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the amount of punctuation spoken by the + synthesizer. The range for the soft driver seems to be 0-2. + TODO: How is this related to speakup's punc_level, or + reading_punc. + +What: /sys/accessibility/speakup/soft/rate +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the rate of the synthesizer. Range is from zero + slowest, to nine fastest. + +What: /sys/accessibility/speakup/soft/tone +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the tone of the speech synthesizer. The range for + the soft driver seems to be 0-2. This seems to make no + difference if using espeak and the espeakup connector. + TODO: does espeakup support different tonalities? + +What: /sys/accessibility/speakup/soft/trigger_time +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: TODO: + +What: /sys/accessibility/speakup/soft/voice +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the voice used by the synthesizer if the + synthesizer can speak in more than one voice. The range for the + soft driver is 0-7. Note that while espeak supports multiple + voices, this parameter will not set the voice when the espeakup + connector is used between speakup and espeak. + +What: /sys/accessibility/speakup/soft/vol +KernelVersion: 2.6 +Contact: speakup@linux-speakup.org +Description: Gets or sets the volume of the speech synthesizer. Range is 0-9, + with zero being the softest, and nine being the loudest. + diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index d3e53a6d8331..5c62bfb0f3f5 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -1569,7 +1569,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_voc_raw KernelVersion: 4.3 Contact: linux-iio@vger.kernel.org Description: - Raw (unscaled no offset etc.) percentage reading of a substance. + Raw (unscaled no offset etc.) reading of a substance. Units + after application of scale and offset are percents. What: /sys/bus/iio/devices/iio:deviceX/in_resistance_raw What: /sys/bus/iio/devices/iio:deviceX/in_resistanceX_raw diff --git a/Documentation/ABI/testing/sysfs-bus-iio-icm42600 b/Documentation/ABI/testing/sysfs-bus-iio-icm42600 new file mode 100644 index 000000000000..0bf1fd4f5bf1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-icm42600 @@ -0,0 +1,20 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied calibration offset (assumed to fix production + inaccuracies). Values represent a real physical offset expressed + in SI units (m/s^2 for accelerometer and rad/s for gyroscope). + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Range of available values for hardware offset. Values in SI + units (m/s^2 for accelerometer and rad/s for gyroscope). diff --git a/Documentation/ABI/testing/sysfs-bus-iio-scd30 b/Documentation/ABI/testing/sysfs-bus-iio-scd30 new file mode 100644 index 000000000000..b9712f390bec --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-scd30 @@ -0,0 +1,34 @@ +What: /sys/bus/iio/devices/iio:deviceX/calibration_auto_enable +Date: June 2020 +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Contaminants build-up in the measurement chamber or optical + elements deterioration leads to sensor drift. + + One can compensate for sensor drift by using automatic self + calibration procedure (asc). + + Writing 1 or 0 to this attribute will respectively activate or + deactivate asc. + + Upon reading current asc status is returned. + +What: /sys/bus/iio/devices/iio:deviceX/calibration_forced_value +Date: June 2020 +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Contaminants build-up in the measurement chamber or optical + elements deterioration leads to sensor drift. + + One can compensate for sensor drift by using forced + recalibration (frc). This is useful in case there's known + co2 reference available nearby the sensor. + + Picking value from the range [400 1 2000] and writing it to the + sensor will set frc. + + Upon reading current frc value is returned. Note that after + power cycling default value (i.e 400) is returned even though + internally sensor had recalibrated itself. diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.txt new file mode 100644 index 000000000000..3782f6a09e97 --- /dev/null +++ b/Documentation/admin-guide/spkguide.txt @@ -0,0 +1,1575 @@ + +The Speakup User's Guide +For Speakup 3.1.2 and Later +By Gene Collins +Updated by others +Last modified on Mon Sep 27 14:26:31 2010 +Document version 1.3 + +Copyright (c) 2005 Gene Collins +Copyright (c) 2008 Samuel Thibault +Copyright (c) 2009, 2010 the Speakup Team + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled "GNU Free +Documentation License". + +Preface + +The purpose of this document is to familiarize users with the user +interface to Speakup, a Linux Screen Reader. If you need instructions +for installing or obtaining Speakup, visit the web site at +http://linux-speakup.org/. Speakup is a set of patches to the standard +Linux kernel source tree. It can be built as a series of modules, or as +a part of a monolithic kernel. These details are beyond the scope of +this manual, but the user may need to be aware of the module +capabilities, depending on how your system administrator has installed +Speakup. If Speakup is built as a part of a monolithic kernel, and the +user is using a hardware synthesizer, then Speakup will be able to +provide speech access from the time the kernel is loaded, until the time +the system is shutdown. This means that if you have obtained Linux +installation media for a distribution which includes Speakup as a part +of its kernel, you will be able, as a blind person, to install Linux +with speech access unaided by a sighted person. Again, these details +are beyond the scope of this manual, but the user should be aware of +them. See the web site mentioned above for further details. + +1. Starting Speakup + +If your system administrator has installed Speakup to work with your +specific synthesizer by default, then all you need to do to use Speakup +is to boot your system, and Speakup should come up talking. This +assumes of course that your synthesizer is a supported hardware +synthesizer, and that it is either installed in or connected to your +system, and is if necessary powered on. + +It is possible, however, that Speakup may have been compiled into the +kernel with no default synthesizer. It is even possible that your +kernel has been compiled with support for some of the supported +synthesizers and not others. If you find that this is the case, and +your synthesizer is supported but not available, complain to the person +who compiled and installed your kernel. Or better yet, go to the web +site, and learn how to patch Speakup into your own kernel source, and +build and install your own kernel. + +If your kernel has been compiled with Speakup, and has no default +synthesizer set, or you would like to use a different synthesizer than +the default one, then you may issue the following command at the boot +prompt of your boot loader. + +linux speakup.synth=ltlk + +This command would tell Speakup to look for and use a LiteTalk or +DoubleTalk LT at boot up. You may replace the ltlk synthesizer keyword +with the keyword for whatever synthesizer you wish to use. The +speakup.synth parameter will accept the following keywords, provided +that support for the related synthesizers has been built into the +kernel. + +acntsa -- Accent SA +acntpc -- Accent PC +apollo -- Apollo +audptr -- Audapter +bns -- Braille 'n Speak +dectlk -- DecTalk Express (old and new, db9 serial only) +decext -- DecTalk (old) External +dtlk -- DoubleTalk PC +keypc -- Keynote Gold PC +ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only) +spkout -- Speak Out +txprt -- Transport +dummy -- Plain text terminal + +Note: Speakup does * NOT * support usb connections! Speakup also does * +NOT * support the internal Tripletalk! + +Speakup does support two other synthesizers, but because they work in +conjunction with other software, they must be loaded as modules after +their related software is loaded, and so are not available at boot up. +These are as follows: + +decpc -- DecTalk PC (not available at boot up) +soft -- One of several software synthesizers (not available at boot up) + +See the sections on loading modules and software synthesizers later in +this manual for further details. It should be noted here that the +speakup.synth boot parameter will have no effect if Speakup has been +compiled as modules. In order for Speakup modules to be loaded during +the boot process, such action must be configured by your system +administrator. This will mean that you will hear some, but not all, of +the bootup messages. + +2. Basic operation + +Once you have booted the system, and if necessary, have supplied the +proper bootup parameter for your synthesizer, Speakup will begin +talking as soon as the kernel is loaded. In fact, it will talk a lot! +It will speak all the boot up messages that the kernel prints on the +screen during the boot process. This is because Speakup is not a +separate screen reader, but is actually built into the operating +system. Since almost all console applications must print text on the +screen using the kernel, and must get their keyboard input through the +kernel, they are automatically handled properly by Speakup. There are a +few exceptions, but we'll come to those later. + +Note: In this guide I will refer to the numeric keypad as the keypad. +This is done because the speakupmap.map file referred to later in this +manual uses the term keypad instead of numeric keypad. Also I'm lazy +and would rather only type one word. So keypad it is. Got it? Good. + +Most of the Speakup review keys are located on the keypad at the far +right of the keyboard. The numlock key should be off, in order for these +to work. If you toggle the numlock on, the keypad will produce numbers, +which is exactly what you want for spreadsheets and such. For the +purposes of this guide, you should have the numlock turned off, which is +its default state at bootup. + +You probably won't want to listen to all the bootup messages every time +you start your system, though it's a good idea to listen to them at +least once, just so you'll know what kind of information is available to +you during the boot process. You can always review these messages after +bootup with the command: + +dmesg | more + +In order to speed the boot process, and to silence the speaking of the +bootup messages, just press the keypad enter key. This key is located +in the bottom right corner of the keypad. Speakup will shut up and stay +that way, until you press another key. + +You can check to see if the boot process has completed by pressing the 8 +key on the keypad, which reads the current line. This also has the +effect of starting Speakup talking again, so you can press keypad enter +to silence it again if the boot process has not completed. + +When the boot process is complete, you will arrive at a "login" prompt. +At this point, you'll need to type in your user id and password, as +provided by your system administrator. You will hear Speakup speak the +letters of your user id as you type it, but not the password. This is +because the password is not displayed on the screen for security +reasons. This has nothing to do with Speakup, it's a Linux security +feature. + +Once you've logged in, you can run any Linux command or program which is +allowed by your user id. Normal users will not be able to run programs +which require root privileges. + +When you are running a program or command, Speakup will automatically +speak new text as it arrives on the screen. You can at any time silence +the speech with keypad enter, or use any of the Speakup review keys. + +Here are some basic Speakup review keys, and a short description of what +they do. + +keypad 1 -- read previous character +keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak + the current character phonetically) +keypad 3 -- read next character +keypad 4 -- read previous word +keypad 5 -- read current word (press twice rapidly to spell the current word) +keypad 6 -- read next word +keypad 7 -- read previous line +keypad 8 -- read current line (press twice rapidly to hear how much the + text on the current line is indented) +keypad 9 -- read next line +keypad period -- speak current cursor position and announce current + virtual console + +It's also worth noting that the insert key on the keypad is mapped +as the speakup key. Instead of pressing and releasing this key, as you +do under DOS or Windows, you hold it like a shift key, and press other +keys in combination with it. For example, repeatedly holding keypad +insert, from now on called speakup, and keypad enter will toggle the +speaking of new text on the screen on and off. This is not the same as +just pressing keypad enter by itself, which just silences the speech +until you hit another key. When you hit speakup plus keypad enter, +Speakup will say, "You turned me off.", or "Hey, that's better." When +Speakup is turned off, no new text on the screen will be spoken. You +can still use the reading controls to review the screen however. + +3. Using the Speakup Help System + +In order to enter the Speakup help system, press and hold the speakup +key (remember that this is the keypad insert key), and press the f1 key. +You will hear the message: + +"Press space to leave help, cursor up or down to scroll, or a letter to +go to commands in list." + +When you press the spacebar to leave the help system, you will hear: + +"Leaving help." + +While you are in the Speakup help system, you can scroll up or down +through the list of available commands using the cursor keys. The list +of commands is arranged in alphabetical order. If you wish to jump to +commands in a specific part of the alphabet, you may press the letter of +the alphabet you wish to jump to. + +You can also just explore by typing keyboard keys. Pressing keys will +cause Speakup to speak the command associated with that key. For +example, if you press the keypad 8 key, you will hear: + +"Keypad 8 is line, say current." + +You'll notice that some commands do not have keys assigned to them. +This is because they are very infrequently used commands, and are also +accessible through the sys system. We'll discuss the sys system later +in this manual. + +You'll also notice that some commands have two keys assigned to them. +This is because Speakup has a built in set of alternative key bindings +for laptop users. The alternate speakup key is the caps lock key. You +can press and hold the caps lock key, while pressing an alternate +speakup command key to activate the command. On most laptops, the +numeric keypad is defined as the keys in the j k l area of the keyboard. + +There is usually a function key which turns this keypad function on and +off, and some other key which controls the numlock state. Toggling the +keypad functionality on and off can become a royal pain. So, Speakup +gives you a simple way to get at an alternative set of key mappings for +your laptop. These are also available by default on desktop systems, +because Speakup does not know whether it is running on a desktop or +laptop. So you may choose which set of Speakup keys to use. Some +system administrators may have chosen to compile Speakup for a desktop +system without this set of alternate key bindings, but these details are +beyond the scope of this manual. To use the caps lock for its normal +purpose, hold the shift key while toggling the caps lock on and off. We +should note here, that holding the caps lock key and pressing the z key +will toggle the alternate j k l keypad on and off. + +4. Keys and Their Assigned Commands + +In this section, we'll go through a list of all the speakup keys and +commands. You can also get a list of commands and assigned keys from +the help system. + +The following list was taken from the speakupmap.map file. Key +assignments are on the left of the equal sign, and the associated +Speakup commands are on the right. The designation "spk" means to press +and hold the speakup key, a.k.a. keypad insert, a.k.a. caps lock, while +pressing the other specified key. + +spk key_f9 = punc_level_dec +spk key_f10 = punc_level_inc +spk key_f11 = reading_punc_dec +spk key_f12 = reading_punc_inc +spk key_1 = vol_dec +spk key_2 = vol_inc +spk key_3 = pitch_dec +spk key_4 = pitch_inc +spk key_5 = rate_dec +spk key_6 = rate_inc +key_kpasterisk = toggle_cursoring +spk key_kpasterisk = speakup_goto +spk key_f1 = speakup_help +spk key_f2 = set_win +spk key_f3 = clear_win +spk key_f4 = enable_win +spk key_f5 = edit_some +spk key_f6 = edit_most +spk key_f7 = edit_delim +spk key_f8 = edit_repeat +shift spk key_f9 = edit_exnum + key_kp7 = say_prev_line +spk key_kp7 = left_edge + key_kp8 = say_line +double key_kp8 = say_line_indent +spk key_kp8 = say_from_top + key_kp9 = say_next_line +spk key_kp9 = top_edge + key_kpminus = speakup_parked +spk key_kpminus = say_char_num + key_kp4 = say_prev_word +spk key_kp4 = say_from_left + key_kp5 = say_word +double key_kp5 = spell_word +spk key_kp5 = spell_phonetic + key_kp6 = say_next_word +spk key_kp6 = say_to_right + key_kpplus = say_screen +spk key_kpplus = say_win + key_kp1 = say_prev_char +spk key_kp1 = right_edge + key_kp2 = say_char +spk key_kp2 = say_to_bottom +double key_kp2 = say_phonetic_char + key_kp3 = say_next_char +spk key_kp3 = bottom_edge + key_kp0 = spk_key + key_kpdot = say_position +spk key_kpdot = say_attributes +key_kpenter = speakup_quiet +spk key_kpenter = speakup_off +key_sysrq = speech_kill + key_kpslash = speakup_cut +spk key_kpslash = speakup_paste +spk key_pageup = say_first_char +spk key_pagedown = say_last_char +key_capslock = spk_key + spk key_z = spk_lock +key_leftmeta = spk_key +ctrl spk key_0 = speakup_goto +spk key_u = say_prev_line +spk key_i = say_line +double spk key_i = say_line_indent +spk key_o = say_next_line +spk key_minus = speakup_parked +shift spk key_minus = say_char_num +spk key_j = say_prev_word +spk key_k = say_word +double spk key_k = spell_word +spk key_l = say_next_word +spk key_m = say_prev_char +spk key_comma = say_char +double spk key_comma = say_phonetic_char +spk key_dot = say_next_char +spk key_n = say_position + ctrl spk key_m = left_edge + ctrl spk key_y = top_edge + ctrl spk key_dot = right_edge +ctrl spk key_p = bottom_edge +spk key_apostrophe = say_screen +spk key_h = say_from_left +spk key_y = say_from_top +spk key_semicolon = say_to_right +spk key_p = say_to_bottom +spk key_slash = say_attributes + spk key_enter = speakup_quiet + ctrl spk key_enter = speakup_off + spk key_9 = speakup_cut +spk key_8 = speakup_paste +shift spk key_m = say_first_char + ctrl spk key_semicolon = say_last_char + +5. The Speakup Sys System + +The Speakup screen reader also creates a speakup subdirectory as a part +of the sys system. + +As a convenience, run as root + +ln -s /sys/accessibility/speakup /speakup + +to directly access speakup parameters from /speakup. +You can see these entries by typing the command: + +ls -1 /speakup/* + +If you issue the above ls command, you will get back something like +this: + +/speakup/attrib_bleep +/speakup/bell_pos +/speakup/bleep_time +/speakup/bleeps +/speakup/cursor_time +/speakup/delimiters +/speakup/ex_num +/speakup/key_echo +/speakup/keymap +/speakup/no_interrupt +/speakup/punc_all +/speakup/punc_level +/speakup/punc_most +/speakup/punc_some +/speakup/reading_punc +/speakup/repeats +/speakup/say_control +/speakup/say_word_ctl +/speakup/silent +/speakup/spell_delay +/speakup/synth +/speakup/synth_direct +/speakup/version + +/speakup/i18n: +announcements +characters +chartab +colors +ctl_keys +formatted +function_names +key_names +states + +/speakup/soft: +caps_start +caps_stop +delay_time +direct +freq +full_time +jiffy_delta +pitch +inflection +punct +rate +tone +trigger_time +voice +vol + +Notice the two subdirectories of /speakup: /speakup/i18n and +/speakup/soft. +The i18n subdirectory is described in a later section. +The files under /speakup/soft represent settings that are specific to the +driver for the software synthesizer. If you use the LiteTalk, your +synthesizer-specific settings would be found in /speakup/ltlk. In other words, +a subdirectory named /speakup/KWD is created to hold parameters specific +to the device whose keyword is KWD. +These parameters include volume, rate, pitch, and others. + +In addition to using the Speakup hot keys to change such things as +volume, pitch, and rate, you can also echo values to the appropriate +entry in the /speakup directory. This is very useful, since it +lets you control Speakup parameters from within a script. How you +would write such scripts is somewhat beyond the scope of this manual, +but I will include a couple of simple examples here to give you a +general idea of what such scripts can do. + +Suppose for example, that you wanted to control both the punctuation +level and the reading punctuation level at the same time. For +simplicity, we'll call them punc0, punc1, punc2, and punc3. The scripts +might look something like this: + +#!/bin/bash +# punc0 +# set punc and reading punc levels to 0 +echo 0 >/speakup/punc_level +echo 0 >/speakup/reading_punc +echo Punctuation level set to 0. + +#!/bin/bash +# punc1 +# set punc and reading punc levels to 1 +echo 1 >/speakup/punc_level +echo 1 >/speakup/reading_punc +echo Punctuation level set to 1. + +#!/bin/bash +# punc2 +# set punc and reading punc levels to 2 +echo 2 >/speakup/punc_level +echo 2 >/speakup/reading_punc +echo Punctuation level set to 2. + +#!/bin/bash +# punc3 +# set punc and reading punc levels to 3 +echo 3 >/speakup/punc_level +echo 3 >/speakup/reading_punc +echo Punctuation level set to 3. + +If you were to store these four small scripts in a directory in your +path, perhaps /usr/local/bin, and set the permissions to 755 with the +chmod command, then you could change the default reading punc and +punctuation levels at the same time by issuing just one command. For +example, if you were to execute the punc3 command at your shell prompt, +then the reading punc and punc level would both get set to 3. + +I should note that the above scripts were written to work with bash, but +regardless of which shell you use, you should be able to do something +similar. + +The Speakup sys system also has another interesting use. You can echo +Speakup parameters into the sys system in a script during system +startup, and speakup will return to your preferred parameters every time +the system is rebooted. + +Most of the Speakup sys parameters can be manipulated by a regular user +on the system. However, there are a few parameters that are dangerous +enough that they should only be manipulated by the root user on your +system. There are even some parameters that are read only, and cannot +be written to at all. For example, the version entry in the Speakup +sys system is read only. This is because there is no reason for a user +to tamper with the version number which is reported by Speakup. Doing +an ls -l on /speakup/version will return this: + +-r--r--r-- 1 root root 0 Mar 21 13:46 /speakup/version + +As you can see, the version entry in the Speakup sys system is read +only, is owned by root, and belongs to the root group. Doing a cat of +/speakup/version will display the Speakup version number, like +this: + +cat /speakup/version +Speakup v-2.00 CVS: Thu Oct 21 10:38:21 EDT 2004 +synth dtlk version 1.1 + +The display shows the Speakup version number, along with the version +number of the driver for the current synthesizer. + +Looking at entries in the Speakup sys system can be useful in many +ways. For example, you might wish to know what level your volume is set +at. You could type: + +cat /speakup/KWD/vol +# Replace KWD with the keyword for your synthesizer, E.G., ltlk for LiteTalk. +5 + +The number five which comes back is the level at which the synthesizer +volume is set at. + +All the entries in the Speakup sys system are readable, some are +writable by root only, and some are writable by everyone. Unless you +know what you are doing, you should probably leave the ones that are +writable by root only alone. Most of the names are self explanatory. +Vol for controlling volume, pitch for pitch, inflection for pitch range, rate +for controlling speaking rate, etc. If you find one you aren't sure about, you +can post a query on the Speakup list. + +6. Changing Synthesizers + +It is possible to change to a different synthesizer while speakup is +running. In other words, it is not necessary to reboot the system +in order to use a different synthesizer. You can simply echo the +synthesizer keyword to the /speakup/synth sys entry. +Depending on your situation, you may wish to echo none to the synth +sys entry, to disable speech while one synthesizer is disconnected and +a second one is connected in its place. Then echo the keyword for the +new synthesizer into the synth sys entry in order to start speech +with the newly connected synthesizer. See the list of synthesizer +keywords in section 1 to find the keyword which matches your synth. + +7. Loading modules + +As mentioned earlier, Speakup can either be completely compiled into the +kernel, with the exception of the help module, or it can be compiled as +a series of modules. When compiled as modules, Speakup will only be +able to speak some of the bootup messages if your system administrator +has configured the system to load the modules at boo time. The modules +can be loaded after the file systems have been checked and mounted, or +from an initrd. There is a third possibility. Speakup can be compiled +with some components built into the kernel, and others as modules. As +we'll see in the next section, this is particularly useful when you are +working with software synthesizers. + +If Speakup is completely compiled as modules, then you must use the +modprobe command to load Speakup. You do this by loading the module for +the synthesizer driver you wish to use. The driver modules are all +named speakup_<keyword>, where <keyword> is the keyword for the +synthesizer you want. So, in order to load the driver for the DecTalk +Express, you would type the following command: + +modprobe speakup_dectlk + +Issuing this command would load the DecTalk Express driver and all other +related Speakup modules necessary to get Speakup up and running. + +To completely unload Speakup, again presuming that it is entirely built +as modules, you would give the command: + +modprobe -r speakup_dectlk + +The above command assumes you were running a DecTalk Express. If you +were using a different synth, then you would substitute its keyword in +place of dectlk. + +If you have multiple drivers loaded, you need to unload all of them, in +order to completely unload Speakup. +For example, if you have loaded both the dectlk and ltlk drivers, use the +command: +modprobe -r speakup_dectlk speakup_ltlk + +You cannot unload the driver for software synthesizers when a user-space +daemon is using /dev/softsynth. First, kill the daemon. Next, remove +the driver with the command: +modprobe -r speakup_soft + +Now, suppose we have a situation where the main Speakup component +is built into the kernel, and some or all of the drivers are built as +modules. Since the main part of Speakup is compiled into the kernel, a +partial Speakup sys system has been created which we can take advantage +of by simply echoing the synthesizer keyword into the +/speakup/synth sys entry. This will cause the kernel to +automatically load the appropriate driver module, and start Speakup +talking. To switch to another synth, just echo a new keyword to the +synth sys entry. For example, to load the DoubleTalk LT driver, +you would type: + +echo ltlk >/speakup/synth + +You can use the modprobe -r command to unload driver modules, regardless +of whether the main part of Speakup has been built into the kernel or +not. + +8. Using Software Synthesizers + +Using a software synthesizer requires that some other software be +installed and running on your system. For this reason, software +synthesizers are not available for use at bootup, or during a system +installation process. +There are two freely-available solutions for software speech: Espeakup and +Speech Dispatcher. +These are described in subsections 8.1 and 8.2, respectively. + +During the rest of this section, we assume that speakup_soft is either +built in to your kernel, or loaded as a module. + +If your system does not have udev installed , before you can use a +software synthesizer, you must have created the /dev/softsynth device. +If you have not already done so, issue the following commands as root: + +cd /dev +mknod softsynth c 10 26 + +While we are at it, we might just as well create the /dev/synth device, +which can be used to let user space programs send information to your +synthesizer. To create /dev/synth, change to the /dev directory, and +issue the following command as root: + +mknod synth c 10 25 + +of both. + +8.1. Espeakup + +Espeakup is a connector between Speakup and the eSpeak software synthesizer. +Espeakup may already be available as a package for your distribution +of Linux. If it is not packaged, you need to install it manually. +You can find it in the contrib/ subdirectory of the Speakup sources. +The filename is espeakup-$VERSION.tar.bz2, where $VERSION +depends on the current release of Espeakup. The Speakup 3.1.2 source +ships with version 0.71 of Espeakup. +The README file included with the Espeakup sources describes the process +of manual installation. + +Assuming that Espeakup is installed, either by the user or by the distributor, +follow these steps to use it. + +Tell Speakup to use the "soft driver: +echo soft > /speakup/synth + +Finally, start the espeakup program. There are two ways to do it. +Both require root privileges. + +If Espeakup was installed as a package for your Linux distribution, +you probably have a distribution-specific script that controls the operation +of the daemon. Look for a file named espeakup under /etc/init.d or +/etc/rc.d. Execute the following command with root privileges: +/etc/init.d/espeakup start +Replace init.d with rc.d, if your distribution uses scripts located under +/etc/rc.d. +Your distribution will also have a procedure for starting daemons at +boot-time, so it is possible to have software speech as soon as user-space +daemons are started by the bootup scripts. +These procedures are not described in this document. + +If you built Espeakup manually, the "make install" step placed the binary +under /usr/bin. +Run the following command as root: +/usr/bin/espeakup +Espeakup should start speaking. + +8.2. Speech Dispatcher + +For this option, you must have a package called +Speech Dispatcher running on your system, and it must be configured to +work with one of its supported software synthesizers. + +Two open source synthesizers you might use are Flite and Festival. You +might also choose to purchase the Software DecTalk from Fonix Sales Inc. +If you run a google search for Fonix, you'll find their web site. + +You can obtain a copy of Speech Dispatcher from free(b)soft at +http://www.freebsoft.org/. Follow the installation instructions that +come with Speech Dispatcher in order to install and configure Speech +Dispatcher. You can check out the web site for your Linux distribution +in order to get a copy of either Flite or Festival. Your Linux +distribution may also have a precompiled Speech Dispatcher package. + +Once you've installed, configured, and tested Speech Dispatcher with your +chosen software synthesizer, you still need one more piece of software +in order to make things work. You need a package called speechd-up. +You get it from the free(b)soft web site mentioned above. After you've +compiled and installed speechd-up, you are almost ready to begin using +your software synthesizer. + +Now you can begin using your software synthesizer. In order to do so, +echo the soft keyword to the synth sys entry like this: + +echo soft >/speakup/synth + +Next run the speechd_up command like this: + +speechd_up & + +Your synth should now start talking, and you should be able to adjust +the pitch, rate, etc. + +9. Using The DecTalk PC Card + +The DecTalk PC card is an ISA card that is inserted into one of the ISA +slots in your computer. It requires that the DecTalk PC software be +installed on your computer, and that the software be loaded onto the +Dectalk PC card before it can be used. + +You can get the dec_pc.tgz file from the linux-speakup.org site. The +dec_pc.tgz file is in the ~ftp/pub/linux/speakup directory. + +After you have downloaded the dec_pc.tgz file, untar it in your home +directory, and read the Readme file in the newly created dec_pc +directory. + +The easiest way to get the software working is to copy the entire dec_pc +directory into /user/local/lib. To do this, su to root in your home +directory, and issue the command: + +cp dec_pc /usr/local/lib + +You will need to copy the dtload command from the dec_pc directory to a +directory in your path. Either /usr/bin or /usr/local/bin is a good +choice. + +You can now run the dtload command in order to load the DecTalk PC +software onto the card. After you have done this, echo the decpc +keyword to the synth entry in the sys system like this: + +echo decpc >/speakup/synth + +Your DecTalk PC should start talking, and then you can adjust the pitch, +rate, volume, voice, etc. The voice entry in the Speakup sys system +will accept a number from 0 through 7 for the DecTalk PC synthesizer, +which will give you access to some of the DecTalk voices. + +10. Using Cursor Tracking + +In Speakup version 2.0 and later, cursor tracking is turned on by +default. This means that when you are using an editor, Speakup will +automatically speak characters as you move left and right with the +cursor keys, and lines as you move up and down with the cursor keys. +This is the traditional sort of cursor tracking. +Recent versions of Speakup provide two additional ways to control the +text that is spoken when the cursor is moved: +"highlight tracking" and "read window." +They are described later in this section. +Sometimes, these modes get in your way, so you can disable cursor tracking +altogether. + +You may select among the various forms of cursor tracking using the keypad +asterisk key. +Each time you press this key, a new mode is selected, and Speakup speaks +the name of the new mode. The names for the four possible states of cursor +tracking are: "cursoring on", "highlight tracking", "read window", +and "cursoring off." The keypad asterisk key moves through the list of +modes in a circular fashion. + +If highlight tracking is enabled, Speakup tracks highlighted text, +rather than the cursor itself. When you move the cursor with the arrow keys, +Speakup speaks the currently highlighted information. +This is useful when moving through various menus and dialog boxes. +If cursor tracking isn't helping you while navigating a menu, +try highlight tracking. + +With the "read window" variety of cursor tracking, you can limit the text +that Speakup speaks by specifying a window of interest on the screen. +See section 15 for a description of the process of defining windows. +When you move the cursor via the arrow keys, Speakup only speaks +the contents of the window. This is especially helpful when you are hearing +superfluous speech. Consider the following example. + +Suppose that you are at a shell prompt. You use bash, and you want to +explore your command history using the up and down arrow keys. If you +have enabled cursor tracking, you will hear two pieces of information. +Speakup speaks both your shell prompt and the current entry from the +command history. You may not want to hear the prompt repeated +each time you move, so you can silence it by specifying a window. Find +the last line of text on the screen. Clear the current window by pressing +the key combination speakup f3. Use the review cursor to find the first +character that follows your shell prompt. Press speakup + f2 twice, to +define a one-line window. The boundaries of the window are the +character following the shell prompt and the end of the line. Now, cycle +through the cursor tracking modes using keypad asterisk, until Speakup +says "read window." Move through your history using your arrow keys. +You will notice that Speakup no longer speaks the redundant prompt. + +Some folks like to turn cursor tracking off while they are using the +lynx web browser. You definitely want to turn cursor tracking off when +you are using the alsamixer application. Otherwise, you won't be able +to hear your mixer settings while you are using the arrow keys. + +11. Cut and Paste + +One of Speakup's more useful features is the ability to cut and paste +text on the screen. This means that you can capture information from a +program, and paste that captured text into a different place in the +program, or into an entirely different program, which may even be +running on a different console. + +For example, in this manual, we have made references to several web +sites. It would be nice if you could cut and paste these urls into your +web browser. Speakup does this quite nicely. Suppose you wanted to +past the following url into your browser: + +http://linux-speakup.org/ + +Use the speakup review keys to position the reading cursor on the first +character of the above url. When the reading cursor is in position, +press the keypad slash key once. Speakup will say, "mark". Next, +position the reading cursor on the rightmost character of the above +url. Press the keypad slash key once again to actually cut the text +from the screen. Speakup will say, "cut". Although we call this +cutting, Speakup does not actually delete the cut text from the screen. +It makes a copy of the text in a special buffer for later pasting. + +Now that you have the url cut from the screen, you can paste it into +your browser, or even paste the url on a command line as an argument to +your browser. + +Suppose you want to start lynx and go to the Speakup site. + +You can switch to a different console with the alt left and right +arrows, or you can switch to a specific console by typing alt and a +function key. These are not Speakup commands, just standard Linux +console capabilities. + +Once you've changed to an appropriate console, and are at a shell prompt, +type the word lynx, followed by a space. Now press and hold the speakup +key, while you type the keypad slash character. The url will be pasted +onto the command line, just as though you had typed it in. Press the +enter key to execute the command. + +The paste buffer will continue to hold the cut information, until a new +mark and cut operation is carried out. This means you can paste the cut +information as many times as you like before doing another cut +operation. + +You are not limited to cutting and pasting only one line on the screen. +You can also cut and paste rectangular regions of the screen. Just +position the reading cursor at the top left corner of the text to be +cut, mark it with the keypad slash key, then position the reading cursor +at the bottom right corner of the region to be cut, and cut it with the +keypad slash key. + +12. Changing the Pronunciation of Characters + +Through the /speakup/i18n/characters sys entry, Speakup gives you the +ability to change how Speakup pronounces a given character. You could, +for example, change how some punctuation characters are spoken. You can +even change how Speakup will pronounce certain letters. + +You may, for example, wish to change how Speakup pronounces the z +character. The author of Speakup, Kirk Reiser, is Canadian, and thus +believes that the z should be pronounced zed. If you are an American, +you might wish to use the zee pronunciation instead of zed. You can +change the pronunciation of both the upper and lower case z with the +following two commands: + +echo 90 zee >/speakup/characters +echo 122 zee >/speakup/characters + +Let's examine the parts of the two previous commands. They are issued +at the shell prompt, and could be placed in a startup script. + +The word echo tells the shell that you want to have it display the +string of characters that follow the word echo. If you were to just +type: + +echo hello. + +You would get the word hello printed on your screen as soon as you +pressed the enter key. In this case, we are echoing strings that we +want to be redirected into the sys system. + +The numbers 90 and 122 in the above echo commands are the ascii numeric +values for the upper and lower case z, the characters we wish to change. + +The string zee is the pronunciation that we want Speakup to use for the +upper and lower case z. + +The > symbol redirects the output of the echo command to a file, just +like in DOS, or at the Windows command prompt. + +And finally, /speakup/i18n/characters is the file entry in the sys system +where we want the output to be directed. Speakup looks at the numeric +value of the character we want to change, and inserts the pronunciation +string into an internal table. + +You can look at the whole table with the following command: + +cat /speakup/i18n/characters + +Speakup will then print out the entire character pronunciation table. I +won't display it here, but leave you to look at it at your convenience. + +13. Mapping Keys + +Speakup has the capability of allowing you to assign or "map" keys to +internal Speakup commands. This section necessarily assumes you have a +Linux kernel source tree installed, and that it has been patched and +configured with Speakup. How you do this is beyond the scope of this +manual. For this information, visit the Speakup web site at +http://linux-speakup.org/. The reason you'll need the kernel source +tree patched with Speakup is that the genmap utility you'll need for +processing keymaps is in the +/usr/src/linux-<version_number>/drivers/char/speakup directory. The +<version_number> in the above directory path is the version number of +the Linux source tree you are working with. + +So ok, you've gone off and gotten your kernel source tree, and patched +and configured it. Now you can start manipulating keymaps. + +You can either use the +/usr/src/linux-<version_number>/drivers/char/speakup/speakupmap.map file +included with the Speakup source, or you can cut and paste the copy in +section 4 into a separate file. If you use the one in the Speakup +source tree, make sure you make a backup of it before you start making +changes. You have been warned! + +Suppose that you want to swap the key assignments for the Speakup +say_last_char and the Speakup say_first_char commands. The +speakupmap.map lists the key mappings for these two commands as follows: + +spk key_pageup = say_first_char +spk key_pagedown = say_last_char + +You can edit your copy of the speakupmap.map file and swap the command +names on the right side of the = (equals) sign. You did make a backup, +right? The new keymap lines would look like this: + +spk key_pageup = say_last_char +spk key_pagedown = say_first_char + +After you edit your copy of the speakupmap.map file, save it under a new +file name, perhaps newmap.map. Then exit your editor and return to the +shell prompt. + +You are now ready to load your keymap with your swapped key assignments. + Assuming that you saved your new keymap as the file newmap.map, you +would load your keymap into the sys system like this: + +/usr/src/linux-<version_number>/drivers/char/speakup/genmap newmap.map +>/speakup/keymap + +Remember to substitute your kernel version number for the +<version_number> in the above command. Also note that although the +above command wrapped onto two lines in this document, you should type +it all on one line. + +Your say first and say last characters should now be swapped. Pressing +speakup pagedown should read you the first non-whitespace character on +the line your reading cursor is in, and pressing speakup pageup should +read you the last character on the line your reading cursor is in. + +You should note that these new mappings will only stay in effect until +you reboot, or until you load another keymap. + +One final warning. If you try to load a partial map, you will quickly +find that all the mappings you didn't include in your file got deleted +from the working map. Be extremely careful, and always make a backup! +You have been warned! + +14. Internationalizing Speakup + +Speakup indicates various conditions to the user by speaking messages. +For instance, when you move to the left edge of the screen with the +review keys, Speakup says, "left." +Prior to version 3.1.0 of Speakup, all of these messages were in English, +and they could not be changed. If you used a non-English synthesizer, +you still heard English messages, such as "left" and "cursoring on." +In version 3.1.0 or higher, one may load translations for the various +messages via the /sys filesystem. + +The directory /speakup/i18n contains several collections of messages. +Each group of messages is stored in its own file. +The following section lists all of these files, along with a brief description +of each. + +14.1. Files Under the i18n Subdirectory + +* announcements: +This file contains various general announcements, most of which cannot +be categorized. You will find messages such as "You killed Speakup", +"I'm alive", "leaving help", "parked", "unparked", and others. +You will also find the names of the screen edges and cursor tracking modes +here. + +* characters: +See section 12 for a description of this file. + +* chartab: +See section 12. Unlike the rest of the files in the i18n subdirectory, +this one does not contain messages to be spoken. + +* colors: +When you use the "say attributes" function, Speakup says the name of the +foreground and background colors. These names come from the i18n/colors +file. + +* ctl_keys: +Here, you will find names of control keys. These are used with Speakup's +say_control feature. + +* formatted: +This group of messages contains embedded formatting codes, to specify +the type and width of displayed data. If you change these, you must +preserve all of the formatting codes, and they must appear in the order +used by the default messages. + +* function_names: +Here, you will find a list of names for Speakup functions. These are used +by the help system. For example, suppose that you have activated help mode, +and you pressed keypad 3. Speakup says: +"keypad 3 is character, say next." +The message "character, say next" names a Speakup function, and it +comes from this function_names file. + +* key_names: +Again, key_names is used by Speakup's help system. In the previous +example, Speakup said that you pressed "keypad 3." +This name came from the key_names file. + +* states: +This file contains names for key states. +Again, these are part of the help system. For instance, if you had pressed +speakup + keypad 3, you would hear: +"speakup keypad 3 is go to bottom edge." +The speakup key is depressed, so the name of the key state is speakup. +This part of the message comes from the states collection. + +14.2. Loading Your Own Messages + +The files under the i18n subdirectory all follow the same format. +They consist of lines, with one message per line. +Each message is represented by a number, followed by the text of the message. +The number is the position of the message in the given collection. +For example, if you view the file /speakup/i18n/colors, you will see the +following list: + +0 black +1 blue +2 green +3 cyan +4 red +5 magenta +6 yellow +7 white +8 grey + +You can change one message, or you can change a whole group. +To load a whole collection of messages from a new source, simply use +the cp command: +cp ~/my_colors /speakup/i18n/colors +You can change an individual message with the echo command, +as shown in the following example. + +The Spanish name for the color blue is azul. +Looking at the colors file, we see that the name "blue" is at position 1 +within the colors group. Let's change blue to azul: +echo '1 azul' > /speakup/i18n/colors +The next time that Speakup says message 1 from the colors group, it will +say "azul", rather than "blue." + +In the future, translations into various languages will be made available, +and most users will just load the files necessary for their language. + +14.3. No Support for Non-Western-European Languages + +As of the current release, Speakup only supports Western European languages. +Support for the extended characters used by languages outside of the Western +European family of languages is a work in progress. + +15. Using Speakup's Windowing Capability + +Speakup has the capability of defining and manipulating windows on the +screen. Speakup uses the term "Window", to mean a user defined area of +the screen. The key strokes for defining and manipulating Speakup +windows are as follows: + +speakup + f2 -- Set the bounds of the window. +Speakup + f3 -- clear the current window definition. +speakup + f4 -- Toggle window silence on and off. +speakup + keypad plus -- Say the currently defined window. + +These capabilities are useful for tracking a certain part of the screen +without rereading the whole screen, or for silencing a part of the +screen that is constantly changing, such as a clock or status line. + +There is no way to save these window settings, and you can only have one +window defined for each virtual console. There is also no way to have +windows automatically defined for specific applications. + +In order to define a window, use the review keys to move your reading +cursor to the beginning of the area you want to define. Then press +speakup + f2. Speakup will tell you that the window starts at the +indicated row and column position. Then move the reading cursor to the +end of the area to be defined as a window, and press speakup + f2 again. + If there is more than one line in the window, Speakup will tell you +that the window ends at the indicated row and column position. If there +is only one line in the window, then Speakup will tell you that the +window is the specified line on the screen. If you are only defining a +one line window, you can just press speakup + f2 twice after placing the +reading cursor on the line you want to define as a window. It is not +necessary to position the reading cursor at the end of the line in order +to define the whole line as a window. + +16. Tools for Controlling Speakup + +The speakup distribution includes extra tools (in the tools directory) +which were written to make speakup easier to use. This section will +briefly describe the use of these tools. + +16.1. Speakupconf + +speakupconf began life as a contribution from Steve Holmes, a member of +the speakup community. We would like to thank him for his work on the +early versions of this project. + +This script may be installed as part of your linux distribution, but if +it isn't, the recommended places to put it are /usr/local/bin or +/usr/bin. This script can be run by any user, so it does not require +root privileges. + +Speakupconf allows you to save and load your Speakup settings. It works +by reading and writing the /sys files described above. + +The directory that speakupconf uses to store your settings depends on +whether it is run from the root account. If you execute speakupconf as +root, it uses the directory /etc/speakup. Otherwise, it uses the directory +~/.speakup, where ~ is your home directory. +Anyone who needs to use Speakup from your console can load his own custom +settings with this script. + +speakupconf takes one required argument: load or save. +Use the command +speakupconf save +to save your Speakup settings, and +speakupconf load +to load them into Speakup. +A second argument may be specified to use an alternate directory to +load or save the speakup parameters. + +16.2. Talkwith + +Charles Hallenbeck, another member of the speakup community, wrote the +initial versions of this script, and we would also like to thank him for +his work on it. + +This script needs root privileges to run, so if it is not installed as +part of your linux distribution, the recommended places to install it +are /usr/local/sbin or /usr/sbin. + +Talkwith allows you to switch synthesizers on the fly. It takes a synthesizer +name as an argument. For instance, +talkwith dectlk +causes Speakup to use the DecTalk Express. If you wish to switch to a +software synthesizer, you must also indicate which daemon you wish to +use. There are two possible choices: +spd and espeakup. spd is an abbreviation for speechd-up. +If you wish to use espeakup for software synthesis, give the command +talkwith soft espeakup +To use speechd-up, type: +talkwith soft spd +Any arguments that follow the name of the daemon are passed to the daemon +when it is invoked. For instance: +talkwith espeakup --default-voice=fr +causes espeakup to use the French voice. +Note that talkwith must always be executed with root privileges. + +Talkwith does not attempt to load your settings after the new +synthesizer is activated. You can use speakupconf to load your settings +if desired. + + GNU Free Documentation License + Version 1.2, November 2002 + + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The "Document", below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as "you". You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section "Entitled XYZ" means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as "Acknowledgements", +"Dedications", "Endorsements", or "History".) To "Preserve the Title" +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. +O. Preserve any Warranty Disclaimers. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +https://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +The End. diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml index d124eba1ce54..fd4eaa3d0ab4 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml @@ -12,8 +12,8 @@ maintainers: description: | Analog Devices ADXL345/ADXL375 3-Axis Digital Accelerometers that supports both I2C & SPI interfaces. - http://www.analog.com/en/products/mems/accelerometers/adxl345.html - http://www.analog.com/en/products/sensors-mems/accelerometers/adxl375.html + https://www.analog.com/en/products/mems/accelerometers/adxl345.html + https://www.analog.com/en/products/sensors-mems/accelerometers/adxl375.html properties: compatible: diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt deleted file mode 100644 index b25bf3a77e0f..000000000000 --- a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt +++ /dev/null @@ -1,22 +0,0 @@ -Kionix KXSD9 Accelerometer device tree bindings - -Required properties: - - compatible: should be set to "kionix,kxsd9" - - reg: i2c slave address - -Optional properties: - - vdd-supply: The input supply for VDD - - iovdd-supply: The input supply for IOVDD - - interrupts: The movement detection interrupt - - mount-matrix: See mount-matrix.txt - -Example: - -kxsd9@18 { - compatible = "kionix,kxsd9"; - reg = <0x18>; - interrupt-parent = <&foo>; - interrupts = <57 IRQ_TYPE_EDGE_FALLING>; - iovdd-supply = <&bar>; - vdd-supply = <&baz>; -}; diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml new file mode 100644 index 000000000000..d61ab4fa3d71 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/accel/kionix,kxsd9.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Kionix KXSD9 Accelerometer + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + +description: | + 3 axis 12 bit accelerometer with +-8G range on all axes. Also has a + 12 bit auxiliary ADC channel. Interface is either SPI or I2C. + +properties: + compatible: + const: kionix,kxsd9 + + reg: + maxItems: 1 + + vdd-supply: true + iovdd-supply: true + + interrupts: + maxItems: 1 + + mount-matrix: + description: an optional 3x3 mounting rotation matrix. + +required: + - compatible + - reg + +examples: + - | + # include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + accel@18 { + compatible = "kionix,kxsd9"; + reg = <0x18>; + iovdd-supply = <&iovdd>; + vdd-supply = <&vdd>; + interrupts = <57 IRQ_TYPE_EDGE_FALLING>; + mount-matrix = "-0.984807753012208", "0", "-0.173648177666930", + "0", "-1", "0", + "-0.173648177666930", "0", "0.984807753012208"; + }; + }; + - | + # include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + accel@0 { + compatible = "kionix,kxsd9"; + reg = <0>; + spi-max-frequency = <10000000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt deleted file mode 100644 index cd9048cf9dcf..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt +++ /dev/null @@ -1,49 +0,0 @@ -* Ingenic JZ47xx ADC controller IIO bindings - -Required properties: - -- compatible: Should be one of: - * ingenic,jz4725b-adc - * ingenic,jz4740-adc - * ingenic,jz4770-adc -- reg: ADC controller registers location and length. -- clocks: phandle to the SoC's ADC clock. -- clock-names: Must be set to "adc". -- #io-channel-cells: Must be set to <1> to indicate channels are selected - by index. - -ADC clients must use the format described in iio-bindings.txt, giving -a phandle and IIO specifier pair ("io-channels") to the ADC controller. - -Example: - -#include <dt-bindings/iio/adc/ingenic,adc.h> - -adc: adc@10070000 { - compatible = "ingenic,jz4740-adc"; - #io-channel-cells = <1>; - - reg = <0x10070000 0x30>; - - clocks = <&cgu JZ4740_CLK_ADC>; - clock-names = "adc"; - - interrupt-parent = <&intc>; - interrupts = <18>; -}; - -adc-keys { - ... - compatible = "adc-keys"; - io-channels = <&adc INGENIC_ADC_AUX>; - io-channel-names = "buttons"; - ... -}; - -battery { - ... - compatible = "ingenic,jz4740-battery"; - io-channels = <&adc INGENIC_ADC_BATTERY>; - io-channel-names = "battery"; - ... -}; diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml new file mode 100644 index 000000000000..9f414dbdae86 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml @@ -0,0 +1,71 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2019-2020 Artur Rojek +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/iio/adc/ingenic,adc.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Ingenic JZ47xx ADC controller IIO bindings + +maintainers: + - Artur Rojek <contact@artur-rojek.eu> + +description: > + Industrial I/O subsystem bindings for ADC controller found in + Ingenic JZ47xx SoCs. + + ADC clients must use the format described in iio-bindings.txt, giving + a phandle and IIO specifier pair ("io-channels") to the ADC controller. + +properties: + compatible: + enum: + - ingenic,jz4725b-adc + - ingenic,jz4740-adc + - ingenic,jz4770-adc + + '#io-channel-cells': + const: 1 + description: + Must be set to <1> to indicate channels are selected by index. + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: adc + + interrupts: + maxItems: 1 + +required: + - compatible + - '#io-channel-cells' + - reg + - clocks + - clock-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/jz4740-cgu.h> + #include <dt-bindings/iio/adc/ingenic,adc.h> + + adc@10070000 { + compatible = "ingenic,jz4740-adc"; + #io-channel-cells = <1>; + + reg = <0x10070000 0x30>; + + clocks = <&cgu JZ4740_CLK_ADC>; + clock-names = "adc"; + + interrupt-parent = <&intc>; + interrupts = <18>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt deleted file mode 100644 index c8787688122a..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt +++ /dev/null @@ -1,173 +0,0 @@ -Qualcomm's SPMI PMIC ADC - -- SPMI PMIC voltage ADC (VADC) provides interface to clients to read - voltage. The VADC is a 15-bit sigma-delta ADC. -- SPMI PMIC5 voltage ADC (ADC) provides interface to clients to read - voltage. The VADC is a 16-bit sigma-delta ADC. - -VADC node: - -- compatible: - Usage: required - Value type: <string> - Definition: Should contain "qcom,spmi-vadc". - Should contain "qcom,spmi-adc5" for PMIC5 ADC driver. - Should contain "qcom,spmi-adc-rev2" for PMIC rev2 ADC driver. - Should contain "qcom,pms405-adc" for PMS405 PMIC - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: VADC base address in the SPMI PMIC register map. - -- #address-cells: - Usage: required - Value type: <u32> - Definition: Must be one. Child node 'reg' property should define ADC - channel number. - -- #size-cells: - Usage: required - Value type: <u32> - Definition: Must be zero. - -- #io-channel-cells: - Usage: required - Value type: <u32> - Definition: Must be one. For details about IIO bindings see: - Documentation/devicetree/bindings/iio/iio-bindings.txt - -- interrupts: - Usage: optional - Value type: <prop-encoded-array> - Definition: End of conversion interrupt. - -Channel node properties: - -- reg: - Usage: required - Value type: <u32> - Definition: ADC channel number. - See include/dt-bindings/iio/qcom,spmi-vadc.h - -- label: - Usage: required for "qcom,spmi-adc5" and "qcom,spmi-adc-rev2" - Value type: <empty> - Definition: ADC input of the platform as seen in the schematics. - For thermistor inputs connected to generic AMUX or GPIO inputs - these can vary across platform for the same pins. Hence select - the platform schematics name for this channel. - -- qcom,decimation: - Usage: optional - Value type: <u32> - Definition: This parameter is used to decrease ADC sampling rate. - Quicker measurements can be made by reducing decimation ratio. - - For compatible property "qcom,spmi-vadc", valid values are - 512, 1024, 2048, 4096. If property is not found, default value - of 512 will be used. - - For compatible property "qcom,spmi-adc5", valid values are 250, 420 - and 840. If property is not found, default value of 840 is used. - - For compatible property "qcom,spmi-adc-rev2", valid values are 256, - 512 and 1024. If property is not present, default value is 1024. - -- qcom,pre-scaling: - Usage: optional - Value type: <u32 array> - Definition: Used for scaling the channel input signal before the signal is - fed to VADC. The configuration for this node is to know the - pre-determined ratio and use it for post scaling. Select one from - the following options. - <1 1>, <1 3>, <1 4>, <1 6>, <1 20>, <1 8>, <10 81>, <1 10> - If property is not found default value depending on chip will be used. - -- qcom,ratiometric: - Usage: optional - Value type: <empty> - Definition: Channel calibration type. - - For compatible property "qcom,spmi-vadc", if this property is - specified VADC will use the VDD reference (1.8V) and GND for - channel calibration. If property is not found, channel will be - calibrated with 0.625V and 1.25V reference channels, also - known as absolute calibration. - - For compatible property "qcom,spmi-adc5" and "qcom,spmi-adc-rev2", - if this property is specified VADC will use the VDD reference - (1.875V) and GND for channel calibration. If property is not found, - channel will be calibrated with 0V and 1.25V reference channels, - also known as absolute calibration. - -- qcom,hw-settle-time: - Usage: optional - Value type: <u32> - Definition: Time between AMUX getting configured and the ADC starting - conversion. The 'hw_settle_time' is an index used from valid values - and programmed in hardware to achieve the hardware settling delay. - - For compatible property "qcom,spmi-vadc" and "qcom,spmi-adc-rev2", - Delay = 100us * (hw_settle_time) for hw_settle_time < 11, - and 2ms * (hw_settle_time - 10) otherwise. - Valid values are: 0, 100, 200, 300, 400, 500, 600, 700, 800, - 900 us and 1, 2, 4, 6, 8, 10 ms. - If property is not found, channel will use 0us. - - For compatible property "qcom,spmi-adc5", delay = 15us for - value 0, 100us * (value) for values < 11, - and 2ms * (value - 10) otherwise. - Valid values are: 15, 100, 200, 300, 400, 500, 600, 700, 800, - 900 us and 1, 2, 4, 6, 8, 10 ms - Certain controller digital versions have valid values of - 15, 100, 200, 300, 400, 500, 600, 700, 1, 2, 4, 8, 16, 32, 64, 128 ms - If property is not found, channel will use 15us. - -- qcom,avg-samples: - Usage: optional - Value type: <u32> - Definition: Number of samples to be used for measurement. - Averaging provides the option to obtain a single measurement - from the ADC that is an average of multiple samples. The value - selected is 2^(value). - - For compatible property "qcom,spmi-vadc", valid values - are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 - If property is not found, 1 sample will be used. - - For compatible property "qcom,spmi-adc5" and "qcom,spmi-adc-rev2", - valid values are: 1, 2, 4, 8, 16 - If property is not found, 1 sample will be used. - -NOTE: - -For compatible property "qcom,spmi-vadc" following channels, also known as -reference point channels, are used for result calibration and their channel -configuration nodes should be defined: -VADC_REF_625MV and/or VADC_SPARE1(based on PMIC version) VADC_REF_1250MV, -VADC_GND_REF and VADC_VDD_VADC. - -Example: - -#include <dt-bindings/iio/qcom,spmi-vadc.h> -#include <linux/irq.h> -/* ... */ - - /* VADC node */ - pmic_vadc: vadc@3100 { - compatible = "qcom,spmi-vadc"; - reg = <0x3100>; - interrupts = <0x0 0x31 0x0 IRQ_TYPE_EDGE_RISING>; - #address-cells = <1>; - #size-cells = <0>; - #io-channel-cells = <1>; - io-channel-ranges; - - /* Channel node */ - adc-chan@VADC_LR_MUX10_USB_ID { - reg = <VADC_LR_MUX10_USB_ID>; - qcom,decimation = <512>; - qcom,ratiometric; - qcom,hw-settle-time = <200>; - qcom,avg-samples = <1>; - qcom,pre-scaling = <1 3>; - }; - }; - - /* IIO client node */ - usb { - io-channels = <&pmic_vadc VADC_LR_MUX10_USB_ID>; - io-channel-names = "vadc"; - }; diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml new file mode 100644 index 000000000000..e6263b617941 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.yaml @@ -0,0 +1,278 @@ +# SPDX-License-Identifier: GPL-2.0-only +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/qcom,spmi-vadc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm's SPMI PMIC ADC + +maintainers: + - Andy Gross <agross@kernel.org> + - Bjorn Andersson <bjorn.andersson@linaro.org> + +description: | + SPMI PMIC voltage ADC (VADC) provides interface to clients to read + voltage. The VADC is a 15-bit sigma-delta ADC. + SPMI PMIC5/PMIC7 voltage ADC (ADC) provides interface to clients to read + voltage. The VADC is a 16-bit sigma-delta ADC. + +properties: + compatible: + oneOf: + - items: + - const: qcom,pms405-adc + - const: qcom,spmi-adc-rev2 + + - items: + - enum: + - qcom,spmi-vadc + - qcom,spmi-adc5 + - qcom,spmi-adc-rev2 + - qcom,spmi-adc7 + + reg: + description: VADC base address in the SPMI PMIC register map + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + '#io-channel-cells': + const: 1 + + interrupts: + maxItems: 1 + description: + End of conversion interrupt. + +required: + - compatible + - reg + - '#address-cells' + - '#size-cells' + - '#io-channel-cells' + +patternProperties: + "^.*@[0-9a-f]+$": + type: object + description: | + Represents the external channels which are connected to the ADC. + For compatible property "qcom,spmi-vadc" following channels, also known as + reference point channels, are used for result calibration and their channel + configuration nodes should be defined: + VADC_REF_625MV and/or VADC_SPARE1(based on PMIC version) VADC_REF_1250MV, + VADC_GND_REF and VADC_VDD_VADC. + + properties: + reg: + description: | + ADC channel number. + See include/dt-bindings/iio/qcom,spmi-vadc.h + For PMIC7 ADC, the channel numbers are specified separately per PMIC + in the PMIC-specific files in include/dt-bindings/iio/. + + label: + $ref: /schemas/types.yaml#/definitions/string + description: | + ADC input of the platform as seen in the schematics. + For thermistor inputs connected to generic AMUX or GPIO inputs + these can vary across platform for the same pins. Hence select + the platform schematics name for this channel. + + qcom,decimation: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + This parameter is used to decrease ADC sampling rate. + Quicker measurements can be made by reducing decimation ratio. + + qcom,pre-scaling: + description: | + Used for scaling the channel input signal before the signal is + fed to VADC. The configuration for this node is to know the + pre-determined ratio and use it for post scaling. It is a pair of + integers, denoting the numerator and denominator of the fraction by which + input signal is multiplied. For example, <1 3> indicates the signal is scaled + down to 1/3 of its value before ADC measurement. + If property is not found default value depending on chip will be used. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + oneOf: + - items: + - const: 1 + - enum: [ 1, 3, 4, 6, 20, 8, 10 ] + + - items: + - const: 10 + - const: 81 + + qcom,ratiometric: + description: | + Channel calibration type. + - For compatible property "qcom,spmi-vadc", if this property is + specified VADC will use the VDD reference (1.8V) and GND for + channel calibration. If property is not found, channel will be + calibrated with 0.625V and 1.25V reference channels, also + known as absolute calibration. + - For compatible property "qcom,spmi-adc5", "qcom,spmi-adc7" and + "qcom,spmi-adc-rev2", if this property is specified VADC will use + the VDD reference (1.875V) and GND for channel calibration. If + property is not found, channel will be calibrated with 0V and 1.25V + reference channels, also known as absolute calibration. + type: boolean + + qcom,hw-settle-time: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Time between AMUX getting configured and the ADC starting + conversion. The 'hw_settle_time' is an index used from valid values + and programmed in hardware to achieve the hardware settling delay. + + qcom,avg-samples: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Number of samples to be used for measurement. + Averaging provides the option to obtain a single measurement + from the ADC that is an average of multiple samples. The value + selected is 2^(value). + + required: + - reg + +allOf: + - if: + properties: + compatible: + contains: + const: qcom,spmi-vadc + + then: + patternProperties: + "^.*@[0-9a-f]+$": + properties: + qcom,decimation: + enum: [ 512, 1024, 2048, 4096 ] + default: 512 + + qcom,hw-settle-time: + enum: [ 0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2, + 4, 6, 8, 10 ] + default: 0 + + qcom,avg-samples: + enum: [ 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 ] + default: 1 + + - if: + properties: + compatible: + contains: + const: qcom,spmi-adc-rev2 + + then: + patternProperties: + "^.*@[0-9a-f]+$": + properties: + qcom,decimation: + enum: [ 256, 512, 1024 ] + default: 1024 + + qcom,hw-settle-time: + enum: [ 0, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2, + 4, 6, 8, 10 ] + default: 0 + + qcom,avg-samples: + enum: [ 1, 2, 4, 8, 16 ] + default: 1 + + - if: + properties: + compatible: + contains: + const: qcom,spmi-adc5 + + then: + patternProperties: + "^.*@[0-9a-f]+$": + properties: + qcom,decimation: + enum: [ 250, 420, 840 ] + default: 840 + + qcom,hw-settle-time: + enum: [ 15, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1, 2, + 4, 6, 8, 10, 16, 32, 64, 128 ] + default: 15 + + qcom,avg-samples: + enum: [ 1, 2, 4, 8, 16 ] + default: 1 + + - if: + properties: + compatible: + contains: + const: qcom,spmi-adc7 + + then: + patternProperties: + "^.*@[0-9a-f]+$": + properties: + qcom,decimation: + enum: [ 85, 340, 1360 ] + default: 1360 + + qcom,hw-settle-time: + enum: [ 15, 100, 200, 300, 400, 500, 600, 700, 1000, 2000, 4000, + 8000, 16000, 32000, 64000, 128000 ] + default: 15 + + qcom,avg-samples: + enum: [ 1, 2, 4, 8, 16 ] + default: 1 + +examples: + - | + spmi_bus { + #address-cells = <1>; + #size-cells = <0>; + /* VADC node */ + pmic_vadc: adc@3100 { + compatible = "qcom,spmi-vadc"; + reg = <0x3100>; + interrupts = <0x0 0x31 0x0 0x1>; + #address-cells = <1>; + #size-cells = <0>; + #io-channel-cells = <1>; + io-channel-ranges; + + /* Channel node */ + adc-chan@39 { + reg = <0x39>; + qcom,decimation = <512>; + qcom,ratiometric; + qcom,hw-settle-time = <200>; + qcom,avg-samples = <1>; + qcom,pre-scaling = <1 3>; + }; + + adc-chan@9 { + reg = <0x9>; + }; + + adc-chan@a { + reg = <0xa>; + }; + + adc-chan@e { + reg = <0xe>; + }; + + adc-chan@f { + reg = <0xf>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml new file mode 100644 index 000000000000..97fe6cbb2efa --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads8688.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,ads8688.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments' ADS8684 and ADS8688 ADC chip + +maintainers: + - Sean Nyekjaer <sean@geanix.com> + +description: | + SPI 16bit ADCs with 4/8 channels. + +properties: + compatible: + enum: + - ti,ads8684 + - ti,ads8688 + + reg: + maxItems: 1 + + vref-supply: + description: Optional external reference. If not supplied, assume + REFSEL input tied low to enable the internal reference. + +required: + - compatible + - reg + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "ti,ads8688"; + reg = <0>; + vref-supply = <&vdd_supply>; + spi-max-frequency = <1000000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt b/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt deleted file mode 100644 index a02337d7efa4..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt +++ /dev/null @@ -1,20 +0,0 @@ -* Texas Instruments' ADS8684 and ADS8688 ADC chip - -Required properties: - - compatible: Should be "ti,ads8684" or "ti,ads8688" - - reg: spi chip select number for the device - -Recommended properties: - - spi-max-frequency: Definition as per - Documentation/devicetree/bindings/spi/spi-bus.txt - -Optional properties: - - vref-supply: The regulator supply for ADC reference voltage - -Example: -adc@0 { - compatible = "ti,ads8688"; - reg = <0>; - vref-supply = <&vdd_supply>; - spi-max-frequency = <1000000>; -}; diff --git a/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml b/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml new file mode 100644 index 000000000000..40d87346ff4c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/sensirion,scd30.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/chemical/sensirion,scd30.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sensirion SCD30 carbon dioxide sensor + +maintainers: + - Tomasz Duszynski <tomasz.duszynski@octakon.com> + +description: | + Air quality sensor capable of measuring co2 concentration, temperature + and relative humidity. + +properties: + compatible: + enum: + - sensirion,scd30 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vdd-supply: true + + sensirion,sel-gpios: + description: GPIO connected to the SEL line + maxItems: 1 + + sensirion,pwm-gpios: + description: GPIO connected to the PWM line + maxItems: 1 + +required: + - compatible + +additionalProperties: false + +examples: + - | + # include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + co2-sensor@61 { + compatible = "sensirion,scd30"; + reg = <0x61>; + vdd-supply = <&vdd>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; + - | + # include <dt-bindings/interrupt-controller/irq.h> + serial { + co2-sensor { + compatible = "sensirion,scd30"; + vdd-supply = <&vdd>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt index 639c94ed83e9..17af395b99d9 100644 --- a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt +++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt @@ -6,7 +6,7 @@ Is is programmable through an SPI interface. The internal DACs are loaded when the LOADDACS pin is pulled down. -http://www.ti.com/lit/ds/sbas106/sbas106.pdf +https://www.ti.com/lit/ds/sbas106/sbas106.pdf Required Properties: - compatible: Should be one of: diff --git a/Documentation/devicetree/bindings/iio/iio-bindings.txt b/Documentation/devicetree/bindings/iio/iio-bindings.txt index af33267727f4..aa63cac7323e 100644 --- a/Documentation/devicetree/bindings/iio/iio-bindings.txt +++ b/Documentation/devicetree/bindings/iio/iio-bindings.txt @@ -9,7 +9,7 @@ specifier is an array of one or more cells identifying the IIO output on a device. The length of an IIO specifier is defined by the value of a #io-channel-cells property in the IIO provider node. -[1] http://marc.info/?l=linux-iio&m=135902119507483&w=2 +[1] https://marc.info/?l=linux-iio&m=135902119507483&w=2 ==IIO providers== diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml index 0d0ef84e22b9..33d8e9fd14b7 100644 --- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml +++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml @@ -37,6 +37,15 @@ properties: set if the specified interrupt pin should be configured as open drain. If not set, defaults to push-pull. + vdd-supply: + description: provide VDD power to the sensor. + + vddio-supply: + description: provide VDD IO power to the sensor. + + mount-matrix: + description: an optional 3x3 mounting rotation matrix + required: - compatible - reg @@ -52,9 +61,14 @@ examples: bmi160@68 { compatible = "bosch,bmi160"; reg = <0x68>; + vdd-supply = <&pm8916_l17>; + vddio-supply = <&pm8916_l6>; interrupt-parent = <&gpio4>; interrupts = <12 IRQ_TYPE_EDGE_RISING>; interrupt-names = "INT1"; + mount-matrix = "0", "1", "0", + "-1", "0", "0", + "0", "0", "1"; }; }; - | diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml new file mode 100644 index 000000000000..abd8d25e1136 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/imu/invensense,icm42600.yaml @@ -0,0 +1,90 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/imu/invensense,icm42600.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: InvenSense ICM-426xx Inertial Measurement Unit + +maintainers: + - Jean-Baptiste Maneyrol <jmaneyrol@invensense.com> + +description: | + 6-axis MotionTracking device that combines a 3-axis gyroscope and a 3-axis + accelerometer. + + It has a configurable host interface that supports I3C, I2C and SPI serial + communication, features a 2kB FIFO and 2 programmable interrupts with + ultra-low-power wake-on-motion support to minimize system power consumption. + + Other industry-leading features include InvenSense on-chip APEX Motion + Processing engine for gesture recognition, activity classification, and + pedometer, along with programmable digital filters, and an embedded + temperature sensor. + + https://invensense.tdk.com/wp-content/uploads/2020/03/DS-000292-ICM-42605-v1.4.pdf + +properties: + compatible: + enum: + - invensense,icm42600 + - invensense,icm42602 + - invensense,icm42605 + - invensense,icm42622 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + drive-open-drain: + type: boolean + + vdd-supply: + description: Regulator that provides power to the sensor + + vddio-supply: + description: Regulator that provides power to the bus + +required: + - compatible + - reg + - interrupts + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + icm42605@68 { + compatible = "invensense,icm42605"; + reg = <0x68>; + interrupt-parent = <&gpio2>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&vdd>; + vddio-supply = <&vddio>; + }; + }; + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + spi0 { + #address-cells = <1>; + #size-cells = <0>; + + icm42602@0 { + compatible = "invensense,icm42602"; + reg = <0>; + spi-max-frequency = <24000000>; + spi-cpha; + spi-cpol; + interrupt-parent = <&gpio1>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&vdd>; + vddio-supply = <&vddio>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/light/apds9300.txt b/Documentation/devicetree/bindings/iio/light/apds9300.txt index aa199e09a493..3aa6db3ee99d 100644 --- a/Documentation/devicetree/bindings/iio/light/apds9300.txt +++ b/Documentation/devicetree/bindings/iio/light/apds9300.txt @@ -1,6 +1,6 @@ * Avago APDS9300 ambient light sensor -http://www.avagotech.com/docs/AV02-1077EN +https://www.avagotech.com/docs/AV02-1077EN Required properties: diff --git a/Documentation/devicetree/bindings/iio/light/apds9960.txt b/Documentation/devicetree/bindings/iio/light/apds9960.txt index 3af325ad194b..c53ddb81c4aa 100644 --- a/Documentation/devicetree/bindings/iio/light/apds9960.txt +++ b/Documentation/devicetree/bindings/iio/light/apds9960.txt @@ -1,6 +1,6 @@ * Avago APDS9960 gesture/RGB/ALS/proximity sensor -http://www.avagotech.com/docs/AV02-4191EN +https://www.avagotech.com/docs/AV02-4191EN Required properties: diff --git a/Documentation/devicetree/bindings/iio/light/opt3001.txt b/Documentation/devicetree/bindings/iio/light/opt3001.txt index 47b13eb8f4ec..9e6f2998e751 100644 --- a/Documentation/devicetree/bindings/iio/light/opt3001.txt +++ b/Documentation/devicetree/bindings/iio/light/opt3001.txt @@ -6,7 +6,7 @@ the optional generation of IIO events on rising/falling light threshold changes requires the use of interrupts. Without interrupts, only the simple reading of the current light value is supported through the IIO API. -http://www.ti.com/product/opt3001 +https://www.ti.com/product/opt3001 Required properties: - compatible: should be "ti,opt3001" diff --git a/Documentation/devicetree/bindings/iio/light/vl6180.txt b/Documentation/devicetree/bindings/iio/light/vl6180.txt index 2c52952715a0..fb9137d85df9 100644 --- a/Documentation/devicetree/bindings/iio/light/vl6180.txt +++ b/Documentation/devicetree/bindings/iio/light/vl6180.txt @@ -1,6 +1,6 @@ STMicro VL6180 - ALS, range and proximity sensor -Link to datasheet: http://www.st.com/resource/en/datasheet/vl6180x.pdf +Link to datasheet: https://www.st.com/resource/en/datasheet/vl6180x.pdf Required properties: diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt b/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt deleted file mode 100644 index aa67ceb0d4e0..000000000000 --- a/Documentation/devicetree/bindings/iio/magnetometer/ak8975.txt +++ /dev/null @@ -1,30 +0,0 @@ -* AsahiKASEI AK8975 magnetometer sensor - -Required properties: - - - compatible : should be "asahi-kasei,ak8975" - - reg : the I2C address of the magnetometer - -Optional properties: - - - gpios : should be device tree identifier of the magnetometer DRDY pin - - vdd-supply: an optional regulator that needs to be on to provide VDD - - mount-matrix: an optional 3x3 mounting rotation matrix - -Example: - -ak8975@c { - compatible = "asahi-kasei,ak8975"; - reg = <0x0c>; - gpios = <&gpj0 7 0>; - vdd-supply = <&ldo_3v3_gnss>; - mount-matrix = "-0.984807753012208", /* x0 */ - "0", /* y0 */ - "-0.173648177666930", /* z0 */ - "0", /* x1 */ - "-1", /* y1 */ - "0", /* z1 */ - "-0.173648177666930", /* x2 */ - "0", /* y2 */ - "0.984807753012208"; /* z2 */ -}; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml b/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml new file mode 100644 index 000000000000..f4393bfbf355 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/magnetometer/asahi-kasei,ak8975.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/magnetometer/asahi-kasei,ak8975.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AsahiKASEI AK8975 magnetometer sensor + +maintainers: + - Jonathan Albrieux <jonathan.albrieux@gmail.com> + +properties: + compatible: + oneOf: + - enum: + - asahi-kasei,ak8975 + - asahi-kasei,ak8963 + - asahi-kasei,ak09911 + - asahi-kasei,ak09912 + - enum: + - ak8975 + - ak8963 + - ak09911 + - ak09912 + deprecated: true + + reg: + maxItems: 1 + + gpios: + maxItems: 1 + description: | + AK8975 has a "Data ready" pin (DRDY) which informs that data + is ready to be read and is possible to listen on it. If used, + this should be active high. Prefer interrupt over this. + + interrupts: + maxItems: 1 + description: interrupt for DRDY pin. Triggered on rising edge. + + vdd-supply: + description: | + an optional regulator that needs to be on to provide VDD power to + the sensor. + + mount-matrix: + description: an optional 3x3 mounting rotation matrix. + + reset-gpios: + description: | + an optional pin needed for AK09911 to set the reset state. This should + be usually active low + +required: + - compatible + - reg + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + magnetometer@c { + compatible = "asahi-kasei,ak8975"; + reg = <0x0c>; + interrupt-parent = <&gpio6>; + interrupts = <15 IRQ_TYPE_EDGE_RISING>; + vdd-supply = <&ldo_3v3_gnss>; + reset-gpios = <&msmgpio 111 GPIO_ACTIVE_LOW>; + mount-matrix = "-0.984807753012208", /* x0 */ + "0", /* y0 */ + "-0.173648177666930", /* z0 */ + "0", /* x1 */ + "-1", /* y1 */ + "0", /* z1 */ + "-0.173648177666930", /* x2 */ + "0", /* y2 */ + "0.984807753012208"; /* z2 */ + }; + }; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt b/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt index fd5fca90fb39..22912e43b60c 100644 --- a/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt +++ b/Documentation/devicetree/bindings/iio/magnetometer/bmc150_magn.txt @@ -4,7 +4,11 @@ http://ae-bst.resource.bosch.com/media/products/dokumente/bmc150/BST-BMC150-DS00 Required properties: - - compatible : should be "bosch,bmc150_magn" + - compatible : should be one of: + "bosch,bmc150_magn" + "bosch,bmc156_magn" + "bosch,bmm150" + "bosch,bmm150_magn" (DEPRECATED, use bosch,bmm150) - reg : the I2C address of the magnetometer Optional properties: diff --git a/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt index 566711b9950c..4f245e8469fd 100644 --- a/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt +++ b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt @@ -1,7 +1,7 @@ * Microchip MCP41010/41050/41100/42010/42050/42100 Digital Potentiometer Datasheet publicly available at: -http://ww1.microchip.com/downloads/en/devicedoc/11195c.pdf +https://ww1.microchip.com/downloads/en/devicedoc/11195c.pdf The node for this driver must be a child node of a SPI controller, hence all mandatory properties described in diff --git a/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt b/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt index e6d0c2eb345c..f3ab02b0dd41 100644 --- a/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt +++ b/Documentation/devicetree/bindings/iio/potentiostat/lmp91000.txt @@ -1,7 +1,7 @@ * Texas Instruments LMP91000 series of potentiostats -LMP91000: http://www.ti.com/lit/ds/symlink/lmp91000.pdf -LMP91002: http://www.ti.com/lit/ds/symlink/lmp91002.pdf +LMP91000: https://www.ti.com/lit/ds/symlink/lmp91000.pdf +LMP91002: https://www.ti.com/lit/ds/symlink/lmp91002.pdf Required properties: diff --git a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml index 64c18f1693f0..be2be4b556db 100644 --- a/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml @@ -13,7 +13,7 @@ description: | Bindings for the All Sensors DLH series pressure sensors. Specifications about the sensors can be found at: - http://www.allsensors.com/cad/DS-0355_Rev_B.PDF + https://www.allsensors.com/cad/DS-0355_Rev_B.PDF properties: compatible: diff --git a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml index f86f8b23ef18..ce795279839e 100644 --- a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml +++ b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml @@ -17,9 +17,9 @@ description: | until it is received once again Specifications about the devices can be found at: - http://www.robot-electronics.co.uk/htm/srf04tech.htm + https://www.robot-electronics.co.uk/htm/srf04tech.htm - http://www.maxbotix.com/documents/LV-MaxSonar-EZ_Datasheet.pdf + https://www.maxbotix.com/documents/LV-MaxSonar-EZ_Datasheet.pdf properties: compatible: diff --git a/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml index d226fd7d5258..3cd0b70cd6cf 100644 --- a/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml +++ b/Documentation/devicetree/bindings/soc/microchip/atmel,at91rm9200-tcb.yaml @@ -52,14 +52,20 @@ properties: patternProperties: "^timer@[0-2]$": - description: The timer block channels that are used as timers. + description: The timer block channels that are used as timers or counters. type: object properties: compatible: - const: atmel,tcb-timer + items: + - enum: + - atmel,tcb-timer + - microchip,tcb-capture reg: description: - List of channels to use for this particular timer. + List of channels to use for this particular timer. In Microchip TCB capture + mode channels are registered as a counter devices, for the qdec mode TCB0's + channel <0> and <1> are required. + minItems: 1 maxItems: 3 @@ -153,3 +159,23 @@ examples: reg = <1>; }; }; + /* TCB0 Capture with QDEC: */ + timer@f800c000 { + compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfff7c000 0x100>; + interrupts = <18 4>; + clocks = <&tcb0_clk>, <&clk32k>; + clock-names = "t0_clk", "slow_clk"; + + timer@0 { + compatible = "microchip,tcb-capture"; + reg = <0>, <1>; + }; + + timer@2 { + compatible = "atmel,tcb-timer"; + reg = <2>; + }; + }; diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst index e622f8f6e56a..b02c52cd69d6 100644 --- a/Documentation/driver-api/generic-counter.rst +++ b/Documentation/driver-api/generic-counter.rst @@ -262,7 +262,7 @@ the system. Counter Counts may be allocated via counter_count structures, and respective Counter Signal associations (Synapses) made via counter_synapse structures. Associated counter_synapse structures are -stored as an array and set to the the synapses array member of the +stored as an array and set to the synapses array member of the respective counter_count structure. These counter_count structures are set to the counts array member of an allocated counter_device structure before the Counter is registered to the system. diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst index e9036ef9f8f4..dd64c9c5fb1e 100644 --- a/Documentation/driver-api/iio/buffers.rst +++ b/Documentation/driver-api/iio/buffers.rst @@ -88,7 +88,7 @@ fields in iio_chan_spec definition:: The driver implementing the accelerometer described above will have the following channel definition:: - struct struct iio_chan_spec accel_channels[] = { + struct iio_chan_spec accel_channels[] = { { .type = IIO_ACCEL, .modified = 1, |