cam: Add doxygen docs to cam_sim_alloc

[imp]

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

[mav]

sys/cam/cam_sim.c

75

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().

[imp]

sys/cam/cam_sim.c

75

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().

[imp]

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

[mav]

sys/cam/cam_sim.c

75

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

95

What is this separator?

[imp]

last round of tweaks from mav@

[imp]

sys/cam/cam_sim.c

75

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

95

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