Merge commit '9276b3991ba20d5a5660887ba81b0bc7bed25a0c'
[unleashed.git] / share / man / man9f / mac_prop_info.9f
blob0582665ce3ea801a9db5c3b3a9d09e0ff625d0e9
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source.  A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2016 Joyent, Inc.
13 .\"
14 .Dd May 31, 2016
15 .Dt MAC_PROP_INFO 9F
16 .Os
17 .Sh NAME
18 .Nm mac_prop_info ,
19 .Nm mac_prop_info_set_default_link_flowctrl ,
20 .Nm mac_prop_info_set_default_str ,
21 .Nm mac_prop_info_set_default_uint8 ,
22 .Nm mac_prop_info_set_default_uint32 ,
23 .Nm mac_prop_info_set_default_uint64 ,
24 .Nm mac_prop_info_set_perm ,
25 .Nm mac_prop_info_set_range_uint32
26 .Nd mac property information functions
27 .Sh SYNOPSIS
28 .In sys/mac_provider.h
29 .Ft void
30 .Fo mac_prop_info_set_default_link_flowctrl
31 .Fa "mac_prop_info_handle_t hdl"
32 .Fa "link_flowctrl_t fctl"
33 .Fc
34 .Ft void
35 .Fo mac_prop_info_set_default_str
36 .Fa "mac_prop_info_handle_t hdl"
37 .Fa "const char *str"
38 .Fc
39 .Ft void
40 .Fo mac_prop_info_set_default_uint8
41 .Fa "mac_prop_info_handle_t hdl"
42 .Fa "uint8_t u8"
43 .Fc
44 .Ft void
45 .Fo mac_prop_info_set_default_uint16
46 .Fa "mac_prop_info_handle_t hdl"
47 .Fa "uint16_t u16"
48 .Fc
49 .Ft void
50 .Fo mac_prop_info_set_default_uint32
51 .Fa "mac_prop_info_handle_t hdl"
52 .Fa "uint32_t u32"
53 .Fc
54 .Ft void
55 .Fo mac_prop_info_set_perm
56 .Fa "mac_prop_info_handle_t hdl"
57 .Fa "uint8_t perm"
58 .Fc
59 .Ft void
60 .Fo mac_prop_info_set_range_uint32
61 .Fa "mac_prop_info_handle_t hdl"
62 .Fa "uint32_t low"
63 .Fa "uint32_t high"
64 .Fc
65 .Sh INTERFACE LEVEL
66 illumos DDI specific
67 .Sh PARAMETERS
68 .Bl -tag -width Ds
69 .It Ft hdl
70 A pointer to the MAC property information handle.
71 .It Ft fctl
72 A valid link flow control entry.
73 Valid values are documented in the
74 .Sy MAC_PROP_FLOWCTRL
75 property description in the
76 .Sx PROPERTIES
77 section of
78 .Xr mac 9E .
79 .It Ft str
80 A null-terminated ASCII character string that describes that contains a
81 value of a property.
82 .It Ft u8
83 An 8-bit unsigned value.
84 .It Ft u16
85 An 16-bit unsigned value.
86 .It Ft u32
87 An 32-bit unsigned value.
88 .It Ft perm
89 An 8-bit unsigned value which is the bitwise inclusive OR of the
90 following values:
91 .Bl -tag -width Ds
92 .It Sy MAC_PROP_PERM_READ
93 This flag indicates that a property is
94 .Sy readable .
95 .It Sy MAC_PROP_PERM_WRITE
96 This flag indicates that a property is
97 .Sy writable .
98 .It Sy MAC_PROP_PERM_RW
99 This flag indicates that a property is both
100 .Sy readable
102 .Sy writable .
103 This is equivalent to specifying both
104 .Sy MAC_PROP_PERM_READ
106 .Sy MAC_PROP_PERM_WRITE .
108 .It Ft low
109 A 32-bit unsigned value that represents the lowest possible value of an
110 integer property, generally inclusive.
111 .It Ft high
112 A 32-bit unsigned value that represents the highest possible value an
113 integer property, generally inclusive.
115 .Sh DESCRIPTION
117 .Sy mac_prop_info
118 family of functions are used to fill in metadata about a given property
119 as part of a driver's
120 .Xr mc_propinfo 9E
121 entry point.
122 These functions can be used to fill in information about the default value that
123 the device assigns to a property and the permissions that a privileged user has
124 to update the property.
127 .Fn mac_prop_info_set_perm
128 function is used to set the permissions of a property.
129 These permissions indicate whether or not the property can be read or modified
130 from the device driver's perspective.
131 The permissions for a given property should generally not change for a given
132 device and they do not need to take into account user privileges.
133 For the most case, properties will only take one of two values:
134 .Sy MAC_PROP_PERM_READ
136 .Sy MAC_PROP_PERM_RW .
137 Usually it does not make sense for a property to just have
138 .Sy MAC_PROP_PERM_WRITE .
140 Subsequent calls to the
141 .Fn mac_prop_info_set_perm
142 function will override the values stored in previous calls.
145 .Fn mac_prop_info_set_range_uint32
146 function is used to indicate a range of possible integer values that a
147 device may take.
148 This range is generally inclusive, meaning the property may be set to any value
149 in the range of
150 .Fa low
152 .Fa high .
153 Each time the
154 .Fn mac_prop_info_set_range_uint32
155 function is called, a new property range is added, allowing for multiple
156 disjoint ranges to be specified for a given property.
158 The remaining functions,
159 .Fn mac_prop_info_set_default_link_flowctrl ,
160 .Fn mac_prop_info_set_default_str ,
161 .Fn mac_prop_info_set_uint8 ,
162 .Fn mac_prop_info_set_uint16 ,
163 .Fn mac_prop_info_set_uint32 ,
165 .Fn mac_prop_info_set_range_uint32
166 update the default value of a given property.
167 The default value is the initial value that the property takes after the device
168 driver has called
169 .Xr mac_register 9F .
170 If these functions are called multiple times, then the default value
171 will be replaced with each call.
173 The different functions each support a different type of default value
174 and some are used for specific properties.
176 .Fn mac_prop_info_set_default_link_flowctrl
177 function works with properties that describe flow control properties.
178 The various values of a
179 .Ft link_flowctrl_t
180 are documented in
181 .Xr mac 9E .
184 .Fn mac_prop_info_set_default_str
185 function sets the default value for properties that use strings.
186 The device driver should ensure that it uses alphanumeric ASCII characters
187 only in the string to guarantee portability.
190 .Fn mac_prop_info_set_default_uint8 ,
191 .Fn mac_prop_info_set_default_uint16 ,
193 .Fn mac_prop_info_set_default_uint32
194 functions set the default value for values whose properties are 8-, 16-,
195 and 32-bit unsigned values respectively.
196 .Sh CONTEXT
197 These functions are generally called on a handle passed into the
198 .Xr mc_propinfo 9E
199 entry point, though they function in both
200 .Sy user
202 .Sy kernel
203 context.
204 .Sh RETURN VALUES
205 All of the functions documented here do not return a value.
206 It is not the driver's responsibility to ensure that there is sufficient space
207 for permissions, ranges, or default values in the
208 .Ft mac_prop_info_handle_t
209 structures: the surrounding driver framework will transparently take
210 care of that and ensure that errors are correctly propagated.
211 .Sh SEE ALSO
212 .Xr mac 9E ,
213 .Xr mc_getprop 9E ,
214 .Xr mc_propinfo 9E ,
215 .Xr mc_setprop 9E