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 2019 Joyent, Inc. 13.\" Copyright 2020 Oxide Computer Company 14.\" 15.Dd May 19, 2020 16.Dt DDI_UFM_SLOT 9F 17.Os 18.Sh NAME 19.Nm ddi_ufm_slot , 20.Nm ddi_ufm_slot_set_version , 21.Nm ddi_ufm_slot_set_attrs , 22.Nm ddi_ufm_slot_set_misc , 23.Nm ddi_ufm_slot_set_imgsize 24.Nd UFM slot property routines 25.Sh SYNOPSIS 26#include <sys/ddi_ufm.h> 27.sp 28.Ft void 29.Fo ddi_ufm_slot_set_version 30.Fa "ddi_ufm_slot_t *usp" 31.Fa "const char *version" 32.Fc 33.Ft void 34.Fo ddi_ufm_slot_set_attrs 35.Fa "ddi_ufm_slot_t *usp" 36.Fa "ddi_ufm_attr_t attrs" 37.Fc 38.Ft void 39.Fo ddi_ufm_slot_set_misc 40.Fa "ddi_ufm_slot_t *usp" 41.Fa "nvlist_t *nvl" 42.Fc 43.Ft void 44.Fo ddi_ufm_slot_set_imgsize 45.Fa "ddi_ufm_slot_t *usp" 46.Fa "uint64_t len" 47.Fc 48.Sh INTERFACE LEVEL 49.Sy Evolving - 50This interface is evolving still in illumos. 51API and ABI stability is not guaranteed. 52.Sh PARAMETERS 53.Bl -tag -width Fa 54.It Fa usp 55A pointer to a UFM slot structure that was passed to the driver in its 56.Xr ddi_ufm_op_fill_slot 9E 57entry point. 58.It Fa version 59A device-specific ASCII string that indicates the current version of the 60firmware image in the slot. 61.It Fa attrs 62The bitwise-inclusive-OR of one of several attributes of a firmware 63slot. 64See the discussion of the 65.Fn ddi_ufm_op_fill_slot 66function in 67.Xr ddi_ufm 9E . 68.It Fa nvl 69An nvlist_t with ancillary, device-specific data. 70.It Fa len 71The length in bytes of a firmware image in a slot. 72.El 73.Sh DESCRIPTION 74The 75.Fn ddi_ufm_slot_set_version , 76.Fn ddi_ufm_slot_set_attrs , 77.Fn ddi_ufm_slot_set_misc , 78and 79.Fn ddi_ufm_slot_set_imgsize 80functions are used by device drivers to set information about a firmware 81slot on the slot structure 82.Fa usp 83as a part of implementing their 84.Xr ddi_ufm_op_fill_slot 9E 85entry point. 86For more information on slots and the use of these functions, see the 87description of the 88.Fn ddi_ufm_op_fill_slot 89function in 90.Xr ddi_ufm 9E . 91.Pp 92The 93.Fn ddi_ufm_slot_set_version 94function sets the version property of a firmware slot. 95The version should be a human-readable ASCII string that describes the current 96firmware revision in a way that makes sense to an administrator and someone 97who is referencing the documentation of a vendor. 98.Pp 99The 100.Fn ddi_ufm_slot_set_attrs 101function describes attributes of a UFM slot as defined by the 102ddi_ufm_attr_t enum. 103.Pp 104The 105.Fn ddi_ufm_slot_set_misc 106function is used by the driver to set ancillary key-value data that may 107be useful to a consumer. 108For example, a driver may use this method to encode specific information that 109the firmware provides about how or when it was produced or installed on the 110device. 111The driver should create an nvlist for this purpose with 112.Xr nvlist_alloc 9F . 113Once the driver passes the nvlist to the 114.Fn ddi_ufm_slot_set_misc 115function, then the driver must not manipulate or free the nvlist at all. 116It is the property of the UFM subsystem. 117.Pp 118the 119.Fn ddi_ufm_slot_set_imgsize 120function is used by the driver to indicate the size of a firmware image 121in a slot. 122Consumers use this to determine the amount of data that they should read 123for a firmware image itself. 124.Sh CONTEXT 125These functions should only be called in the context of the 126.Xr ddi_ufm_op_fill_slot 9E 127entry point. 128.Sh SEE ALSO 129