pcmcia: add new CIS access helpers
Dominik Brodowski [Sun, 18 Oct 2009 21:32:33 +0000 (23:32 +0200)]
As a replacement to pcmcia_get_{first,next}_tuple() and
pcmcia_get_tuple_data(), three new -- and easier to use --
functions are added:

- pcmcia_get_tuple() to get the very first CIS entry of one
  type.

- pcmcia_loop_tuple() to loop over all CIS entries of one type.

- pcmcia_get_mac_from_cis() to read out the hardware MAC address
  from CISTPL_FUNCE.

Only a handful of drivers need these functions anyway, as most
CIS access is already handled by pcmcia_loop_config(), which
now shares the same backed (pccard_loop_tuple()) with
pcmcia_loop_tuple().

A pcmcia_get_mac_from_cis() bug noted by Komuro
<komurojun-mbn@nifty.com> has been fixed in this revision.

Signed-off-by: Dominik Brodowski <linux@dominikbrodowski.net>

Documentation/pcmcia/driver-changes.txt
drivers/pcmcia/cistpl.c
drivers/pcmcia/cs_internal.h
drivers/pcmcia/pcmcia_resource.c
drivers/pcmcia/rsrc_mgr.c
include/pcmcia/ds.h

index 0599343..adfb83e 100644 (file)
@@ -1,5 +1,12 @@
 This file details changes in 2.6 which affect PCMCIA card driver authors:
 
+* New CIS tuple access (as of 2.6.33)
+   Instead of pcmcia_get_{first,next}_tuple(), pcmcia_get_tuple_data() and
+   pcmcia_parse_tuple(), a driver shall use "pcmcia_get_tuple()" if it is
+   only interested in one (raw) tuple, or "pcmcia_loop_tuple()" if it is
+   interested in all tuples of one type. To decode the MAC from CISTPL_FUNCE,
+   a new helper "pcmcia_get_mac_from_cis()" was added.
+
 * New configuration loop helper (as of 2.6.28)
    By calling pcmcia_loop_config(), a driver can iterate over all available
    configuration options. During a driver's probe() phase, one doesn't need
index 6c4a4fc..24dd3c1 100644 (file)
@@ -1482,6 +1482,67 @@ done:
 }
 EXPORT_SYMBOL(pccard_read_tuple);
 
