Staging: add speakup to the staging directory

Speakup is a kernel based screen review package for the linux operating
system.  It allows blind users to interact with applications on the
linux console by means of synthetic speech.

The authors and maintainers of this code include the following:

Kirk Reiser, Andy Berdan, John Covici, Brian and
David Borowski, Christopher Brannon, Samuel Thibault and William Hubbs.

Signed-off-by: William Hubbs <w.d.hubbs@gmail.com>
Signed-off-by: Samuel Thibault <samuel.thibault@ens-lyon.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

drivers/staging/Kconfig

@@ -173,5 +173,7 @@ source "drivers/staging/ft1000/Kconfig"
 
 source "drivers/staging/intel_sst/Kconfig"
 
+source "drivers/staging/speakup/Kconfig"
+
 endif # !STAGING_EXCLUDE_BUILD
 endif # STAGING

drivers/staging/Makefile

@@ -67,3 +67,4 @@ obj-$(CONFIG_USB_ENESTORAGE)	+= keucr/
 obj-$(CONFIG_BCM_WIMAX)	+= bcm/
 obj-$(CONFIG_FT1000)		+= ft1000/
 obj-$(CONFIG_SND_INTEL_SST)		+= intel_sst/
+obj-$(CONFIG_SPEAKUP)	+= speakup/

drivers/staging/speakup/DefaultKeyAssignments

@@ -0,0 +1,46 @@
+This file is intended to give you an overview of the default keys used
+by speakup for it's review functions.  You may change them to be
+anything you want but that will take some familiarity with key
+mapping.
+
+We have remapped the insert or zero key on the keypad to act as a
+shift key.  Well, actually as an altgr key.  So in the following list
+InsKeyPad-period means hold down the insert key like a shift key and
+hit the keypad period.
+
+KeyPad-8		Say current Line
+InsKeyPad-8		say from top of screen to reading cursor.
+KeyPad-7		Say Previous Line (UP one line)
+KeyPad-9		Say Next Line (down one line)
+KeyPad-5		Say Current Word
+InsKeyPad-5		Spell Current Word
+KeyPad-4		Say Previous Word (left one word)
+InsKeyPad-4		say from left edge of line to reading cursor.
+KeyPad-6		Say Next Word (right one word)
+InsKeyPad-6		Say from reading cursor to right edge of line.
+KeyPad-2		Say Current Letter
+InsKeyPad-2		say current letter phonetically
+KeyPad-1		Say Previous Character (left one letter)
+KeyPad-3		Say Next Character (right one letter)
+KeyPad-plus		Say Entire Screen
+InsKeyPad-plus		Say from reading cursor line to bottom of screen.
+KeyPad-Minus		Park reading cursor (toggle)
+InsKeyPad-minus		Say character hex and decimal value.
+KeyPad-period		Say Position (current line, position and console)
+InsKeyPad-period	say colour attributes of current position.
+InsKeyPad-9		Move reading cursor to top of screen (insert pgup)
+InsKeyPad-3		Move reading cursor to bottom of screen (insert pgdn)
+InsKeyPad-7		Move reading cursor to left edge of screen (insert home)
+InsKeyPad-1		Move reading cursor to right edge of screen (insert end)
+ControlKeyPad-1		Move reading cursor to last character on current line.
+KeyPad-Enter		Shut Up (until another key is hit) and sync reading cursor
+InsKeyPad-Enter		Shut Up (until toggled back on).
+InsKeyPad-star n<x|y>	go to line (y) or column (x). Where 'n' is any
+		allowed value for the row or column for your current screen.
+KeyPad-/		Mark and Cut screen region.
+InsKeyPad-/		Paste screen region into any console.
+
+Hitting any key while speakup is outputting speech will quiet the
+synth until it has caught up with what is being printed on the
+console.
+

drivers/staging/speakup/Kconfig

