csx_DupHandle(9f)

1csx_DupHandle(9F)        Kernel Functions for Drivers        csx_DupHandle(9F)
2
3
4

NAME

6       csx_DupHandle - duplicate access handle
7

SYNOPSIS

9       #include <sys/pccard.h>
10
11
12
13       int32_t csx_DupHandle(acc_handle_t handle1, acc_handle_t *handle2,
14            uint32_t flags);
15
16

INTERFACE LEVEL

18       Solaris DDI Specific (Solaris DDI)
19

PARAMETERS

21       handle1     The   access  handle  returned  from  csx_RequestIO(9F)  or
22                   csx_RequestWindow(9F) that is to be duplicated.
23
24
25       handle2     A pointer to the newly-created duplicated data access  han‐
26                   dle.
27
28
29       flags       The  access attributes that will be applied to the new han‐
30                   dle.
31
32

DESCRIPTION

34       This function duplicates the handle, handle1, into a new  handle,  han‐
35       dle2,  that  has the access attributes specified in the flags argument.
36       Both the original handle and the new handle are active and can be  used
37       with the common access functions.
38
39
40       Both  handles  must  be explicitly freed when they are no longer neces‐
41       sary.
42
43
44       The flags argument is bit-mapped. The following bits are defined:
45
46         WIN_ACC_NEVER_SWAP       Host endian byte ordering
47         WIN_ACC_BIG_ENDIAN       Big endian byte ordering
48         WIN_ACC_LITTLE_ENDIAN    Little endian byte ordering
49         WIN_ACC_STRICT_ORDER     Program ordering references
50         WIN_ACC_UNORDERED_OK     May re-order references
51         WIN_ACC_MERGING_OK       Merge stores to consecutive locations
52         WIN_ACC_LOADCACHING_OK   May cache load operations
53         WIN_ACC_STORECACHING_OK  May cache store operations
54
55
56
57       WIN_ACC_BIG_ENDIAN and WIN_ACC_LITTLE_ENDIAN describe the endian  char‐
58       acteristics of the device as big endian or little endian, respectively.
59       Even though most of the devices will have the same endian  characteris‐
60       tics as their busses, there are examples of devices with an I/O proces‐
61       sor that has  opposite  endian  characteristics  of  the  busses.  When
62       WIN_ACC_BIG_ENDIAN or WIN_ACC_LITTLE_ENDIAN is  set, byte swapping will
63       automatically be performed by the system if the host  machine  and  the
64       device data formats have opposite endian characteristics. The implemen‐
65       tation may take advantage of hardware platform byte swapping  capabili‐
66       ties.   When WIN_ACC_NEVER_SWAP is specified, byte swapping will not be
67       invoked in the data access functions. The ability to specify the  order
68       in which the CPU will reference data is provided by the following flags
69       bits. Only one of the following bits may be specified:
70
71       WIN_ACC_STRICT_ORDER        The data references must be issued by a CPU
72                                   in  program  order.  Strict ordering is the
73                                   default behavior.
74
75
76       WIN_ACC_UNORDERED_OK        The CPU may re-order the data   references.
77                                   This  includes  all  kinds  of  re-ordering
78                                   (that is, a load followed by a store may be
79                                   replaced by a store followed by a load).
80
81
82       WIN_ACC_MERGING_OK          The CPU may merge individual stores to con‐
83                                   secutive locations. For  example,  the  CPU
84                                   may  turn  two consecutive byte stores into
85                                   one halfword store. It may also batch indi‐
86                                   vidual loads. For example, the CPU may turn
87                                   two consecutive byte loads into  one  half‐
88                                   word  load.  Setting  this bit also implies
89                                   re-ordering.
90
91
92       WIN_ACC_LOADCACHING_OK      The CPU may cache the data it  fetches  and
93                                   reuse  it  until  another store occurs. The
94                                   default behavior is to fetch  new  data  on
95                                   every  load.  Setting this bit also implies
96                                   merging and re-ordering.
97
98
99       WIN_ACC_STORECACHING_OK     The CPU may keep the data in the cache  and
100                                   push  it  to the device (perhaps with other
101                                   data) at a later time. The  default  behav‐
102                                   ior is to push the data right away. Setting
103                                   this bit also implies load  caching,  merg‐
104                                   ing, and re-ordering.
105
106
107
108       These  values  are  advisory,  not  mandatory. For example, data can be
109       ordered without being merged or cached, even though a  driver  requests
110       unordered, merged and cached together.
111

RETURN VALUES

113       CS_SUCCESS                  Successful operation.
114
115
116       CS_FAILURE                  Error in flags argument or handle could not
117                                   be duplicated for some reason.
118
119
120       CS_UNSUPPORTED_FUNCTION     No PCMCIA hardware installed.
121
122

CONTEXT

124       This function may be called from user or kernel context.
125