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