author | Graeme Price <GRAEME.PRICE@NOKIA.COM> |
Fri, 15 Oct 2010 14:32:18 +0100 | |
changeset 15 | 307f4279f433 |
permissions | -rw-r--r-- |
15
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
1 |
<?xml version="1.0" encoding="utf-8"?> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
2 |
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
3 |
<!-- This component and the accompanying materials are made available under the terms of the License |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
4 |
"Eclipse Public License v1.0" which accompanies this distribution, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
5 |
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
6 |
<!-- Initial Contributors: |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
7 |
Nokia Corporation - initial contribution. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
8 |
Contributors: |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
9 |
--> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
10 |
<!DOCTYPE concept |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
11 |
PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
12 |
<concept id="GUID-3722B946-07CF-4AEA-B228-E50642D6B5BE" xml:lang="en"><title>Register Access Implementation Guide</title><shortdesc>Describes the implementation of the Register Access platform |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
13 |
service.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
14 |
<p>A ASSP hardware register is a physical interface to an item of |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
15 |
hardware which contains values, such as bit fields, for controlling |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
16 |
ASSP features.</p> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
17 |
<section id="GUID-514E76B0-009C-48D4-935C-FBE48FDD3631-GENID-1-2-1-10-1-5-1-8-1-1-9-1-4-1-3-2"><title>ASSP</title><p> An ASSP (Application Specific Standard Product) is a class of |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
18 |
integrated circuit. Different ASSPs have different architectures and |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
19 |
instructions sets. The <xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita"><apiname>AsspRegister</apiname></xref> class provides device driver writers with a simple interface to |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
20 |
access ASSP registers. Hardware implementers must provide the specified |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
21 |
functionality on a given platform and ASSP by writing the appropriate |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
22 |
machine instructions. </p></section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
23 |
<section id="GUID-DBEB025D-B457-493B-A052-274801C21B1E"><title>Pre-requisites</title><p>Before the implementing a register access implementation, the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
24 |
following must be decided:</p><ul> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
25 |
<li><p>The area in memory to which the registers are mapped. The start |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
26 |
of this memory region is known as the base address.</p></li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
27 |
<li><p>The location of each register in terms of an offset from the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
28 |
base address.</p></li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
29 |
</ul><p>The above information will be present in a specific header |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
30 |
file which is used by any device driver that uses this API. This header |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
31 |
file also contains other information required to access the registers, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
32 |
such as:</p><ul> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
33 |
<li><p>constants for bit field offsets</p></li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
34 |
<li><p>bit field values</p></li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
35 |
</ul></section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
36 |
<section id="GUID-CF41655A-5B14-47C4-811A-C9F9352B0688"><title>Implementation</title><p>To provide register access, hardware implementers need to implement |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
37 |
the <xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita"><apiname>AsspRegister</apiname></xref> class. </p><p>Generic access to a register is provided in the form of three |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
38 |
operations on a hardware register: read, write and modify. All these |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
39 |
functions can be called in any context. </p><p>Symbian platform provides |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
40 |
the class header and inline implementations of the 8, 16 and 32-bit |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
41 |
wide functions. You must implement all the register modify functions |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
42 |
and all functions to access 64-bit wide registers. You may also need |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
43 |
to replace the inline 8, 16 and 32-bit wide register read and write |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
44 |
functions if the ASSP contains write-only registers. </p> <p>You must |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
45 |
implement these functions atomically so that there is no possibility |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
46 |
of another thread or interrupt service routine accessing the contents |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
47 |
of the register before the function returns. Where you cannot implement |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
48 |
the function with a single machine instruction you must disable interrupts |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
49 |
during the register operation (if you are working with a single core |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
50 |
architecture) or wrap a spinlock around the register operation (if |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
51 |
you are working with a multicore architecture). </p> <p>There are |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
52 |
three cases in which you must enforce atomicity with interrupt disabled |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
53 |
or use of spinlocks. </p> <ul> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
54 |
<li id="GUID-3D835089-4626-584F-9FB1-EBD9CBF7A8D0"><p>The modify operations |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
55 |
involve reading the register, taking a local copy, changing the local |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
56 |
copy and writing it back to the register and cannot be performed with |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
57 |
a single machine instruction. </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
58 |
<li id="GUID-939FFD27-60EB-5465-95B7-A3654FBB5941"><p>Operations on |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
59 |
write-only registers involve maintaining a copy of the current contents |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
60 |
of the register within the <xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita"><apiname>AsspRegister</apiname></xref> class. All write and modify operations therefore cannot be performed |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
61 |
with a single machine instruction. </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
62 |
<li id="GUID-26D38D30-DFF3-5DCD-8163-157A228C50D6"><p>Some architectures |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
63 |
contain 64-bit registers. In this case, 64-bit operations involve |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
64 |
at least two machine instructions. </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
65 |
</ul><p>Baseport implementations of the Register Access platform service |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
66 |
come in the form of a ASSP library (or DLL). To avoid the need for |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
67 |
each device driver which uses the ASSP register class having to specify |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
68 |
a baseport specific library file corresponding to the ASSP library, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
69 |
the name of the baseport specific library file should instead be included |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
70 |
in a file used to define other variant specific settings such as the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
71 |
CPU core type, the memory model and the name of the variant. Each |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
72 |
baseport will have a file called <filepath>variant.mmh</filepath>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
73 |
where <codeph>variant</codeph> is the name of the baseport to be used. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
74 |
An example of this being used in a <filepath>variant.mmh</filepath> file is:</p><codeblock xml:space="preserve">#if defined(__USING_BASPORT__) |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
75 |
library VariantTarget(basport_name,assp_library) |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
76 |
#endif |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
77 |
</codeblock><note>baseport_name is the name of the variant and assp_library |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
78 |
is the name of the ASSP specific library file.</note><p>In order to |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
79 |
specify which baseport assp register set up is to be used in the client |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
80 |
projects for this baseport, the following line is included in the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
81 |
MMP file of those projects</p><codeblock xml:space="preserve">#define __USING_BASEPORT___</codeblock></section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
82 |
</conbody><related-links> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
83 |
<link href="http://developer.symbian.org/main/documentation/reference/s3/pdk/GUID-16AED228-539F-4BF7-A7FD-9A01FF1A9A84.html.dita"> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
84 |
<linktext>SMP - Locking</linktext></link> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
85 |
</related-links></concept> |