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 /* 13 * Copyright 2020 Joyent, Inc. 14 */ 15 16 #ifndef _SYS_DDI_UFM_H 17 #define _SYS_DDI_UFM_H 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 #ifdef _KERNEL 24 #include <sys/cred.h> 25 #include <sys/dditypes.h> 26 #include <sys/nvpair.h> 27 #include <sys/param.h> 28 #else 29 #include <sys/nvpair.h> 30 #include <sys/param.h> 31 #include <sys/types.h> 32 #endif /* _KERNEL */ 33 34 #define DDI_UFM_DEV "/dev/ufm" 35 #define DDI_UFM_CURRENT_VERSION 1 36 #define DDI_UFM_VERSION_ONE 1 37 38 #define UFM_IOC ('u' << 24) | ('f' << 16) | ('m' << 8) 39 #define UFM_IOC_GETCAPS (UFM_IOC | 1) 40 #define UFM_IOC_REPORTSZ (UFM_IOC | 2) 41 #define UFM_IOC_REPORT (UFM_IOC | 3) 42 #define UFM_IOC_MAX UFM_IOC_REPORT 43 44 /* 45 * Bitfield enumerating the DDI UFM capabilities supported by this device 46 * instance. Currently there is only a single capability of being able to 47 * report UFM information. Future UFM versions may add additional capabilities 48 * such as the ability to obtain a raw dump the firmware image or ability to 49 * upgrade the firmware. When support for new capabilties are added to the DDI 50 * UFM subsystem, it should be reflected in this enum and the implementation of 51 * the UFM_IOC_GETCAPS should be extended appropriately. 52 */ 53 typedef enum { 54 DDI_UFM_CAP_REPORT = 1 << 0 55 } ddi_ufm_cap_t; 56 57 /* 58 * This struct defines the input/output data for the UFM_IOC_GETCAPS ioctl. 59 * Callers should specify the ufmg_version and ufmg_devpath fields. On success 60 * the ufmg_caps field will be filled in with a value indicating the supported 61 * UFM capabilities of the device specified in ufmg_devpath. 62 */ 63 typedef struct ufm_ioc_getcaps { 64 uint_t ufmg_version; /* DDI_UFM_VERSION */ 65 uint_t ufmg_caps; /* UFM Caps */ 66 char ufmg_devpath[MAXPATHLEN]; 67 } ufm_ioc_getcaps_t; 68 69 /* 70 * This struct defines the input/output data for the UFM_IOC_REPORTSZ ioctl. 71 * Callers should specify the ufbz_version and ufbz_devpath fields. On success 72 * the ufmg_size field will be filled in with the amount of space (in bytes) 73 * required to hold the UFM data for this device instance. This should be used 74 * to allocate a sufficiently size buffer for the UFM_IOC_REPORT ioctl. 75 */ 76 typedef struct ufm_ioc_bufsz { 77 uint_t ufbz_version; /* DDI_UFM_VERSION */ 78 size_t ufbz_size; /* sz of buf to be returned by ioctl */ 79 char ufbz_devpath[MAXPATHLEN]; 80 } ufm_ioc_bufsz_t; 81 82 #ifdef _KERNEL 83 typedef struct ufm_ioc_bufsz32 { 84 uint_t ufbz_version; 85 size32_t ufbz_size; 86 char ufbz_devpath[MAXPATHLEN]; 87 } ufm_ioc_bufsz32_t; 88 #endif /* _KERNEL */ 89 90 /* 91 * This struct defines the input/output data for the UFM_IOC_REPORT ioctl. 92 * Callers should specify the ufmr_version, ufmr_bufsz and ufmr_devpath fields. 93 * On success, the ufmr_buf field will point to a packed nvlist containing the 94 * UFM data for the specified device instance. The value of ufmr_bufsz will be 95 * updated to reflect the actual size of data copied out. 96 */ 97 typedef struct ufm_ioc_report { 98 uint_t ufmr_version; /* DDI_UFM_VERSION */ 99 size_t ufmr_bufsz; /* size of caller-supplied buffer */ 100 caddr_t ufmr_buf; /* buf to hold packed output nvl */ 101 char ufmr_devpath[MAXPATHLEN]; 102 } ufm_ioc_report_t; 103 104 #ifdef _KERNEL 105 typedef struct ufm_ioc_report32 { 106 uint_t ufmr_version; 107 size32_t ufmr_bufsz; 108 caddr32_t ufmr_buf; 109 char ufmr_devpath[MAXPATHLEN]; 110 } ufm_ioc_report32_t; 111 #endif /* _KERNEL */ 112 113 /* 114 * The UFM_IOC_REPORT ioctl return UFM image and slot data in the form of a 115 * packed nvlist. The nvlist contains and array of nvlists (one-per-image). 116 * Each image nvlist contains will contain a string nvpair containing a 117 * description of the image and an optional nvlist nvpair containing 118 * miscellaneous image information. 119 */ 120 #define DDI_UFM_NV_IMAGES "ufm-images" 121 #define DDI_UFM_NV_IMAGE_DESC "ufm-image-description" 122 #define DDI_UFM_NV_IMAGE_MISC "ufm-image-misc" 123 124 /* 125 * Each image nvlist also contains an array of nvlists representing the slots. 126 */ 127 #define DDI_UFM_NV_IMAGE_SLOTS "ufm-image-slots" 128 129 /* 130 * Each slot nvlist as a string nvpair describing the firmware image version 131 * and an uint32 nvpair describing the slot attributes (see ddi_ufm_attr_t 132 * above). An option nvlist nvpar may be present containing additional 133 * miscellaneous slot data. 134 */ 135 #define DDI_UFM_NV_SLOT_VERSION "ufm-slot-version" 136 137 typedef enum { 138 DDI_UFM_ATTR_READABLE = 1 << 0, 139 DDI_UFM_ATTR_WRITEABLE = 1 << 1, 140 DDI_UFM_ATTR_ACTIVE = 1 << 2, 141 DDI_UFM_ATTR_EMPTY = 1 << 3 142 } ddi_ufm_attr_t; 143 144 #define DDI_UFM_ATTR_MAX DDI_UFM_ATTR_READABLE | \ 145 DDI_UFM_ATTR_WRITEABLE | \ 146 DDI_UFM_ATTR_ACTIVE | \ 147 DDI_UFM_ATTR_EMPTY 148 149 #define DDI_UFM_NV_SLOT_ATTR "ufm-slot-attributes" 150 151 #define DDI_UFM_NV_SLOT_MISC "ufm-slot-misc" 152 153 #ifdef _KERNEL 154 /* opaque structures */ 155 typedef struct ddi_ufm_handle ddi_ufm_handle_t; 156 typedef struct ddi_ufm_image ddi_ufm_image_t; 157 typedef struct ddi_ufm_slot ddi_ufm_slot_t; 158 159 /* 160 * DDI UFM Operations vector 161 */ 162 typedef struct ddi_ufm_ops { 163 int (*ddi_ufm_op_nimages)(ddi_ufm_handle_t *, void *, uint_t *); 164 int (*ddi_ufm_op_fill_image)(ddi_ufm_handle_t *, void *, uint_t, 165 ddi_ufm_image_t *); 166 int (*ddi_ufm_op_fill_slot)(ddi_ufm_handle_t *, void *, uint_t, uint_t, 167 ddi_ufm_slot_t *); 168 int (*ddi_ufm_op_getcaps)(ddi_ufm_handle_t *, void *, ddi_ufm_cap_t *); 169 } ddi_ufm_ops_t; 170 171 /* 172 * During a device driver's attach(9E) entry point, a device driver should 173 * register with the UFM subsystem by filling out a UFM operations vector 174 * (see above) and then calling ddi_ufm_init(9F). The driver may pass in a 175 * value, usually a pointer to its soft state pointer, which it will then 176 * receive when its subsequent entry points are called. 177 */ 178 int ddi_ufm_init(dev_info_t *, uint_t version, ddi_ufm_ops_t *, 179 ddi_ufm_handle_t **, void *); 180 181 /* 182 * Device drivers should call ddi_ufm_update(9F) after driver initialization is 183 * complete and after calling ddi_ufm_init(9F), in order to indicate to the 184 * UFM subsystem that the driver is in a state where it is ready to receive 185 * calls to its UFM entry points. 186 * 187 * Additionally, whenever the driver detects a change in the state of a UFM, it 188 * should call ddi_ufm_update(9F). This will cause the UFM subsystem to 189 * invalidate any cached state regarding this driver's UFM(s) 190 */ 191 void ddi_ufm_update(ddi_ufm_handle_t *); 192 193 /* 194 * A device driver should call ddi_ufm_fini(9F) during its detach(9E) entry 195 * point. Upon return, the driver is gaurunteed that no further DDI UFM entry 196 * points will be called and thus any related state can be safely torn down. 197 * 198 * After return, the UFM handle is no longer valid and should not be used in 199 * any future ddi_ufm_* calls. 200 */ 201 void ddi_ufm_fini(ddi_ufm_handle_t *); 202 203 /* 204 * These interfaces should only be called within the context of a 205 * ddi_ufm_op_fill_image callback. 206 */ 207 void ddi_ufm_image_set_desc(ddi_ufm_image_t *, const char *); 208 void ddi_ufm_image_set_nslots(ddi_ufm_image_t *, uint_t); 209 void ddi_ufm_image_set_misc(ddi_ufm_image_t *, nvlist_t *); 210 211 /* 212 * These interfaces should only be called within the context of a 213 * ddi_ufm_op_fill_slot callback. 214 */ 215 void ddi_ufm_slot_set_version(ddi_ufm_slot_t *, const char *); 216 void ddi_ufm_slot_set_attrs(ddi_ufm_slot_t *, ddi_ufm_attr_t); 217 void ddi_ufm_slot_set_misc(ddi_ufm_slot_t *, nvlist_t *); 218 #endif /* _KERNEL */ 219 220 #ifdef __cplusplus 221 } 222 #endif 223 224 #endif /* _SYS_DDI_UFM_H */ 225