Safely Check and Send SCSI Enclosure Firmware with sg_ses_microcode

You will finish with a repeatable way to inspect an enclosure's Download Microcode status and, when the vendor's procedure authorises it, send a firmware image in controlled chunks. Allow 20 minutes for a status check and preparation. Allow longer for the update itself, including a maintenance window and any required power cycle.

You need the sg3-utils package, the correct SCSI generic device for the enclosure, a vendor-approved firmware file, and permission to access that device. This guide was checked with Ubuntu package sg3-utils 1.46-3ubuntu4. The installed utility identifies itself as sg_ses_microcode 1.18 20190513, while the local manual is dated January 2018 and labels its source release sg3_utils 1.43. Treat the installed command's help and the enclosure vendor's instructions as the final authority for your host.

1. Confirm the binary and device

Start with read-only checks. These do not send SCSI commands to the enclosure:

$ command -v sg_ses_microcode
/usr/bin/sg_ses_microcode
$ sg_ses_microcode --version
sg_ses_microcode: version: 1.18 20190513
$ sg_map -i
# identify the enclosure's matching /dev/sgN device

The exact sg_map output depends on the host. Do not copy /dev/sgN from this article. If your account cannot open the device, use the ordinary local access procedure, such as membership of the appropriate device group. Use sudo only when your system requires it, and check the device again after privilege escalation.

Checkpoint: write down the verified device path as ENCLOSURE_DEV. A path such as /dev/sg4 is an example, not a safe default.

2. Read the current download status

With only a device argument, the utility fetches and decodes the Download Microcode status diagnostic page. It does not need a firmware file and is the safest useful first operation:

$ ENCLOSURE_DEV=/dev/sg4
$ sg_ses_microcode "$ENCLOSURE_DEV"
Download microcode status diagnostic page:
  number of secondary subenclosures: 3
  generation code: 0x0
   subenclosure identifier: 0 [primary]
     download microcode status: No download microcode operation in progress [0x0]
     download microcode maximum size: 4194304 bytes

Your enclosure may report a different number of sub-enclosures, maximum size, generation code, status, buffer ID or offset. A non-zero or in-progress status is a stopping point: record the complete output and follow the enclosure vendor's recovery procedure before starting another operation. The default sub-enclosure identifier is 0, the primary enclosure.

If you need a particular secondary enclosure, read its status explicitly:

$ sg_ses_microcode --subenc=1 "$ENCLOSURE_DEV"

Checkpoint: continue only when the status is understood, the target sub-enclosure is correct, and the firmware file is documented for that exact hardware.

3. Validate the plan without sending commands

--dry-run still opens the device and requires a device argument, but skips the actual SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS calls. It supplies dummy status responses, so it is suitable for checking option spelling and file handling, not for proving that an enclosure accepts the image:

$ sg_ses_microcode --dry-run \
    --mode=dmc_offs_save \
    --bpw=4096 \
    --in=/path/to/vendor-firmware.bin \
    "$ENCLOSURE_DEV"

The mode dmc_offs_save means download with offsets, save, and activate. The mode is a change request, not a harmless inspection. In dry-run mode no SCSI command is sent, but the file must still be readable and the device must still be opened. Use /dev/null as the device only when you deliberately want the dummy path and do not need a real enclosure response.

Use the file's actual length unless the vendor specifies a different transfer length. --skip starts at a byte offset in a regular input file; --length limits the data length and fills a short input with 0xff bytes. Do not add either option to a normal whole-image update without a documented reason.

4. Send the image in bounded chunks

Large single SCSI transfers can exceed an operating system, pass-through, device or enclosure limit. The manual's practical example uses 4 KiB chunks. A controlled update therefore looks like this, after a maintenance window has started:

$ sudo sg_ses_microcode \
    --bpw=4096 \
    --mode=dmc_offs_save \
    --in=/path/to/vendor-firmware.bin \
    --subenc=0 \
    "$ENCLOSURE_DEV"

$ printf 'sg_ses_microcode exit status: %s\n' "$?"
sg_ses_microcode exit status: 0

--bpw is the maximum bytes per SEND DIAGNOSTIC command and should be a multiple of four. With it, the utility advances the buffer offset for each chunk. The separate --offset option is ignored when --bpw is present. If your vendor specifies a different chunk size, use that value; otherwise start conservatively and confirm the enclosure's limits.

Do not interrupt power or remove the enclosure while commands are outstanding. Each SEND DIAGNOSTIC command has a long operating-system timeout. A timeout or sense error is not permission to retry blindly: preserve the terminal output, read the status page, and consult the vendor procedure.

5. Check activation and recover from a failed attempt

Read status again after the command returns:

$ sudo sg_ses_microcode "$ENCLOSURE_DEV"
# inspect the status and additional-status fields

The enclosure may activate the firmware during a later power cycle. Verify the new revision with an inquiry command when the enclosure is stable:

$ sudo sg_inq "$ENCLOSURE_DEV"
# compare the revision string with the vendor's expected value

If you used dmc_offs_defer, the image is saved but activation is deferred. The documented follow-up is a separate activation request:

$ sudo sg_ses_microcode --mode=activate_mc --subenc=0 "$ENCLOSURE_DEV"

Use that only when the vendor instructs you to activate deferred microcode. The device may reset, so the activation mode has no trailing status fetch. Some devices also need a power cycle. If a device reports an illegal request with sense code 0x26/0x00, the manual identifies a non-standard implementation that may require --non; treat that as a vendor-specific recovery experiment, not a universal fix.