@@ -0,0 +1,195 @@
+menu "Speakup console speech"
+
+config SPEAKUP
+	depends on VT
+	tristate "Speakup core"
+	---help---
+		This is the Speakup screen reader.  Think of it as a
+		video console for blind people.  If built in to the
+		kernel, it can speak everything on the text console from
+		boot up to shutdown.  For more information on Speakup,
+		point your browser at http://www.linux-speakup.org/.
+		There is also a mailing list at the above url that you
+		can subscribe to.
+
+		Supported synthesizers are accent sa, accent pc,
+		appollo II., Auddapter, Braille 'n Speak, Dectalk
+		external (old), Dectalk PC (full length isa board),
+		Dectalk express, Doubletalk, Doubletalk LT or
+		Litetalk, Keynote Gold internal PC, software
+		synthesizers, Speakout, transport, and a dummy module
+		that can be used with a plain text terminal.
+
+		Speakup can either be built in or compiled as a module
+		by answering y or m.  If you answer y here, then you
+		must answer either y or m to at least one of the
+		synthesizer drivers below.  If you answer m here, then
+		the synthesizer drivers below can only be built as
+		modules.
+
+		These drivers are not standalone drivers, but must be
+		used in conjunction with Speakup.  Think of them as
+		video cards for blind people.
+
+
+		The Dectalk pc driver can only be built as a module, and
+		requires software to be pre-loaded on to the card before
+		the module can be loaded.  See the decpc choice below
+		for more details.
+
+		If you are not a blind person, or don't have access to
+		one of the listed synthesizers, you should say n.
+
+if SPEAKUP
+config SPEAKUP_SYNTH_ACNTSA
+	tristate "Accent SA synthesizer support"
+	---help---
+		This is the Speakup driver for the Accent SA
+		synthesizer.  You can say y to build it into the kernel,
+		or m to build it as a module.  See the configuration
+		help on the Speakup choice above for more info.
+
+config SPEAKUP_SYNTH_ACNTPC
+	tristate "Accent PC synthesizer support"
+	---help---
+		This is the Speakup driver for the accent pc
+		synthesizer.  You can say y to build it into the kernel,
+		or m to build it as a module.  See the configuration
+		help on the Speakup choice above for more info.
+
+config SPEAKUP_SYNTH_APOLLO
+	tristate "Apollo II synthesizer support"
+	---help---
+		This is the Speakup driver for the Apollo II
+		synthesizer.  You can say y to build it into the kernel,
+		or m to build it as a module.  See the configuration
+		help on the Speakup choice above for more info.
+
+config SPEAKUP_SYNTH_AUDPTR
+	tristate "Audapter synthesizer support"
+	---help---
+		This is the Speakup driver for the Audapter synthesizer.
+		 You can say y to build it into the kernel, or m to
+		build it as a module.  See the configuration help on the
+		Speakup choice above for more info.
+
+config SPEAKUP_SYNTH_BNS
+	tristate "Braille 'n' Speak synthesizer support"
+	---help---
+		This is the Speakup driver for the Braille 'n' Speak
+		synthesizer.  You can say y to build it into the kernel,
+		or m to build it as a module.  See the configuration
+		help on the Speakup choice above for more info.
+
+config SPEAKUP_SYNTH_DECTLK
+	tristate "DECtalk Express synthesizer support"
+	---help---
+
+		This is the Speakup driver for the DecTalk Express
+		synthesizer.  You can say y to build it into the kernel,
+		or m to build it as a module.  See the configuration
+		help on the Speakup choice above for more info.
+
+config SPEAKUP_SYNTH_DECEXT
+	tristate "DECtalk External (old) synthesizer support"
+	---help---
+
+		This is the Speakup driver for the DecTalk External
+		(old) synthesizer.  You can say y to build it into the
+		kernel, or m to build it as a module.  See the
+		configuration help on the Speakup choice above for more
+		info.
+
+config SPEAKUP_SYNTH_DECPC
+	depends on m
+	tristate "DECtalk PC (big ISA card) synthesizer support"
+	---help---
+
+		This is the Speakup driver for the DecTalk PC (full
+		length ISA) synthesizer.  You can say m to build it as
+		a module.  See the configuration help on the Speakup
+		choice above for more info.
+
+		In order to use the DecTalk PC driver, you must download
+		the dec_pc.tgz file from linux-speakup.org.  It is in
+		the pub/linux/goodies directory.  The dec_pc.tgz file
+		contains the software which must be pre-loaded on to the
+		DecTalk PC board in order to use it with this driver.
+		This driver must be built as a module, and can not be
+		loaded until the file system is mounted and the DecTalk
+		PC software has been pre-loaded on to the board.
+
+		See the README file in the dec_pc.tgz file for more
+		details.
+
+config SPEAKUP_SYNTH_DTLK
+	tristate "DoubleTalk PC synthesizer support"
+	---help---
+
+		This is the Speakup driver for the internal DoubleTalk
+		PC synthesizer.  You can say y to build it into the
+		kernel, or m to build it as a module.  See the
+		configuration help on the Speakup choice above for more
+		info.
+
+config SPEAKUP_SYNTH_KEYPC
+	tristate "Keynote Gold PC synthesizer support"
+	---help---
+
+		This is the Speakup driver for the Keynote Gold
+		PC synthesizer.  You can say y to build it into the
+		kernel, or m to build it as a module.  See the
+		configuration help on the Speakup choice above for more
+		info.
+
+config SPEAKUP_SYNTH_LTLK
+	tristate "DoubleTalk LT/LiteTalk synthesizer support"
+---help---
+
+		This is the Speakup driver for the LiteTalk/DoubleTalk
+		LT synthesizer.  You can say y to build it into the
+		kernel, or m to build it as a module.  See the
+		configuration help on the Speakup choice above for more
+		info.
+
+config SPEAKUP_SYNTH_SOFT
+	tristate "Userspace software synthesizer support"
+	---help---
+
+		This is the software synthesizer device node.  It will
+		register a device /dev/softsynth which midware programs
+		and speech daemons may open and read to provide kernel
+		output to software synths such as espeak, festival,
+		flite and so forth.  You can select 'y' or 'm' to have
+		it built-in to the kernel or loaded as a module.
+
+config SPEAKUP_SYNTH_SPKOUT
+	tristate "Speak Out synthesizer support"
+	---help---
+
+		This is the Speakup driver for the Speakout synthesizer.
+		 You can say y to build it into the kernel, or m to
+		build it as a module.  See the configuration help on the
+		Speakup choice above for more info.
+
+config SPEAKUP_SYNTH_TXPRT
+	tristate "Transport synthesizer support"
+	---help---
+
+		This is the Speakup driver for the Transport
+		synthesizer.  You can say y to build it into the kernel,
+		or m to build it as a module.  See the configuration
+		help on the Speakup choice above for more info.
+
+config SPEAKUP_SYNTH_DUMMY
+	tristate "Dummy synthesizer driver (for testing)"
+	---help---
+
+		This is a dummy Speakup driver for plugging a mere serial
+		terminal.  This is handy if you want to test speakup but
+		don't have the hardware.  You can say y to build it into
+		the kernel, or m to build it as a module.  See the
+		configuration help on the Speakup choice above for more info.
+
+endif	# SPEAKUP
+endmenu

