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
66illumos DDI specific
67.Sh PARAMETERS
68.Bl -tag -width Ds
69.It Ft hdl
70A pointer to the MAC property information handle.
71.It Ft fctl
72A valid link flow control entry. Valid values are documented in the
73.Sy MAC_PROP_FLOWCTRL
74property description in the
75.Sx PROPERTIES
76section of
77.Xr mac 9E .
78.It Ft str
79A null-terminated ASCII character string that describes that contains a
80value of a property.
81.It Ft u8
82An 8-bit unsigned value.
83.It Ft u16
84An 16-bit unsigned value.
85.It Ft u32
86An 32-bit unsigned value.
87.It Ft perm
88An 8-bit unsigned value which is the bitwise inclusive OR of the
89following values:
90.Bl -tag -width Ds
91.It Sy MAC_PROP_PERM_READ
92This flag indicates that a property is
93.Sy readable .
94.It Sy MAC_PROP_PERM_WRITE
95This flag indicates that a property is
96.Sy writable .
97.It Sy MAC_PROP_PERM_RW
98This flag indicates that a property is both
99.Sy readable
100and
101.Sy writeable .
102This is equivalent to specifying both
103.Sy MAC_PROP_PERM_READ
104and
105.Sy MAC_PROP_PERM_WRITE .
106.El
107.It Ft low
108A 32-bit unsigned value that represents the lowest possible value of an
109integer property, generally inclusive.
110.It Ft high
111A 32-bit unsigned value that represents the highest possible value an
112integer property, generally inclusive.
113.El
114.Sh DESCRIPTION
115The
116.Sy mac_prop_info
117family of functions are used to fill in metadata about a given property
118as part of a driver's
119.Xr mc_propinfo 9E
120entry point. These functions can be used to fill in information about
121the default value that the device assigns to a property and the
122permissions that a privileged user has to update the property.
123.Pp
124The
125.Fn mac_prop_info_set_perm
126function is used to set the permissions of a property. These permissions
127indicate whether or not the property can be read or modified from the
128device driver's perspective. The permissions for a given property should
129generally not change for a given device and they do not need to take
130into account user privileges. For the most case, properties will only
131take one of two values:
132.Sy MAC_PROP_PERM_READ
133or
134.Sy MAC_PROP_PERM_RW .
135Usually it does not make sense for a property to just have
136.Sy MAC_PROP_PERM_WRITE .
137.Pp
138Subsequent calls to the
139.Fn mac_prop_info_set_perm
140function will override the values stored in previous calls.
141.Pp
142The
143.Fn mac_prop_info_set_range_uint32
144function is used to indicate a range of possible integer values that a
145device may take. This range is generally inclusive, meaning the property
146may be set to any value in the range of
147.Fa low
148to
149.Fa high .
150Each time the
151.Fn mac_prop_info_set_range_uint32
152function is called, a new property range is added, allowing for multiple
153disjoint ranges to be specified for a given property.
154.Pp
155The remaining functions,
156.Fn mac_prop_info_set_default_link_flowctrl ,
157.Fn mac_prop_info_set_default_str ,
158.Fn mac_prop_info_set_uint8 ,
159.Fn mac_prop_info_set_uint16 ,
160.Fn mac_prop_info_set_uint32 ,
161and
162.Fn mac_prop_info_set_range_uint32
163update the default value of a given property. The default value is the
164initial value that the property takes after the device driver has called
165.Xr mac_register 9F .
166If these functions are called multiple times, then the default value
167will be replaced with each call.
168.Pp
169The different functions each support a different type of default value
170and some are used for specific properties. The
171.Fn mac_prop_info_set_default_link_flowctrl
172function works with properties that describe flow control properties.
173The various values of a
174.Ft link_flowctrl_t
175are documented in
176.Xr mac 9E .
177.Pp
178The
179.Fn mac_prop_info_set_default_str
180function sets the default value for properties that use strings. The
181device driver should ensure that it uses alphanumeric ASCII characters
182only in the string to guarantee portability.
183.Pp
184The
185.Fn mac_prop_info_set_default_uint8 ,
186.Fn mac_prop_info_set_default_uint16 ,
187and
188.Fn mac_prop_info_set_default_uint32
189functions set the default value for values whose properties are 8-, 16-,
190and 32-bit unsigned values respectively.
191.Sh CONTEXT
192These functions are generally called on a handle passed into the
193.Xr mc_propinfo 9E
194entry point, though they function in both
195.Sy user
196and
197.Sy kernel
198context.
199.Sh RETURN VALUES
200All of the functions documented here do not return a value. It is not
201the driver's responsibility to ensure that there is sufficient space for
202permissions, ranges, or default values in the
203.Ft mac_prop_info_handle_t
204structures: the surrounding driver framework will transparently take
205care of that and ensure that errors are correctly propagated.
206.Sh SEE ALSO
207.Xr mac 9E ,
208.Xr mc_getprop 9E ,
209.Xr mc_propinfo 9E ,
210.Xr mc_setprop 9E
211