1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book id="userspace_std_api_bltlib">
<bookinfo>
<title>bltlib
</title>
<copyright>
<year>2010</year>
<holder>ST-Ericsson AB</holder>
</copyright>
</bookinfo>
<toc></toc>
<chapter id="intro">
<title>Introduction</title>
<!-- Do NOT change the chapter id or title! -->
<para>
bltlib is a library and API towards the device driver for the B2R2 graphics hardware.
<!-- Do NOT change the chapter id or title!
For numbered lists, outside of the para tag,
use the tags
(orderedlist)
(listitem)(para) ... (/para)(/listitem)
...
(listitem)(para) ... (/para)(/listitem)
(orderedlist)
For a bulleted list, outside of the para tag,
use the tags
(itemizedlist)
(listitem)(para) ... (/para)(/listitem)
...
(listitem)(para) ... (/para)(/listitem)
(itemizedlist)
For a table, outside of the para tag,
use the tags
(table)
(title) ... (title)
(tgroup cols="number_of_columns")(tbody)
(row)(entry) ... (/entry) (entry) ... (/entry) (/row)
(row)(entry) ... (/entry) (entry) ... (/entry) (/row)
(/tbody)(/tgroup)
(/table)
To omit the title for the table, use (informaltable)
instead of (table).
For hyper-links, use (ulink) tag.
Avoid duplicating information into this chapter
that is better located in the UML model. -->
</para>
</chapter>
<chapter id="conformance-description">
<title>Conformance Description</title>
<!-- Do NOT change the chapter id or title! -->
<section id="conformance-description-intro">
<title>Introduction</title>
<para>This chapter describes conformance and implementation-defined
behaviour of the module.</para>
</section>
<section id="conformance-description-references">
<title>References</title>
<!-- Do NOT change the section id or title! -->
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Title</entry>
<entry>Web Link</entry>
</row>
</thead>
<tbody>
<!-- EXAMPLE:
<row>
<entry>OpenGL ES 1.1 - April 4, 2007 </entry>
<entry><ulink
url="http://www.khronos.org/registry/gles/specs/1.1/es_full_spec.1.1.10.pdf">http://www.khronos.org/registry/gles/specs/1.1/es_full_spec.1.1.10.pdf
</ulink></entry>
</row>
-->
<row>
<entry>OpenMAX AL 1.0.1</entry>
<entry><ulink
url="http://www.khronos.org/registry/omxal/">Khronos registry (OpenMAX AL)
</ulink></entry>
</row> -->
</tbody>
</tgroup>
</informaltable>
</para>
</section>
<section id="conformance-description-function-conformance">
<title>Function Conformance</title>
<!-- Do NOT change the section id or title! -->
<para>
TODO: For each function or set of functions,
supply one row indicating functions,
the header file defining the function
and the level of implementation support
provided by the platform.
A conformance description describes which features,
interfaces of the standard that are supported or not
supported.
While the UML model may reference features,
or featuresets or functionality, in the broad sence,
this table must explicitly list all functions or other
means of controlling the API, so that a developer
knows for each and every function if the function is
implemented or not.
All header files that defines functions
must be listed and linked using (ulink), and also
referenced in the toc-locations.xml file.
What is stated about functions, is also valid if the module
implements an API in another way, such as using methods,
operations or signals.
</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Functions</entry>
<entry>Header File</entry>
<entry>Description/Conformance</entry>
</row>
</thead>
<tbody>
<row>
<entry>All functions</entry>
<entry><ulink url="includes/blt_api.h">blt_api.h</ulink></entry>
<entry>Functions/Functionality are fully implemented</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
See Implementation Description for implementation-defined behaviour.
</para>
</section>
</chapter>
<chapter id="implementation-description">
<title>Implementation Description</title>
<!-- Do NOT change the chapter id or title! -->
<section id="implementation-description-details">
<title>Implementation details</title>
<!-- Do NOT change the section id or title! -->
<para>
The client fills in a blt_req struct with all of the information required for the
blitting job.
The request method then submits the job to the blitting driver and hardware.
The driver analyzes the job and splits it into the required nodes.
If the job is run in synchronous mode, the request method returns only when the
job has been completed (or has failed). If the job is run in asynchronous mode,
the request method returns immediately. The client can use the synch method to
wait for completion.
When a client sends a request to bltlib, the job is sorted into a prioritized queue.
When the job can acquire the resources it needs, it is dispatched to the blitting hardware.
<!-- TODO: Description of which features, interfaces of the standard
that are supported or vice versa.
Describe the behavior of the implementation for
implementation-specific features.
An implementation description describes the behavior of the
implementation of implementation-specific features.
An implementation-specific feature is a feature that the
standard does not fully specify or is specifically left up to
the implementer. All implementation-specific behavior must be
documented to make the interface usable.
The implementation description also needs to include sizes
or values that are specific to the implementation.
Other implementation-specific information that may need to be
included is limitations that are brought on by platform
hardware or software constraints. These constraints change the
standard behavior of the specified functionality and may impact
the software accessing the functionality.
Not every standard interface is exposed to the customer's
domains. Some interfaces are interfaces between platform
components and only documented in platform internal reference
manuals.
What to disclose in the documentation about an implementation
is generally quite limited. Only information that the user needs
to know about the implementation is to be described.
Restrict the documentation to phenomena that are externally
visible. Once information is exposed, other elements may rely
on it, and changes to the internal implementation will have a
more widespread effect. Avoid documenting more than is necessary.
While the UML model may reference features,
or featuresets or functionality, in the broad sence,
this table must explicitly list all functions or other
means of controlling the API that has been modified, extended or added,
so that a developer knows for each and every function
that the function does not execute in the same way as it
would do if implemented by another vendor than ST-Ericsson.
For functions added to the standard, ensure they are
documented in the relevant header file, using the documentation
format used by the standard, or doxygen, if the standard's
header files does not include any documentation.
Ensure that any header files added by ST-Ericsson is linked
to using (ulink), and that they are referenced in the
toc-locations.xml file.
What is stated about functions, is also valid if the module
implements an API in another way, such as using methods,
operations or signals.
Use an (informaltable) to specify details on function-by
function-level. -->
</para>
<!-- <para>EXAMPLE: ST-Ericsson provides the ARM reference implementation.</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Functions</entry>
<entry>Header File</entry>
<entry>Description/Conformance</entry>
</row>
</thead>
<tbody>
<row>
<entry></entry>
<entry></entry>
<entry><emphasis>TODO Modify example below</emphasis></entry>
</row>
<row>
<entry>g_function()</entry>
<entry><ulink url="includes/another_include_file.h">another_include_file.h</ulink></entry>
<entry>The function returns ... .
Restriction: The function can only be used ... .
</entry>
</row>
<row>
<entry>h_ste_function()</entry>
<entry><ulink url="includes/another_include_file.h">another_include_file.h</ulink></entry>
<entry>This function is an STE-extension to the standard.
</entry>
</row>
<row>
<entry>All functions</entry>
<entry><ulink url="includes/ste_extensions.h">ste_extensions.h</ulink></entry>
<entry>All functions in this file are STE-extensions to the standard.
</entry>
</row>
<row>
<entry>TODO: List functions</entry>
<entry><ulink
url="includes/an_include_file.h">
Provide a link using the ulink tag to the header file,
Ensure the url matches what is specified in
the toc_location.xml file using the
(includefile) or (includedirectory) elementsd in that
file.
</ulink></entry>
<entry>TODO: Describe extensions, restrictions, additions and
implementation-specific details.</entry>
</row>
</tbody>
</tgroup>
</informaltable> -->
</section>
<section id="implementation-description-supported-versions">
<title>Supported versions</title>
<!-- Do NOT change the section id or title! -->
<para>This section specifies the supported versions of the module. </para>
<para>
bltlib supports only a subset of the bitmap formats defined by OpenMAX,
due to limitations in the blitting hardware.
<!-- TODO: Specify the supported versions
The conformance description can also
describe the conformance degree (or level)
according to a definition given by the reference manual
or by the standard.
Standard interfaces can be implemented in more than one
place in the architecture. In those cases, the behavior
of the implementations can differ. Several coexisting
implementations affect the documentation.
If suitable, different implementations are documented by
the same category. The documentation shall clearly describe
that there are different implementations and the differences
between them. The differences between implementations are
expected to be small. -->
</para>
<para></para>
</section>
</chapter>
<chapter id="specifications">
<title>Specifications</title>
<!-- Do NOT change the chapter id or title! -->
<para>
bltlib does not implement a standard specification but defines its own API.
Still, it borrows from some of the data types used in OpenMAX.
</para>
<row>
<entry>OpenMAX AL 1.0.1</entry>
<entry></entry>
</row> -->
<itemizedlist>
<listitem>
<para>
<ulink
url="http://www.khronos.org/registry/omxal/">Khronos registry (OpenMAX AL)
</ulink>
</para>
</listitem>
</itemizedlist>
</chapter>
</book>
|
