1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source. A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright (c) 2019, Joyent, Inc.
.\"
.Dd Apr 30, 2019
.Dt DDI_UFM 9F
.Os
.Sh NAME
.Nm ddi_ufm ,
.Nm ddi_ufm_init ,
.Nm ddi_ufm_update ,
.Nm ddi_ufm_fini
.Nd DDI upgradable firmware module interfaces
.Sh SYNOPSIS
.In sys/ddi_ufm.h
.Ft int
.Fo ddi_ufm_init
.Fa "dev_info_t *dip"
.Fa "int version"
.Fa "ddi_ufm_ops_t *ops"
.Fa "ddi_ufm_handle_t **ufmpp"
.Fa "void *drv_arg"
.Fc
.Ft void
.Fo ddi_ufm_update
.Fa "ddi_ufm_handle_t *ufmp"
.Fc
.Ft void
.Fo ddi_ufm_fini
.Fa "ddi_ufm_handle_t *ufmp"
.Fc
.Sh INTERFACE LEVEL
.Sy Evolving -
This interface is evolving still in illumos.
API and ABI stability is not guaranteed.
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa dip
Pointer to the devices
.Vt dev_info
structure for the specific instance.
.It Fa version
A value which indicates the current revision of the interface that the
device supports.
Should generally be set to
.Dv DDI_UFM_CURRENT_VERSION .
.It Fa ops
A pointer to a UFM operations structure.
See
.Xr ddi_ufm 9E
for more information.
.It Fa ufmp
A pinter to the opaque handle returned from
.Fn ddi_ufm_init .
.It Fa ufmpp
A pointer to store the opaque handle from
.Fn ddi_ufm_init .
.It Fa drv_arg
A driver specific argument that will be passed to various operations.
.El
.Sh DESCRIPTION
These functions provide support for initializing and performing various
upgradeable firmware module (UFM) operations.
For more information, please see
.Xr ddi_ufm 9E .
.Pp
The
.Fn ddi_ufm_init
function is used to initialize support for the UFM subsystem for a given
device.
The
.Fa dip
argument should be the
.Vt dev_info
structure of the specific device.
The
.Fa version
argument represents the current revision of the UFM interface that the
driver supports.
Drivers inside of illumos should always use
.Dv DDI_UFM_CURRENT_VERSION .
Device drivers which need to bind to a specific revision, should instead
pass the latest version:
.Dv DDI_UFM_VERSION_ONE .
The operations structure,
.Fa ops ,
should be filled according to the rules in
.Xr ddi_ufm 9E .
These will be the entry points that device drivers call.
The value of
.Fa drv_arg
will be passed to all of the driver's entry points.
When the function returns,
.Fa ufmpp
will be filled in with a handle that the driver should reference when
needing to perform subsequent UFM operations.
No UFM entry points will be called until after the driver calls the
.Fn ddi_ufm_update
function.
.Pp
When the device driver is detaching or needs to unregister from the UFM
subsystem, then the device driver should call the
.Fn ddi_ufm_fini
function with the handle that they obtained during the call to
initialize.
Note, this function will block and ensure that any outstanding UFM operations
are terminated.
The driver must not hold any locks that are required in its callbacks across
the call to
.Fn ddi_ufm_fini .
.Pp
The
.Fn ddi_ufm_update
function should be used in two different circumstances.
It should be used at the end of a driver's
.Xr attach 9E
endpoint to indicate that it is ready to receive UFM requests.
It should also be called whenever the driver believes that the UFM might have
changed or the device's capabilities.
This may happen after a device reset or firmware change.
Unlike the other functions, this can be called from any context with any locks
held, excepting high-level interrupt context which normal device drivers
will not have interrupts for.
.Sh RETURN VALUES
Upon successful completion, the
.Fn ddi_ufm_init
function returns zero, indicating that it has successfully registered
with the UFM subsystem.
.Fa ufmpp
will be filled in with a pointer to the UFM handle.
.Pp
The
.Fn ddi_ufm_init
and
.Fn ddi_ufm_fini
functions are generally called from a device's
.Xr attach 9E
and
.Xr fini 9E
routines, though they may be called from
.Sy user
or
.Sy kernel
context.
.Pp
The
.Fn ddi_ufm_update
function may be called from any context except a high-level interrupt
handler above lock level.
.Sh SEE ALSO
.Xr attach 9E ,
.Xr ddi_ufm 9E ,
.Xr fini 9E
|
