FreeBSD Quirk Guidelines

Introduction

FreeBSD drivers make every attempt possible to support the standards behind hardware. Where possible and not in conflict with the standard, they also attempt to work around hardware which doesn't strictly conform. However, some devices have flaws which can't be worked around while keeping the driver compatible with the standard. For these devices, we have created a quirks mechanism to indicate to the driver that it must avoid certain commands or use them differently with a specific model and/or version of hardware. This document focuses on identifying and committing quirks for storage hardware involving CAM and UMASS but is applicable to other areas.

CAM provides a generic transport for SCSI-like devices. Many different transports use SCSI command sets including parallel SCSI, firewire (1394), USB UMASS, fibre channel, and ATAPI. For block devices (i.e. hard drives, flash adapters, cameras) there are two standards, SBC and RBC. SCSI hard drives are usually SBC-compliant and smaller devices like flash drives are usually RBC-compliant. Multimedia devices including CDROMs and DVD-RW are usually MMC-compliant.

Please follow these guidelines to get your device working as soon as possible. If you are a committer, please do NOT commit quirks directly but follow this process also.

Determing the problem

The first step is to determine what's wrong. If the device should be supported but hangs while attaching, it's possible a quirk can help. The types of things a quirk can fix are:

Testing a Quirk

After you have an idea what you want to try, edit the proper file above, using wildcarding to be sure your device is matched. Here is a list of the common things to try. Note that some devices require multiple quirks or quirks in different drivers. For example, some USB pen drives or flash readers require quirks in both da(4) and umass(4).

Filing a PR

All quirk submissions MUST go through GNATS. For information on how to submit a PR, see this page. Please include the following in your PR:

Here are some examples of well-formed PRs:

What happens next

I will review your submission, respond with comments, and once the quirk is deemed necessary and ready for committing, I'll commit it, referencing the PR. (Again, all quirks must be submitted as PRs).

Questions? Email njl AT freebsd.org

Note to Committers

Please insert quirks in the right section in scsi_da.c, sorted by PR number. Always include the name and PR number for scsi_da.c (see above for an example.) Please sort quirks alphabetically in umass.c. Follow the surrounding style in all drivers. Be sure to correspond with the submitter to be sure the quirk you are adding is the minimum necessary, not quirking other useful features and not overly broad (i.e., too many wildcards).

Links

  1. SBC (SCSI block commands)
  2. RBC (reduced block commands)
  3. MMC (multimedia commands)