1508a0e8cSRob Johnston.\" 2508a0e8cSRob Johnston.\" This file and its contents are supplied under the terms of the 3508a0e8cSRob Johnston.\" Common Development and Distribution License ("CDDL"), version 1.0. 4508a0e8cSRob Johnston.\" You may only use this file in accordance with the terms of version 5508a0e8cSRob Johnston.\" 1.0 of the CDDL. 6508a0e8cSRob Johnston.\" 7508a0e8cSRob Johnston.\" A full copy of the text of the CDDL should have accompanied this 8508a0e8cSRob Johnston.\" source. A copy of the CDDL is also available via the Internet at 9508a0e8cSRob Johnston.\" http://www.illumos.org/license/CDDL. 10508a0e8cSRob Johnston.\" 11508a0e8cSRob Johnston.\" 12508a0e8cSRob Johnston.\" Copyright (c) 2019, Joyent, Inc. 13508a0e8cSRob Johnston.\" 14508a0e8cSRob Johnston.Dd Apr 30, 2019 15508a0e8cSRob Johnston.Dt DDI_UFM 9F 16508a0e8cSRob Johnston.Os 17508a0e8cSRob Johnston.Sh NAME 18508a0e8cSRob Johnston.Nm ddi_ufm , 19508a0e8cSRob Johnston.Nm ddi_ufm_init , 20508a0e8cSRob Johnston.Nm ddi_ufm_update , 21508a0e8cSRob Johnston.Nm ddi_ufm_fini 22508a0e8cSRob Johnston.Nd DDI upgradable firmware module interfaces 23508a0e8cSRob Johnston.Sh SYNOPSIS 24508a0e8cSRob Johnston.In sys/ddi_ufm.h 25508a0e8cSRob Johnston.Ft int 26508a0e8cSRob Johnston.Fo ddi_ufm_init 27508a0e8cSRob Johnston.Fa "dev_info_t *dip" 28508a0e8cSRob Johnston.Fa "int version" 29508a0e8cSRob Johnston.Fa "ddi_ufm_ops_t *ops" 30508a0e8cSRob Johnston.Fa "ddi_ufm_handle_t **ufmpp" 31508a0e8cSRob Johnston.Fa "void *drv_arg" 32508a0e8cSRob Johnston.Fc 33508a0e8cSRob Johnston.Ft void 34508a0e8cSRob Johnston.Fo ddi_ufm_update 35508a0e8cSRob Johnston.Fa "ddi_ufm_handle_t *ufmp" 36508a0e8cSRob Johnston.Fc 37508a0e8cSRob Johnston.Ft void 38508a0e8cSRob Johnston.Fo ddi_ufm_fini 39508a0e8cSRob Johnston.Fa "ddi_ufm_handle_t *ufmp" 40508a0e8cSRob Johnston.Fc 41508a0e8cSRob Johnston.Sh INTERFACE LEVEL 42508a0e8cSRob Johnston.Sy Evolving - 43508a0e8cSRob JohnstonThis interface is evolving still in illumos. 44508a0e8cSRob JohnstonAPI and ABI stability is not guaranteed. 45508a0e8cSRob Johnston.Sh PARAMETERS 46508a0e8cSRob Johnston.Bl -tag -width Fa 47508a0e8cSRob Johnston.It Fa dip 48508a0e8cSRob JohnstonPointer to the devices 49508a0e8cSRob Johnston.Vt dev_info 50508a0e8cSRob Johnstonstructure for the specific instance. 51508a0e8cSRob Johnston.It Fa version 52508a0e8cSRob JohnstonA value which indicates the current revision of the interface that the 53508a0e8cSRob Johnstondevice supports. 54508a0e8cSRob JohnstonShould generally be set to 55508a0e8cSRob Johnston.Dv DDI_UFM_CURRENT_VERSION . 56508a0e8cSRob Johnston.It Fa ops 57508a0e8cSRob JohnstonA pointer to a UFM operations structure. 58508a0e8cSRob JohnstonSee 59508a0e8cSRob Johnston.Xr ddi_ufm 9E 60508a0e8cSRob Johnstonfor more information. 61508a0e8cSRob Johnston.It Fa ufmp 62508a0e8cSRob JohnstonA pinter to the opaque handle returned from 63508a0e8cSRob Johnston.Fn ddi_ufm_init . 64508a0e8cSRob Johnston.It Fa ufmpp 65508a0e8cSRob JohnstonA pointer to store the opaque handle from 66508a0e8cSRob Johnston.Fn ddi_ufm_init . 67508a0e8cSRob Johnston.It Fa drv_arg 68508a0e8cSRob JohnstonA driver specific argument that will be passed to various operations. 69508a0e8cSRob Johnston.El 70508a0e8cSRob Johnston.Sh DESCRIPTION 71508a0e8cSRob JohnstonThese functions provide support for initializing and performing various 72508a0e8cSRob Johnstonupgradeable firmware module (UFM) operations. 73508a0e8cSRob JohnstonFor more information, please see 74508a0e8cSRob Johnston.Xr ddi_ufm 9E . 75508a0e8cSRob Johnston.Pp 76508a0e8cSRob JohnstonThe 77508a0e8cSRob Johnston.Fn ddi_ufm_init 78508a0e8cSRob Johnstonfunction is used to initialize support for the UFM subsystem for a given 79508a0e8cSRob Johnstondevice. 80508a0e8cSRob JohnstonThe 81508a0e8cSRob Johnston.Fa dip 82508a0e8cSRob Johnstonargument should be the 83508a0e8cSRob Johnston.Vt dev_info 84508a0e8cSRob Johnstonstructure of the specific device. 85508a0e8cSRob JohnstonThe 86508a0e8cSRob Johnston.Fa version 87508a0e8cSRob Johnstonargument represents the current revision of the UFM interface that the 88508a0e8cSRob Johnstondriver supports. 89508a0e8cSRob JohnstonDrivers inside of illumos should always use 90508a0e8cSRob Johnston.Dv DDI_UFM_CURRENT_VERSION . 91508a0e8cSRob JohnstonDevice drivers which need to bind to a specific revision, should instead 92508a0e8cSRob Johnstonpass the latest version: 93508a0e8cSRob Johnston.Dv DDI_UFM_VERSION_ONE . 94508a0e8cSRob JohnstonThe operations structure, 95508a0e8cSRob Johnston.Fa ops , 96508a0e8cSRob Johnstonshould be filled according to the rules in 97508a0e8cSRob Johnston.Xr ddi_ufm 9E . 98508a0e8cSRob JohnstonThese will be the entry points that device drivers call. 99508a0e8cSRob JohnstonThe value of 100508a0e8cSRob Johnston.Fa drv_arg 101508a0e8cSRob Johnstonwill be passed to all of the driver's entry points. 102508a0e8cSRob JohnstonWhen the function returns, 103508a0e8cSRob Johnston.Fa ufmpp 104508a0e8cSRob Johnstonwill be filled in with a handle that the driver should reference when 105508a0e8cSRob Johnstonneeding to perform subsequent UFM operations. 106508a0e8cSRob JohnstonNo UFM entry points will be called until after the driver calls the 107508a0e8cSRob Johnston.Fn ddi_ufm_update 108508a0e8cSRob Johnstonfunction. 109508a0e8cSRob Johnston.Pp 110508a0e8cSRob JohnstonWhen the device driver is detaching or needs to unregister from the UFM 111508a0e8cSRob Johnstonsubsystem, then the device driver should call the 112508a0e8cSRob Johnston.Fn ddi_ufm_fini 113508a0e8cSRob Johnstonfunction with the handle that they obtained during the call to 114508a0e8cSRob Johnstoninitialize. 115508a0e8cSRob JohnstonNote, this function will block and ensure that any outstanding UFM operations 116508a0e8cSRob Johnstonare terminated. 117508a0e8cSRob JohnstonThe driver must not hold any locks that are required in its callbacks across 118508a0e8cSRob Johnstonthe call to 119508a0e8cSRob Johnston.Fn ddi_ufm_fini . 120508a0e8cSRob Johnston.Pp 121508a0e8cSRob JohnstonThe 122508a0e8cSRob Johnston.Fn ddi_ufm_update 123508a0e8cSRob Johnstonfunction should be used in two different circumstances. 124508a0e8cSRob JohnstonIt should be used at the end of a driver's 125508a0e8cSRob Johnston.Xr attach 9E 126508a0e8cSRob Johnstonendpoint to indicate that it is ready to receive UFM requests. 127508a0e8cSRob JohnstonIt should also be called whenever the driver believes that the UFM might have 128*8d55b806SRobert Mustacchichanged or the device's capabilities. 129508a0e8cSRob JohnstonThis may happen after a device reset or firmware change. 130508a0e8cSRob JohnstonUnlike the other functions, this can be called from any context with any locks 131508a0e8cSRob Johnstonheld, excepting high-level interrupt context which normal device drivers 132508a0e8cSRob Johnstonwill not have interrupts for. 133508a0e8cSRob Johnston.Sh RETURN VALUES 134508a0e8cSRob JohnstonUpon successful completion, the 135508a0e8cSRob Johnston.Fn ddi_ufm_init 136508a0e8cSRob Johnstonfunction returns zero, indicating that it has successfully registered 137508a0e8cSRob Johnstonwith the UFM subsystem. 138508a0e8cSRob Johnston.Fa ufmpp 139508a0e8cSRob Johnstonwill be filled in with a pointer to the UFM handle. 140508a0e8cSRob Johnston.Pp 141508a0e8cSRob JohnstonThe 142508a0e8cSRob Johnston.Fn ddi_ufm_init 143508a0e8cSRob Johnstonand 144508a0e8cSRob Johnston.Fn ddi_ufm_fini 145508a0e8cSRob Johnstonfunctions are generally called from a device's 146508a0e8cSRob Johnston.Xr attach 9E 147508a0e8cSRob Johnstonand 148508a0e8cSRob Johnston.Xr fini 9E 149508a0e8cSRob Johnstonroutines, though they may be called from 150508a0e8cSRob Johnston.Sy user 151508a0e8cSRob Johnstonor 152508a0e8cSRob Johnston.Sy kernel 153508a0e8cSRob Johnstoncontext. 154508a0e8cSRob Johnston.Pp 155508a0e8cSRob JohnstonThe 156508a0e8cSRob Johnston.Fn ddi_ufm_update 157508a0e8cSRob Johnstonfunction may be called from any context except a high-level interrupt 158508a0e8cSRob Johnstonhandler above lock level. 159508a0e8cSRob Johnston.Sh SEE ALSO 160508a0e8cSRob Johnston.Xr attach 9E , 161508a0e8cSRob Johnston.Xr ddi_ufm 9E , 162508a0e8cSRob Johnston.Xr fini 9E 163