Project

General

Profile

Actions
Copy link

Bug #13410

closed

ddi_ufm(9E) typos and such

Added by Ryan Zezeski over 2 years ago. Updated over 2 years ago.

Status:
Closed
Priority:
Normal
Assignee:
Robert Mustacchi
Category:
manpage - manual pages
Start date:
Due date:
% Done:

100%

Estimated time:
Difficulty:
Bite-size
Tags:
Gerrit CR:
1140
External Bug:

Description

  • The parameters section mentions nslotp, but there is no such parameter in any of the callbacks.
  • Either I'm slow today or this sentence is hard to parse: "A buffer to place data firmware data read into."
  • The first graph goes to some length to make it clear that images are not just "firmware" (even though this subsystem is named the Upgradable Firmware Module). However, the rest of the man page wavers between referring to them as "image(s)" or "firmware image(s)". This doesn't seem to interfere with my understanding of how things work -- I get the gist -- but this slight dissonance might throw someone for a loop. Just a thought.
  • "...image can be downloaded to the device without impacting the [current device] if it fails..." I'm pretty sure this should be either "current image" (or maybe "active image") or "device".
  • "If a driver indicates support for multiple images [or slots]..." From what I can tell there is no way to a driver to indicate the number of slots for a given image (this gets back to the missing nslotp, perhaps in the past there was a way to specify this data. But the current API seems to dictate that rather you simply return an error if the consumer requests a bogus slot number.
  • There are three sentences which start "This [attributes] indicates".
  • The man page uses imgid and slotid, but drivers seem to prefer to use imgno/slotno. Might be nice to change the man page to use the most common naming scheme.
  • Under the ddi_ufm_op_getcaps() section, specifically for the DDI_UFM_CAP_REPORT cap, it implies that the ddi_ufm_op_fill_image is optional. Yet the ddi_ufm_init() implementation specifically VERIFYs that this callback is not NULL. Furthermore, is it ever the case that a device doesn't implement the DDI_UFM_CAP_REPORT? What would be the reason for such a decision?
  • "it need know that it has" I can't parse this.
  • "...adequate locking to its structure members as [others] may be accessing..."
Actions
Copy link
 #1

Updated by Robert Mustacchi over 2 years ago

  • Assignee set to Robert Mustacchi
Actions
Copy link
 #2

Updated by Electric Monk over 2 years ago

  • Gerrit CR set to 1140
Actions
Copy link
 #3

Updated by Robert Mustacchi over 2 years ago

I tested this mostly through using man.

Actions
Copy link
 #4

Updated by Electric Monk over 2 years ago

  • Status changed from New to Closed
  • % Done changed from 0 to 100

git commit 3561e562ae78c234d96711f36e19360789b0ffe3

commit  3561e562ae78c234d96711f36e19360789b0ffe3
Author: Robert Mustacchi <rm@fingolfin.org>
Date:   2021-01-12T00:23:37.000Z

    13410 ddi_ufm(9E) typos and such
    Reviewed by: Peter Tribble <peter.tribble@gmail.com>
    Reviewed by: Ryan Zezeski <ryan@oxide.computer>
    Approved by: Dan McDonald <danmcd@joyent.com>

Actions
Copy link

Also available in: Atom PDF