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 (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21/*
22 * Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
23 * Use is subject to license terms.
24 */
25
26#ifndef	_SYS_DDIPROPDEFS_H
27#define	_SYS_DDIPROPDEFS_H
28
29#ifdef	__cplusplus
30extern "C" {
31#endif
32
33/*
34 * ddiprops.h:	All definitions related to DDI properties.
35 *		Structure definitions are private to the DDI
36 *		implementation.  See also, ddipropfuncs.h
37 */
38
39/*
40 * ddi_prop_op_t:	Enum for prop_op functions
41 */
42
43typedef enum {
44	PROP_LEN = 0,		/* Get prop len only */
45	PROP_LEN_AND_VAL_BUF,	/* Get len+val into callers buffer */
46	PROP_LEN_AND_VAL_ALLOC,	/* Get len+val into alloc-ed buffer */
47	PROP_EXISTS		/* Does the property exist? */
48} ddi_prop_op_t;
49
50/*
51 * ddi_prop_t:	The basic item used to store software defined propeties.
52 *		Note that properties are always stored by reference.
53 */
54
55typedef struct ddi_prop {
56	struct ddi_prop	*prop_next;
57	dev_t		prop_dev;	/* specific match/wildcard */
58	char		*prop_name;	/* Property name */
59	int		prop_flags;	/* See flags below */
60	int		prop_len;	/* Prop length (0 == Bool. prop) */
61	caddr_t		prop_val;	/* ptr to property value */
62} ddi_prop_t;
63
64/*
65 * A referenced property list, used for sharing properties among
66 * multiple driver instances
67 */
68typedef struct ddi_prop_list {
69	ddi_prop_t	*prop_list;
70	int		prop_ref;
71} ddi_prop_list_t;
72
73/*
74 * Handle passed around to encode/decode a property value.
75 */
76typedef struct ddi_prop_handle {
77	void			*ph_data;	/* Encoded data */
78	void			*ph_cur_pos;	/* encode/decode position */
79	void			*ph_save_pos;	/* Save/restore position */
80	uint_t			ph_size;	/* Size of encoded data */
81	uint_t			ph_flags;	/* See below */
82	struct prop_handle_ops	*ph_ops;	/* Encode/decode routines */
83} prop_handle_t;
84
85/*
86 * Property handle encode/decode ops
87 */
88typedef struct prop_handle_ops {
89	int (*op_prop_int)(prop_handle_t *ph, uint_t cmd, int *data);
90	int (*op_prop_str)(prop_handle_t *ph, uint_t cmd, char *data);
91	int (*op_prop_bytes)(prop_handle_t *ph, uint_t cmd,
92				uchar_t *data, uint_t size);
93	int (*op_prop_int64)(prop_handle_t *ph, uint_t cmd, int64_t *data);
94} prop_handle_ops_t;
95
96/*
97 * Data passed back to driver.  The driver gets a pointer to driver_data.
98 * When we get it back we do negative indexing to find the size and free
99 * routine to call
100 */
101struct prop_driver_data {
102	size_t	pdd_size;
103	void	(*pdd_prop_free)(struct prop_driver_data *);
104};
105
106
107/*
108 * Macros to call the integer/string/byte OBP 1275 operators
109 */
110#define	DDI_PROP_INT(ph, cmd, data)		\
111		(*(ph)->ph_ops->op_prop_int)((ph), (cmd), (data))
112#define	DDI_PROP_STR(ph, cmd, data)		\
113		(*(ph)->ph_ops->op_prop_str)((ph), (cmd), (data))
114#define	DDI_PROP_BYTES(ph, cmd, data, size)	\
115		(*(ph)->ph_ops->op_prop_bytes)((ph), (cmd), (data), (size))
116
117/*
118 * Macro to call the 64 bit integer operator
119 */
120#define	DDI_PROP_INT64(ph, cmd, data)		\
121		(*(ph)->ph_ops->op_prop_int64)((ph), (cmd), (data))
122
123/*
124 * Property handle commands
125 */
126typedef enum {
127	DDI_PROP_CMD_GET_ESIZE,		/* Get encoded size of data  */
128	DDI_PROP_CMD_GET_DSIZE,		/* Get decoded size of data */
129	DDI_PROP_CMD_DECODE,		/* Decode the current data */
130	DDI_PROP_CMD_ENCODE,		/* Encode the current data */
131	DDI_PROP_CMD_SKIP		/* Skip the current data */
132} ddi_prop_cmd_t;
133
134/*
135 * Return values from property handle encode/decode ops
136 * Positive numbers are used to return the encoded or
137 * decode size of the object, so an ok return must be positive,
138 * and all error returns negative.
139 */
140typedef enum {
141	DDI_PROP_RESULT_ERROR = -2,	/* error in encoding/decoding data */
142	DDI_PROP_RESULT_EOF,		/* end of data reached */
143	DDI_PROP_RESULT_OK		/* if >= to DDI_PROP_RESULT_OK, */
144					/* operation was successful */
145} ddi_prop_result_t;
146
147/* 1275 property cell */
148typedef uint32_t prop_1275_cell_t;
149
150/* Length of a 1275 property cell */
151#define	PROP_1275_CELL_SIZE	sizeof (prop_1275_cell_t)
152#define	CELLS_1275_TO_BYTES(n)	((n) * PROP_1275_CELL_SIZE)
153#define	BYTES_TO_1275_CELLS(n)	((n) / PROP_1275_CELL_SIZE)
154
155/*
156 * Property handle flags
157 */
158#define	PH_FROM_PROM	0x01	/* Property came from the prom */
159
160/*
161 * Return values from property functions:
162 */
163
164#define	DDI_PROP_SUCCESS	0
165#define	DDI_PROP_NOT_FOUND	1	/* Prop not defined */
166#define	DDI_PROP_UNDEFINED	2	/* Overriden to undefine a prop */
167#define	DDI_PROP_NO_MEMORY	3	/* Unable to allocate/no sleep */
168#define	DDI_PROP_INVAL_ARG	4	/* Invalid calling argument */
169#define	DDI_PROP_BUF_TOO_SMALL	5	/* Callers buf too small */
170#define	DDI_PROP_CANNOT_DECODE	6	/* Could not decode prop */
171#define	DDI_PROP_CANNOT_ENCODE	7	/* Could not encode prop */
172#define	DDI_PROP_END_OF_DATA	8	/* Prop found in an encoded format */
173
174/*
175 * used internally in the framework only
176 */
177#define	DDI_PROP_FOUND_1275	255	/* Prop found in OPB 1275 format */
178
179/*
180 * Size of a 1275 int in bytes
181 */
182#define	PROP_1275_INT_SIZE	4
183
184/*
185 * Property flags:
186 */
187
188#define	DDI_PROP_DONTPASS	0x0001	/* Don't pass request to parent */
189#define	DDI_PROP_CANSLEEP	0x0002	/* Memory allocation may sleep */
190
191/*
192 * Used internally by the DDI property rountines and masked in DDI(9F)
193 * interfaces...
194 */
195
196#define	DDI_PROP_SYSTEM_DEF	0x0004	/* System defined property */
197
198/*
199 * Used in framework only, to inhibit certain pre-defined s/w property
200 * names from coming from the prom.
201 */
202#define	DDI_PROP_NOTPROM	0x0008	/* Don't look at prom properties */
203
204/*
205 * Used interally by the DDI property routines to implement the old
206 * depricated functions with the new functions
207 */
208#define	DDI_PROP_DONTSLEEP	0x0010	/* Memory allocation may not sleep */
209#define	DDI_PROP_STACK_CREATE	0x0020	/* Do a LIFO stack of properties */
210#define	DDI_PROP_UNDEF_IT	0x0040	/* Undefine a property */
211#define	DDI_PROP_HW_DEF		0x0080	/* Hardware defined property */
212
213/*
214 * Type of data property contains
215 */
216#define	DDI_PROP_TYPE_INT		0x0100
217#define	DDI_PROP_TYPE_STRING		0x0200
218#define	DDI_PROP_TYPE_BYTE		0x0400
219#define	DDI_PROP_TYPE_COMPOSITE		0x0800
220#define	DDI_PROP_TYPE_INT64		0x1000
221
222#define	DDI_PROP_TYPE_ANY		(DDI_PROP_TYPE_INT	|	\
223					DDI_PROP_TYPE_STRING	|	\
224					DDI_PROP_TYPE_BYTE	|	\
225					DDI_PROP_TYPE_COMPOSITE)
226
227#define	DDI_PROP_TYPE_MASK		(DDI_PROP_TYPE_INT	|	\
228					DDI_PROP_TYPE_STRING	|	\
229					DDI_PROP_TYPE_BYTE	|	\
230					DDI_PROP_TYPE_COMPOSITE	|	\
231					DDI_PROP_TYPE_INT64)
232
233/*
234 * This flag indicates that the LDI lookup routine
235 * should match the request regardless of the actual
236 * dev_t with which the property was created.  In other
237 * words, any dev_t value found on the property list
238 * is an acceptable part of the match criteria.
239 */
240#define	LDI_DEV_T_ANY		0x2000
241
242/*
243 * Private flag that should ONLY be used by the LDI Framework
244 * to indicate a property search of an unbound dlpi2 dip.
245 * The LDI property lookup interfaces will set this flag if
246 * it is determined that the dip representing a dlpi-style2
247 * driver is currently unbound (dip == NULL) at the time of
248 * the property lookup request.
249 */
250#define	DDI_UNBND_DLPI2		0x4000
251
252/*
253 * Private flag that indicates that a typed interface that predates typed
254 * properties is being used - the framework should set additional typed flags
255 * (DDI_PROP_TYPE_INT64) when expanding search to DDI_PROP_TYPE_ANY.
256 */
257#define	DDI_PROP_CONSUMER_TYPED	0x8000
258
259/*
260 * Private flag that indicates that the ldi is doing a driver prop_op
261 * call to check for driver dynamic properties.  This request should
262 * not be passed onto the common property lookup framework since all
263 * the ldi property interface are typed and driver prop_op lookups are
264 * not.
265 */
266#define	DDI_PROP_DYNAMIC	0x10000
267
268/*
269 * Private flag used to lookup global properties specified in rootnex.conf file
270 */
271#define	DDI_PROP_ROOTNEX_GLOBAL	0x20000
272
273
274/*
275 * DDI_DEV_T_NONE:	When creating, property is not associated with
276 *			particular dev_t.
277 * DDI_DEV_T_ANY:	Wildcard dev_t when searching properties.
278 */
279#define	DDI_DEV_T_NONE		((dev_t)-1)
280#define	DDI_DEV_T_ANY		((dev_t)-2)
281/*
282 * DDI_MAJOR_T_UNKNOWN	Used when a driver does not know its dev_t during
283 *			a property create.
284 * DDI_MAJOR_T_NONE	Used when a driver does not have a major number.
285 */
286#define	DDI_MAJOR_T_UNKNOWN	((major_t)0)
287#define	DDI_MAJOR_T_NONE	((major_t)-1)
288
289/*
290 * Some DDI property names...
291 */
292
293/*
294 * One of the following boolean properties shall be defined in the
295 * root node, and defines the addressing mode understood by the root
296 * node of the implementation....
297 */
298
299#define	DDI_RELATIVE_ADDRESSING		"relative-addressing"
300#define	DDI_GENERIC_ADDRESSING		"generic-addressing"
301
302/*
303 * Common property encoded data search routine.  Returns the encoded data
304 * in valuep.  Match is done on dip, dev, data type (in flags), and name.
305 */
306int ddi_prop_search_common(dev_t dev, dev_info_t *dip, ddi_prop_op_t prop_op,
307    uint_t flags, char *name, void *valuep, uint_t *lengthp);
308
309
310/*
311 * Property debugging support in kernel...
312 */
313
314/*
315 * Property debugging support...  Be careful about enabling this when
316 * you are tipping in to the console.  Undefine PROP_DEBUG to remove
317 * all support from the code. (c.f. autoconf.c and zs_common.c)
318 *
319 * It does no good to enable this if the rest of the kernel was built with
320 * this disabled (specifically, the core kernel module.)
321 *
322 * #define	DDI_PROP_DEBUG	1
323 */
324
325#ifdef	DDI_PROP_DEBUG
326#define	ddi_prop_printf	if (ddi_prop_debug_flag != 0) printf
327
328/*
329 * Returns prev value of debugging flag, non-zero enables debug printf's
330 */
331
332int ddi_prop_debug(int enable);
333
334#endif	/* DDI_PROP_DEBUG */
335
336#ifdef	__cplusplus
337}
338#endif
339
340#endif /* _SYS_DDIPROPDEFS_H */
341