+
+/**
+ * pccard_loop_tuple() - loop over tuples in the CIS
+ * @s:         the struct pcmcia_socket where the card is inserted
+ * @function:  the device function we loop for
+ * @code:      which CIS code shall we look for?
+ * @parse:     buffer where the tuple shall be parsed (or NULL, if no parse)
+ * @priv_data: private data to be passed to the loop_tuple function.
+ * @loop_tuple:        function to call for each CIS entry of type @function. IT
+ *             gets passed the raw tuple, the paresed tuple (if @parse is
+ *             set) and @priv_data.
+ *
+ * pccard_loop_tuple() loops over all CIS entries of type @function, and
+ * calls the @loop_tuple function for each entry. If the call to @loop_tuple
+ * returns 0, the loop exits. Returns 0 on success or errorcode otherwise.
+ */
+int pccard_loop_tuple(struct pcmcia_socket *s, unsigned int function,
+                     cisdata_t code, cisparse_t *parse, void *priv_data,
+                     int (*loop_tuple) (tuple_t *tuple,
+                                        cisparse_t *parse,
+                                        void *priv_data))
+{
+       tuple_t tuple;
+       cisdata_t *buf;
+       int ret;
+
+       buf = kzalloc(256, GFP_KERNEL);
+       if (buf == NULL) {
+               dev_printk(KERN_WARNING, &s->dev, "no memory to read tuple\n");
+               return -ENOMEM;
+       }
+
+       tuple.TupleData = buf;
+       tuple.TupleDataMax = 255;
+       tuple.TupleOffset = 0;
+       tuple.DesiredTuple = code;
+       tuple.Attributes = 0;
+
+       ret = pccard_get_first_tuple(s, function, &tuple);
+       while (!ret) {
+               if (pccard_get_tuple_data(s, &tuple))
+                       goto next_entry;
+
+               if (parse)
+                       if (pcmcia_parse_tuple(&tuple, parse))
+                               goto next_entry;
+
+               ret = loop_tuple(&tuple, parse, priv_data);
+               if (!ret)
+                       break;
+
+next_entry:
+               ret = pccard_get_next_tuple(s, function, &tuple);
+       }
+
+       kfree(buf);
+       return ret;
+}
+EXPORT_SYMBOL(pccard_loop_tuple);
+
+
 /*======================================================================
 
     This tries to determine if a card has a sensible CIS.  It returns
index 1f4098f..06a14c9 100644 (file)
@@ -199,6 +199,13 @@ int pcmcia_replace_cis(struct pcmcia_socket *s,
                       const u8 *data, const size_t len);
 int pccard_validate_cis(struct pcmcia_socket *s, unsigned int *count);
 
+/* loop over CIS entries */
+int pccard_loop_tuple(struct pcmcia_socket *s, unsigned int function,
+                     cisdata_t code, cisparse_t *parse, void *priv_data,
+                     int (*loop_tuple) (tuple_t *tuple,
+                                        cisparse_t *parse,
+                                        void *priv_data));
+
 /* rsrc_mgr.c */
 int pcmcia_validate_mem(struct pcmcia_socket *s);
 struct resource *pcmcia_find_io_region(unsigned long base,
index d919e96..0bfb05a 100644 (file)
@@ -20,6 +20,7 @@
 #include <linux/delay.h>
 #include <linux/pci.h>
 #include <linux/device.h>
+#include <linux/netdevice.h>
 
 #include <pcmcia/cs_types.h>
 #include <pcmcia/ss.h>
@@ -885,13 +886,40 @@ EXPORT_SYMBOL(pcmcia_disable_device);
 
 
 struct pcmcia_cfg_mem {
-       tuple_t tuple;
+       struct pcmcia_device *p_dev;
+       void *priv_data;
+       int (*conf_check) (struct pcmcia_device *p_dev,
+                          cistpl_cftable_entry_t *cfg,
+                          cistpl_cftable_entry_t *dflt,
+                          unsigned int vcc,
+                          void *priv_data);
        cisparse_t parse;
-       u8 buf[256];
        cistpl_cftable_entry_t dflt;
 };
 
 /**
+ * pcmcia_do_loop_config() - internal helper for pcmcia_loop_config()
+ *
+ * pcmcia_do_loop_config() is the internal callback for the call from
+ * pcmcia_loop_config() to pccard_loop_tuple(). Data is transferred
+ * by a struct pcmcia_cfg_mem.
+ */
+static int pcmcia_do_loop_config(tuple_t *tuple, cisparse_t *parse, void *priv)
+{
+       cistpl_cftable_entry_t *cfg = &parse->cftable_entry;
+       struct pcmcia_cfg_mem *cfg_mem = priv;
+
+       /* default values */
+       cfg_mem->p_dev->conf.ConfigIndex = cfg->index;
+       if (cfg->flags & CISTPL_CFTABLE_DEFAULT)
+               cfg_mem->dflt = *cfg;
+
+       return cfg_mem->conf_check(cfg_mem->p_dev, cfg, &cfg_mem->dflt,
+                                  cfg_mem->p_dev->socket->socket.Vcc,
+                                  cfg_mem->priv_data);
+}
+
+/**
  * pcmcia_loop_config() - loop over configuration options
  * @p_dev:     the struct pcmcia_device which we need to loop for.
  * @conf_check:        function to call for each configuration option.
@@ -913,48 +941,173 @@ int pcmcia_loop_config(struct pcmcia_device *p_dev,
                       void *priv_data)
 {
        struct pcmcia_cfg_mem *cfg_mem;
-
-       tuple_t *tuple;
        int ret;
-       unsigned int vcc;
 
        cfg_mem = kzalloc(sizeof(struct pcmcia_cfg_mem), GFP_KERNEL);
        if (cfg_mem == NULL)
                return -ENOMEM;
 
-       /* get the current Vcc setting */
-       vcc = p_dev->socket->socket.Vcc;
+       cfg_mem->p_dev = p_dev;
+       cfg_mem->conf_check = conf_check;
+       cfg_mem->priv_data = priv_data;
 
-       tuple = &cfg_mem->tuple;
-       tuple->TupleData = cfg_mem->buf;
-       tuple->TupleDataMax = 255;
-       tuple->TupleOffset = 0;
-       tuple->DesiredTuple = CISTPL_CFTABLE_ENTRY;
-       tuple->Attributes = 0;
+       ret = pccard_loop_tuple(p_dev->socket, p_dev->func,
+                               CISTPL_CFTABLE_ENTRY, &cfg_mem->parse,
+                               cfg_mem, pcmcia_do_loop_config);
 
-       ret = pcmcia_get_first_tuple(p_dev, tuple);
-       while (!ret) {
-               cistpl_cftable_entry_t *cfg = &cfg_mem->parse.cftable_entry;
+       kfree(cfg_mem);
+       return ret;
+}
+EXPORT_SYMBOL(pcmcia_loop_config);
 
-               if (pcmcia_get_tuple_data(p_dev, tuple))
-                       goto next_entry;
 
-               if (pcmcia_parse_tuple(tuple, &cfg_mem->parse))
-                       goto next_entry;
+struct pcmcia_loop_mem {
+       struct pcmcia_device *p_dev;
+       void *priv_data;
+       int (*loop_tuple) (struct pcmcia_device *p_dev,
+                          tuple_t *tuple,
+                          void *priv_data);
+};
 
-               /* default values */
-               p_dev->conf.ConfigIndex = cfg->index;
-               if (cfg->flags & CISTPL_CFTABLE_DEFAULT)
-                       cfg_mem->dflt = *cfg;
+/**
+ * pcmcia_do_loop_tuple() - internal helper for pcmcia_loop_config()
+ *
+ * pcmcia_do_loop_tuple() is the internal callback for the call from
+ * pcmcia_loop_tuple() to pccard_loop_tuple(). Data is transferred
+ * by a struct pcmcia_cfg_mem.
+ */
+static int pcmcia_do_loop_tuple(tuple_t *tuple, cisparse_t *parse, void *priv)
+{
+       struct pcmcia_loop_mem *loop = priv;
 
-               ret = conf_check(p_dev, cfg, &cfg_mem->dflt, vcc, priv_data);
-               if (!ret)
-                       break;
+       return loop->loop_tuple(loop->p_dev, tuple, loop->priv_data);
+};
+
+/**
+ * pcmcia_loop_tuple() - loop over tuples in the CIS
+ * @p_dev:     the struct pcmcia_device which we need to loop for.
+ * @code:      which CIS code shall we look for?
+ * @priv_data: private data to be passed to the loop_tuple function.
+ * @loop_tuple:        function to call for each CIS entry of type @function. IT
+ *             gets passed the raw tuple and @priv_data.
+ *
+ * pcmcia_loop_tuple() loops over all CIS entries of type @function, and
+ * calls the @loop_tuple function for each entry. If the call to @loop_tuple
+ * returns 0, the loop exits. Returns 0 on success or errorcode otherwise.
+ */
+int pcmcia_loop_tuple(struct pcmcia_device *p_dev, cisdata_t code,
+                     int (*loop_tuple) (struct pcmcia_device *p_dev,
+                                        tuple_t *tuple,
+                                        void *priv_data),
+                     void *priv_data)
+{
+       struct pcmcia_loop_mem loop = {
+               .p_dev = p_dev,
+               .loop_tuple = loop_tuple,
+               .priv_data = priv_data};
+
+       return pccard_loop_tuple(p_dev->socket, p_dev->func, code, NULL,
+                                &loop, pcmcia_do_loop_tuple);
+};
+EXPORT_SYMBOL(pcmcia_loop_tuple);
 
-next_entry:
-               ret = pcmcia_get_next_tuple(p_dev, tuple);
+
+struct pcmcia_loop_get {
+       size_t len;
+       cisdata_t **buf;
+};
+
+/**
+ * pcmcia_do_get_tuple() - internal helper for pcmcia_get_tuple()
+ *
+ * pcmcia_do_get_tuple() is the internal callback for the call from
+ * pcmcia_get_tuple() to pcmcia_loop_tuple(). As we're only interested in
+ * the first tuple, return 0 unconditionally. Create a memory buffer large
+ * enough to hold the content of the tuple, and fill it with the tuple data.
+ * The caller is responsible to free the buffer.
+ */
+static int pcmcia_do_get_tuple(struct pcmcia_device *p_dev, tuple_t *tuple,
+                              void *priv)
+{
+       struct pcmcia_loop_get *get = priv;
+
+       *get->buf = kzalloc(tuple->TupleDataLen, GFP_KERNEL);
+       if (*get->buf) {
+               get->len = tuple->TupleDataLen;
+               memcpy(*get->buf, tuple->TupleData, tuple->TupleDataLen);
        }
+       return 0;
+};
+
+/**
+ * pcmcia_get_tuple() - get first tuple from CIS
+ * @p_dev:     the struct pcmcia_device which we need to loop for.
+ * @code:      which CIS code shall we look for?
+ * @buf:        pointer to store the buffer to.
+ *
+ * pcmcia_get_tuple() gets the content of the first CIS entry of type @code.
+ * It returns the buffer length (or zero). The caller is responsible to free
+ * the buffer passed in @buf.
+ */
+size_t pcmcia_get_tuple(struct pcmcia_device *p_dev, cisdata_t code,
+                       unsigned char **buf)
+{
+       struct pcmcia_loop_get get = {
+               .len = 0,
+               .buf = buf,
+       };
+
+       *get.buf = NULL;
+       pcmcia_loop_tuple(p_dev, code, pcmcia_do_get_tuple, &get);
+
+       return get.len;
+};
+EXPORT_SYMBOL(pcmcia_get_tuple);
+
+
+/**
+ * pcmcia_do_get_mac() - internal helper for pcmcia_get_mac_from_cis()
+ *
+ * pcmcia_do_get_mac() is the internal callback for the call from
+ * pcmcia_get_mac_from_cis() to pcmcia_loop_tuple(). We check whether the
+ * tuple contains a proper LAN_NODE_ID of length 6, and copy the data
+ * to struct net_device->dev_addr[i].
+ */
+static int pcmcia_do_get_mac(struct pcmcia_device *p_dev, tuple_t *tuple,
+                            void *priv)
+{
+       struct net_device *dev = priv;
+       int i;
+
+       if (tuple->TupleData[0] != CISTPL_FUNCE_LAN_NODE_ID)
+               return -EINVAL;
+       if (tuple->TupleDataLen < ETH_ALEN + 2) {
+               dev_warn(&p_dev->dev, "Invalid CIS tuple length for "
+                       "LAN_NODE_ID\n");
+               return -EINVAL;
+       }
+
+       if (tuple->TupleData[1] != ETH_ALEN) {
+               dev_warn(&p_dev->dev, "Invalid header for LAN_NODE_ID\n");
+               return -EINVAL;
+       }
+       for (i = 0; i < 6; i++)
+               dev->dev_addr[i] = tuple->TupleData[i+2];
+       return 0;
+};
+
+/**
+ * pcmcia_get_mac_from_cis() - read out MAC address from CISTPL_FUNCE
+ * @p_dev:     the struct pcmcia_device for which we want the address.
+ * @dev:       a properly prepared struct net_device to store the info to.
+ *
+ * pcmcia_get_mac_from_cis() reads out the hardware MAC address from
+ * CISTPL_FUNCE and stores it into struct net_device *dev->dev_addr which
+ * must be set up properly by the driver (see examples!).
+ */
+int pcmcia_get_mac_from_cis(struct pcmcia_device *p_dev, struct net_device *dev)
+{
+       return pcmcia_loop_tuple(p_dev, CISTPL_FUNCE, pcmcia_do_get_mac, dev);
+};
+EXPORT_SYMBOL(pcmcia_get_mac_from_cis);
 
-       return ret;
-}
-EXPORT_SYMBOL(pcmcia_loop_config);
index e592e0e..de0e770 100644 (file)
@@ -18,6 +18,7 @@
 #include <pcmcia/cs_types.h>
 #include <pcmcia/ss.h>
 #include <pcmcia/cs.h>
