redonkable/alistair23-linux
redonkable/alistair23-linux
1
0
Fork 0
Code Releases Activity

staging: ti dspbridge: add driver documentation

Browse source 
Add a README with a general overview of TI's DSP Bridge driver,
a short explanations of how error codes are currently used,
and a CONTRIBUTORS file with all past & present contributors.

For additional information about TI's DSP Bridge,
check out http://omapzoom.org/gf/project/omapbridge/docman/?subdir=3

Note: if by any chance we forgot to mention any contributor,
please let us know and we will fix that.

Signed-off-by: Omar Ramirez Luna <omar.ramirez@ti.com>
Signed-off-by: Kanigeri, Hari <h-kanigeri2@ti.com>
Signed-off-by: Ameya Palande <ameya.palande@nokia.com>
Signed-off-by: Guzman Lugo, Fernando <fernando.lugo@ti.com>
Signed-off-by: Hebbar, Shivananda <x0hebbar@ti.com>
Signed-off-by: Ramos Falcon, Ernesto <ernesto@ti.com>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Anna, Suman <s-anna@ti.com>
Signed-off-by: Gupta, Ramesh <grgupta@ti.com>
Signed-off-by: Gomez Castellanos, Ivan <ivan.gomez@ti.com>
Signed-off-by: Andy Shevchenko <ext-andriy.shevchenko@nokia.com>
Signed-off-by: Armando Uribe De Leon <x0095078@ti.com>
Signed-off-by: Deepak Chitriki <deepak.chitriki@ti.com>
Signed-off-by: Menon, Nishanth <nm@ti.com>
Signed-off-by: Phil Carmody <ext-phil.2.carmody@nokia.com>
Signed-off-by: Ohad Ben-Cohen <ohad@wizery.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
This commit is contained in:
Omar Ramirez Luna 2010-06-23 16:01:55 +03:00 committed by Greg Kroah-Hartman
parent 6c2bfdc77f
commit 6c5fe83876
3 changed files with 309 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

82
drivers/staging/tidspbridge/Documentation/CONTRIBUTORS Normal file
View file

@ -0,0 +1,82 @@
TI DSP/Bridge Driver - Contributors File
The DSP/Bridge project wish to thank all of its contributors, current bridge
driver is the result of the work of all of them. If any name is accidentally
omitted, let us know by sending a mail to omar.ramirez@ti.com or
x095840@ti.com.
Please keep the following list in alphabetical order.
Suman Anna
Sripal Bagadia
Felipe Balbi
Ohad Ben-Cohen
Phil Carmody
Deepak Chitriki
Felipe Contreras
Hiroshi Doyu
Seth Forshee
Ivan Gomez Castellanos
Mark Grosen
Ramesh Gupta G
Fernando Guzman Lugo
Axel Haslam
Janet Head
Shivananda Hebbar
Hari Kanigeri
Tony Lindgren
Antonio Luna
Hari Nagalla
Nishanth Menon
Ameya Palande
Vijay Pasam
Gilbert Pitney
Omar Ramirez Luna
Ernesto Ramos
Chris Ring
Larry Schiefer
Rebecca Schultz Zavin
Bhavin Shah
Andy Shevchenko
Jeff Taylor
Roman Tereshonkov
Armando Uribe de Leon
Nischal Varide
Wenbiao Wang
The following list was taken from file Revision History, if you recognize your
alias or did any contribution to the project please let us now, so we can
proper credit your work.
ag
ap
cc
db
dh4
dr
hp
jg
kc
kln
kw
ge
gv
map
mf
mk
mr
nn
rajesh
rg
rr
rt
sb
sg
sh
sp
srid
swa
vp
ww

70
drivers/staging/tidspbridge/Documentation/README Normal file
View file

@ -0,0 +1,70 @@
Linux DSP/BIOS Bridge release
DSP/BIOS Bridge overview
========================
DSP/BIOS Bridge is designed for platforms that contain a GPP and one or more
attached DSPs. The GPP is considered the master or "host" processor, and the
attached DSPs are processing resources that can be utilized by applications
and drivers running on the GPP.
The abstraction that DSP/BIOS Bridge supplies, is a direct link between a GPP
program and a DSP task. This communication link is partitioned into two
types of sub-links: messaging (short, fixed-length packets) and data
streaming (multiple, large buffers). Each sub-link operates independently,
and features in-order delivery of data, meaning that messages are delivered
in the order they were submitted to the message link, and stream buffers are
delivered in the order they were submitted to the stream link.
In addition, a GPP client can specify what inputs and outputs a DSP task
uses. DSP tasks typically use message objects for passing control and status
information and stream objects for efficient streaming of real-time data.
GPP Software Architecture
=========================
A GPP application communicates with its associated DSP task running on the
DSP subsystem using the DSP/BIOS Bridge API. For example, a GPP audio
application can use the API to pass messages to a DSP task that is managing
data flowing from analog-to-digital converters (ADCs) to digital-to-analog
converters (DACs).
From the perspective of the GPP OS, the DSP is treated as just another
peripheral device. Most high level GPP OS typically support a device driver
model, whereby applications can safely access and share a hardware peripheral
through standard driver interfaces. Therefore, to allow multiple GPP
applications to share access to the DSP, the GPP side of DSP/BIOS Bridge
implements a device driver for the DSP.
Since driver interfaces are not always standard across GPP OS, and to provide
some level of interoperability of application code using DSP/BIOS Bridge
between GPP OS, DSP/BIOS Bridge provides a standard library of APIs which
wrap calls into the device driver. So, rather than calling GPP OS specific
driver interfaces, applications (and even other device drivers) can use the
standard API library directly.
DSP Software Architecture
=========================
For DSP/BIOS, DSP/BIOS Bridge adds a device-independent streaming I/O (STRM)
interface, a messaging interface (NODE), and a Resource Manager (RM) Server.
The RM Server runs as a task of DSP/BIOS and is subservient to commands
and queries from the GPP. It executes commands to start and stop DSP signal
processing nodes in response to GPP programs making requests through the
(GPP-side) API.
DSP tasks started by the RM Server are similar to any other DSP task with two
important differences: they must follow a specific task model consisting of
three C-callable functions (node create, execute, and delete), with specific
sets of arguments, and they have a pre-defined task environment established
by the RM Server.
Tasks started by the RM Server communicate using the STRM and NODE interfaces
and act as servers for their corresponding GPP clients, performing signal
processing functions as requested by messages sent by their GPP client.
Typically, a DSP task moves data from source devices to sink devices using
device independent I/O streams, performing application-specific processing
and transformations on the data while it is moved. For example, an audio
task might perform audio decompression (ADPCM, MPEG, CELP) on data received
from a GPP audio driver and then send the decompressed linear samples to a
digital-to-analog converter.

