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