+#include <pcmcia/cistpl.h>
 #include "cs_internal.h"
 
 
index a2be80b..2eb6e24 100644 (file)
@@ -34,6 +34,7 @@
 struct pcmcia_socket;
 struct pcmcia_device;
 struct config_t;
+struct net_device;
 
 /* dynamic device IDs for PCMCIA device drivers. See
  * Documentation/pcmcia/driver.txt for details.
@@ -176,26 +177,39 @@ const char *pcmcia_error_ret(int ret);
                           pcmcia_error_ret(ret));      \
        }
 
-/* CIS access.
- * Use the pcmcia_* versions in PCMCIA drivers
+
+/*
+ * CIS access.
+ *
+ * Please use the following functions to access CIS tuples:
+ * - pcmcia_get_tuple()
+ * - pcmcia_loop_tuple()
+ * - pcmcia_get_mac_from_cis()
+ *
+ * To parse a tuple_t, pcmcia_parse_tuple() exists. Its interface
+ * might change in future.
  */
-int pcmcia_parse_tuple(tuple_t *tuple, cisparse_t *parse);
 
-int pccard_get_first_tuple(struct pcmcia_socket *s, unsigned int function,
-                          tuple_t *tuple);
-#define pcmcia_get_first_tuple(p_dev, tuple) \
-               pccard_get_first_tuple(p_dev->socket, p_dev->func, tuple)
+/* get the very first CIS entry of type @code. Note that buf is pointer
+ * to u8 *buf; and that you need to kfree(buf) afterwards. */
+size_t pcmcia_get_tuple(struct pcmcia_device *p_dev, cisdata_t code,
+                       u8 **buf);
 
