1tuple(9S)                 Data Structures for Drivers                tuple(9S)
2
3
4

NAME

6       tuple - card information structure (CIS) access structure
7

SYNOPSIS

9       #include <sys/pccard.h>
10
11

INTERFACE LEVEL

13       Solaris DDI Specific (Solaris DDI)
14

DESCRIPTION

16       The tuple_t structure is the basic data structure provided by card ser‐
17       vices to manage PC card information. A PC card provides  identification
18       and  configuration  information  through its card information structure
19       (CIS). A PC card driver accesses a PC card's CIS through  various  card
20       services functions.
21
22
23       The  CIS  information  allows  PC cards to be self-identifying: the CIS
24       provides information to the system so that it can identify  the  proper
25       PC  card driver for the PC card, and provides configuration information
26       so that the driver can allocate appropriate resources to configure  the
27       PC card for proper operation in the system.
28
29
30       The  CIS  information  is  contained on the PC card in a linked list of
31       tuple data structures called a CIS chain. Each  tuple  has  a  one-byte
32       type  and  a  one-byte link, an offset to the next tuple in the list. A
33       PC card can have one or more CIS chains.
34
35
36       A multi-function PC card that complies with the PC Card  95  MultiFunc‐
37       tion  Metaformat  specification will have one or more global CIS chains
38       that collectively are referred to as the global  CIS.  These  PC  Cards
39       will  also  have one or more per-function CIS chains. Each per-function
40       collection of CIS chains is referred to as a function-specific CIS.
41
42
43       To examine a PC card's CIS, first a PC  card  driver  must  locate  the
44       desired tuple by calling csx_GetFirstTuple(9F). Once the first tuple is
45       located, subsequent tuples  may  be  located  by  calling  csx_GetNext‐
46       Tuple(9F).  See csx_GetFirstTuple(9F). The linked list of tuples may be
47       inspected one by one, or the driver may narrow the search by requesting
48       only tuples of a particular type.
49
50
51       Once a tuple has been located, the PC card driver may inspect the tuple
52       data. The most convenient way to do this  for  standard  tuples  is  by
53       calling  one of the number of tuple-parsing utility functions; for cus‐
54       tom tuples, the driver may get access to the raw tuple data by  calling
55       csx_GetTupleData(9F).
56
57
58       Solaris  PC  card  drivers  do  not need to be concerned with which CIS
59       chain a tuple appears in. On a multi-function PC card, the client  will
60       get  the tuples from the global CIS followed by the tuples in the func‐
61       tion-specific CIS. The caller will not get any tuples from a  function-
62       specific CIS that does not belong to the caller's function.
63

STRUCTURE MEMBERS

65       The structure members of tuple_t are:
66
67         uint32_t      Socket;          /* socket number */
68         uint32_t      Attributes;      /* tuple attributes */
69         cisdata_t     DesiredTuple;    /* tuple to search for */
70         cisdata_t     TupleOffset;     /* tuple data offset */
71         cisdata_t     TupleDataMax;    /* max tuple data size */
72         cisdata_t     TupleDataLen;    /* actual tuple data length */
73         cisdata_t     TupleData[CIS_MAX_TUPLE_DATA_LEN];
74                                        /* body tuple data */
75         cisdata_t     TupleCode;       /* tuple type code */
76         cisdata_t     TupleLink;       /* tuple link */
77
78
79
80       The fields are defined as follows:
81
82       Socket           Not  used  in  Solaris, but for portability with other
83                        card services implementations, it should be set to the
84                        logical socket number.
85
86
87       Attributes       This  field  is  bit-mapped.  The  following  bits are
88                        defined:
89
90                        TUPLE_RETURN_LINK
91
92                            Return link tuples if set.
93
94
95                        TUPLE_RETURN_IGNORED_TUPLES
96
97                            Return ignored tuples if set. Ignored  tuples  are
98                            those  tuples in a multi-function PC card's global
99                            CIS chain that are duplicates of the  same  tuples
100                            in a function-specific CIS chain.
101
102
103                        TUPLE_RETURN_NAME
104
105                            Return  tuple  name  string using the csx_ParseTu‐
106                            ple(9F) function if set.
107
108
109
110       DesiredTuple     This field is the requested  tuple  type  code  to  be
111                        returned   when   calling   csx_GetFirstTuple(9F)   or
112                        csx_GetNextTuple(9F). RETURN_FIRST_TUPLE  is  used  to
113                        return  the  first  tuple  regardless  of  tuple type.
114                        RETURN_NEXT_TUPLE is used to  return  the  next  tuple
115                        regardless of tuple type.
116
117
118       TupleOffset      This  field  allows  partial  tuple  information to be
119                        retrieved, starting at the specified offset within the
120                        tuple.  This  field  must  only  be set before calling
121                        csx_GetTupleData(9F).
122
123
124       TupleDataMax     This field is the size of the tuple data  buffer  that
125                        card  services  uses  to  return  raw  tuple data from
126                        csx_GetTupleData(9F). It can be larger than the number
127                        of bytes in the tuple data body. Card services ignores
128                        any value placed here by the client.
129
130
131       TupleDataLen     This field is the actual size of the tuple data  body.
132                        It  represents  the  number  of  tuple data body bytes
133                        returned by csx_GetTupleData(9F).
134
135
136       TupleData        This field is an array of  bytes  containing  the  raw
137                        tuple  data  body  contents  returned by csx_GetTuple‐
138                        Data(9F).
139
140
141       TupleCode        This field is the tuple type code and is  returned  by
142                        csx_GetFirstTuple(9F)  or  csx_GetNextTuple(9F) when a
143                        tuple matching the DesiredTuple field is returned.
144
145
146       TupleLink        This field is the tuple link, the offset to  the  next
147                        tuple,  and  is  returned  by csx_GetFirstTuple(9F) or
148                        csx_GetNextTuple(9F)  when  a   tuple   matching   the
149                        DesiredTuple field is returned.
150
151

SEE ALSO

153       csx_GetFirstTuple(9F),     csx_GetTupleData(9F),    csx_ParseTuple(9F),
154       csx_Parse_CISTPL_BATTERY(9F),           csx_Parse_CISTPL_BYTEORDER(9F),
155       csx_Parse_CISTPL_CFTABLE_ENTRY(9F),        csx_Parse_CISTPL_CONFIG(9F),
156       csx_Parse_CISTPL_DATE(9F),                 csx_Parse_CISTPL_DEVICE(9F),
157       csx_Parse_CISTPL_FUNCE(9F),                csx_Parse_CISTPL_FUNCID(9F),
158       csx_Parse_CISTPL_JEDEC_C(9F),              csx_Parse_CISTPL_MANFID(9F),
159       csx_Parse_CISTPL_SPCL(9F),                 csx_Parse_CISTPL_VERS_1(9F),
160       csx_Parse_CISTPL_VERS_2(9F)
161
162
163       PC Card 95 Standard,  PCMCIA/JEIDA
164
165
166
167SunOS 5.11                        20 Dec 1996                        tuple(9S)
Impressum