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
30 extern "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 
43 typedef 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 
55 typedef 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  */
68 typedef 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  */
76 typedef 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  */
88 typedef 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  */
101 struct 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  */
126 typedef 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  */
140 typedef 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 */
148 typedef 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  */
306 int 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 
332 int 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