-int pccard_get_next_tuple(struct pcmcia_socket *s, unsigned int function,
-                         tuple_t *tuple);
-#define pcmcia_get_next_tuple(p_dev, tuple) \
-               pccard_get_next_tuple(p_dev->socket, p_dev->func, tuple)
+/* loop over CIS entries */
+int pcmcia_loop_tuple(struct pcmcia_device *p_dev, cisdata_t code,
+                     int (*loop_tuple) (struct pcmcia_device *p_dev,
+                                        tuple_t *tuple,
+                                        void *priv_data),
+                     void *priv_data);
 
-int pccard_get_tuple_data(struct pcmcia_socket *s, tuple_t *tuple);
-#define pcmcia_get_tuple_data(p_dev, tuple) \
-               pccard_get_tuple_data(p_dev->socket, tuple)
+/* get the MAC address from CISTPL_FUNCE */
+int pcmcia_get_mac_from_cis(struct pcmcia_device *p_dev,
+                           struct net_device *dev);
 
 
+/* parse a tuple_t */
+int pcmcia_parse_tuple(tuple_t *tuple, cisparse_t *parse);
+
 /* loop CIS entries for valid configuration */
 int pcmcia_loop_config(struct pcmcia_device *p_dev,
                       int      (*conf_check)   (struct pcmcia_device *p_dev,
@@ -215,6 +229,21 @@ int pcmcia_reset_card(struct pcmcia_socket *skt);
 int pcmcia_access_configuration_register(struct pcmcia_device *p_dev,
                                         conf_reg_t *reg);
 
+/* deprecated -- do not use in drivers. */
+int pccard_get_first_tuple(struct pcmcia_socket *s, unsigned int function,
+                       tuple_t *tuple);
+#define pcmcia_get_first_tuple(p_dev, tuple) \
+       pccard_get_first_tuple(p_dev->socket, p_dev->func, tuple)
+
+int pccard_get_next_tuple(struct pcmcia_socket *s, unsigned int function,
+                       tuple_t *tuple);
+#define pcmcia_get_next_tuple(p_dev, tuple) \
+       pccard_get_next_tuple(p_dev->socket, p_dev->func, tuple)
+
+int pccard_get_tuple_data(struct pcmcia_socket *s, tuple_t *tuple);
+#define pcmcia_get_tuple_data(p_dev, tuple) \
+       pccard_get_tuple_data(p_dev->socket, tuple)
+
 /* device configuration */
 int pcmcia_request_io(struct pcmcia_device *p_dev, io_req_t *req);
 int pcmcia_request_irq(struct pcmcia_device *p_dev, irq_req_t *req);