tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
staging: ti dspbridge: add driver documentation
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>
authored by
Omar Ramirez Luna
and committed by
Greg Kroah-Hartman
6c5fe838
6c2bfdc7
+309
+82
drivers/staging/tidspbridge/Documentation/CONTRIBUTORS
+82
drivers/staging/tidspbridge/Documentation/CONTRIBUTORS
···
1
+
TI DSP/Bridge Driver - Contributors File
2
+
3
+
The DSP/Bridge project wish to thank all of its contributors, current bridge
4
+
driver is the result of the work of all of them. If any name is accidentally
5
+
omitted, let us know by sending a mail to omar.ramirez@ti.com or
6
+
x095840@ti.com.
7
+
8
+
Please keep the following list in alphabetical order.
9
+
10
+
Suman Anna
11
+
Sripal Bagadia
12
+
Felipe Balbi
13
+
Ohad Ben-Cohen
14
+
Phil Carmody
15
+
Deepak Chitriki
16
+
Felipe Contreras
17
+
Hiroshi Doyu
18
+
Seth Forshee
19
+
Ivan Gomez Castellanos
20
+
Mark Grosen
21
+
Ramesh Gupta G
22
+
Fernando Guzman Lugo
23
+
Axel Haslam
24
+
Janet Head
25
+
Shivananda Hebbar
26
+
Hari Kanigeri
27
+
Tony Lindgren
28
+
Antonio Luna
29
+
Hari Nagalla
30
+
Nishanth Menon
31
+
Ameya Palande
32
+
Vijay Pasam
33
+
Gilbert Pitney
34
+
Omar Ramirez Luna
35
+
Ernesto Ramos
36
+
Chris Ring
37
+
Larry Schiefer
38
+
Rebecca Schultz Zavin
39
+
Bhavin Shah
40
+
Andy Shevchenko
41
+
Jeff Taylor
42
+
Roman Tereshonkov
43
+
Armando Uribe de Leon
44
+
Nischal Varide
45
+
Wenbiao Wang
46
+
47
+
48
+
49
+
The following list was taken from file Revision History, if you recognize your
50
+
alias or did any contribution to the project please let us now, so we can
51
+
proper credit your work.
52
+
53
+
ag
54
+
ap
55
+
cc
56
+
db
57
+
dh4
58
+
dr
59
+
hp
60
+
jg
61
+
kc
62
+
kln
63
+
kw
64
+
ge
65
+
gv
66
+
map
67
+
mf
68
+
mk
69
+
mr
70
+
nn
71
+
rajesh
72
+
rg
73
+
rr
74
+
rt
75
+
sb
76
+
sg
77
+
sh
78
+
sp
79
+
srid
80
+
swa
81
+
vp
82
+
ww
+70
drivers/staging/tidspbridge/Documentation/README
+70
drivers/staging/tidspbridge/Documentation/README
···
1
+
Linux DSP/BIOS Bridge release
2
+
3
+
DSP/BIOS Bridge overview
4
+
========================
5
+
6
+
DSP/BIOS Bridge is designed for platforms that contain a GPP and one or more
7
+
attached DSPs. The GPP is considered the master or "host" processor, and the
8
+
attached DSPs are processing resources that can be utilized by applications
9
+
and drivers running on the GPP.
10
+
11
+
The abstraction that DSP/BIOS Bridge supplies, is a direct link between a GPP
12
+
program and a DSP task. This communication link is partitioned into two
13
+
types of sub-links: messaging (short, fixed-length packets) and data
14
+
streaming (multiple, large buffers). Each sub-link operates independently,
15
+
and features in-order delivery of data, meaning that messages are delivered
16
+
in the order they were submitted to the message link, and stream buffers are
17
+
delivered in the order they were submitted to the stream link.
18
+
19
+
In addition, a GPP client can specify what inputs and outputs a DSP task
20
+
uses. DSP tasks typically use message objects for passing control and status
21
+
information and stream objects for efficient streaming of real-time data.
22
+
23
+
GPP Software Architecture
24
+
=========================
25
+
26
+
A GPP application communicates with its associated DSP task running on the
27
+
DSP subsystem using the DSP/BIOS Bridge API. For example, a GPP audio
28
+
application can use the API to pass messages to a DSP task that is managing
29
+
data flowing from analog-to-digital converters (ADCs) to digital-to-analog
30
+
converters (DACs).
31
+
32
+
From the perspective of the GPP OS, the DSP is treated as just another
33
+
peripheral device. Most high level GPP OS typically support a device driver
34
+
model, whereby applications can safely access and share a hardware peripheral
35
+
through standard driver interfaces. Therefore, to allow multiple GPP
36
+
applications to share access to the DSP, the GPP side of DSP/BIOS Bridge
37
+
implements a device driver for the DSP.
38
+
39
+
Since driver interfaces are not always standard across GPP OS, and to provide
40
+
some level of interoperability of application code using DSP/BIOS Bridge
41
+
between GPP OS, DSP/BIOS Bridge provides a standard library of APIs which
42
+
wrap calls into the device driver. So, rather than calling GPP OS specific
43
+
driver interfaces, applications (and even other device drivers) can use the
44
+
standard API library directly.
45
+
46
+
DSP Software Architecture
47
+
=========================
48
+
49
+
For DSP/BIOS, DSP/BIOS Bridge adds a device-independent streaming I/O (STRM)
50
+
interface, a messaging interface (NODE), and a Resource Manager (RM) Server.
51
+
The RM Server runs as a task of DSP/BIOS and is subservient to commands
52
+
and queries from the GPP. It executes commands to start and stop DSP signal
53
+
processing nodes in response to GPP programs making requests through the
54
+
(GPP-side) API.
55
+
56
+
DSP tasks started by the RM Server are similar to any other DSP task with two
57
+
important differences: they must follow a specific task model consisting of
58
+
three C-callable functions (node create, execute, and delete), with specific
59
+
sets of arguments, and they have a pre-defined task environment established
60
+
by the RM Server.
61
+
62
+
Tasks started by the RM Server communicate using the STRM and NODE interfaces
63
+
and act as servers for their corresponding GPP clients, performing signal
64
+
processing functions as requested by messages sent by their GPP client.
65
+
Typically, a DSP task moves data from source devices to sink devices using
66
+
device independent I/O streams, performing application-specific processing
67
+
and transformations on the data while it is moved. For example, an audio
68
+
task might perform audio decompression (ADPCM, MPEG, CELP) on data received
69
+
from a GPP audio driver and then send the decompressed linear samples to a
70
+
digital-to-analog converter.
+157
drivers/staging/tidspbridge/Documentation/error-codes
+157
drivers/staging/tidspbridge/Documentation/error-codes
···
1
+
DSP/Bridge Error Code Guide
2
+
3
+
4
+
Success code is always taken as 0, except for one case where a success status
5
+
different than 0 can be possible, this is when enumerating a series of dsp
6
+
objects, if the enumeration doesn't have any more objects it is considered as a
7
+
successful case. In this case a positive ENODATA is returned (TODO: Change to
8
+
avoid this case).
9
+
10
+
Error codes are returned as a negative 1, if an specific code is expected, it
11
+
can be propagated to user space by reading errno symbol defined in errno.h, for
12
+
specific details on the implementation a copy of the standard used should be
13
+
read first.
14
+
15
+
The error codes used by this driver are:
16
+
17
+
[EPERM]
18
+
General driver failure.
19
+
20
+
According to the use case the following might apply:
21
+
- Device is in 'sleep/suspend' mode due to DPM.
22
+
- User cannot mark end of stream on an input channel.
23
+
- Requested operation is invalid for the node type.
24
+
- Invalid alignment for the node messaging buffer.
25
+
- The specified direction is invalid for the stream.
26
+
- Invalid stream mode.
27
+
28
+
[ENOENT]
29
+
The specified object or file was not found.
30
+
31
+
[ESRCH]
32
+
A shared memory buffer contained in a message or stream could not be mapped
33
+
to the GPP client process's virtual space.
34
+
35
+
[EIO]
36
+
Driver interface I/O error.
37
+
38
+
or:
39
+
- Unable to plug channel ISR for configured IRQ.
40
+
- No free I/O request packets are available.
41
+
42
+
[ENXIO]
43
+
Unable to find a named section in DSP executable or a non-existent memory
44
+
segment identifier was specified.
45
+
46
+
[EBADF]
47
+
General error for file handling:
48
+
49
+
- Unable to open file.
50
+
- Unable to read file.
51
+
- An error occurred while parsing the DSP executable file.
52
+
53
+
[ENOMEM]
54
+
A memory allocation failure occurred.
55
+
56
+
[EACCES]
57
+
- Unable to read content of DCD data section; this is typically caused by
58
+
improperly configured nodes.
59
+
- Unable to decode DCD data section content; this is typically caused by
60
+
changes to DSP/BIOS Bridge data structures.
61
+
- Unable to get pointer to DCD data section; this is typically caused by
62
+
improperly configured UUIDs.
63
+
- Unable to load file containing DCD data section; this is typically
64
+
caused by a missing COFF file.
65
+
- The specified COFF file does not contain a valid node registration
66
+
section.
67
+
68
+
[EFAULT]
69
+
Invalid pointer or handler.
70
+
71
+
[EEXIST]
72
+
Attempted to create a channel manager when one already exists.
73
+
74
+
[EINVAL]
75
+
Invalid argument.
76
+
77
+
[ESPIPE]
78
+
Symbol not found in the COFF file. DSPNode_Create will return this if
79
+
the iAlg function table for an xDAIS socket is not found in the COFF file.
80
+
In this case, force the symbol to be linked into the COFF file.
81
+
DSPNode_Create, DSPNode_Execute, and DSPNode_Delete will return this if
82
+
the create, execute, or delete phase function, respectively, could not be
83
+
found in the COFF file.
84
+
85
+
- No symbol table is loaded/found for this board.
86
+
- Unable to initialize the ZL COFF parsing module.
87
+
88
+
[EPIPE]
89
+
I/O is currently pending.
90
+
91
+
- End of stream was already requested on this output channel.
92
+
93
+
[EDOM]
94
+
A parameter is specified outside its valid range.
95
+
96
+
[ENOSYS]
97
+
The indicated operation is not supported.
98
+
99
+
[EIDRM]
100
+
During enumeration a change in the number or properties of the objects
101
+
has occurred.
102
+
103
+
[ECHRNG]
104
+
Attempt to created channel manager with too many channels or channel ID out
105
+
of range.
106
+
107
+
[EBADR]
108
+
The state of the specified object is incorrect for the requested operation.
109
+
110
+
- Invalid segment ID.
111
+
112
+
[ENODATA]
113
+
Unable to retrieve resource information from the registry.
114
+
115
+
- No more registry values.
116
+
117
+
[ETIME]
118
+
A timeout occurred before the requested operation could complete.
119
+
120
+
[ENOSR]
121
+
A stream has been issued the maximum number of buffers allowed in the
122
+
stream at once; buffers must be reclaimed from the stream before any more
123
+
can be issued.
124
+
125
+
- No free channels are available.
126
+
127
+
[EILSEQ]
128
+
Error occurred in a dynamic loader library function.
129
+
130
+
[EISCONN]
131
+
The Specified Connection already exists.
132
+
133
+
[ENOTCONN]
134
+
Nodes not connected.
135
+
136
+
[ETIMEDOUT]
137
+
Timeout occurred waiting for a response from the hardware.
138
+
139
+
- Wait for flush operation on an output channel timed out.
140
+
141
+
[ECONNREFUSED]
142
+
No more connections can be made for this node.
143
+
144
+
[EALREADY]
145
+
Channel is already in use.
146
+
147
+
[EREMOTEIO]
148
+
dwTimeOut parameter was CHNL_IOCNOWAIT, yet no I/O completions were
149
+
queued.
150
+
151
+
[ECANCELED]
152
+
I/O has been cancelled on this channel.
153
+
154
+
[ENOKEY]
155
+
Invalid subkey parameter.
156
+
157
+
- UUID not found in registry.