cis.h revision 7c478bd95313f5f23a4c958a745db2134aa03244
1/*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License, Version 1.0 only
6 * (the "License").  You may not use this file except in compliance
7 * with the License.
8 *
9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 * or http://www.opensolaris.org/os/licensing.
11 * See the License for the specific language governing permissions
12 * and limitations under the License.
13 *
14 * When distributing Covered Code, include this CDDL HEADER in each
15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 * If applicable, add the following below this CDDL HEADER, with the
17 * fields enclosed by brackets "[]" replaced with your own identifying
18 * information: Portions Copyright [yyyy] [name of copyright owner]
19 *
20 * CDDL HEADER END
21 */
22/*
23 * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
24 * Use is subject to license terms.
25 */
26
27#ifndef _CIS_H
28#define	_CIS_H
29
30#pragma ident	"%Z%%M%	%I%	%E% SMI"
31
32/*
33 * This is the Card Services Card Information Structure (CIS) interpreter
34 *	header file.  CIS information in this file is based on the
35 *	Release 2.01 PCMCIA standard.
36 */
37
38
39#ifdef	__cplusplus
40extern "C" {
41#endif
42
43
44#if defined(DEBUG)
45#define	CIS_DEBUG
46#endif
47
48
49/*
50 * The CIS interpreter has a single entry point with a bunch of function
51 *	id numbers.
52 */
53#define	CISP_CIS_SETUP		0x01	/* setup CS address in CIS */
54#define	CISP_CIS_LIST_CREATE	0x02	/* create the CIS linked list */
55#define	CISP_CIS_LIST_DESTROY	0x03	/* destroy the CIS linked list */
56#define	CISP_CIS_GET_LTUPLE	0x04	/* get a tuple */
57#define	CISP_CIS_PARSE_TUPLE	0x05	/* parse a tuple */
58#define	CISP_CIS_CONV_DEVSPEED	0x06	/* convert devspeed to nS and back */
59#define	CISP_CIS_CONV_DEVSIZE	0x07	/* convert device size */
60
61/*
62 * Make the  calls to CardServices look like function calls.
63 */
64#define	CIS_CARD_SERVICES	(*cis_card_services)
65
66/*
67 * define the tuples that we recognize
68 *
69 * Layer 1 - Basic Compatability TUples
70 */
71#define	CISTPL_NULL		0x000	/* null tuple - ignore */
72#define	CISTPL_DEVICE		0x001	/* device information */
73#define	CISTPL_LONGLINK_CB	0x002	/* longlink to next tuple chain */
74#define	CISTPL_CONFIG_CB	0x004	/* configuration tuple */
75#define	CISTPL_CFTABLE_ENTRY_CB	0x005	/* configuration table entry */
76#define	CISTPL_LONGLINK_MFC	0x006	/* multi-function tuple */
77#define	CISTPL_BAR		0x007	/* Base Address Register definition */
78#define	CISTPL_CHECKSUM		0x010	/* checksum control */
79#define	CISTPL_LONGLINK_A	0x011	/* long-link to AM */
80#define	CISTPL_LONGLINK_C	0x012	/* long-link to CM */
81#define	CISTPL_LINKTARGET	0x013	/* link-target control */
82#define	CISTPL_NO_LINK		0x014	/* no-link control */
83#define	CISTPL_VERS_1		0x015	/* level 1 version information */
84#define	CISTPL_ALTSTR		0x016	/* alternate language string */
85#define	CISTPL_DEVICE_A		0x017	/* AM device information */
86#define	CISTPL_JEDEC_C		0x018	/* JEDEC programming info for CM */
87#define	CISTPL_JEDEC_A		0x019	/* JEDEC programming info for AM */
88#define	CISTPL_CONFIG		0x01a	/* configuration */
89#define	CISTPL_CFTABLE_ENTRY	0x01b	/* configuration-table-entry */
90#define	CISTPL_DEVICE_OC	0x01c	/* other op conditions CM device info */
91#define	CISTPL_DEVICE_OA	0x01d	/* other op conditions AM device info */
92#define	CISTPL_DEVICEGEO	0x01e	/* Common Memory device geometry */
93#define	CISTPL_DEVICEGEO_A	0x01f	/* Attribute Memory device geometry */
94#define	CISTPL_MANFID		0x020 	/* manufacturer identification */
95#define	CISTPL_FUNCID		0x021	/* function identification */
96#define	CISTPL_FUNCE		0x022	/* function extension */
97
98/*
99 * Layer 2 - Data Recording Format Tuples
100 */
101#define	CISTPL_SWIL		0x023	/* software interleave */
102#define	CISTPL_VERS_2		0x040	/* level 2 version information */
103#define	CISTPL_FORMAT		0x041	/* Common Memory recording format */
104#define	CISTPL_GEOMETRY		0x042	/* geometry */
105#define	CISTPL_BYTEORDER	0x043	/* byte order */
106#define	CISTPL_DATE		0x044	/* card initialization date */
107#define	CISTPL_BATTERY		0x045	/* battery replacement date */
108#define	CISTPL_FORMAT_A		0x047	/* Attribute Memory recording format */
109
110/*
111 * Layer 3 - Data Organization Tuples
112 */
113#define	CISTPL_ORG		0x046	/* organization */
114
115/*
116 * Layer 4 - System Specific Standard Tuples
117 */
118#define	CISTPL_VEND_SPEC_80	0x080	/* vendor-specific 0x80 */
119#define	CISTPL_VEND_SPEC_81	0x081	/* vendor-specific 0x81 */
120#define	CISTPL_VEND_SPEC_82	0x082	/* vendor-specific 0x82 */
121#define	CISTPL_VEND_SPEC_83	0x083	/* vendor-specific 0x83 */
122#define	CISTPL_VEND_SPEC_84	0x084	/* vendor-specific 0x84 */
123#define	CISTPL_VEND_SPEC_85	0x085	/* vendor-specific 0x85 */
124#define	CISTPL_VEND_SPEC_86	0x086	/* vendor-specific 0x86 */
125#define	CISTPL_VEND_SPEC_87	0x087	/* vendor-specific 0x87 */
126#define	CISTPL_VEND_SPEC_88	0x088	/* vendor-specific 0x88 */
127#define	CISTPL_VEND_SPEC_89	0x089	/* vendor-specific 0x89 */
128#define	CISTPL_VEND_SPEC_8a	0x08a	/* vendor-specific 0x8a */
129#define	CISTPL_VEND_SPEC_8b	0x08b	/* vendor-specific 0x8b */
130#define	CISTPL_VEND_SPEC_8c	0x08c	/* vendor-specific 0x8c */
131#define	CISTPL_VEND_SPEC_8d	0x08d	/* vendor-specific 0x8d */
132#define	CISTPL_VEND_SPEC_8e	0x08e	/* vendor-specific 0x8e */
133#define	CISTPL_VEND_SPEC_8f	0x08f	/* vendor-specific 0x8f */
134#define	CISTPL_SPCL		0x090	/* special-purpose tuple */
135#define	CISTPL_END		0x0ff	/* end-of-list tuple */
136
137/*
138 * Macro to check if tuple is a vendor-specific tuple.
139 */
140#define	CISTPL_VENDSPEC_START	CISTPL_VEND_SPEC_80
141#define	CISTPL_VENDSPEC_END	CISTPL_VEND_SPEC_8f
142#define	CISTPL_IS_VENDOR_SPECIFIC(td)	(((td) >= CISTPL_VENDSPEC_START) &&   \
143						((td) <= CISTPL_VENDSPEC_END))
144
145/*
146 * The GetFirstTuple and GetNextTuple Card Services function calls use
147 *	the DesiredTuple member of the tuple_t structure to determine
148 *	while tuple type to return; since the CIS parser doesn't ever
149 *	return CISTPL_END tuples, we can never ask for those tuples,
150 *	so we overload this tuple code to mean that we want the
151 *	first (or next) tuple in the chain.
152 * XXX - If we ever do return CISTPL_END tuples, we'll have to
153 *	re-think this.
154 */
155#define	RETURN_FIRST_TUPLE	0x0ff	/* return first/next tuple */
156#define	RETURN_NEXT_TUPLE	0x0ff	/* return first/next tuple */
157
158/*
159 * types for data in CIS and pointers into PC card's CIS space
160 *
161 * The "size" member is used by the NEXT_CIS_ADDR macro so that
162 *	we don't run past the end of the mapped CIS address space.
163 */
164typedef uchar_t cisdata_t;
165
166typedef struct cisptr_t {
167    acc_handle_t	handle;	/* access handle of CIS space */
168    uint32_t		size;	/* size of mapped area */
169    uint32_t		offset;	/* byte offset into CIS space */
170	/* see flag definitions for cistpl_t structure */
171    uint32_t		flags;
172} cisptr_t;
173
174/*
175 * This is the maximum length that the data portion of a tuple can be.
176 *	We have to use this since the brain-damaged 2.01 PCMCIA spec
177 *	specifies that you can end a CIS chain by putting a CISTPL_END
178 *	in the link field of the last VALID tuple.
179 */
180#define	CIS_MAX_TUPLE_DATA_LEN	254
181
182/*
183 * This is the maximum size of the string used to describe the name
184 *	of the tuple.
185 */
186#define	CIS_MAX_TUPLE_NAME_LEN	40
187
188/*
189 * CIS_MAX_FUNCTIONS defines the maximum number of functions that can
190 *	exist on a card.
191 */
192#define	CIS_MAX_FUNCTIONS	8	/* max number of functions per card */
193
194/*
195 * Macros to manipulate addresses and data in various CIS spaces
196 *
197 * NEXT_CIS_ADDR(cisptr_t *) increments the offset to point to the
198 *	next data element in the CIS, based on what space the CIS
199 *	we are reading resides in.  If the resulting address would
200 *	be past the end of the mapped-in area, we return NULL,
201 *	otherwise the adjusted offset value is returned. Note that
202 *	this only works if the "size" member specifies the maximum
203 *	mapped in window size and an "offset" member value of zero
204 *	refers to the first byte of the window.
205 *
206 * GET_CIS_DATA(ptr) returns the data byte at the current CIS location.
207 *
208 * GET_CIS_ADDR(tp,ptr) returns the virtual address that was saved by a
209 *	call to STORE_CIS_ADDR.
210 *
211 * BAD_CIS_ADDR is a flag that should be returned by callers of NEXT_CIS_ADDR
212 *	if that macro returns NULL.  Note that this flag shares the same bit
213 *	field definitions as the tuple handler flags defined in cis_handlers.h
214 *	so check that file if you make any changes to these flags.
215 * XXX - not the best distribution of flags, I'm afraid
216 */
217#define	NEXT_CIS_ADDR(ptr)	\
218			(((ptr->flags&CISTPLF_AM_SPACE)?(ptr->offset += 2): \
219				(ptr->offset++)),	\
220				((ptr->offset > ptr->size)?(NULL):ptr->offset))
221#define	GET_CIS_DATA(ptr)	csx_Get8(ptr->handle, ptr->offset)
222#define	GET_CIS_ADDR(tp)	((cisdata_t *)(uintptr_t)(tp)->offset)
223#define	BAD_CIS_ADDR	0x080000000 /* read past end of mapped CIS error */
224
225/*
226 * CIS_MEM_ALLOC(len) is used to allocate memory for our local linked
227 *	CIS list; we use a macro so that the same code can be used in
228 *	the kernel as well as in user space
229 *
230 * CIS_MEM_FREE(ptr) - same comment as CIS_MEM_ALLOC
231 */
232#if !defined(_KERNEL)
233#ifdef	CISMALLOC_DEBUG
234#define	CIS_MEM_ALLOC(len)		cis_malloc((uint32_t)len)
235#define	CIS_MEM_FREE(ptr)		cis_free(ptr)
236#else
237#define	CIS_MEM_ALLOC(len)		malloc((uint32_t)len)
238#define	CIS_MEM_FREE(ptr)		free(ptr)
239#endif	/* CISMALLOC_DEBUG */
240#else
241#define	CIS_MEM_ALLOC(len)		cis_malloc((uint32_t)len)
242#define	CIS_MEM_FREE(ptr)		cis_free(ptr)
243#endif
244
245typedef struct cis_u_malloc_tag_t {
246	caddr_t		addr;
247	uint32_t	len;
248} cis_u_malloc_tag_t;
249
250/*
251 * We keep the tuples in a locally-maintained linked list.  This allows
252 *	us to return the tuple information at any time to a client for
253 *	those cards that make their CIS inaccessible once the card is
254 *	configured.
255 */
256typedef struct cistpl_t {
257	cisdata_t	type;	/* type of tuple */
258	cisdata_t	len;	/* length of tuple data */
259	cisdata_t	*data;	/* data in tuple */
260	union {
261		cisdata_t	*byte;	/* read pointer for GET_BYTE macros */
262		uint16_t	*sword;
263	}		read;
264	uint32_t	flags;	/* misc flags */
265	uint32_t	offset;	/* CIS address offset of start of tuple */
266	struct cistpl_t	*prev;	/* back pointer */
267	struct cistpl_t	*next;	/* forward pointer */
268} cistpl_t;
269
270/*
271 * Flags that are used in the cistpl_t and cisptr_t linked lists
272 */
273#define	CISTPLF_NOERROR		0x000000000 /* no error return from handler */
274#define	CISTPLF_UNKNOWN		0x000000001 /* unknown tuple */
275#define	CISTPLF_REGS		0x000000002 /* tuple contains registers */
276#define	CISTPLF_COPYOK		0x000000004 /* OK to copy tuple data */
277#define	CISTPLF_VALID		0x000000008 /* tuple is valid */
278#define	CISTPLF_GLOBAL_CIS	0x000000010 /* tuple from global CIS */
279#define	CISTPLF_MF_CIS		0x000000020 /* tuple from MF CIS chain */
280#define	CISTPLF_FROM_AM		0x000000040 /* tuple read from AM space */
281#define	CISTPLF_FROM_CM		0x000000080 /* tuple read from CM space */
282#define	CISTPLF_IGNORE_TUPLE	0x000000100 /* ignore this tuple */
283#define	CISTPLF_VENDOR_SPECIFIC	0x000000200 /* vnedor-specific tuple */
284#define	CISTPLF_LINK_INVALID	0x001000000 /* tuple link is invalid */
285#define	CISTPLF_PARAMS_INVALID	0x002000000 /* tuple body is invalid */
286#define	CISTPLF_AM_SPACE	0x010000000 /* this tuple is in AM space */
287#define	CISTPLF_CM_SPACE	0x020000000 /* this tuple is in CM space */
288#define	CISTPLF_LM_SPACE	0x040000000 /* this tuple is in local memory */
289#define	CISTPLF_MEM_ERR		0x080000000 /* GET_BYTE macros memory error */
290
291/*
292 * Some convienience macros
293 */
294#define	CISTPLF_SPACE_MASK	(CISTPLF_AM_SPACE | CISTPLF_CM_SPACE |	\
295							CISTPLF_LM_SPACE)
296#define	CISTPLF_FROM_MASK	(CISTPLF_FROM_AM | CISTPLF_FROM_CM)
297
298/*
299 * Values used internally on calls to cis_get_ltuple.
300 *
301 * The GET_XXX_LTUPLEF and FIND_XXX_XXX values are mutually exclusive,
302 *	i.e. cis_get_ltuple can only do one of these operations per call.
303 *
304 * The other flags are bit flags and they share the flags parameter.
305 *
306 *    CIS_GET_LTUPLE_IGNORE - return tuples with CISTPLF_IGNORE_TUPLE
307 *				set in cistpl_t->flags
308 */
309#define	GET_FIRST_LTUPLEF	0x000000001 /* return first tuple in list */
310#define	GET_LAST_LTUPLEF	0x000000002 /* return last tuple in list */
311#define	FIND_LTUPLE_FWDF	0x000000003 /* find tuple, fwd search from tp */
312#define	FIND_LTUPLE_BACKF	0x000000004 /* find tuple, backward from tp */
313#define	FIND_NEXT_LTUPLEF	0x000000005 /* find tuple, fwd from tp+1 */
314#define	FIND_PREV_LTUPLEF	0x000000006 /* find tuple, backward from tp-1 */
315#define	GET_NEXT_LTUPLEF	0x000000007 /* return next tuple in list */
316#define	GET_PREV_LTUPLEF	0x000000008 /* return prev tuple in list */
317#define	CIS_GET_LTUPLE_OPMASK	0x00000ffff /* mask for operation values */
318#define	CIS_GET_LTUPLE_IGNORE	0x000010000 /* return ignored tuples */
319
320/*
321 * macros for getting various data types out of a tuple
322 * Note that due to the modem tuple using a few big-endian values,
323 * we have to support both big and little endian macros
324 *
325 * Common Memory Specific macros - these will also work for tuples in
326 *	local memory
327 */
328#define	GET_CM_BYTE(tp)	(((size_t)(tp)->len >= \
329				((uintptr_t)(tp)->read.byte - \
330					(uintptr_t)(tp)->data)) ? \
331			 *(tp)->read.byte++ : ((tp)->flags |= CISTPLF_MEM_ERR))
332#define	GET_CM_SHORT(tp)	(((size_t)(tp)->len >= \
333					(((uintptr_t)(tp)->read.byte - \
334						(uintptr_t)(tp)->data) + 1)) ? \
335				(*(tp)->read.byte++ | \
336					(*(tp)->read.byte++ << 8)) : \
337					((tp)->flags |= CISTPLF_MEM_ERR))
338#define	GET_CM_BE_SHORT(tp) (((size_t)(tp)->len >= \
339				(((uintptr_t)(tp)->read.byte - \
340					(uintptr_t)(tp)->data) + 1)) ? \
341				((*(tp)->read.byte++ << 8) | \
342					*(tp)->read.byte++) : \
343				((tp)->flags |= CISTPLF_MEM_ERR))
344#define	GET_CM_INT24(tp)	(GET_CM_SHORT(tp) | (GET_CM_BYTE(tp)<<16))
345#define	GET_CM_LONG(tp)	(GET_CM_SHORT(tp) | (GET_CM_SHORT(tp) << 16))
346#define	GET_CM_LEN(tp)	((size_t)(tp)->len - \
347				((uintptr_t)(tp)->read.byte - \
348				(uintptr_t)(tp)->data))
349
350/* Attribute Memory Specific macros */
351#define	GET_AM_BYTE(tp)	(((size_t)(tp)->len >= \
352				(((uintptr_t)(tp)->read.byte - \
353					(uintptr_t)(tp)->data))>>1) ? \
354			 *(cisdata_t *)(tp)->read.sword++ : \
355				((tp)->flags |= CISTPLF_MEM_ERR))
356#define	GET_AM_SHORT(tp) (GET_AM_BYTE(tp) | (GET_AM_BYTE(tp) << 8))
357#define	GET_AM_BE_SHORT(tp)  ((GET_AM_BYTE(tp) << 8) | GET_AM_BYTE(tp))
358#define	GET_AM_INT24(tp) (GET_AM_SHORT(tp) | (GET_AM_BYTE(tp)<<16))
359#define	GET_AM_LONG(tp)  (GET_AM_SHORT(tp) | (GET_AM_SHORT(tp) << 16))
360#define	GET_AM_LEN(tp)	((size_t)(tp)->len - (((uintptr_t)(tp)->read.byte - \
361				(uintptr_t)(tp)->data) >> 1))
362
363/* generic macros */
364#define	RESET_TP(tp)	(tp)->read.byte = (tp)->data
365#define	LOOK_BYTE(tp)	*(tp)->read.byte
366#define	GET_BYTE_ADDR(tp) (tp)->read.byte
367
368#define	GET_BYTE(tp)	(((tp)->flags & CISTPLF_AM_SPACE) ? \
369				GET_AM_BYTE(tp) : GET_CM_BYTE(tp))
370#define	GET_SHORT(tp) 	(((tp)->flags & CISTPLF_AM_SPACE) ? \
371				GET_AM_SHORT(tp) : GET_CM_SHORT(tp))
372#define	GET_BE_SHORT(tp) (((tp)->flags & CISTPLF_AM_SPACE) ? \
373				GET_AM_BE_SHORT(tp) : GET_CM_BE_SHORT(tp))
374#define	GET_INT24(tp)	(((tp)->flags & CISTPLF_AM_SPACE) ? \
375				GET_AM_INT24(tp) : GET_CM_INT24(tp))
376#define	GET_LONG(tp)	(((tp)->flags & CISTPLF_AM_SPACE) ? \
377				GET_AM_LONG(tp) : GET_CM_LONG(tp))
378#define	GET_LEN(tp)	(((tp)->flags & CISTPLF_AM_SPACE) ? \
379				GET_AM_LEN(tp) : GET_CM_LEN(tp))
380
381/*
382 * cistpl_ignore_list_t - this structure describes tuples in the global
383 *				CIS list that we want to ignore if they
384 *				also show up in a function-specific CIS.
385 */
386typedef struct cistpl_ignore_list_t {
387	cisdata_t	type;
388} cistpl_ignore_list_t;
389
390#ifdef	__cplusplus
391}
392#endif
393
394#endif	/* _CIS_H */
395