drivers/staging/speakup/Makefile

@@ -0,0 +1,30 @@
+obj-$(CONFIG_SPEAKUP_SYNTH_ACNTSA) += speakup_acntsa.o
+obj-$(CONFIG_SPEAKUP_SYNTH_ACNTPC) += speakup_acntpc.o
+obj-$(CONFIG_SPEAKUP_SYNTH_APOLLO) += speakup_apollo.o
+obj-$(CONFIG_SPEAKUP_SYNTH_AUDPTR) += speakup_audptr.o
+obj-$(CONFIG_SPEAKUP_SYNTH_BNS) += speakup_bns.o
+obj-$(CONFIG_SPEAKUP_SYNTH_DECTLK) += speakup_dectlk.o
+obj-$(CONFIG_SPEAKUP_SYNTH_DECEXT) += speakup_decext.o
+obj-$(CONFIG_SPEAKUP_SYNTH_DECPC) += speakup_decpc.o
+obj-$(CONFIG_SPEAKUP_SYNTH_DTLK) += speakup_dtlk.o
+obj-$(CONFIG_SPEAKUP_SYNTH_KEYPC) += speakup_keypc.o
+obj-$(CONFIG_SPEAKUP_SYNTH_LTLK) += speakup_ltlk.o
+obj-$(CONFIG_SPEAKUP_SYNTH_SOFT) += speakup_soft.o
+obj-$(CONFIG_SPEAKUP_SYNTH_SPKOUT) += speakup_spkout.o
+obj-$(CONFIG_SPEAKUP_SYNTH_TXPRT) += speakup_txprt.o
+obj-$(CONFIG_SPEAKUP_SYNTH_DUMMY) += speakup_dummy.o
+
+obj-$(CONFIG_SPEAKUP) += speakup.o
+speakup-objs := \
+	buffers.o \
+	devsynth.o \
+	i18n.o \
+	fakekey.o \
+	main.o \
+	keyhelp.o \
+	kobjects.o \
+	selection.o \
+	serialio.o \
+	synth.o \
+	thread.o \
+	varhandlers.o

drivers/staging/speakup/TODO

@@ -0,0 +1,47 @@
+Speakup project home:  http://www.linux-speakup.org
+
+Mailing List:  speakup@braille.uwo.ca
+
+Speakup is a kernel based screen review package for the linux operating
+system.  It allows blind users to interact with applications on the
+linux console by means of synthetic speech.
+
+Currently, speakup has several issues we know of.
+
+The first issue has to do with the way speakup communicates with serial
+ports.  Currently, we communicate directly with the hardware
+ports. This however conflicts with the standard serial port drivers,
+which poses various problems. This is also not working for modern hardware
+such as PCI-based serial ports.  Also, there is not a way we can
+communicate with USB devices.  The current serial port handling code is
+in serialio.c in this directory.
+
+Some places are currently using in_atomic() because speakup functions
+are called in various contexts, and a couple of things can't happen
+in these cases. Pushing work to some worker thread would probably help,
+as was already done for the serial port driving part.
+
+There is a duplication of the selection functions in selections.c. These
+functions should get exported from drivers/char/selection.c (clear_selection
+notably) and used from there instead.
+
+The kobjects may have to move to a more proper place in /sys. The
+discussion on lkml resulted to putting speech synthesizers in the
+"speech" class, and the speakup screen reader itself into
+/sys/class/vtconsole/vtcon0/speakup, the nasty path being handled by
+userland tools.
+
+Another issue seems to only happen on SMP systems.  It seems
+that text in the output buffer gets garbled because a lock is not set.
+This bug happens regularly, but no one has been able to find a situation
+which produces it consistently.
+
+Patches, suggestions, corrections, etc, are definitely welcome.
+
+We prefer that you contact us on the mailing list; however, if you do
+not want to subscribe to a mailing list, send your email to all of the
+following:
+
+w.d.hubbs@gmail.com, chris@the-brannons.com, kirk@braille.uwo.ca and
+samuel.thibault@ens-lyon.org.
+