![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to KernelLevelSupport.frame 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 KernelLevelSupport.frame CVS log | Up to [Apple Darwin 0.x] / driverkit / doc / OLD_NRW |
Darwin 0.2 Driver Kit
<MakerFile 2.0J>
Aa� � N L � ff � � � � � � H H $ d d Footnote *�� . � � [ � ' [ �
1stHeading
2ndHeading
3rdHeading
4thHeading � � � � � -m2 -� . /� 0 1� 2� 3� 4 5� 6 7� 8 9� : ; >� ? @� E F� G �%� �1 7second-level heading; headings:second-level[headings:2] ���
�-
� �/
� �2
� �3
� �5
� �7
� �9
� �>
� �@
� �F
�
�
�
�
� <$lastpagenum>
� <$monthname> <$daynum>, <$year>�
� "<$monthnum>/<$daynum>/<$shortyear>6�
� ;<$monthname> <$daynum>, <$year> <$hour>:<$minute00> <$ampm>q
� "<$monthnum>/<$daynum>/<$shortyear>��
� <$monthname> <$daynum>, <$year>�
� "<$monthnum>/<$daynum>/<$shortyear>
� <$fullfilename>
�
<$filename>
� <$paranum[ChapterNum]>
� <$paratext[ChapterTitle]>
�
<$curpagenum>
�
<$paratext[1Head]>�
�
<$marker1>
�
� Page # page <$pagenum> �
� Heading & Page <$paratext> on page <$pagenum>
� Status PRELIMINARYHea
�
Figure Number
<$paranum>
� Heading� <$paratext>
� Page page <$pagenum>�
� Section & Page %section <$paranum> on page <$pagenum> u�{ u v ! ! A w A� x " "% y & &d Av z ' 'd gs | 5 @e An } 7 7 A- ~ 8 82 �k
�
�9
3 �
�F
3 �
- tpa
�
thn
ynu
- r>� "
3 thn
3 num
yea
( ;
( me> !
>, "
$ho #
( ute $
( m>q %
$mo &
$da '
hor (
( � )
thn *
ynu +
( r>� ,
' $mo -
$da .
hor /
& � 0 � lfi 1
& �
2 � ena SUMMARY3 � anu 4
Num 5
' 6
' t[C 7
* le] 8
&
9 � num SUMMARY:
& ate ;
& >� <
& $ma = � � SUMMARY>
pa ?
num SYNOPSIS@
& A
& ara B
& pag C
& um> D
tus SYNOPSISE
& � F
Num G
& ara H
& He I � $pa SUMMARYJ � e SUMMARYK � � SUMMARYL
' %se M
' ara N
' age O
m> SYNOPSISP
* Q
R � S
A SYNOPSIST
' A� U
' x " V
' W
' &d X
' Y
gs Z
* | 5 [
\ � 7 ]
& ^ � SUMMARY_
& ` � SUMMARYa
�F SYNOPSISb
&
3 c
- d
&
e
SYNOPSISf
g
& h � thn SUMMARYi
SYNOPSISj
SYNOPSISl
& >, m
$ho n � ute o
' m>q p
' $mo q
' $da r
* hor s � � SUMMARYt
*
u
& +
( v � ,
' w
-
SYNOPSISx
' y
' z
' {
' |
' }
* 3 � ~
& 4
5
' �
& 6
' � � 7
* SUMMARY�
& �
SYNOPSIS�
�
& �
& � � SUMMARY�
& �
SYNOPSIS�
' �
' �
' �
' �
* �
E
& �
& F
� � G
& SUMMARY� � �
' �
' J � �
' UMM �
' � �
' RY �
' �
' �
�
& �
P
* SYNOPSIS�
& �
�
�
& T
' �
& U
' �
& V
' �
& W
' �
X
' �
& Y
�
Z
* �
& [
�
\ � �
& ]
& �
^ � � � UMM �
' �
' �
' RY �
' �
' b
& �
& c
�
* d
& �
& e
� � YNO �
' �
' �
' thn �
' RY �
' �
' j
�
' YNO �
>, �
& $ho �
& ute �
& m>q �
& $mo �
& $da �
& hor �
& � �
& RY �
& �
& � � �
& �
' x
' �
' y
' �
' z
' �
' {
' �
' |
' �
* }
* �
& ~
& �
&
�
�
& � � � � �
' UMM �
' �
' �
' SIS �
* �
& �
& �
& �
& �
& �
& �
�
& YNO �
& �
& �
& �
'
' E
&
' F
' G
&
' RY
'
'
'
'
'
'
'
'
&
&
&
& �
&
& �
& �
!
& �
& #
& �
& &
& �
& (
& �
& *
& �
,
& �
& -
�
.
�
& /
�
0
�
& 1
�
5
& � � 7
& �
' 9 � �
' ;
' �
' <
' �
' =
' �
' >
' �
& ?
' �
* @
' �
& A
' � � B
' �
' C
' �
' D
* �
' J
& �
' P
& �
' R
& �
' s
�
' SYNOPSISt
' �
} A ( d � ! " � d � � H ��X�
� H ��X�
u
&
& �� �� �� h
_ xNRW Device Driver Guide > 14 ? of @ 16 E F 8/1/91 G COMPANY CONFIDENTIAL
& �� �� �� `
_ & $ 6 � � � $ 6 � w
& UR UR �� `
U
' $ 6 � ! � " $ 6 � v
' UR UR �� `
U H ��X�
" � ! H ��X�
x
&
& �� �� �� h
_ wNRW Device Driver Guide 5 # 6 of 7 4 8 9 7/31/91 : COMPANY CONFIDENTIAL
<
' �� �� �� `
_
' +�� �� �� `
_ ' d # �
' & ' �
& d $ �
% % � $ 6 � % � $ $ 6 � 5 )| UR UR �� 8
U LAn NRW DMA device driver can map in the first 0xf00000 (15 M) bytes of its �X UM UR �� 8
U Tassociated slot space, or a portion thereof. A non-NRW DMA device driver can map in !UH UR �� @8
U 7all 16 MB of its slot space, or a portion thereof
S.
& ;UC UR �� `
] m68k devices:
UU> UR �� <
U UOnly drivers associated with non-native devices can map in slot space; native device bU9 UR �� @<
U 1drivers have no slot space associated with them.
' |U4 UR �� `>
V�� BBoard space
Uconsists of up to 256 MB, starting at 0xs000000.
�U/ UR �� `#
] m88k devices:
�U* UR �� B
UNR XDrivers associated with devices in slots 13 and 14 are allowed to map in all or part of �U% UR �� @B
UEN Atheir board space. Other drivers can not map in any board space.
�U UR �� `$
] m68k devices:
�U UR �� `G
U HOnly drivers associated with non-native devices can map in board space.
&�l �� UT `*
[ Initialization RPCs
)AU UR �� -
U UOperations are performed upon device ports by a combination of kernel rpc's, and for tNU
UR �� -
UUR _performance reasons, a set of kernel traps. Kernel rpc's control access to the device and its [U UR �� @-
U registers.
f i��Y �� UT `0
[a dev_intr_attach()
�T� UR �� `2
U Request interrupt notification.
<�T� UR �� `s
U a
c�T� UR �� `.
Viv #import <Devices/user_driver.h>
at�T� UR �� `t
UUR "dev_return_t
Vdev_intr_attach(
�T� UR �� `5
Uth port_t
adev_port
U,
Bo
T� UR �� `6
Uis port_t
aintr_port
U);
T� UR �� `,
UUR
�7T� UR �� `7
Uic
DESCRIPTION
�HT� UR �� :
Vas Sdev_intr_attach
U() requests that interrupt notification messages for the device URUT� UR �� @:
Ur 7represented by dev_port be sent to the port intr_port.
.
oT� UR �� A
U YOnly a single port may be attached for device interrupts at any point in time. (A policy a|T� UR �� @A
U -decision, more than functional requirement.)
$ 6 � & � ' # $ 6 � y of l UR UR �� `
UU
R H ��X�
' � & # a H ��X�
z l t �� �� �� `
_ts `NRW Device Driver Guide # of 18 7/30/91 COMPANY CONFIDENTIAL
�� �� �� `
_t
i +�� �� �� `
_UR � d ( � #i ) ) � iv $ 6 � ) � ( re $ 6 � % +| 5 UR UR �� `C
Urt RIn NRW, this request also binds a device interrupt with an interrupt request bit.
!UM UR �� `E
aic Ddev_port
U is the port representing the device access capability.
ha ;UH UR �� `H
aca Qintr_port
U is the port to which interrupt notification messages will be sent.
n p�� �� UT `3
[_p dev_intr_detach()
�U? UR �� `=
Uin Disable interrupt notification.
e �U: UR �� `?
Upo
�U5 UR �� `@
V a #import <Devices/user_driver.h>
re �U0 UR �� `L
Ueq &dev_return_t
Vdev_intr_detach
U(
�U+ UR �� `M
U port_t
adev_port
U,
of �U& UR �� `N
U�� port_t
aintr_port
U);
U! UR �� `P
U
DESCRIPTION
$U UR �� Q
V ]dev_intr_detach
U disassociates interrupt notification messages for the device represented 71U UR �� @Q
UNY :by
adev_port
U from being sent to
aintr_port
U.
f�h �� UT `R
[ dev_chan_attach()
�U UR �� `9
U ,Attach a DMA channel to a specified device.
�U UR �� `D
U
+�U UR �� `F
V #import <Devices/user_driver.h>
r�T� UR �� `T
Ua &dev_return_t
Vdev_chan_attach
U(
�T� UR �� `U
U�� port_t
adev_port
U,
po�T� UR �� `V
Ue int
achan_num
U,
ha�T� UR �� `W
Uca !boolean_t
astream_mode
U,
h�T� UR �� `X
Uat int
abuffer_size
U);
��T� UR �� `Z
Ude
DESCRIPTION
+T� UR �� ;
Vin Jdev_chan_attach
U associates a system-wide global DMA channel with the 8T� UR �� @;
Uic ^device-specific local channel
achan_num
U of the device represented by
adev_port
U.
RT� UR �� ]
Ud ZA
Vdev_chan_attach
U must be performed for each physical dma channel to be used with _T� UR �� @]
UUR
the device.
eyT� UR �� `_
adi Ddev_port
U is the port representing the device access capability.
7 d * � or + + � to $ 6 � + � * R $ 6 � ) -| ch UR UR �� b
aa Wchan_num
U is the device physical channel number that should be bound with a logical riv UM UR �� @b
U��
dma channel.
e .UH UR �� g
an_ Tstream_mode
U specifies whether or not the device-specific hardware is capable of ;UC UR �� g
UU Egenerating an End Of Record signal on input. See the description for � HU> UR �� @g
Ua Bchan_dma_enqueue for more information on streaming mode channels.
bU9 UR �� l
a_a Zbuffer_size
U is the device-specific DMA buffer size. The kernel needs this information oU4 UR �� l
Uan Qwhen performing DMA dequeue operations; it is also used in verifying correct DMA ] |U/ UR �� @l
Uan alignment.
ust ��� �� UT `n
[ea dev_chan_detach()
�U& UR �� `J
Uh (Dissociate a DMA channel from a device.
UR �U! UR �� `O
Upo
�U UR �� `Y
Vre #import <Devices/user_driver.h>
tyU UR �� `o
U &dev_return_t
Vdev_chan_detach
U(
U UR �� `p
U port_t
adev_port
U,
+U
UR �� `q
U - int
achan_num
U);
RKU UR �� `r
U_n
DESCRIPTION
e\U UR �� u
Vne Ydev_chan_detach
U disassociates the local DMA channel
achan_num
U from the device RiT� UR �� @u
Uam !represented by
adev_port
U.
t��O �� UT `v
[ h dev_reg_map()
�T� UR �� `I
U�� 1Map a device page into a driver�s address space.
u�T� UR �� `S
Uti
f�T� UR �� `[
Vg #import <Devices/user_driver.h>
fo�T� UR �� `x
Ung "dev_return_t
Vdev_reg_map
U(
T� UR �� `y
Uis port_t
adev_port
U,
er T� UR �� `z
Uee !vm_task_t
atarget_task
U,
l%T� UR �� `{
Uin 1vm_offset_t *
aaddr
U,/* in/out */
i2T� UR �� `|
UU/ boolean_t
aanywhere
U);
���RT� UR �� `}
Ude DESCRIPTION
)
cT� UR �� ~
Uh Vdev_reg_map maps the device register page of the device associated with dev_port into pT� UR �� ~
U/u Uthe target task at addr. This RPC is invalid for m88k devices which are not NRW DMA �}T� UR �� @~
U )devices and for non-native m68k devices.
d , � �� - - �
e $ 6 � - � , ac $ 6 � + /|
_n UR UR �� `�
avi ;dev_port
U is the kernel provided handle for the device.
��O !UM UR �� `�
ade Ztarget_task
U represents the address space into which the device page should be mapped.
;UH UR �� `�
aT� Waddr
U is the address in
atarget_task
U where the device page should be mapped.
Vd UUC UR �� �
aT� \anywhere
U is a boolean; if true, indicates the kernel may pick any unused address to map as bU> UR �� @�
U�� the device page.
e ��� �� UT `\
[ ' dev_reg_unmap()
i �U5 UR �� `^
UU/ 4Remove a device page from a driver�s address space.
de �U0 UR �� `a
UT�
R �U+ UR �� `c
Vre #import <Devices/user_driver.h>
e �U& UR �� `�
Uci $dev_return_t
Vdev_reg_unmap
U(
~U! UR �� `�
Uas port_t
adev_port
U,
id U UR �� `�
Uhi !vm_task_t
atarget_task
U,
~ U UR �� `�
Ufo vm_offset_t
aaddr
U);
>U UR �� `�
U DESCRIPTION
OU
UR �� �
V
e Pdev_reg_unmap
U unmaps the device register page of the device associated with \U UR �� �
a� kdev_port
U.
atarget_task
U and
aaddr
U must match similar parameters passed to a previous call resiU UR �� @�
Upa to dev_reg_map().
��T �� UT `�
[e dev_slot_map()
���T� UR �� ``
U i .Map slot space into a driver�s address space.
�T� UR �� `e
Ube
p�T� UR �� `f
V�� #import <Devices/user_driver.h>
n;�T� UR �� `�
Us #dev_return_t
Vdev_slot_map
U(
s t T� UR �� `�
U�� port_t
adev_port
U,
���T� UR �� `�
U !vm_task_t
atarget_task
U,
/%T� UR �� `�
Upa vm_offset_t
aoffset
U,
2T� UR �� `�
Ua vm_size_t
alen
U,
e?T� UR �� `�
U/u 1vm_offset_t *
aaddr
U,/* in/out */
LT� UR �� `�
UU boolean_t
aanywhere
U);
t fT� UR �� `�
Ud
d . � ta / / � UR $ 6 � / � . dr $ 6 � - 1| UR UR UR �� �
Vre \dev_slot_map
U maps the slot space of the NeXTbus device associated with
adev_port
U � UM UR �� @�
Ua Sinto the target task at
aaddr
U. This RPC is illegal for native m68k devices.
all .UH UR �� `�
a� ;dev_port
U is the kernel provided handle for the device.
�� HUC UR �� `�
a i Ztarget_task
U represents the address space into which the device page should be mapped.
bU> UR �� `�
a/u Voffset
U is an offset within the device's slot space at which mapping should begin.
|U9 UR �� `�
a Naddr
U is the address in target_task where the slot space should be mapped.
�U4 UR �� �
a dlen
U is the length in bytes of the region to be mapped. The maximum value for (
aoffset
U + _o �U/ UR �� �
a
U Nlen
U) is 0xf00000 (15M) for NRW DMA devices and 0x1000000 (16 M) for other �U* UR �� @�
Ud devices.
�U% UR �� �
a \anywhere
U is a boolean, if true, indicates the kernel may pick any unused address to map �U UR �� @�
U the slot space.
� �q �� UT `�
[
dev_slot_unmap()
a*U UR �� `h
Ude 0Remove slot space from a driver�s address space
��AU UR �� `j
U t
eRU
UR �� `m
V
#import <Devices/user_driver.h>
mlU UR �� `�
UUH %dev_return_t
Vdev_slot_unmap
U(
eyU UR �� `�
Ule port_t
adev_port
U,
���T� UR �� `�
Uas !vm_task_t
atarget_task
U,
i�T� UR �� `�
Uce vm_offset_t
aaddr
U,
UR�T� UR �� `�
Uet vm_size_t
alen
U);
�T� UR �� `�
Uce DESCRIPTION
in�T� UR �� �
VU9 Odev_slot_unmap
U unmaps the slot space of the NeXTbus device associated with uld�T� UR �� @�
aUR sdev_port
U.
aaddr
Uand
alen
U must match similar fields from a previous call to
Vdev_slot_map
U.
�U/ d 0 � 00 1 1 � ev $ 6 � 1 � 0 r $ 6 � / 3| �� �� �� UT `�
[a dev_board_map()
in &UN UR �� `s
U m /Map board space into a driver�s address space.
@� =UI UR �� `w
Uce
� NUD UR �� `
V
#import <Devices/user_driver.h>
h hU? UR �� `�
Usp $dev_return_t
Vdev_board_map
U(
U uU: UR �� `�
U
e port_t
adev_port
U,
<D �U5 UR �� `�
U.h !vm_task_t
atarget_task
U,
n �U0 UR �� `�
Uma vm_offset_t
aoffset
U,
�U+ UR �� `�
Ut vm_size_t
alen
U,
s �U& UR �� `�
Uta 0vm_offset_t *
aaddr
U,/* in/out */
t �U! UR �� `�
UT� boolean_t
aanywhere
U);
le �U UR �� `�
U��
� �U UR �� �
Vin Mdev_board_map
U maps the board space of the NeXTbus device associated with e �U UR �� @�
ath 3dev_port
U into the target task at
aaddr
U.
andU
UR �� `�
ama ;dev_port
U is the kernel provided handle for the device.
U.+U UR �� `�
a Ztarget_task
U represents the address space into which the board space should be mapped.
EU UR �� `�
a 3 Woffset
U is an offset within the device's board space at which mapping should begin.
rd _T� UR �� `�
ar� Waddr
U is the address in
atarget_task
U where the board space should be mapped.
rivyT� UR �� �
a�� dlen
U is the length in bytes of the region to be mapped. The maximum value for (
aoffset
U + U5�T� UR �� @�
a len
U) is 0x10000000 (256M).
�U0�T� UR �� �
a \anywhere
U is a boolean, if true, indicates the kernel may pick any unused address to map ta�T� UR �� @�
U
a the board space.
�; �� UT `�
[UR dev_board_unmap()
T� UR �� `K
U
2Remoce board space from a driver�s address space.
T� UR �� `i
U
s(T� UR �� `t
Vf #import <Devices/user_driver.h>
eBT� UR �� `�
Uth &dev_return_t
Vdev_board_unmap
U(
OT� UR �� `�
UU
port_t
adev_port
U,
i\T� UR �� `�
Ude !vm_task_t
atarget_task
U,
RiT� UR �� `�
Uet vm_offset_t
aaddr
U,
ssvT� UR �� `�
Uth vm_size_t
alen
U);
d 2 � U 3 3 � he $ 6 � 3 � 2 pi $ 6 � 1 :| ad i UR UR �� `�
U
a DESCRIPTION
U UM UR �� �
Vpa Ndev_slot_map
U unmaps the board space of the NeXTbus device associated with %UH UR �� �
aap ]dev_port
U.
aaddr
Uand
alen
U must match similar fields from a previous call to 5 2UC UR �� @�
U�� dev_board_map.
e
g�� �� UT `�
[f Operational RPC's
��� �� UT `�
[y chan_command()
ma �U6 UR �� `�
U� Issue channel-specific command.
UT �U1 UR �� `�
Ud_
a �U, UR �� `�
VK #import <Devices/user_driver.h>
iv �U' UR �� `�
U.
$chan_return_t
Vchan_command
U(
t
U" UR �� `�
UT� port_t
adev_port
U,
��U UR �� `�
Urn int
achan_num
U,
(
$U UR �� `�
UU
#chan_command_t
acommand
U);
URDU UR �� `�
U_t DESCRIPTION
etUU UR �� d
VUR ]chan_command
U is used to issue commands on the dma channel identified by
adev_port
U bU UR �� d
U Zand
achan_num
U. CHAN_NONE can be specified for
achan_num
U if no channels are oU UR �� d
U Qattached; in this case the only legal chan_command_t bits are CC_INTR_ENABLE and
|T� UR �� @d
Ud QINTR_DISABLE. Otherwise it is an error if the device or channel is not attached.
�T� UR �� `�
aen ;dev_port
U is the kernel provided handle for the device.
UR�T� UR �� `�
abo (chan_num
U is a local channel number.
na�T� UR �� `�
aUT 7command
U is the command for the channel to execute:
han�T� UR �� `�
Und -CC_START_READ -- enable read dma (68K only)
K�T� UR �� `�
U/u /CC_START_WRITE -- enable write dma (68K only)
_t T� UR �� `�
UU =CC_ABORT -- abort current dma (disables channel) (68K only)
R2T� UR �� `�
Ut 4CC_INTR_ENABLE -- enable interrupts on the channel
ndLT� UR �� `�
U); 6CC_INTR_DISABLE -- disable interrupts on the channel
fT� UR �� �
U
DAll commands may be or'ed with CC_INTR_ENABLE or CC_INTR_DISABLE to posT� UR �� �
U�� ;form compound commands (e.g. CC_ABORT | CC_INTR_DISABLE or or �T� UR �� �
Uf CCC_START_READ | CC_INTR_ENABLE). Note than on NRW, CC_START_READ, le d 4 � R_ 5 5 � �� $ 6 � 5 � 4 it $ 6 � %| ot he
��
�� UU h�
Z� 1 Kernel-Level Driver Support
ro B�� �� UT `
[he
Device Ports
� ]UM UR �� !
Uch YRights to access a device's registers, to program its dma channel, and receive interrupt r jUH UR �� !
Uec ^notification are conveyed by a task holding send rights to a per-device port referred to here wUC UR �� !
U-- cas the
adev_port
U. The kernel responds to requests sent on the dev_port in order to provide l) �U> UR �� !
UUR fthese services to the requesting task.
adev_port
U's are created early in system initialization �U9 UR �� @!
Urr Zand passed out to the appropriate device drivers by a process that is not described here.
ƪ� �� UT `"
[po Register Mapping
� �U0 UR �� %
Umm [This interface provides various mechanisms for device drivers to map the physical register BLE �U+ UR �� %
URW [space associated with their devices into their local address space. Which mechanism(s) can � �U& UR �� %
Uit Zbe used by a particular device driver are determined by the machine architecture, whether U! UR �� @%
U�� _the device is a native device or a NextBus device, and the Slot ID in which the device lives.
rog"U UR �� &
Ul, _For the purposes of the following discussion, an
VNRW DMA Device
U is defined as a device ght/U UR �� &
Upo [in an m88k machine which resides in a slot with whose NextBus slot Id bits 9 through 7 are que<U UR �� @&
UT� \'111'. A
Vnative device
U is a device which is an integral part of an m68k-based CPU.
deVU
UR �� '
Ure [There are three kinds of device register space which can be mapped in to a device driver's evicU UR �� @'
Uoc local address space:
e}U UR �� )
VUT \Register Space
U consists of one page (the size of which is machine dependent but can for or�T� UR �� )
U m Znow be assumed to be 8k bytes) consisting of device-specific registers. For m88k devices, �T� UR �� )
U s Ythe format of a device page is defined in the NRW system spec, section 5.2.8.2. For m68k �T� UR �� )
Uth \devices, a device page is the physical memory region comprising all of the registers in one us�T� UR �� @)
Ulo Unative device; the start of the register space may not be page-aligned in this case.
w�T� UR �� `+
] m88k devices:
�T� UR �� /
Us TA driver can map in a register page if and only if it is associated with an NRW DMA e �T� UR �� @/
Uts Device.
7 T� UR �� `(
]�� m68k devices:
&T� UR �� `1
Uic _A driver can map in a register page if and only if it is associated with a native device.
S
re @T� UR �� `4
Sic P
VSlot Space
Uconsists of up to 16 MB of memory, starting at 0xfs000000.
ocZT� UR �� `
]ac m88k devices:
d 6 � st 7 8 � e $ 6 � 7 � 8 6 ca $ 6 � } ed 8 UR UR �� `
Ug d H ��X�
8 � 7 6 d H ��X�
~ f ce �� �� �� h
_n O1- - # . / Running H/F 1 0 : 2 Running H/F 2 ; 3 PRELIMINARY 4 dev d 9 � gi : : � he $ 6 � : � 9 ) $ 6 � 3 <| st &ce UR UR �� �
Uli NCC_START_WRITE, and CC_ABORT are done by the driver by directly accessing the UM UR �� @�
Ua channel command register.
I�� �� UT `
[wi chan_dma_enqueue()
UR gUD UR �� `�
Uce *Add a DMA Frame to the current DMA queue.
~U? UR �� `�
UA
v �U: UR �� `�
Vgi #import <Devices/user_driver.h>
oc �U5 UR �� `
Ue (chan_return_t
Vchan_dma_enqueue
U(
S �U0 UR �� `
Uis port_t
adev_port
U,
sta �U+ UR �� `
U0. int
achan_num
U,
8 �U& UR �� `
U task_t
atask_port
U,
�U! UR �� `
Ue vm_offset_t
aaddr
U,
�U UR �� `
U vm_size_t
alen
U,
d �U UR �� `
U�� direction_t
arw
U,
U UR �� `
U d chan_desc_cmd_t
acmd
U,
~ U
UR �� `
U�� unsigned char
aindex
U,
Ru U UR �� `
U $chan_enqueue_opts_t
aopts
U,
4 +U UR �� `
U unsigned
adma_id
U,
: :8T� UR �� `
U boolean_t *
arunning
U);
6 ET� UR �� `
U
<VT� UR ��
Vce Wchan_dma_enqueue
U builds and enqueues a list of dma descriptors describing a block esscT� UR ��
U�� ]of memory. This block of memory is referred to as a
Vframe
U. The frame may cross page �pT� UR ��
Uam Vboundaries in most cases. The exception is for channels which have been configured as }T� UR ��
Uoc X"streaming mode" channels per
Vdev_chan_attach
U(). Frames for DMA read operations rt�T� UR ��
U, S(device to memory) for streaming mode channels must not cross page boundaries. The at�T� UR ��
UU! \reason for this restriction is that when the device-specific logic signals "End of record",
d�T� UR ��
U�� Wthe DMA hardware will advance to the next buffer descriptor, not the next frame. There UR�T� UR ��
Usi Ois no way for the hardware to advance to the next frame; frames are a software
U�T� UR ��
U Tconstruct. Therefor for such channels, we force one frame to consist of exactly one );�T� UR �� @
U DMA descriptor.
���T� UR ��
U_e RThere are system dependent limits to the amount of memory that may be queued with �T� UR ��
Vof Ychan_dma_enqueue
U; exceeding this limit will return an error and the data will not be ��T� UR �� @
Uam
enqueued.
T� UR ��
a baddr
U must be aligned to the size of the device buffer. On m68K machines,
alen
U must be &T� UR ��
Uan Wa multiple of the device buffer length for all descriptors with CEO_EOR not set in the for3T� UR ��
aan `opts
U argument. On m88k machines,
alen
U must be a multiple of the device buffer length ha@T� UR �� @
Usp for DMA read operations.
fZT� UR �� `
UUR CChains of DMA frames will be limited to some length by the kernel.
ptotT� UR �� `�
aam ;dev_port
U is the kernel provided handle for the device.
to d ; � ar < < � UR $ 6 � < � ; fo $ 6 � : >| si ex UR UR �� `
aUR (chan_num
U is a local channel number.
�� !UM UR �� `
ae :task_port
U is the task where dma will be done to/from.
;UH UR �� `!
aUR Haddr
U is the address in the current task where the dma should begin.
ro UUC UR �� `#
al Dlen
U is the length of the dma in the target tasks address space.
m oU> UR �� &
ath Trw
U is the direction of the dma, either DMA_DIR_READ (from the device to memory) an |U9 UR �� @&
Ue .or DMA_DIR_WRITE (from memory to the device).
�U4 UR �� `(
ahe 8cmd
U is a NRW channel descriptor command (m88k only)
ne �U/ UR �� `*
at \index
U contains the region and register index to which cmd will be written (m88k only).
T� �U* UR �� `,
aCh [opts
U are channel options that should apply to the frame being enqueued. These include:
_po �U% UR �� -
Uel GCEO_EOR -- the last descriptor in the frame should be indicated as the �U UR �� @-
UUR end-of-record.
< � U UR �� `.
U 9CEO_DESC_INTR -- interrupt when this frame is completed.
�%U UR �� `/
U
3CEO_ENABLE_INTR -- enable interrupt notification.
:ta?U UR �� `0
U t ACEO_ENABLE_CHAN -- enable DMA channel after enqueue (m68k only).
iYU UR �� `1
Uhe ?CEO_DESC_CMD -- enable channel descriptor command (m88k only)
DlesU UR �� 5
ah ^dma_id
U is an integer, uninterpreted by the kernel, whose sole purpose is to identify this �U UR �� @5
UMA Zframe when
Vchan_dma_dequeue
U()'d.
adma_id
U must not be equal to DMA_ID_NULL.
�T� UR �� 7
aU4 [running
U is returned; on the m68k this indicates whether the channel was enabled at the at �T� UR �� 7
Uin Stime of the enqueue (if not, a channel enable will be required). On the m88k, this ���T� UR �� 7
U a Yindicates whetehr or not the transfer engine had a non-empty descriptor list at the time R�T� UR �� 7
UEO ]of the enqueue. If on the m88k
arunning
U is FALSE, a Load Descriptor operation will be f�T� UR �� @7
UUR necessary to start the channel.
er d = �
� > > � C $ 6 � > � = n $ 6 � < F| EN !HA �� �� UT `9
[an chan_dma_dequeue()
8k &UN UR �� `�
U�� /Dequeue DMA frames from the current DMA queue.
tor =UI UR �� `�
Uy)
e NUD UR �� `�
Vh #import <Devices/user_driver.h>
rp hU? UR �� `;
Ul, (chan_return_t
Vchan_dma_dequeue
U(
U uU: UR �� `<
Ufr port_t
adev_port
U,
U �U5 UR �� `=
U
U int
achan_num
U,
_I �U0 UR �� `>
U�� #chan_dequeue_opt_t
aopts
U,
th �U+ UR �� `?
Ute vm_size_t *
abcount
U,
e �U& UR �� `@
UUR &chan_status_t *
achan_status
U,
�U! UR �� `A
Ue $dma_status_t *
adma_status
U,
�� �U UR �� `B
U a boolean_t *
aeor
U,
�U UR �� `C
U h unsigned *
adma_id
U);
a �U UR �� `D
UUR DESCRIPTION
ofU
UR �� J
Vn Gchan_dma_dequeue
U dequeues a single DMA frame which was enqueued by �T�U UR �� J
Vne Wchan_dma_enqueue
U. It will only dequeue frames that meet the criteria specified in CU UR �� J
a � ]opts
U. It unlocks the associated memory. It returns an indication if more descriptors are d(T� UR �� @J
UUN 8available to dequeue by the criteria specified in opts.
quBT� UR �� P
V�� Mchan_dma_dequeue
U will return an error (CR_BUSY) if the CDO_ALL option is �OT� UR �� P
Uur Tspecified, the channel is running , and no completed frames are available. In other U5\T� UR �� P
U Twords, it is not possible to dequeue non-completed descriptors while the channel is U+iT� UR �� @P
U running.
�T� UR �� `R
aU& ;dev_port
U is the kernel provided handle for the device.
UR�T� UR �� `�
aa_ *chan_num
U is a logical channel number.
�T� UR �� `�
an_ Aopts
U are options to
Vchan_dma_dequeue
U, these include:
a�T� UR �� `�
UUR +CDO_DONE -- dequeue only completed frames.
a_d�T� UR �� `�
Us CDO_ALL -- dequeue all frames.
eueT� UR �� `�
U�� *CDO_ENABLE_INTR -- enable interrupt msgs.
T� UR �� �
Uha NCDO_EI_IF_MT -- reenables device interrupts for the device if no more frames ,T� UR �� @�
Ury may be dequeued.
iFT� UR �� `�
Ucr !The flags may be or'ed together.
v`T� UR �� �
a b \bcount
U(returned) is the byte count of actually transferred data. It is only valid for ermT� UR �� @�
U�� Qtransfer from the device into memory (i.e. DMA reads). Zero returned on writes.
o d ? � n @ @ � P $ 6 � @ � ? d $ 6 � H | c i d E �
F F � de $ 6 � F � E ha $ 6 � > H| a_
_n UR UR �� �
al ^chan_status
U is the channel descriptor status (only valid for m88k). It is only valid for UM UR �� �
U�� Utransfer from the device into memory (i.e. DMA reads). Zero returned on writes. The - !UH UR �� @�
Us. *meaning of this field is device-specific.
;UC UR �� �
ams \dma_status
U is machine-independent and indicates the current state of the channel (e.g., re HU> UR �� @�
U�� /running, idle, underrun). Only valid for m68k.
!Th bU9 UR �� �
aed ]eor
U is an end of record indication (only valid for certain device and only valid on "DMA e oU4 UR �� @�
Uy 0read" transactions). FALSE returned on writes.
e �U/ UR �� �
a ( ^dma_id
U is an integer, uninterpreted by the kernel, whose sole purpose is to identify this �U* UR �� �
U ]frame to the device driver.
adma_id
U matches the dma_id of a frame previously enqueued � �U% UR �� �
U ]via
Vchan_dma_enqueue
U. If
adma_id
Uis DMA_ID_NULL, no descriptors are available �U UR �� �
UUR Vfor dequeueing. (This is not an error - that is,
Vchan_dma_dequeue
U will return �U UR �� @�
Ur CR_SUCCESS in this case.)
�U UR �� `�
U i d G � ur H H � UH $ 6 � H � G fi $ 6 � F @| ms � � � Ud � 6 t Left d � � e Rightc nnd � � � ( �� d � � � * nd d � � 4 k. d � � # eo RightNo1Head Rightcord � � � id LeftBlankFooterc d � � � , e d � � � . " Leftd � � � 0 d � � � $ � d � � � 2 eg d � � � 9 er d � � � ; t Leftd � � � =
� d � � ?
dr Leftd � � � E he d � � � G sl Left �
E
9 $ $ $ '
� @ �
Z P ad
p 1Heada BodyUR H Z $ '
� @ �
[ @
th
l FctHead
FctSummaryUC � � $
� @ �
U d H � UH � �
BodyIndented26 ~ ~ $
� @ �
U
� � Ri tc � � ( FunctVarDesc * l l $
� @ �
X # Tip� Bold Tip: kF
� @ �
U P Figure FigureTitled � l $
� @ �
U q d �
FctSummary SUMMARY\tr
FctLibrary � l $
� @ �
U q eft �
Z
FctLibrary LIBRARY\t FctSynopsis
~ ~ $
� @ �
U � �
� BodyIndented ma � @ �
_ v� UH � �
FooterLeft � � $
� @ �
V P
� tc V � TableHead TableBody$ l $ $
� @ �
X A ^� Ti l Warning Bold \tWarning:\t Body l l $
� @ �
U l � ~ @
U � � Body l l $
� @ �
U Ca \tr
FigCaption Default Font C:Figure <n>-<n+> Body l l $
� @ �
X Syn Note Bold Note: H H $
� @ �
[
FctHeadShort l l $
� @ �
] P
GlossTerm
GlossDef l l $ � @ �
U P
FctSubHead BodyIndented ~ ~ $
� @ �
V p $
� � �
HeaderFile Function l l $
� @ �
V P $
Troubleshooting Body l l $
� @ �
U Ca Fig1Caption Default Font C:Figure <n>-<n=1> Body ~ l $ � @ �
U igu ~ � �
X � yn � BulletShort �\t l l $ � @ �
` CQ �
ChapterNum
C:Chapter <n>H ChapterTitle � ~ $
� @ �
U NA
� Gl sT � � sD � Num1Long
N:<n=1>.\t
NumberLong ~ l $
� @ �
U ead ~ � � @
V � �
BulletLong �\t � ~ $
� @ �
U N e � @ � � � NumLong N:<n+>.\t � @ �
_ � �v� � FooterRighta � l $
� @
U q �
FctSummary SUMMARY\t
FctLibrary � � $
� @
U �
` � V � TableBody l l $ A � @
` p $ ChapterTitle Body � � $
I �
CodeExamp3 H H $ '
� @
[ P
2HeadV Body l l $ '
� @
\ P
3Head Body l l $ '
� @
] P
4Head Body@ ~ l $ � @
U NA i ~ � � � Num1Short
N:<n=1>.\t NumberShort ~ l $ � @
U N \t ~ @
U � � � NumShort N:<n+>.\t l l $
� @
U q FctSynopsis SYNOPSIS
HeaderFile � � $
I $
CodeExamp2 H Z $ '
� @
[ @
$
FctHead
FctSummary ~ l $
� @
X NA
~ � � � d Step1 Bold
N:<n=1>.\t
NumberBold l l $
� @
U l ~ � � @
U � Body ~ l $
� @
X N � ~ \t Nu � or � � Step Bold N:<n+>.\t l l $
� @
U
U GlossDef ~ ~ $
I � Fc yn � � PS
� Fi � � � 2 D V h Ex p2z � � � @ � � � CodeExamp � @
_
v� � �
FooterLeft l l $
� @
U q .\t FctSynopsis SYNOPSIS
HeaderFile ~ ~ $
� @
V p @
� � � �
X
HeaderFile Function � � $
� @
U n � � � �
BodyIndented2 $ $ $ '
� @
Z P
1Head Body H H $ '
� @
[ P
2Head Body ~ ~ $
� @
&
U � � @ � BodyIndented � ~ $ � @
'
U @ ~ � v� � � �
ot � � � �
U 2 \tD V h Function ~ ~ $
� @
(
] �
� �
� BodyIndented
X � ~ $ � @
)
U ~ � � � � �
dy � ed � � 2 @
ZD V h Function l l $ � @
*
U P
FctSubHead BodyIndented � @
-
_ v� � �
FooterLeft � @
3
_ '
U �v� � FooterRight
I
y
T ��
I ��
J U Italic ��
K Emphasisnc ��
L BookName /��
M
Bold ���
N Symbol ��
O X Subscript ���
P Trademark ���
Q Superscript� ��
R GlossTerm ��k<
S ���
U ��ģ
V
��ģ
X
Bold
U ��ģ
Z
��ģ
[
Bo ��ģ
\
� ~l
]
nw
_ ���
` nw
a Courier Helvetica Symbol Times Regular� Regular
Bold Regular Italic �A|���x�X����Kơ ��4�����Gc�n�V�e���/�>��V[2�@�{�� �Y,éaL
��@�ls�G����)��:��vy_W�Ȉ TPP���'Y �� ��%�M����3�z���\۫�w1��f��Ua��sw�\Wl��P�E ���� S��#�
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.