[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <b61d3687-70ea-1ab7-63e1-44e381d36012@acm.org>
Date: Tue, 14 Jun 2022 12:33:07 -0700
From: Bart Van Assche <bvanassche@....org>
To: John Garry <john.garry@...wei.com>, axboe@...nel.dk,
damien.lemoal@...nsource.wdc.com, jejb@...ux.ibm.com,
martin.petersen@...cle.com, brking@...ibm.com, hare@...e.de,
hch@....de
Cc: linux-block@...r.kernel.org, linux-ide@...r.kernel.org,
linux-kernel@...r.kernel.org, linux-scsi@...r.kernel.org,
chenxiang66@...ilicon.com
Subject: Re: [PATCH RFC v2 02/18] scsi: core: Resurrect
scsi_{get,free}_host_dev()
On 6/9/22 03:29, John Garry wrote:
> +/**
> + * scsi_get_host_dev - Create a scsi_device that points to the host adapter itself
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
What does this mean? That part of the function description is not
clear to me.
> + * @shost: Host that needs a scsi_device
^^^^^^^^^^^^^
This is not detailed enough. Consider changing "a scsi_device" into
"a scsi device for allocating reserved commands from".
> + *
> + * Lock status: None assumed.
> + *
> + * Returns: The scsi_device or NULL
> + *
> + * Notes:
> + * Attach a single scsi_device to the Scsi_Host - this should
> + * be made to look like a "pseudo-device" that points to the
> + * HA itself.
> + *
> + * Note - this device is not accessible from any high-level
> + * drivers (including generics), which is probably not
> + * optimal. We can add hooks later to attach.
The "which is probably not optimal. We can add hooks later to attach."
part probably should be moved to the patch description.
> + */
> +struct scsi_device *scsi_get_host_dev(struct Scsi_Host *shost)
> +{
> + struct scsi_device *sdev = NULL;
> + struct scsi_target *starget;
> +
> + mutex_lock(&shost->scan_mutex);
> + if (!scsi_host_scan_allowed(shost))
> + goto out;
> + starget = scsi_alloc_target(&shost->shost_gendev, 0, shost->this_id);
^^^^^^^^^^^^^^^^^^
Is it guaranteed that this channel / id combination will not be used for
any other SCSI device?
What if shost->this_id == -1?
> + if (!starget)
> + goto out;
> +
> + sdev = scsi_alloc_sdev(starget, 0, NULL);
> + if (sdev)
> + sdev->borken = 0;
> + else
> + scsi_target_reap(starget);
> + put_device(&starget->dev);
> + out:
> + mutex_unlock(&shost->scan_mutex);
> + return sdev;
> +}
> +EXPORT_SYMBOL(scsi_get_host_dev);
Elsewhere in the SCSI core "get..dev" means increment the reference count of
a SCSI device. Maybe scsi_alloc_host_dev() is a better name?
> +/*
> + * These two functions are used to allocate and free a pseudo device
> + * which will connect to the host adapter itself rather than any
> + * physical device. You must deallocate when you are done with the
> + * thing. This physical pseudo-device isn't real and won't be available
> + * from any high-level drivers.
> + */
Please keep function comments in .c files because that makes it more likely
that the comment and the implementation will remain in sync.
Thanks,
Bart.
Powered by blists - more mailing lists