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 .\"
  14 .Dd Apr 30, 2019
  15 .Dt DDI_UFM 9E
  16 .Os
  17 .Sh NAME
  18 .Nm ddi_ufm ,
  19 .Nm ddi_ufm_op_nimages ,
  20 .Nm ddi_ufm_op_fill_image ,
  21 .Nm ddi_ufm_op_fill_slot ,
  22 .Nm ddi_ufm_op_getcaps
  23 .Nd DDI upgradable firmware module entry points
  24 .Sh SYNOPSIS
  25 .Vt typedef struct ddi_ufm_handle ddi_ufm_handle_t
  26 .Vt typedef struct ddi_ufm_ops ddi_ufm_ops_t
  27 .In sys/ddi_ufm.h
  28 .Ft int
  29 .Fo ddi_ufm_op_getcaps
  30 .Fa "ddi_ufm_handle_t *uhp"
  31 .Fa "void *drv_arg"
  32 .Fa "ddi_ufm_cap_t *caps"
  33 .Fc
  34 .Ft int

 350 which indicates that the driver is capable of reporting UFM information for this
 351 instance.
 352 Future UFM versions may add additional capabilities such as the ability to
 353 obtain a raw dump of the firmware image or to upgrade the firmware.
 354 .Pp
 355 The driver should indicate the supported capabilities by setting the value in
 356 the
 357 .Ft caps
 358 parameter.
 359 Once the driver has populated
 360 .Ft caps
 361 with an appropriate value, then the driver should return
 362 .Sy 0 .
 363 Otherwise, the driver should return the appropriate error number.
 364 For a full list of error numbers, see
 365 .Xr Intro 2 .
 366 Common values are:
 367 .Bl -tag -width Er -offset width
 368 .It Er EIO
 369 An error occurred talking to the device while trying to discover firmware
 370 capabilties.
 371 .It Er ENOMEM
 372 The driver was unable to allocate memory.
 373 .El
 374 .El
 375 .Ss Caching and Updates
 376 The system will fetch firmware and slot information on an as-needed
 377 basis.
 378 Once it obtains some information, it may end up caching this information on
 379 behalf of the driver.
 380 Whenever the driver believes that something could have changed -- it need know
 381 that it has -- then the driver must call
 382 .Xr ddi_ufm_update 9F .
 383 .Ss Locking
 384 All UFM operations on a single UFM handle will always be run serially.
 385 However, the device driver may still need to apply adequate locking to
 386 its structure members as other may be accessing the same data structure
 387 or trying to communicate with the device.
 388 .Ss Unregistering from the UFM subsystem
 389 When a device driver is detached, it should unregister from the UFM
 390 subsystem.

   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 .\"
  14 .Dd February 15, 2020
  15 .Dt DDI_UFM 9E
  16 .Os
  17 .Sh NAME
  18 .Nm ddi_ufm ,
  19 .Nm ddi_ufm_op_nimages ,
  20 .Nm ddi_ufm_op_fill_image ,
  21 .Nm ddi_ufm_op_fill_slot ,
  22 .Nm ddi_ufm_op_getcaps
  23 .Nd DDI upgradable firmware module entry points
  24 .Sh SYNOPSIS
  25 .Vt typedef struct ddi_ufm_handle ddi_ufm_handle_t
  26 .Vt typedef struct ddi_ufm_ops ddi_ufm_ops_t
  27 .In sys/ddi_ufm.h
  28 .Ft int
  29 .Fo ddi_ufm_op_getcaps
  30 .Fa "ddi_ufm_handle_t *uhp"
  31 .Fa "void *drv_arg"
  32 .Fa "ddi_ufm_cap_t *caps"
  33 .Fc
  34 .Ft int

 350 which indicates that the driver is capable of reporting UFM information for this
 351 instance.
 352 Future UFM versions may add additional capabilities such as the ability to
 353 obtain a raw dump of the firmware image or to upgrade the firmware.
 354 .Pp
 355 The driver should indicate the supported capabilities by setting the value in
 356 the
 357 .Ft caps
 358 parameter.
 359 Once the driver has populated
 360 .Ft caps
 361 with an appropriate value, then the driver should return
 362 .Sy 0 .
 363 Otherwise, the driver should return the appropriate error number.
 364 For a full list of error numbers, see
 365 .Xr Intro 2 .
 366 Common values are:
 367 .Bl -tag -width Er -offset width
 368 .It Er EIO
 369 An error occurred talking to the device while trying to discover firmware
 370 capabilities.
 371 .It Er ENOMEM
 372 The driver was unable to allocate memory.
 373 .El
 374 .El
 375 .Ss Caching and Updates
 376 The system will fetch firmware and slot information on an as-needed
 377 basis.
 378 Once it obtains some information, it may end up caching this information on
 379 behalf of the driver.
 380 Whenever the driver believes that something could have changed -- it need know
 381 that it has -- then the driver must call
 382 .Xr ddi_ufm_update 9F .
 383 .Ss Locking
 384 All UFM operations on a single UFM handle will always be run serially.
 385 However, the device driver may still need to apply adequate locking to
 386 its structure members as other may be accessing the same data structure
 387 or trying to communicate with the device.
 388 .Ss Unregistering from the UFM subsystem
 389 When a device driver is detached, it should unregister from the UFM
 390 subsystem.