14 data using DMA. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 data using DMA. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
15 <p>The following diagram shows the general relationship between the various |
15 <p>The following diagram shows the general relationship between the various |
16 classes and structs that form the DMA Framework. The individual items are |
16 classes and structs that form the DMA Framework. The individual items are |
17 described in more detail below. </p> |
17 described in more detail below. </p> |
18 <fig id="GUID-C6B032F0-7E05-5E29-8024-B713C42A2434"> |
18 <fig id="GUID-C6B032F0-7E05-5E29-8024-B713C42A2434"> |
19 <image href="GUID-D43AB2F5-32AE-540C-80D8-DE8B2072F1E6_d0e383654_href.png" placement="inline"/> |
19 <image href="GUID-D43AB2F5-32AE-540C-80D8-DE8B2072F1E6_d0e381497_href.png" placement="inline"/> |
20 </fig> |
20 </fig> |
21 <section id="GUID-D9855D5F-3D4D-5A65-A1BB-B7CB94E60316"><title>The DMA Software |
21 <section id="GUID-D9855D5F-3D4D-5A65-A1BB-B7CB94E60316"><title>The DMA Software |
22 Controller</title> <p>This is the <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> object. It has |
22 Controller</title> <p>This is the <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> object. It has |
23 two purposes: </p> <ul> |
23 two purposes: </p> <ul> |
24 <li id="GUID-E4C8A5C5-192B-5E3E-A2F1-D884BF7FE641"><p>It defines the main |
24 <li id="GUID-E4C8A5C5-192B-5E3E-A2F1-D884BF7FE641"><p>It defines the main |
53 at address 1000 and is 300 bytes long. Block B starts at address 2000 and |
53 at address 1000 and is 300 bytes long. Block B starts at address 2000 and |
54 is 700 bytes long. The destination buffer C starts at address 5000 and is |
54 is 700 bytes long. The destination buffer C starts at address 5000 and is |
55 1000 bytes long. Assume that the DMA descriptors are allocated in a pool starting |
55 1000 bytes long. Assume that the DMA descriptors are allocated in a pool starting |
56 at address 600. The following diagram shows the scatter/gather list that the |
56 at address 600. The following diagram shows the scatter/gather list that the |
57 device driver might create: </p> <fig id="GUID-966DC875-FA9E-59E5-A1CA-842F4A82592D"> |
57 device driver might create: </p> <fig id="GUID-966DC875-FA9E-59E5-A1CA-842F4A82592D"> |
58 <image href="GUID-EA0C5715-7CE8-5415-A915-D5701E3C957A_d0e383751_href.png" placement="inline"/> |
58 <image href="GUID-EA0C5715-7CE8-5415-A915-D5701E3C957A_d0e381594_href.png" placement="inline"/> |
59 </fig> <p>If the DMA controller supports the scatter/gather arrangement, then |
59 </fig> <p>If the DMA controller supports the scatter/gather arrangement, then |
60 the framework uses a structure that will be specific to the hardware. This |
60 the framework uses a structure that will be specific to the hardware. This |
61 structure is defined in the platform specific layer. </p> <p>If the DMA controller |
61 structure is defined in the platform specific layer. </p> <p>If the DMA controller |
62 does not support scatter/gather, then the framework uses the generic structure <xref href="GUID-D7934AD9-38F6-325A-A734-F867D886D7C2.dita"><apiname>SDmaPseudoDes</apiname></xref> containing |
62 does not support scatter/gather, then the framework uses the generic structure <xref href="GUID-D7934AD9-38F6-325A-A734-F867D886D7C2.dita"><apiname>SDmaPseudoDes</apiname></xref> containing |
63 the following information: </p> <ul> |
63 the following information: </p> <ul> |
82 to embed additional data in a structure whose layout may be hardware-imposed. </p> <p>Descriptors |
82 to embed additional data in a structure whose layout may be hardware-imposed. </p> <p>Descriptors |
83 and descriptor headers are stored in two parallel arrays allocated at boot-time, |
83 and descriptor headers are stored in two parallel arrays allocated at boot-time, |
84 and each descriptor is always associated with the header of same index, so |
84 and each descriptor is always associated with the header of same index, so |
85 that there is always a one-to-one relationship between the header and the |
85 that there is always a one-to-one relationship between the header and the |
86 descriptor. </p> <fig id="GUID-A635E3EA-883C-5857-8690-E0AE6F43CAC4"> |
86 descriptor. </p> <fig id="GUID-A635E3EA-883C-5857-8690-E0AE6F43CAC4"> |
87 <image href="GUID-99F7E70F-2733-57B2-94F5-A0C0FF9219FE_d0e383807_href.png" placement="inline"/> |
87 <image href="GUID-99F7E70F-2733-57B2-94F5-A0C0FF9219FE_d0e381650_href.png" placement="inline"/> |
88 </fig> <p>In the current design, the only information in the descriptor header |
88 </fig> <p>In the current design, the only information in the descriptor header |
89 is a pointer, <codeph>SDmaDesHdr::iNext</codeph>, that is used to chain headers |
89 is a pointer, <codeph>SDmaDesHdr::iNext</codeph>, that is used to chain headers |
90 together on various lists. So, although the pool of headers is allocated as |
90 together on various lists. So, although the pool of headers is allocated as |
91 an array, they are almost always accessed by following the chain of pointers |
91 an array, they are almost always accessed by following the chain of pointers |
92 linking one header to the next. </p> <p>Descriptors are <i>always</i> accessed |
92 linking one header to the next. </p> <p>Descriptors are <i>always</i> accessed |
117 requests have pointers to the first and last headers in the list. </p> <p>When |
117 requests have pointers to the first and last headers in the list. </p> <p>When |
118 the request is idle, the header list ends with a NULL pointer. This is not |
118 the request is idle, the header list ends with a NULL pointer. This is not |
119 always true when the request is queued (i.e. when the request is being transferred |
119 always true when the request is queued (i.e. when the request is being transferred |
120 or is still pending). The following diagram shows an idle request with three |
120 or is still pending). The following diagram shows an idle request with three |
121 fragments. </p> <fig id="GUID-0A5594BD-05E4-5A97-A3F7-459E3F8638A2"> |
121 fragments. </p> <fig id="GUID-0A5594BD-05E4-5A97-A3F7-459E3F8638A2"> |
122 <image href="GUID-CF252B09-335E-5831-94A6-0B16B64C5030_d0e383893_href.png" placement="inline"/> |
122 <image href="GUID-CF252B09-335E-5831-94A6-0B16B64C5030_d0e381736_href.png" placement="inline"/> |
123 </fig> <p>Splitting a request into fragments is useful because: </p> <ul> |
123 </fig> <p>Splitting a request into fragments is useful because: </p> <ul> |
124 <li id="GUID-BEA0F4C5-4308-54E9-82AB-91570ACC9ADC"><p>it insulates device |
124 <li id="GUID-BEA0F4C5-4308-54E9-82AB-91570ACC9ADC"><p>it insulates device |
125 drivers from the maximum transfer size supported by the underlying DMA controller. </p> </li> |
125 drivers from the maximum transfer size supported by the underlying DMA controller. </p> </li> |
126 <li id="GUID-A768A76B-DD9E-5A25-92D3-23A69299C096"><p>the source and destination |
126 <li id="GUID-A768A76B-DD9E-5A25-92D3-23A69299C096"><p>the source and destination |
127 DMA buffers may not be physically contiguous and thus require fragmenting. </p> </li> |
127 DMA buffers may not be physically contiguous and thus require fragmenting. </p> </li> |
181 channel has a pointer to the header associated with the descriptor being transferred. |
181 channel has a pointer to the header associated with the descriptor being transferred. |
182 The headers of all queued requests are linked together on one linked list. </p> <p>The |
182 The headers of all queued requests are linked together on one linked list. </p> <p>The |
183 following diagram shows a DMA channel with a three-fragment request being |
183 following diagram shows a DMA channel with a three-fragment request being |
184 transferred and a two-fragment one pending. The fragment currently being transferred |
184 transferred and a two-fragment one pending. The fragment currently being transferred |
185 is the second one of the first request. </p> <fig id="GUID-36E11A64-4626-53F9-925C-3DC323DEA895"> |
185 is the second one of the first request. </p> <fig id="GUID-36E11A64-4626-53F9-925C-3DC323DEA895"> |
186 <image href="GUID-86C21C9B-9F08-579F-84E9-CBE46F756373_d0e384006_href.png" placement="inline"/> |
186 <image href="GUID-86C21C9B-9F08-579F-84E9-CBE46F756373_d0e381849_href.png" placement="inline"/> |
187 </fig> <p>The <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita"><apiname>TDmaChannel</apiname></xref> class contains the code and data |
187 </fig> <p>The <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita"><apiname>TDmaChannel</apiname></xref> class contains the code and data |
188 that is common to all of the channel types. The code and data for the specific |
188 that is common to all of the channel types. The code and data for the specific |
189 channel types: single buffer, double buffer, and scatter/gather channels, |
189 channel types: single buffer, double buffer, and scatter/gather channels, |
190 are implemented in the derived classes: <xref href="GUID-A8B4AD1B-770C-363E-A0DE-C78A9786CBDC.dita"><apiname>TDmaSbChannel</apiname></xref>, <xref href="GUID-FD76AF08-6250-3054-8A06-16343E385B23.dita"><apiname>TDmaDbChannel</apiname></xref>, |
190 are implemented in the derived classes: <xref href="GUID-A8B4AD1B-770C-363E-A0DE-C78A9786CBDC.dita"><apiname>TDmaSbChannel</apiname></xref>, <xref href="GUID-FD76AF08-6250-3054-8A06-16343E385B23.dita"><apiname>TDmaDbChannel</apiname></xref>, |
191 and <xref href="GUID-2D4CFBB1-8D64-3CF5-B6F0-B24D16D5BAD4.dita"><apiname>TDmaSgChannel</apiname></xref> respectively. </p> <p><b>TDmaSbChannel |
191 and <xref href="GUID-2D4CFBB1-8D64-3CF5-B6F0-B24D16D5BAD4.dita"><apiname>TDmaSgChannel</apiname></xref> respectively. </p> <p><b>TDmaSbChannel |
192 State Machine</b> </p> <p>For reference purposes, the following diagram shows |
192 State Machine</b> </p> <p>For reference purposes, the following diagram shows |
193 the state machine that <xref href="GUID-A8B4AD1B-770C-363E-A0DE-C78A9786CBDC.dita"><apiname>TDmaSbChannel</apiname></xref> implements to deal |
193 the state machine that <xref href="GUID-A8B4AD1B-770C-363E-A0DE-C78A9786CBDC.dita"><apiname>TDmaSbChannel</apiname></xref> implements to deal |
194 with a single buffer channel. </p> <fig id="GUID-82A8742D-CE5E-5EA2-A19E-6DCA30D9AE61"> |
194 with a single buffer channel. </p> <fig id="GUID-82A8742D-CE5E-5EA2-A19E-6DCA30D9AE61"> |
195 <image href="GUID-85332468-292D-589B-891B-0E7ACBADC7BA_d0e384042_href.png" placement="inline"/> |
195 <image href="GUID-85332468-292D-589B-891B-0E7ACBADC7BA_d0e381885_href.png" placement="inline"/> |
196 </fig> <p><b>TDmaDbChannel |
196 </fig> <p><b>TDmaDbChannel |
197 State Machine</b> </p> <p>For reference purposes, the following diagram shows |
197 State Machine</b> </p> <p>For reference purposes, the following diagram shows |
198 the state machine that <xref href="GUID-FD76AF08-6250-3054-8A06-16343E385B23.dita"><apiname>TDmaDbChannel</apiname></xref> implements to deal |
198 the state machine that <xref href="GUID-FD76AF08-6250-3054-8A06-16343E385B23.dita"><apiname>TDmaDbChannel</apiname></xref> implements to deal |
199 with a double buffer channel. </p> <fig id="GUID-1CF4D292-310C-5D75-9E3B-2DB65217FEEA"> |
199 with a double buffer channel. </p> <fig id="GUID-1CF4D292-310C-5D75-9E3B-2DB65217FEEA"> |
200 <image href="GUID-91958EA5-9444-5895-B4B8-F2C670B81CD7_d0e384059_href.png" placement="inline"/> |
200 <image href="GUID-91958EA5-9444-5895-B4B8-F2C670B81CD7_d0e381902_href.png" placement="inline"/> |
201 </fig> <p><b>TDmaSgChannel |
201 </fig> <p><b>TDmaSgChannel |
202 State Machine</b> </p> <p>For reference purposes, the following diagram shows |
202 State Machine</b> </p> <p>For reference purposes, the following diagram shows |
203 the state machine that <xref href="GUID-2D4CFBB1-8D64-3CF5-B6F0-B24D16D5BAD4.dita"><apiname>TDmaSgChannel</apiname></xref> implements to deal |
203 the state machine that <xref href="GUID-2D4CFBB1-8D64-3CF5-B6F0-B24D16D5BAD4.dita"><apiname>TDmaSgChannel</apiname></xref> implements to deal |
204 with a scatter/gather channel. </p> <fig id="GUID-1206C662-9856-57A1-A0C5-FDF74F2A3BD3"> |
204 with a scatter/gather channel. </p> <fig id="GUID-1206C662-9856-57A1-A0C5-FDF74F2A3BD3"> |
205 <image href="GUID-09EE01E2-BF5E-5302-BA25-46C440ADECF5_d0e384076_href.png" placement="inline"/> |
205 <image href="GUID-09EE01E2-BF5E-5302-BA25-46C440ADECF5_d0e381919_href.png" placement="inline"/> |
206 </fig> </section> |
206 </fig> </section> |
207 <section id="GUID-2F8979D3-A4DC-5919-B027-F8C17739A05D"><title>Streaming and |
207 <section id="GUID-2F8979D3-A4DC-5919-B027-F8C17739A05D"><title>Streaming and |
208 Scatter/Gather DMA Controllers</title> <p>When a transfer request is queued |
208 Scatter/Gather DMA Controllers</title> <p>When a transfer request is queued |
209 onto a channel that is already transferring data, the header descriptor for |
209 onto a channel that is already transferring data, the header descriptor for |
210 the new list of descriptors is appended to the header of the previous request |
210 the new list of descriptors is appended to the header of the previous request |
211 on the queue. If the underlying DMA controller supports hardware descriptors, |
211 on the queue. If the underlying DMA controller supports hardware descriptors, |
212 they must also be linked together. </p> <p>The following diagram shows how |
212 they must also be linked together. </p> <p>The following diagram shows how |
213 headers and descriptors for a new request are appended to the existing ones |
213 headers and descriptors for a new request are appended to the existing ones |
214 for a DMA controller. The dashed arrows represent the new links. </p> <fig id="GUID-7E06E92E-C8D1-53FF-AF03-5B1A3EBC1EA5"> |
214 for a DMA controller. The dashed arrows represent the new links. </p> <fig id="GUID-7E06E92E-C8D1-53FF-AF03-5B1A3EBC1EA5"> |
215 <image href="GUID-28F3F720-A2E0-59C9-8BB4-B6124CFC6C89_d0e384092_href.png" placement="inline"/> |
215 <image href="GUID-28F3F720-A2E0-59C9-8BB4-B6124CFC6C89_d0e381935_href.png" placement="inline"/> |
216 </fig> <p> <i>Note that hardware descriptors are linked together using physical |
216 </fig> <p> <i>Note that hardware descriptors are linked together using physical |
217 addresses, not virtual ones.</i> </p> <p>Linking hardware descriptors together |
217 addresses, not virtual ones.</i> </p> <p>Linking hardware descriptors together |
218 is implemented in the platform specific layer. There are two issues to consider: </p> <ul> |
218 is implemented in the platform specific layer. There are two issues to consider: </p> <ul> |
219 <li id="GUID-4236DD82-FFAD-56D3-B46F-9D2198E0349A"><p>The channel may go idle |
219 <li id="GUID-4236DD82-FFAD-56D3-B46F-9D2198E0349A"><p>The channel may go idle |
220 before the linking is complete, which means that the data for the new request |
220 before the linking is complete, which means that the data for the new request |