the input layer, ALSA, networking, MTD, the character device framework,
or other Linux subsystems.
+Note that there are two types of memory your driver must manage as part
+of interacting with SPI devices.
+
+ - I/O buffers use the usual Linux rules, and must be DMA-safe.
+ You'd normally allocate them from the heap or free page pool.
+ Don't use the stack, or anything that's declared "static".
+
+ - The spi_message and spi_transfer metadata used to glue those
+ I/O buffers into a group of protocol transactions. These can
+ be allocated anywhere it's convenient, including as part of
+ other allocate-once driver data structures. Zero-init these.
+
+If you like, spi_message_alloc() and spi_message_free() convenience
+routines are available to allocate and zero-initialize an spi_message
+with several transfers.
+
How do I write an "SPI Master Controller Driver"?
-------------------------------------------------
if (spi->master->cleanup)
spi->master->cleanup(spi);
- class_device_put(&spi->master->cdev);
+ spi_master_put(spi->master);
kfree(dev);
}
int value;
struct spi_driver *drv = to_spi_driver(dev->driver);
- if (!drv || !drv->suspend)
+ if (!drv->suspend)
return 0;
/* suspend will stop irqs and dma; no more i/o */
int value;
struct spi_driver *drv = to_spi_driver(dev->driver);
- if (!drv || !drv->resume)
+ if (!drv->resume)
return 0;
/* resume may restart the i/o queue */
/* NOTE: caller did any chip->bus_num checks necessary */
- if (!class_device_get(&master->cdev))
+ if (!spi_master_get(master))
return NULL;
proxy = kzalloc(sizeof *proxy, GFP_KERNEL);
return proxy;
fail:
- class_device_put(&master->cdev);
+ spi_master_put(master);
kfree(proxy);
return NULL;
}
struct spi_master *master;
master = container_of(cdev, struct spi_master, cdev);
- put_device(master->cdev.dev);
- master->cdev.dev = NULL;
kfree(master);
}
/**
* spi_alloc_master - allocate SPI master controller
* @dev: the controller, possibly using the platform_bus
- * @size: how much driver-private data to preallocate; a pointer to this
- * memory in the class_data field of the returned class_device
+ * @size: how much driver-private data to preallocate; the pointer to this
+ * memory is in the class_data field of the returned class_device,
+ * accessible with spi_master_get_devdata().
*
* This call is used only by SPI master controller drivers, which are the
* only ones directly touching chip registers. It's how they allocate
* master structure on success, else NULL.
*
* The caller is responsible for assigning the bus number and initializing
- * the master's methods before calling spi_add_master(), or else (on error)
- * calling class_device_put() to prevent a memory leak.
+ * the master's methods before calling spi_add_master(); and (after errors
+ * adding the device) calling spi_master_put() to prevent a memory leak.
*/
struct spi_master * __init_or_module
spi_alloc_master(struct device *dev, unsigned size)
{
struct spi_master *master;
+ if (!dev)
+ return NULL;
+
master = kzalloc(size + sizeof *master, SLAB_KERNEL);
if (!master)
return NULL;
class_device_initialize(&master->cdev);
master->cdev.class = &spi_master_class;
master->cdev.dev = get_device(dev);
- class_set_devdata(&master->cdev, &master[1]);
+ spi_master_set_devdata(master, &master[1]);
return master;
}
*
* This must be called from context that can sleep. It returns zero on
* success, else a negative error code (dropping the master's refcount).
+ * After a successful return, the caller is responsible for calling
+ * spi_unregister_master().
*/
int __init_or_module
spi_register_master(struct spi_master *master)
int status = -ENODEV;
int dynamic = 0;
+ if (!dev)
+ return -ENODEV;
+
/* convention: dynamically assigned bus IDs count down from the max */
if (master->bus_num == 0) {
master->bus_num = atomic_dec_return(&dyn_bus_id);
static int __unregister(struct device *dev, void *unused)
{
/* note: before about 2.6.14-rc1 this would corrupt memory: */
- device_unregister(dev);
+ spi_unregister_device(to_spi_device(dev));
return 0;
}
*/
void spi_unregister_master(struct spi_master *master)
{
- class_device_unregister(&master->cdev);
(void) device_for_each_child(master->cdev.dev, NULL, __unregister);
+ class_device_unregister(&master->cdev);
+ master->cdev.dev = NULL;
}
EXPORT_SYMBOL_GPL(spi_unregister_master);
* by leaving it selected in anticipation that the next message will go
* to the same chip. (That may increase power usage.)
*
+ * Also, the caller is guaranteeing that the memory associated with the
+ * message will not be freed before this call returns.
+ *
* The return value is a negative error code if the message could not be
* submitted, else zero. When the value is zero, then message->status is
* also defined: it's the completion code for the transfer, either zero
* is zero for success, else a negative errno status code.
* This call may only be used from a context that may sleep.
*
- * Parameters to this routine are always copied using a small buffer,
- * large transfers should use use spi_{async,sync}() calls with
- * dma-safe buffers.
+ * Parameters to this routine are always copied using a small buffer;
+ * performance-sensitive or bulk transfer code should instead use
+ * spi_{async,sync}() calls with dma-safe buffers.
*/
int spi_write_then_read(struct spi_device *spi,
const u8 *txbuf, unsigned n_tx,
u8 mode;
#define SPI_CPHA 0x01 /* clock phase */
#define SPI_CPOL 0x02 /* clock polarity */
-#define SPI_MODE_0 (0|0)
-#define SPI_MODE_1 (0|SPI_CPHA) /* (original MicroWire) */
+#define SPI_MODE_0 (0|0) /* (original MicroWire) */
+#define SPI_MODE_1 (0|SPI_CPHA)
#define SPI_MODE_2 (SPI_CPOL|0)
#define SPI_MODE_3 (SPI_CPOL|SPI_CPHA)
#define SPI_CS_HIGH 0x04 /* chipselect active high? */
void (*cleanup)(const struct spi_device *spi);
};
+static inline void *spi_master_get_devdata(struct spi_master *master)
+{
+ return class_get_devdata(&master->cdev);
+}
+
+static inline void spi_master_set_devdata(struct spi_master *master, void *data)
+{
+ class_set_devdata(&master->cdev, data);
+}
+
+static inline struct spi_master *spi_master_get(struct spi_master *master)
+{
+ if (!master || !class_device_get(&master->cdev))
+ return NULL;
+ return master;
+}
+
+static inline void spi_master_put(struct spi_master *master)
+{
+ if (master)
+ class_device_put(&master->cdev);
+}
+
+
/* the spi driver core manages memory for the spi_master classdev */
extern struct spi_master *
spi_alloc_master(struct device *host, unsigned size);
* stay selected until the next transfer. This is purely a performance
* hint; the controller driver may need to select a different device
* for the next message.
+ *
+ * The code that submits an spi_message (and its spi_transfers)
+ * to the lower layers is responsible for managing its memory.
+ * Zero-initialize every field you don't set up explicitly, to
+ * insulate against future API updates.
*/
struct spi_transfer {
/* it's ok if tx_buf == rx_buf (right?)
* for MicroWire, one buffer must be null
- * buffers must work with dma_*map_single() calls
+ * buffers must work with dma_*map_single() calls, unless
+ * spi_message.is_dma_mapped reports a pre-existing mapping
*/
const void *tx_buf;
void *rx_buf;
* @status: zero for success, else negative errno
* @queue: for use by whichever driver currently owns the message
* @state: for use by whichever driver currently owns the message
+ *
+ * The code that submits an spi_message (and its spi_transfers)
+ * to the lower layers is responsible for managing its memory.
+ * Zero-initialize every field you don't set up explicitly, to
+ * insulate against future API updates.
*/
struct spi_message {
struct spi_transfer *transfers;
void *state;
};
+/* It's fine to embed message and transaction structures in other data
+ * structures so long as you don't free them while they're in use.
+ */
+
+static inline struct spi_message *spi_message_alloc(unsigned ntrans, gfp_t flags)
+{
+ struct spi_message *m;
+
+ m = kzalloc(sizeof(struct spi_message)
+ + ntrans * sizeof(struct spi_transfer),
+ flags);
+ if (m) {
+ m->transfers = (void *)(m + 1);
+ m->n_transfer = ntrans;
+ }
+ return m;
+}
+
+static inline void spi_message_free(struct spi_message *m)
+{
+ kfree(m);
+}
+
/**
* spi_setup -- setup SPI mode and clock rate
* @spi: the device whose settings are being modified
* The completion callback is invoked in a context which can't sleep.
* Before that invocation, the value of message->status is undefined.
* When the callback is issued, message->status holds either zero (to
- * indicate complete success) or a negative error code.
+ * indicate complete success) or a negative error code. After that
+ * callback returns, the driver which issued the transfer request may
+ * deallocate the associated memory; it's no longer in use by any SPI
+ * core or controller driver code.
*
* Note that although all messages to a spi_device are handled in
* FIFO order, messages may go to different devices in other orders.
return spi_sync(spi, &m);
}
+/* this copies txbuf and rxbuf data; for small transfers only! */
extern int spi_write_then_read(struct spi_device *spi,
const u8 *txbuf, unsigned n_tx,
u8 *rxbuf, unsigned n_rx);
/* If you're hotplugging an adapter with devices (parport, usb, etc)
- * use spi_new_device() to describe each device. You would then call
- * spi_unregister_device() to start making that device vanish.
+ * use spi_new_device() to describe each device. You can also call
+ * spi_unregister_device() to start making that device vanish, but
+ * normally that would be handled by spi_unregister_master().
*/
extern struct spi_device *
spi_new_device(struct spi_master *, struct spi_board_info *);
projects / linux-2.6 / commitdiff