staging: comedi: mite: document mite_alloc()/mite_detach()

These functions are basically the comedi_driver (*attach)/(*detach)
for this driver.

For aesthetics, rename mite_alloc() to mite_attach() and pass the
comedi_device pointer to it instead of the pci_dev pointer.

Move the functions to the end of the file. This is typically where
a comedi_drivers (*attach)/(*detach) are located.

Add some docbook comments for these exported functions.

Signed-off-by: H Hartley Sweeten <hsweeten@visionengravers.com>
Reviewed-by: Ian Abbott <abbotti@mev.co.uk>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

5 files changed, 53 insertions, 37 deletions

diff --git a/drivers/staging/comedi/drivers/mite.c b/drivers/staging/comedi/drivers/mite.c
index 650c603..f64c5df 100644
--- a/drivers/staging/comedi/drivers/mite.c
+++ b/drivers/staging/comedi/drivers/mite.c
@@ -219,25 +219,6 @@ static void mite_dma_reset(struct mite_channel *mite_chan)
 	       mite_chan->mite->mmio + MITE_CHOR(mite_chan->channel));
 }
 
-struct mite *mite_alloc(struct pci_dev *pcidev)
-{
-	struct mite *mite;
-	unsigned int i;
-
-	mite = kzalloc(sizeof(*mite), GFP_KERNEL);
-	if (mite) {
-		spin_lock_init(&mite->lock);
-		mite->pcidev = pcidev;
-		for (i = 0; i < MAX_MITE_DMA_CHANNELS; ++i) {
-			mite->channels[i].mite = mite;
-			mite->channels[i].channel = i;
-			mite->channels[i].done = 1;
-		}
-	}
-	return mite;
-}
-EXPORT_SYMBOL_GPL(mite_alloc);
-
 static void dump_chip_signature(u32 csigr_bits)
 {
 	unsigned int wpdep;
@@ -340,18 +321,6 @@ int mite_setup2(struct comedi_device *dev,
 }
 EXPORT_SYMBOL_GPL(mite_setup2);
 
-void mite_detach(struct mite *mite)
-{
-	if (!mite)
-		return;
-
-	if (mite->mmio)
-		iounmap(mite->mmio);
-
-	kfree(mite);
-}
-EXPORT_SYMBOL_GPL(mite_detach);
-
 struct mite_ring *mite_alloc_ring(struct mite *mite)
 {
 	struct mite_ring *ring;
@@ -838,6 +807,53 @@ int mite_done(struct mite_channel *mite_chan)
 }
 EXPORT_SYMBOL_GPL(mite_done);
 
+/**
+ * mite_attach() - Allocate and initialize a MITE device for a comedi driver.
+ * @dev: COMEDI device.
+ *
+ * Called by a COMEDI drivers (*auto_attach).
+ *
+ * Returns a pointer to the MITE device on success, or NULL if the MITE cannot
+ * be allocated.
+ */
+struct mite *mite_attach(struct comedi_device *dev)
+{
+	struct pci_dev *pcidev = comedi_to_pci_dev(dev);
+	struct mite *mite;
+	unsigned int i;
+
+	mite = kzalloc(sizeof(*mite), GFP_KERNEL);
+	if (mite) {
+		spin_lock_init(&mite->lock);
+		mite->pcidev = pcidev;
+		for (i = 0; i < MAX_MITE_DMA_CHANNELS; ++i) {
+			mite->channels[i].mite = mite;
+			mite->channels[i].channel = i;
+			mite->channels[i].done = 1;
+		}
+	}
+	return mite;
+}
+EXPORT_SYMBOL_GPL(mite_attach);
+
+/**
+ * mite_detach() - Unmap and free a MITE device for a comedi driver.
+ * @mite: MITE device.
+ *
+ * Called by a COMEDI drivers (*detach).
+ */
+void mite_detach(struct mite *mite)
+{
+	if (!mite)
+		return;
+
+	if (mite->mmio)
+		iounmap(mite->mmio);
+
+	kfree(mite);
+}
+EXPORT_SYMBOL_GPL(mite_detach);
+
 static int __init mite_module_init(void)
 {
 	return 0;
diff --git a/drivers/staging/comedi/drivers/mite.h b/drivers/staging/comedi/drivers/mite.h
index 2d97ad4..d2643e4 100644
--- a/drivers/staging/comedi/drivers/mite.h
+++ b/drivers/staging/comedi/drivers/mite.h
@@ -60,8 +60,6 @@ struct mite {
 	spinlock_t lock;
 };
 
-struct mite *mite_alloc(struct pci_dev *);
-
 int mite_setup2(struct comedi_device *, struct mite *, bool use_win1);
 
 static inline int mite_setup(struct comedi_device *dev,
@@ -70,7 +68,6 @@ static inline int mite_setup(struct comedi_device *dev,
 	return mite_setup2(dev, mite, false);
 }
 
-void mite_detach(struct mite *);
 struct mite_ring *mite_alloc_ring(struct mite *);
 void mite_free_ring(struct mite_ring *ring);
 struct mite_channel *mite_request_channel_in_range(struct mite *,
@@ -101,6 +98,9 @@ int mite_buf_change(struct mite_ring *, struct comedi_subdevice *);
 int mite_init_ring_descriptors(struct mite_ring *, struct comedi_subdevice *,
 			       unsigned int nbytes);
 
+struct mite *mite_attach(struct comedi_device *);
+void mite_detach(struct mite *);
+
 /*
  * Mite registers (used outside of the mite driver)
  */
diff --git a/drivers/staging/comedi/drivers/ni_660x.c b/drivers/staging/comedi/drivers/ni_660x.c
index 041ea67..de75598 100644
--- a/drivers/staging/comedi/drivers/ni_660x.c
+++ b/drivers/staging/comedi/drivers/ni_660x.c
@@ -724,7 +724,7 @@ static int ni_660x_auto_attach(struct comedi_device *dev,
 		return ret;
 	devpriv = dev->private;
 
-	devpriv->mite = mite_alloc(pcidev);
+	devpriv->mite = mite_attach(dev);
 	if (!devpriv->mite)
 		return -ENOMEM;
 
diff --git a/drivers/staging/comedi/drivers/ni_pcidio.c b/drivers/staging/comedi/drivers/ni_pcidio.c
index e176b60..1e30792 100644
--- a/drivers/staging/comedi/drivers/ni_pcidio.c
+++ b/drivers/staging/comedi/drivers/ni_pcidio.c
@@ -897,7 +897,7 @@ static int nidio_auto_attach(struct comedi_device *dev,
 
 	spin_lock_init(&devpriv->mite_channel_lock);
 
-	devpriv->mite = mite_alloc(pcidev);
+	devpriv->mite = mite_attach(dev);
 	if (!devpriv->mite)
 		return -ENOMEM;
 
diff --git a/drivers/staging/comedi/drivers/ni_pcimio.c b/drivers/staging/comedi/drivers/ni_pcimio.c
index 73c7d32..0408ba3 100644
--- a/drivers/staging/comedi/drivers/ni_pcimio.c
+++ b/drivers/staging/comedi/drivers/ni_pcimio.c
@@ -1172,7 +1172,7 @@ static int pcimio_auto_attach(struct comedi_device *dev,
 		return ret;
 	devpriv = dev->private;
 
-	devpriv->mite = mite_alloc(pcidev);
+	devpriv->mite = mite_attach(dev);
 	if (!devpriv->mite)
 		return -ENOMEM;