NAME
dtrace_cam – a DTrace provider for tracing events related to CAM
SYNOPSIS
cam::xpt:action(union ccb *ccb);
cam::xpt:done(union ccb *ccb); a.Fn cam::xpt:async-cb "void *cbarg" "uint32_t async_code" "struct cam_path *path" "void *async_arg"
cam::periph:error(union ccb *ccb, cam_flags camflags, uint32_t sense_flags);
cam::da:error(union ccb *ccb, uint32_t cam_flags, uint32_t sense_flags);
cam::ada:error(union ccb *ccb, uint32_t cam_flags, uint32_t sense_flags);
cam::nda:error(union ccb *ccb, uint32_t cam_flags, uint32_t sense_flags);
cam::sdda:error(union ccb *ccb, uint32_t cam_flags, uint32_t sense_flags);
cam::periph:recovery(union ccb *ccb, int error);
cam::da:recovery(union ccb *ccb, int error);
cam::ada:recovery(union ccb *ccb, int error);
cam::nda:recovery(union ccb *ccb, int error);
cam::sdda:recovery(union ccb *ccb, int error);
cam::periph:invalidate(struct cam_periph *periph);
cam::periph:hold-boot(struct cam_periph *periph);
cam::periph:release-boot(struct cam_periph *periph);
cam::xpt:bus-register(struct cam_sim *sim, path_id_t path_id);
cam::xpt:hold-boot(int buses_to_config);
cam::xpt:release-boot(int buses_to_config);
DESCRIPTION
The cam provider allows the tracing of CAM events. The cam::xpt:action() probe fires when a CAM Control Block (ccb) is submitted to a CAM SIM driver. The cam::xpt:done() probe fires when that request completes. The cam::xpt:async-cb() probe fires just before an async callback is called. The cam::periph:error() probe fires on entry to cam_periph_error(), the generic CAM peripheral driver error handler, before any error recovery or retry decisions are made. The cam::da:error(), cam::ada:error(), cam::nda:error(), and cam::sdda:error() probes fire on entry to the da(4), ada(4), nda(4), and sdda (mmc(4)) peripheral drivers' own error handlers, before they call cam_periph_error() or otherwise process the failing ccb.
The cam::periph:recovery() probe fires once cam_periph_error() has decided how to dispose of the failing ccb, reporting that decision as error: 0 means the ccb is being treated as successful, ERESTART means the request is being retried, and any other value is the errno(2) the request is failing with. Of those, EIO means only this request is being failed, while ENXIO means the device itself is now being treated as gone (a selection timeout, or an error seen after the peripheral was already invalidated). Other errno values can appear as well: CAM_SCSI_STATUS_ERROR handling maps specific SCSI sense key/ASC/ASCQ combinations to whatever errno is most appropriate (EBUSY, ENOSPC, EINVAL, and others) via the table in sys/cam/scsi/scsi_all.c. The cam::da:recovery(), cam::ada:recovery(), cam::nda:recovery(), and cam::sdda:recovery() probes report the same error decision from the corresponding peripheral driver's own error handler, which may resolve the error itself (for example da(4)'s automatic READ/WRITE(6)-to-(10) upgrade) before ever calling cam_periph_error(). The cam::periph:invalidate() probe fires from cam_periph_invalidate() when a peripheral is actually torn down as a result of an unrecoverable error, regardless of which peripheral driver or code path triggered it.
The cam::periph:hold-boot() and cam::periph:release-boot() probes fire from cam_periph_hold_boot() and cam_periph_release_boot(), reporting the cam_periph taking or releasing its own, per-peripheral root-mount hold, which is keyed by periph->periph_name (for example ‘da’ or ‘ada’). Since the probe itself is necessarily generic (SDT probe names are fixed at compile time, not runtime), a consumer wanting to filter by peripheral type should match on periph->periph_name in the enabling's predicate, for example stringof(args[0]->periph_name) == "da".
The cam::xpt:bus-register() probe fires from xpt_bus_register() once a new bus has been assigned a path_id and linked into the list of known busses, reporting the cam_sim being registered and that path_id. The cam::xpt:hold-boot() and cam::xpt:release-boot() probes report the CAM subsystem's shared boot-hold refcount (xsoftc.buses_to_config) immediately after it is incremented or decremented, respectively. This one refcount is shared by every bus's initial scan (via xpt_rescan()) as well as by peripheral drivers' own startup bookkeeping, so root mount can remain blocked on it long after any one contributor has finished; tracing both probes together shows exactly which holds are still outstanding and for how long.
SEE ALSO
HISTORY
The cam provider first appeared in FreeBSD 15.1 and 16.0.
AUTHORS
This manual page was written by Warner Losh ⟨[email protected]⟩.