![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to User_Level_DD_spec CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple Darwin 0.x] / driverkit / doc / OLD_NRW|
Return to User_Level_DD_spec CVS log | Up to [Apple Darwin 0.x] / driverkit / doc / OLD_NRW |
1.1 root 1: {\rtf0\ansi{\fonttbl\f2\fswiss Helvetica;\f0\fmodern Ohlfs;}
2: \paperw10800
3: \paperh9280
4: \margl40
5: \margr0
6: {\colortbl\red0\green0\blue0;}
7: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\f2\b\i0\ul0\fs30 Kernel interface for user-level device driver support\
8:
9: \fs26 Last Revision 24-Jun-91 dmitch
10: \fs30 \
11:
12: \b0\fs24 \
13:
14: \b\fs30 Device Ports\
15:
16: \b0\fs24 \
17: Rights to access a device's registers, to program its dma channel, and receive interrupt notification are conveyed by a task holding send rights to a per-device port referred to here as the
18: \i dev_port
19: \i0 . The kernel responds to requests sent on the dev_port in order to provide these services to the requesting task.
20: \i dev_port
21: \i0 's are created early in system initialization and passed out to the appropriate device drivers by a process that is not described here.\
22: \
23:
24: \b\fs30 Register Mapping\
25: \
26:
27: \b0\fs24 This interface provides various mechanisms for device drivers to map the physical register space associated with their devices into their local address space. Which mechanism(s) can be used by a particular device driver are determined by the machine architecture, whether the device is a native device or a NextBus device, and the Slot ID in which the device lives. \
28: \
29: For the purposes of the following discussion, an
30: \b NRW DMA Device
31: \b0 is defined
32: \fc0 as a device in an m88k machine which resides in a slot with whose NextBus slot Id bits 9 through 7 are '111'. A
33: \b native device
34: \b0 is a device which is an integral part of an m68k-based CPU.\
35:
36: \b\fs30 \
37:
38: \b0\fs24 There are three kinds of device register space which can be mapped in to a device driver's local address space:\
39: \
40:
41: \pard\tx180\tx760\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx11520\fi-400\li760 *
42: \b Register Space
43: \b0 consists of one page (the size of which is machine dependent but can for now be assumed to be 8k bytes) consisting of device-specific registers. For m88k devices, the format of a device page is defined in the NRW system spec, section 5.2.8.2. For m68k devices, a device page is the physical memory region comprising all of the registers in one native device; the start of the register space may not be page-aligned in this case.\
44: \
45:
46: \i m88k devices:
47: \i0 \
48: \
49:
50: \fc0 A driver can map in a register page if and only if it is associated with an NRW DMA Device. \
51: \
52:
53: \i m68k devices:
54: \i0 \
55: \
56: A driver can map in a register page if and only if it is associated with a native device. \
57: \
58:
59: \pard\tx180\tx740\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx11520\fi-400\li760\fc0 *
60: \b Slot Space
61: \b0 consists of up to 16 MB of memory, starting at 0xfs000000. \
62:
63: \pard\tx180\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fi-400\li760\fc0 \
64:
65: \pard\tx180\tx760\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx11520\fi-400\li760\fc0
66: \i m88k devices
67: \i0 :\
68: \
69: An NRW DMA device driver can map in the first 0xf00000 (15 M) bytes of its associated slot space, or a portion thereof. A non-NRW DMA device driver can map in all 16 MB of its slot space, or a portion thereof.\
70: \
71:
72: \i m68k devices:
73: \i0 \
74: \
75: Only drivers associated with non-native devices can map in slot space; native device drivers have no slot space associated with them.\
76: \
77: *
78: \b Board space
79: \b0 consists of up to 256 MB, starting at 0xs000000. \
80:
81: \pard\tx180\tx680\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx11520\fi-400\li760\fc0 \
82:
83: \pard\tx180\tx760\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx11520\fi-400\li760\fc0
84: \i m88k devices:
85: \b\i0 \
86:
87: \pard\tx180\tx680\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx11520\fi-400\li760\fc0 \
88:
89: \pard\tx180\tx740\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx11520\fi-400\li760\fc0
90: \b0 Drivers associated with devices in slots 13 and 14 are allowed to map in all or part of their board space. Other drivers can not map in any board space.\
91: \
92:
93: \i m68k devices:
94: \i0 \
95: \
96: Only drivers associated with non-native devices can map in board space.\
97:
98: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560 \
99: \
100:
101: \b\fs30 Initialization RPC's\
102:
103: \b0\fs24 \
104: Operations are performed upon device ports by a combination of kernel rpc's, and for performance reasons, a set of kernel traps. Kernel rpc's control access to the device and its registers.\
105: \
106:
107: \b dev_return_t
108: \b0 \
109:
110: \b dev_intr_attach(\
111: port_t
112: \b0\i dev_port
113: \b\i0 ,\
114: port_t
115: \b0\i intr_port
116: \b\i0 );\
117:
118: \b0 \
119:
120: \b dev_intr_attach
121: \b0\i
122: \i0 requests that interrupt notification messages for\
123: the device represented by
124: \i dev_port
125: \i0 be sent to the port
126: \i intr_port
127: \i0 .\
128: \
129: Only a single port may be attached for device interrupts at any point in time.\
130: (A policy decision, more than functional requirement.)\
131: \
132: In NRW, this request also binds a device interrupt with an interrupt request\
133: bit.\
134: \
135:
136: \i dev_port
137: \i0 is the port representing the device access capability.\
138: \
139:
140: \i intr_port
141: \i0 is the port to which interrupt notification messages will be sent.\
142:
143: \fc0 \
144: \
145:
146: \b dev_return_t
147: \b0 \
148:
149: \b dev_intr_detach(\
150: port_t
151: \b0\i dev_port
152: \b\i0 ,\
153: port_t
154: \b0\i intr_port
155: \b\i0 );\
156:
157: \b0 \
158:
159: \b dev_intr_detach
160: \b0\i
161: \i0 disassociates interrupt notification messages for\
162: the device represented by
163: \i dev_port
164: \i0 from being sent to
165: \i intr_port.\
166:
167: \i0 \
168:
169: \b dev_return_t
170: \b0 \
171:
172: \b dev
173: \b0 _
174: \b chan_attach(\
175: port_t
176: \b0\i dev_port
177: \b\i0 ,\
178: int
179: \b0\i chan_num,\
180:
181: \b\i0 boolean_t
182: \b0\i stream_mode,\
183:
184: \b\i0 int
185: \b0\i buffer_size
186: \b\i0 );\
187:
188: \b0 \
189:
190: \b\li2100 dev_chan_attach
191: \b0\i
192: \i0 associates a system-wide logical dma channel with the physical device-specific channel
193: \i chan_num
194: \i0 of the device represented by
195: \i dev_port
196: \i0 .\
197:
198: \li0 \
199: A
200: \b dev_chan_attach
201: \b0 must be performed for each physical dma channel\
202: to be used with the device. \
203: \
204:
205: \i dev_port
206: \i0 is the port representing the device access capability.\
207: \
208:
209: \i chan_num
210: \i0 is the device physical channel number that should\
211: be bound with a logical dma channel.\
212: \
213:
214: \i stream_mode
215: \i0 specifies whether or not the device-specific hardware\
216: is capable of generating an End Of Record signal on input. See the\
217: description for chan_dma_enqueue for more information on streaming\
218: mode channels.\
219: \
220:
221: \i buffer_size
222: \i0 is the device-specific DMA buffer size. The kernel needs \
223: this information when performing DMA dequeue operations; it is also\
224: used in verifying correct DMA alignment.\
225: \
226:
227: \b dev_return_t
228: \b0 \
229:
230: \b dev
231: \b0 _
232: \b chan_detach(\
233: port_t
234: \b0\i dev_port
235: \b\i0 ,\
236: int
237: \b0\i chan_num
238: \b\i0 );\
239:
240: \b0 \
241:
242: \b dev_chan_detach
243: \b0\i
244: \i0 disassociates the dma channel
245: \i chan_num\
246:
247: \i0 of the device represented by
248: \i dev_port
249: \i0 from the task represented\
250: by
251: \i target_task
252: \i0 .\
253: \
254:
255: \b dev_return_t
256: \b0 \
257:
258: \b dev_reg_map(\
259: port_t
260: \b0\i dev_port
261: \b\i0 ,\
262:
263: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 vm_task_t
264: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0
265: \b0\i target_task
266: \b\i0 ,\
267: vm_offset_t *
268: \b0\i addr
269: \b , /* in/out */\
270:
271: \i0 boolean_t
272: \i
273: \b0 anywhere
274: \b\i0 );\
275:
276: \b0 \
277:
278: \fi-20\li2100
279: \b dev_reg_map
280: \b0\i
281: \i0 maps the device register page of the device associated with
282: \i dev_port
283: \i0 into the target task at addr. This RPC is invalid for m88k devices which are not NRW DMA devices and for non-native m68k devices.\
284:
285: \fi0\li0 \
286:
287: \i dev_port
288: \i0 is the kernel provided handle for the device.\
289: \
290:
291: \i target_task
292: \i0 represents the address space into which the device\
293: page should be mapped.\
294: \
295:
296: \i addr
297: \i0 is the address in target_task where the device page should\
298: be mapped.\
299: \
300:
301: \i anywhere
302: \i0 is a boolean, if true, indicates the kernel may pick any\
303: unused address to map the device page.\
304: \
305:
306: \b dev_return_t
307: \b0 \
308:
309: \b dev_reg_unmap(\
310: port_t
311: \b0\i dev_port
312: \b\i0 ,\
313:
314: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 vm_task_t
315: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0
316: \b0\i target_task
317: \b ,\
318:
319: \i0 vm_offset_t
320: \b0\i addr
321: \b\i0 );
322: \b0 \
323: \
324:
325: \b dev_reg_unmap
326: \b0\i
327: \i0 unmaps the device register page of the device\
328: associated with
329: \i dev_port
330: \i0 .\
331: \
332: \
333:
334: \b dev_return_t
335: \b0 \
336:
337: \b dev_slot_map(\
338: port_t
339: \b0\i dev_port
340: \b\i0 ,\
341:
342: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 vm_task_t
343: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0
344: \b0\i target_task
345: \b\i0 ,\
346: vm_offset_t
347: \b0\i offset
348: \b\i0 ,\
349:
350: \i
351: \i0 vm_size_t
352: \b0\i len
353: \b\i0 ,\
354: vm_offset_t *
355: \b0\i addr
356: \b , /* in/out */\
357:
358: \i0 boolean_t
359: \b0\i anywhere
360: \b\i0 );\
361:
362: \b0 \
363:
364: \b\fi-20\li2100 dev_slot_map
365: \b0\i
366: \i0 maps the slot space of the NeXTbus device associated with dev_port into the target task at addr. This RPC is illegal for native m68k devices.\
367:
368: \fi0\li0 \
369:
370: \i dev_port
371: \i0 is the kernel provided handle for the device.\
372: \
373:
374: \i target_task
375: \i0 represents the address space into which the device\
376: page should be mapped.\
377: \
378:
379: \i offset
380: \i0 is an offset within the device's slot space at which mapping\
381: should begin.\
382: \
383:
384: \i addr
385: \i0 is the address in target_task where the slot space should\
386: be mapped.\
387: \
388:
389: \i\fi-1100\li3180 len
390: \i0 is the length in bytes of the region to be mapped. The maximum value for
391: \i (offset + len)
392: \i0 is 0xf00000 (15M) for NRW DMA devices and 0x1000000 (16 M) for other devices.\
393:
394: \fi0\li0 \
395:
396: \i anywhere
397: \i0 is a boolean, if true, indicates the kernel may pick any\
398: unused address to map the slot space.\
399: \
400: \
401:
402: \b dev_return_t
403: \b0 \
404:
405: \b dev_slot_unmap(\
406: port_t
407: \b0\i dev_port
408: \b\i0 ,\
409:
410: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 vm_task_t
411: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0
412: \b0\i target_task
413: \b\i0 ,\
414: vm_offset_t
415: \b0\i addr
416: \b ,\
417:
418: \i0 vm_size_t
419: \b0\i len
420: \b\i0 );\
421:
422: \b0 \
423:
424: \b dev_slot_map
425: \b0\i
426: \i0 unmaps the slot space of the NeXTbus \
427: device associated with
428: \i dev_port. addr
429: \i0 and
430: \i len
431: \i0 must match similar \
432: fields from a previous call to
433: \b dev_slot_map
434: \b0 .\
435: \
436:
437: \b dev_return_t
438: \b0 \
439:
440: \b dev_board_map(\
441: port_t
442: \b0\i dev_port
443: \b\i0 ,\
444:
445: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 vm_task_t
446: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0
447: \b0\i target_task
448: \b\i0 ,\
449: vm_offset_t
450: \b0\i offset
451: \b\i0 ,\
452:
453: \i
454: \i0 vm_size_t
455: \b0\i len
456: \b\i0 ,\
457: vm_offset_t *
458: \b0\i addr
459: \b , /* in/out */\
460:
461: \i0 boolean_t
462: \b0\i anywhere
463: \b\i0 );\
464:
465: \b0 \
466:
467: \b dev_board_map
468: \b0\i
469: \i0 maps the board space of the NeXTbus \
470: device associated with dev_port into the target task at addr.\
471: \
472:
473: \i dev_port
474: \i0 is the kernel provided handle for the device.\
475: \
476:
477: \i target_task
478: \i0 represents the address space into which the device\
479: page should be mapped.\
480: \
481:
482: \i offset
483: \i0 is an offset within the device's board space at which mapping\
484: should begin.\
485: \
486:
487: \i addr
488: \i0 is the address in target_task where the board space should\
489: be mapped.\
490: \
491:
492: \pard\tx0\tx1040\tx3140\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\i\fi-1060\li3140\fc0 len
493: \i0 is the length in bytes of the region to be mapped. The maximum value for
494: \i (offset + len)
495: \i0 is 0x10000000 (256M).\
496:
497: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0 \
498:
499: \i anywhere
500: \i0 is a boolean, if true, indicates the kernel may pick any\
501: unused address to map the board space.\
502: \
503: \
504:
505: \b dev_return_t
506: \b0 \
507:
508: \b dev_board_unmap(\
509: port_t
510: \b0\i dev_port
511: \b\i0 ,\
512:
513: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 vm_task_t
514: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0
515: \b0\i target_task
516: \b\i0 ,\
517: vm_offset_t
518: \b0\i addr
519: \b ,\
520:
521: \i0 vm_size_t
522: \b0\i len
523: \b\i0 );\
524:
525: \b0 \
526:
527: \b dev_slot_map
528: \b0\i
529: \i0 unmaps the board space of the NeXTbus \
530: device associated with
531: \i dev_port. addr
532: \i0 and
533: \i len
534: \i0 must match similar \
535: fields from a previous call to
536: \b dev_board_map
537: \b0 .\
538: \
539: \
540:
541: \b\fs30 Operational RPC's\
542:
543: \b0\fs24 \
544: \
545:
546: \b chan_return_t\
547: chan_command(\
548: port_t
549: \b0\i dev_port
550: \b\i0 ,\
551: int
552: \b0\i chan_num
553: \b\i0 ,\
554: chan_command_t
555: \b0\i command
556: \b\i0 );
557: \b0 \
558: \
559:
560: \b\li2100 chan_command
561: \b0 is used to issue commands on the dma channel identified by dev_id and chan_num. CHAN_NONE can be specified for chan_num if no channels are attached; in this case the only legal chan_command_t bits are CC_INTR_ENABLE and INTR_DISABLE. Otherwise it is an error it the device or channel is not attached.\
562:
563: \li0 \
564:
565: \i dev_port
566: \i0 is the kernel provided handle for the device.\
567: \
568:
569: \i chan_num
570: \i0 is a logical channel number.\
571: \
572:
573: \i command
574: \i0 is the command for the channel to execute:\
575:
576: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CC_START_READ
577: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- enable read dma (68K only)\
578:
579: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CC_START_WRITE
580: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- enable write dma (68K only)\
581:
582: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CC_ABORT
583: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- abort current dma (disables channel) (68K only)\
584:
585: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CC_INTR_ENABLE
586: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- enable interrupts on the channel\
587:
588: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CC_INTR_DISABLE
589: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- disable interrupts on the channel\
590: \
591: All commands may be or'ed with
592: \b intr_enable
593: \b0 or
594: \b intr_disable
595: \b0 \
596: to form compound commands (e.g.
597: \b abort | intr_disable
598: \b0 or\
599:
600: \b start_read | intr_enable
601: \b0 ). Note than on NRW, start_read, start_write, and\
602: abort are done by the driver by directly accessing the channel\
603: command register.\
604:
605: \b \
606:
607: \b0 \
608:
609: \b\fs30 Operational Traps
610: \fs26 \
611:
612: \b0\fs24 \
613:
614: \b chan_return_t\
615: chan_dma_enqueue(\
616: port_t
617: \b0\i dev_port
618: \b\i0 ,\
619: int
620: \b0\i chan_num
621: \b\i0 ,\
622: task_t
623: \b0\i task_port
624: \b\i0 ,\
625: vm_offset_t
626: \b0\i addr
627: \b\i0 ,\
628: vm_size_t
629: \b0\i len
630: \b\i0 ,\
631: direction_t
632: \b0\i rw
633: \b\i0 ,\
634: chan_desc_cmd_t
635: \b0\i cmd
636: \b\i0 ,\
637: unsigned char
638: \b0\i index
639: \i0 ,
640: \b \
641: chan_enqueue_opts_t
642: \b0\i opts
643: \b\i0 ,\
644:
645: \i
646: \i0 unsigned
647: \b0\i dma_id
648: \b ,
649: \b0 \
650:
651: \b\i0 boolean_t
652: \i
653: \i0 *
654: \b0\i running
655: \b\i0 );
656: \b0 \
657: \
658:
659: \b\li2100 chan_dma_enqueue
660: \b0 builds and enqueues a list of dma descriptors describing a block of memory. This block of memory is referred to as a
661: \b frame
662: \b0 . The frame may cross page boundaries in most cases. The exception is for channels which have been configured as "streaming mode" channels per dev_chan_attach(). Frames for DMA read operations (device to memory) for streaming mode channels must not cross page boundaries. The reason for this restriction is that when the device-specific logic signals "End of record", the DMA hardware will advance to the next buffer descriptor, not the next frame. There is no way for the hardware to advance to the next frame; frames are a software construct. Therefor for such channels, we force one frame to consist of exactly one DMA descriptor.\
663:
664: \fi2100\li0 \
665:
666: \fi0\li2100 There are system dependent limits to the amount of memory that may be queued with
667: \b chan_dma_enqueue
668: \b0 ; exceeding this limit will return an error and the data will not be enqueued.\
669:
670: \li0 \
671:
672: \i\li2100 addr
673: \i0 must be aligned to the size of the device buffer. On m68K machines,
674: \i len
675: \i0 must be a multiple of the device buffer length for all descriptors with
676: \b eor
677: \b0 not set in the
678: \i opts
679: \i0 argument. On m88k machines, len must be a multiple of the device buffer length for DMA read operations.\
680:
681: \li0 \
682: Chains of DMA frames will be limited to some length by the kernel.\
683: \
684:
685: \i dev_port
686: \i0 is the kernel provided handle for the device.\
687: \
688:
689: \i chan_num
690: \i0 is a per-device logical channel number.\
691: \
692:
693: \i task_port
694: \i0 is the task where dma will be done to/from.\
695: \
696:
697: \i addr
698: \i0 is the address in the current task where the dma should\
699: begin.\
700: \
701:
702: \i len
703: \i0 is the length of the dma in the target tasks address space.\
704: \
705:
706: \i rw
707: \i0 is the direction of the dma, either
708: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 DMA_DIR_READ
709: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 (from the device\
710: to memory) or
711: \b DMA_DIR_WRITE
712: \b0 (from memory to the device).\
713: \
714:
715: \i cmd
716: \i0 is a NRW channel descriptor command (m88k only)\
717: \
718:
719: \fi-3140\li3140
720: \i index
721: \i0 contains the region and register index to which
722: \i cmd
723: \i0 will be written (m88k only).\
724:
725: \fi0\li0
726: \i opts
727: \i0 are channel options that should apply to the frame being\
728: enqueued. These include:\
729:
730: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fi-1060\li4200\fc0 CEO_EOR
731: \b0 -- the last descriptor in the frame should be indicated as the end-of-record.\
732:
733: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0
734: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CEO_DESC_INTR
735: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- interrupt when this frame is completed.\
736:
737: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CEO_ENABLE_INTR
738: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- enable interrupt msgs\
739:
740: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fi-1060\li4200\fc0 CEO_ENABLE_CHAN
741: \b0 -- enable dma channel after enqueue (m68k only).\
742:
743: \pard\tx1040\tx2100\tx3160\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fi-4160\li4160\fc0
744: \b CEO_DESC_CMD
745: \b0 -- enable channel descriptor command (m88k only)\
746:
747: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0 \
748:
749: \i dma_id
750: \i0 is an integer, uninterpreted by the kernel, whose sole purpose\
751: is to identify this frame when
752: \b chan_dma_dequeue
753: \b0 'd. \
754:
755: \i dma_id
756: \i0 must not be equal to DMA_ID_NULL.\
757: \
758:
759: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\i\fi-1080\li3180\fc0 running
760: \i0 is returned; on the m68k this indicates whether the channel was enabled at the time of the enqueue (if not, a channel enable will be required). On the m88k, a FALSE value for
761: \i running
762: \i0 indicates that a chaining update did not occur in time and that the DMA channel needs to be restarted; the frame will still be enqueued in this case.\
763:
764: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\fc0 \
765: \
766:
767: \b chan_return_t\
768: chan_dma_dequeue(\
769: port_t
770: \b0\i dev_port
771: \b\i0 ,\
772: int
773: \b0\i chan_num
774: \b\i0 ,\
775: chan_dequeue_opt_t
776: \b0\i opts
777: \b\i0 ,\
778: vm_size_t *
779: \b0\i bcount
780: \b\i0 ,\
781: chan_status_t *
782: \b0\i chan_status
783: \b\i0 ,\
784: dma_status_t *
785: \b0\i dma_status
786: \b\i0 ,\
787: boolean_t *
788: \b0\i eor
789: \b\i0 ,\
790: unsigned *
791: \b0\i dma_id
792: \b\i0 );
793: \b0 \
794: \
795:
796: \b\li2100 chan_dma_dequeue
797: \b0 dequeues a single dma frame which was enqueued by chan_dma_enqueue. It
798: \li0 will only dequeue
799: \li2100 frames
800: \li0 that meet the criteria
801: \li2100 spe
802: \li0 cified in
803: \i\li2100 opts
804: \i0\li0 .\
805: \
806: It unlocks the associated memory.\
807: \
808: It returns an indication if more descriptors are available to dequeue\
809: by the criteria specified in
810: \i opts
811: \i0 .\
812: \
813: chan_dma_dequeue will return an error (CR_BUSY) if the \
814: dequeue_all option is specified, the channel is running , and \
815: no completed frames are available. In other words, it is \
816: not possible to dequeue non-completed descriptors while the\
817: channel is running.\
818: \
819:
820: \i dev_port
821: \i0 is the kernel provided handle for the device.\
822: \
823:
824: \i chan_num
825: \i0 is a logical channel number.\
826: \
827:
828: \i opts
829: \i0 are options to dma_dequeue, these include:\
830:
831: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CDO_DONE
832: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- dequeue only completed frames.\
833:
834: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CDO_ALL
835: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- dequeue all frames.\
836:
837: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CDO_ENABLE_INTR
838: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- enable interrupt msgs.\
839:
840: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\b\fc0 CDO_EI_IF_MT
841: \pard\tx1040\tx2100\tx3160\tx4220\tx5280\tx6320\tx7380\tx8440\tx9500\tx10560\b0\fc0 -- reenables device interrupts\
842: for the device if no more frames may be dequeued.\
843: \
844: The flags may be or'ed together.\
845: \
846:
847: \i bcount
848: \i0 is the byte count of actually transferred data. It is only valid\
849: for transfer from the device into memory (i.e. reads). Zero\
850: returned on writes.\
851: \
852:
853: \i chan_status
854: \i0 is the channel descriptor status (only valid for m88k). \
855: It is only valid for transfer from the device into memory (i.e. \
856: reads). Zero returned on writes.\
857: \
858:
859: \i dma_status
860: \i0 is machine-independent and indicates the current state of\
861: the channel (e.g., running, idle, underrun). Only valid for\
862: m68k.\
863: \
864:
865: \i eor
866: \i0 is an end of record indication (only valid for certain device and\
867: only valid on "read" transactions). False returned on writes.\
868: \
869:
870: \i dma_id
871: \i0 is an integer, uninterpreted by the kernel, whose sole purpose\
872: is to identify this frame to the device driver. If
873: \i dma_id
874: \i0 \
875: is DMA_ID_NULL, no descriptors are available for dequeueing.\
876: \
877: \
878:
879: \b\fs30 Revision History
880: \b0\fs24 \
881:
882: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 \
883: 18-Jul-91 Doug Mitchell\
884: Added
885: \i buffer_size
886: \i0 argument to dev_chan_attach().\
887: \
888: 08-Jul-91 Doug Mitchell\
889: Changed
890: \i chan_status
891: \i0 and
892: \i desc_status
893: \i0 to
894: \i dma_status
895: \i0 and
896: \i chan_status
897: \i0 \
898: in chan_dma_dequeue().\
899: Clarified limits of
900: \i offset
901: \i0 and
902: \i len
903: \i0 in dev_lot_map() and dev_board_map().\
904: \
905: 27-Jul-91 Doug Mitchell\
906: Refined definition of
907: \i running
908: \i0 return value in chan_dma_enqueue().\
909: Deleted CC_FORCE_BUF_ADV option from chan_command.\
910: \
911: 25-Jun-91 Doug Mitchell\
912:
913: \pard\tx1620\tx2260\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fi-380\li2660\fc0 Added index argument to chan_dma_enqueue().\
914: Added CEO_DESC_CMD bit to Channel enable options.\
915:
916: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 \
917: 24-Jun-91 Doug Mitchell\
918:
919: \pard\tx1620\tx2260\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fi-380\li2660\fc0 Added section on register mapping. Added dev_board_map() and dev_board_unmpap() RPCs.\
920:
921: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0 Fixed some typos.\
922:
923: }
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.