Page MenuHomeFreeBSD

cam: Add doxygen docs to cam_sim_alloc
ClosedPublic

Authored by imp on May 5 2021, 2:16 AM.

Details

Summary

Add description for what each of the parameters are to the cam_sim_alloc
call. Add some additional context for the mtx and queue parameters to
explain what special values passed in mean.

MFC After: 3 days
Sponsored by: Netflix

Diff Detail

Repository
rG FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

imp requested review of this revision.May 5 2021, 2:16 AM
sys/cam/cam_sim.c
74

I don't like this description. I would replace this paragraph with something like:

SCSI Interface Module is the interface between CAM and hardware. SIM receives CCBs from CAM via sim_action callback and translates them into DMA or other hardware transactions. It can be polled for execution via sim_poll callback until it completes CCB processing by calling xpt_done().

sys/cam/cam_sim.c
74

Two things: s/SCSI/Storage/ because while it was originally SCSI Interface Module, it's really become Storage Interface Module with the addition of ata, nvme, and sd/mmc.

Also sim_poll is only used for dumps, and the current sentence implies one polls until xpt_done happens.

Maybe something more like

Storage (formerly SCSI) Interface Module is the interface between CAM and hardware. SIM receives CCBs from CAM via sim_action callback and translates them into DMA or other hardware transactions.  During system dumps, it can be polled with the sim_poll callback. CCB processing is terminated by calling xpt_done().

Fold in mav's suggestions. Let's see if this is better.

sys/cam/cam_sim.c
74

This one is good to me. I would just remove the first sentence, describing internal implementation details ("Allocates memory and ...").

94

What is this separator?

last round of tweaks from mav@

sys/cam/cam_sim.c
74

OK. I'll do that since it repeats the short description.

94

A mistake. It's 80 '-' that I was using for some manual formatting.

This revision is now accepted and ready to land.May 5 2021, 2:59 PM
This revision was automatically updated to reflect the committed changes.