157
drivers/staging/tidspbridge/Documentation/error-codes Normal file
View file

@ -0,0 +1,157 @@
DSP/Bridge Error Code Guide
Success code is always taken as 0, except for one case where a success status
different than 0 can be possible, this is when enumerating a series of dsp
objects, if the enumeration doesn't have any more objects it is considered as a
successful case. In this case a positive ENODATA is returned (TODO: Change to
avoid this case).
Error codes are returned as a negative 1, if an specific code is expected, it
can be propagated to user space by reading errno symbol defined in errno.h, for
specific details on the implementation a copy of the standard used should be
read first.
The error codes used by this driver are:
[EPERM]
General driver failure.
According to the use case the following might apply:
- Device is in 'sleep/suspend' mode due to DPM.
- User cannot mark end of stream on an input channel.
- Requested operation is invalid for the node type.
- Invalid alignment for the node messaging buffer.
- The specified direction is invalid for the stream.
- Invalid stream mode.
[ENOENT]
The specified object or file was not found.
[ESRCH]
A shared memory buffer contained in a message or stream could not be mapped
to the GPP client process's virtual space.
[EIO]
Driver interface I/O error.
or:
- Unable to plug channel ISR for configured IRQ.
- No free I/O request packets are available.
[ENXIO]
Unable to find a named section in DSP executable or a non-existent memory
segment identifier was specified.
[EBADF]
General error for file handling:
- Unable to open file.
- Unable to read file.
- An error occurred while parsing the DSP executable file.
[ENOMEM]
A memory allocation failure occurred.
[EACCES]
- Unable to read content of DCD data section; this is typically caused by
improperly configured nodes.
- Unable to decode DCD data section content; this is typically caused by
changes to DSP/BIOS Bridge data structures.
- Unable to get pointer to DCD data section; this is typically caused by
improperly configured UUIDs.
- Unable to load file containing DCD data section; this is typically
caused by a missing COFF file.
- The specified COFF file does not contain a valid node registration
section.
[EFAULT]
Invalid pointer or handler.
[EEXIST]
Attempted to create a channel manager when one already exists.
[EINVAL]
Invalid argument.
[ESPIPE]
Symbol not found in the COFF file. DSPNode_Create will return this if
the iAlg function table for an xDAIS socket is not found in the COFF file.
In this case, force the symbol to be linked into the COFF file.
DSPNode_Create, DSPNode_Execute, and DSPNode_Delete will return this if
the create, execute, or delete phase function, respectively, could not be
found in the COFF file.
- No symbol table is loaded/found for this board.
- Unable to initialize the ZL COFF parsing module.
[EPIPE]
I/O is currently pending.
- End of stream was already requested on this output channel.
[EDOM]
A parameter is specified outside its valid range.
[ENOSYS]
The indicated operation is not supported.
[EIDRM]
During enumeration a change in the number or properties of the objects
has occurred.
[ECHRNG]
Attempt to created channel manager with too many channels or channel ID out
of range.
[EBADR]
The state of the specified object is incorrect for the requested operation.
- Invalid segment ID.
[ENODATA]
Unable to retrieve resource information from the registry.
- No more registry values.
[ETIME]
A timeout occurred before the requested operation could complete.
[ENOSR]
A stream has been issued the maximum number of buffers allowed in the
stream at once; buffers must be reclaimed from the stream before any more
can be issued.
- No free channels are available.
[EILSEQ]
Error occurred in a dynamic loader library function.
[EISCONN]
The Specified Connection already exists.
[ENOTCONN]
Nodes not connected.
[ETIMEDOUT]
Timeout occurred waiting for a response from the hardware.
- Wait for flush operation on an output channel timed out.
[ECONNREFUSED]
No more connections can be made for this node.
[EALREADY]
Channel is already in use.
[EREMOTEIO]
dwTimeOut parameter was CHNL_IOCNOWAIT, yet no I/O completions were
queued.
[ECANCELED]
I/O has been cancelled on this channel.
[ENOKEY]
Invalid subkey parameter.
- UUID not found in registry.