|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-DB55C1A0-2901-4661-B6B1-3B61BF6FF4FA" xml:lang="en"><title>Register Access Client Interface Guide</title><shortdesc>Explains how to use the Register Access client interface |
|
13 functions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The Register Access client interface is intended for use in writing |
|
15 device drivers. Writing device drivers involves frequent access to |
|
16 hardware registers by reading, writing and modifying them. </p> |
|
17 <section id="GUID-7107B7C2-04E3-4876-892B-20C3F9F12F85"><title>Interface |
|
18 class</title> <p>The client interface for the Register |
|
19 Access platform services is:</p><table id="GUID-A29A52B7-14C5-40F3-A73B-284B0D730965"> |
|
20 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
21 <thead> |
|
22 <row> |
|
23 <entry>Class</entry> |
|
24 <entry>Description</entry> |
|
25 </row> |
|
26 </thead> |
|
27 <tbody> |
|
28 <row> |
|
29 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita"><apiname>AsspRegister</apiname></xref></entry> |
|
30 <entry>Provides read, write and modify functions to access hardware |
|
31 registers of different widths.</entry> |
|
32 </row> |
|
33 </tbody> |
|
34 </tgroup> |
|
35 </table> </section> |
|
36 <section id="GUID-E1D195A0-715F-5961-A67C-A2536D68DAE3"><title>Interface |
|
37 functions</title> <p>The Register Access client interface provides |
|
38 the following functions:</p><table id="GUID-12019299-2FEB-4F6B-8217-D4AD085B12BB"> |
|
39 <tgroup cols="3"><colspec colname="col1"/><colspec colname="col2"/> |
|
40 <colspec colname="col3"/> |
|
41 <thead> |
|
42 <row> |
|
43 <entry>Function</entry> |
|
44 <entry>Return Type</entry> |
|
45 <entry>Description</entry> |
|
46 </row> |
|
47 </thead> |
|
48 <tbody> |
|
49 <row> |
|
50 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-A47E7A93-8180-38BA-8FAD-27ADA0E86EF7"><apiname>AsspRegister::Read8(TLinAddr aAddr)</apiname></xref></entry> |
|
51 <entry>TUint8</entry> |
|
52 <entry>Return the contents of an 8-bit register.</entry> |
|
53 </row> |
|
54 <row> |
|
55 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-41AA4058-4528-3AB7-9084-AA6053AF0656"><apiname>AsspRegister::Read16(TLinAddr aAddr)</apiname></xref></entry> |
|
56 <entry>TUint16</entry> |
|
57 <entry>Return the contents of a 16-bit register.</entry> |
|
58 </row> |
|
59 <row> |
|
60 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-E637527E-537A-367D-91C2-A3BB3AA0A587"><apiname>AsspRegister::Read32(TLinAddr aAddr)</apiname></xref></entry> |
|
61 <entry>TUint32</entry> |
|
62 <entry>Return the contents of a 32-bit register.</entry> |
|
63 </row> |
|
64 <row> |
|
65 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-05FADA8D-5B77-39C6-A939-5EB1B209DD53"><apiname>AsspRegister::Read64(TLinAddr aAddr)</apiname></xref></entry> |
|
66 <entry>TUint64</entry> |
|
67 <entry>Return the contents of a 64-bit register.</entry> |
|
68 </row> |
|
69 <row> |
|
70 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-CB85C4D4-3652-311E-808A-048A43F49F3E"><apiname>AsspRegister::Write8(TLinAddr aAddr, TUint8 aValue)</apiname></xref></entry> |
|
71 <entry>void</entry> |
|
72 <entry>Store a new value in an 8-bit register.</entry> |
|
73 </row> |
|
74 <row> |
|
75 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-C20B9119-AAC8-354B-902A-B4349AEFC00E"><apiname>AsspRegister::Write16(TLinAddr aAddr, TUint16 aValue)</apiname></xref></entry> |
|
76 <entry>void</entry> |
|
77 <entry>Store a new value in a 16-bit register.</entry> |
|
78 </row> |
|
79 <row> |
|
80 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-E18C1674-47EA-3B70-9BEE-55302D58F83B"><apiname>AsspRegister::Write32(TLinAddr aAddr, TUint32 aValue)</apiname></xref></entry> |
|
81 <entry>void</entry> |
|
82 <entry>Store a new value in a 32-bit register.</entry> |
|
83 </row> |
|
84 <row> |
|
85 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-99D3233D-8F1C-3A65-BC1F-F10998728EB8"><apiname>AsspRegister::Write64(TLinAddr aAddr, TUint64 aValue)</apiname></xref></entry> |
|
86 <entry>void</entry> |
|
87 <entry>Store a new value in a 64-bit register.</entry> |
|
88 </row> |
|
89 <row> |
|
90 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-3E66E373-E7DB-3F59-B6B1-3577AAD9FBF0"><apiname>AsspRegister::Modify8(TLinAddr aAddr, TUint8 aClearMask, |
|
91 TUint8 aSetMask)</apiname></xref></entry> |
|
92 <entry>void</entry> |
|
93 <entry>Modify the contents of an 8-bit register.</entry> |
|
94 </row> |
|
95 <row> |
|
96 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-9A6FF0D8-1136-3188-8D85-43EF8919FA7C"><apiname>AsspRegister::Modify16(TLinAddr aAddr, TUint16 aClearMask, |
|
97 TUint16 aSetMask)</apiname></xref></entry> |
|
98 <entry>void</entry> |
|
99 <entry>Modify the contents of a 16-bit register.</entry> |
|
100 </row> |
|
101 <row> |
|
102 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-035D2133-037A-36C5-B47C-A6FD00FEE3BA"><apiname>AsspRegister::Modify32(TLinAddr aAddr, TUint32 aClearMask, |
|
103 TUint32 aSetMask)</apiname></xref></entry> |
|
104 <entry>void</entry> |
|
105 <entry>Modify the contents of a 32-bit register.</entry> |
|
106 </row> |
|
107 <row> |
|
108 <entry><xref href="GUID-66BB033A-3386-3913-9A25-EF3867D42C2C.dita#GUID-66BB033A-3386-3913-9A25-EF3867D42C2C/GUID-7127519C-305D-3727-898F-860023CE586A"><apiname>AsspRegister::Modify64(TLinAddr aAddr, TUint64 aClearMask, |
|
109 TUint64 aSetMask)</apiname></xref></entry> |
|
110 <entry>void</entry> |
|
111 <entry>Modify the contents of a 64-bit register.</entry> |
|
112 </row> |
|
113 </tbody> |
|
114 </tgroup> |
|
115 </table> <p>All these functions can be called in any context. </p> <p>The address of a particular register on a particular platform |
|
116 is typically expressed as a base address and an offset: this is what |
|
117 you pass to the <codeph>aAddr</codeph> argument of these functions |
|
118 as a <codeph>TLinAddr</codeph>. </p> <p>The write functions take an |
|
119 unsigned integer (<codeph>TUint8</codeph>, <codeph>TUint16</codeph>, <codeph>TUint32</codeph> or <codeph>TUint64</codeph>) as the value |
|
120 of the parameter <codeph>aValue</codeph>.</p> <p>The modify functions |
|
121 take two unsigned integers (<codeph>TUint8</codeph>, <codeph>TUint16</codeph>, <codeph>TUint32</codeph> or <codeph>TUint64</codeph>) as arguments. |
|
122 Both the parameters, <codeph>aClearMask</codeph> and <codeph>aSetMask</codeph>, are bitmasks. The <codeph>aClearMask</codeph> argument clears the |
|
123 bits specified and the <codeph>aSetMask</codeph> sets the bits specified. </p> <b>Addressing a register</b><p>The following code reads the current |
|
124 value of a hardware register identified by a base address <codeph>iBaseAddr</codeph> plus an offset <codeph>KHoPciStatus</codeph>. </p><codeblock id="GUID-6308D594-B74D-50EE-A3EB-D8739371E46B" xml:space="preserve">TUint status=AsspRegister::Read16(iBaseAddr+KHoPciStatus);</codeblock><b>Modifying a register</b><p>The following code clears the bits |
|
125 specified by the bitmask <codeph>KHtPciStatus_ParityError</codeph> and sets the bits specified by the bitmask <codeph>NULL</codeph> (that is so say, none in this case). </p><codeblock id="GUID-F000597B-1B52-5C3F-B61E-6B5B88D859C7" xml:space="preserve">AsspRegister::Modify16(baseAddr+KHoPciStatus,KHtPciStatus_ParityError,NULL);</codeblock></section> |
|
126 </conbody><related-links> |
|
127 <link href="GUID-3722B946-07CF-4AEA-B228-E50642D6B5BE.dita"><linktext>Register |
|
128 Access Implementation Guide</linktext></link> |
|
129 </related-links></concept> |