staging: speakup: document sysfs attributes

Speakup exposes a set of sysfs attributes under
/sys/accessibility/speakup/ for user-space to interact with and
configure speakup's kernel modules. This patch describes those
attributes. Some attributes either lack a description or contain
incomplete description. They are marked wit TODO.

Authored-by: Gregory Nowak <greg@gregn.net>
Submitted-by: Okash Khawaja <okash.khawaja@gmail.com>
Signed-off-by: Okash Khawaja <okash.khawaja@gmail.com>
Link: https://lore.kernel.org/r/20191001214729.1770-1-okash.khawaja@gmail.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

1 files changed, 369 insertions, 0 deletions

diff --git a/drivers/staging/speakup/sysfs-driver-speakup b/drivers/staging/speakup/sysfs-driver-speakup
new file mode 100644
index 000000000000..be3f5d6962e9
--- /dev/null
+++ b/drivers/staging/speakup/sysfs-driver-speakup
@@ -0,0 +1,369 @@
+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/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.
+