]> git.karo-electronics.de Git - mv-sheeva.git/blobdiff - drivers/ieee1394/nodemgr.c
Merge branch 'release' of git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6
[mv-sheeva.git] / drivers / ieee1394 / nodemgr.c
index c5ace190bfe6719d78b290276ea92997a76b6563..c4d3d4131f01728725496526687de8a55906bc20 100644 (file)
 #include <linux/kthread.h>
 #include <linux/module.h>
 #include <linux/moduleparam.h>
+#include <linux/mutex.h>
 #include <linux/freezer.h>
 #include <asm/atomic.h>
+#include <asm/semaphore.h>
 
 #include "csr.h"
 #include "highlevel.h"
@@ -115,7 +117,7 @@ static int nodemgr_bus_read(struct csr1212_csr *csr, u64 addr, u16 length,
 
 static int nodemgr_get_max_rom(quadlet_t *bus_info_data, void *__ci)
 {
-       return (CSR1212_BE32_TO_CPU(bus_info_data[2]) >> 8) & 0x3;
+       return (be32_to_cpu(bus_info_data[2]) >> 8) & 0x3;
 }
 
 static struct csr1212_bus_ops nodemgr_csr_ops = {
@@ -144,8 +146,6 @@ static struct csr1212_bus_ops nodemgr_csr_ops = {
  * but now we are much simpler because of the LDM.
  */
 
-static DEFINE_MUTEX(nodemgr_serialize);
-
 struct host_info {
        struct hpsb_host *host;
        struct list_head list;
@@ -153,7 +153,7 @@ struct host_info {
 };
 
 static int nodemgr_bus_match(struct device * dev, struct device_driver * drv);
-static int nodemgr_uevent(struct class_device *cdev, char **envp, int num_envp,
+static int nodemgr_uevent(struct device *dev, char **envp, int num_envp,
                          char *buffer, int buffer_size);
 static void nodemgr_resume_ne(struct node_entry *ne);
 static void nodemgr_remove_ne(struct node_entry *ne);
@@ -164,37 +164,38 @@ struct bus_type ieee1394_bus_type = {
        .match          = nodemgr_bus_match,
 };
 
-static void host_cls_release(struct class_device *class_dev)
+static void host_cls_release(struct device *dev)
 {
-       put_device(&container_of((class_dev), struct hpsb_host, class_dev)->device);
+       put_device(&container_of((dev), struct hpsb_host, host_dev)->device);
 }
 
 struct class hpsb_host_class = {
        .name           = "ieee1394_host",
-       .release        = host_cls_release,
+       .dev_release    = host_cls_release,
 };
 
-static void ne_cls_release(struct class_device *class_dev)
+static void ne_cls_release(struct device *dev)
 {
-       put_device(&container_of((class_dev), struct node_entry, class_dev)->device);
+       put_device(&container_of((dev), struct node_entry, node_dev)->device);
 }
 
 static struct class nodemgr_ne_class = {
        .name           = "ieee1394_node",
-       .release        = ne_cls_release,
+       .dev_release    = ne_cls_release,
 };
 
-static void ud_cls_release(struct class_device *class_dev)
+static void ud_cls_release(struct device *dev)
 {
-       put_device(&container_of((class_dev), struct unit_directory, class_dev)->device);
+       put_device(&container_of((dev), struct unit_directory, unit_dev)->device);
 }
 
 /* The name here is only so that unit directory hotplug works with old
- * style hotplug, which only ever did unit directories anyway. */
+ * style hotplug, which only ever did unit directories anyway.
+ */
 static struct class nodemgr_ud_class = {
        .name           = "ieee1394",
-       .release        = ud_cls_release,
-       .uevent         = nodemgr_uevent,
+       .dev_release    = ud_cls_release,
+       .dev_uevent     = nodemgr_uevent,
 };
 
 static struct hpsb_highlevel nodemgr_highlevel;
@@ -370,9 +371,7 @@ static ssize_t fw_set_ignore_driver(struct device *dev, struct device_attribute
 
        if (state == 1) {
                ud->ignore_driver = 1;
-               down_write(&ieee1394_bus_type.subsys.rwsem);
                device_release_driver(dev);
-               up_write(&ieee1394_bus_type.subsys.rwsem);
        } else if (state == 0)
                ud->ignore_driver = 0;
 
@@ -582,7 +581,7 @@ static void nodemgr_create_drv_files(struct hpsb_protocol_driver *driver)
                        goto fail;
        return;
 fail:
-       HPSB_ERR("Failed to add sysfs attribute for driver %s", driver->name);
+       HPSB_ERR("Failed to add sysfs attribute");
 }
 
 
@@ -606,8 +605,7 @@ static void nodemgr_create_ne_dev_files(struct node_entry *ne)
                        goto fail;
        return;
 fail:
-       HPSB_ERR("Failed to add sysfs attribute for node %016Lx",
-                (unsigned long long)ne->guid);
+       HPSB_ERR("Failed to add sysfs attribute");
 }
 
 
@@ -621,7 +619,7 @@ static void nodemgr_create_host_dev_files(struct hpsb_host *host)
                        goto fail;
        return;
 fail:
-       HPSB_ERR("Failed to add sysfs attribute for host %d", host->id);
+       HPSB_ERR("Failed to add sysfs attribute");
 }
 
 
@@ -681,8 +679,7 @@ static void nodemgr_create_ud_dev_files(struct unit_directory *ud)
        }
        return;
 fail:
-       HPSB_ERR("Failed to add sysfs attributes for unit %s",
-                ud->device.bus_id);
+       HPSB_ERR("Failed to add sysfs attribute");
 }
 
 
@@ -733,11 +730,11 @@ static DEFINE_MUTEX(nodemgr_serialize_remove_uds);
 
 static void nodemgr_remove_uds(struct node_entry *ne)
 {
-       struct class_device *cdev;
+       struct device *dev;
        struct unit_directory *tmp, *ud;
 
-       /* Iteration over nodemgr_ud_class.children has to be protected by
-        * nodemgr_ud_class.sem, but class_device_unregister() will eventually
+       /* Iteration over nodemgr_ud_class.devices has to be protected by
+        * nodemgr_ud_class.sem, but device_unregister() will eventually
         * take nodemgr_ud_class.sem too. Therefore pick out one ud at a time,
         * release the semaphore, and then unregister the ud. Since this code
         * may be called from other contexts besides the knodemgrds, protect the
@@ -747,9 +744,9 @@ static void nodemgr_remove_uds(struct node_entry *ne)
        for (;;) {
                ud = NULL;
                down(&nodemgr_ud_class.sem);
-               list_for_each_entry(cdev, &nodemgr_ud_class.children, node) {
-                       tmp = container_of(cdev, struct unit_directory,
-                                          class_dev);
+               list_for_each_entry(dev, &nodemgr_ud_class.devices, node) {
+                       tmp = container_of(dev, struct unit_directory,
+                                          unit_dev);
                        if (tmp->ne == ne) {
                                ud = tmp;
                                break;
@@ -758,7 +755,7 @@ static void nodemgr_remove_uds(struct node_entry *ne)
                up(&nodemgr_ud_class.sem);
                if (ud == NULL)
                        break;
-               class_device_unregister(&ud->class_dev);
+               device_unregister(&ud->unit_dev);
                device_unregister(&ud->device);
        }
        mutex_unlock(&nodemgr_serialize_remove_uds);
@@ -775,10 +772,9 @@ static void nodemgr_remove_ne(struct node_entry *ne)
 
        HPSB_DEBUG("Node removed: ID:BUS[" NODE_BUS_FMT "]  GUID[%016Lx]",
                   NODE_BUS_ARGS(ne->host, ne->nodeid), (unsigned long long)ne->guid);
-
        nodemgr_remove_uds(ne);
 
-       class_device_unregister(&ne->class_dev);
+       device_unregister(&ne->node_dev);
        device_unregister(dev);
 
        put_device(dev);
@@ -786,7 +782,9 @@ static void nodemgr_remove_ne(struct node_entry *ne)
 
 static int __nodemgr_remove_host_dev(struct device *dev, void *data)
 {
-       nodemgr_remove_ne(container_of(dev, struct node_entry, device));
+       if (dev->bus == &ieee1394_bus_type)
+               nodemgr_remove_ne(container_of(dev, struct node_entry,
+                                 device));
        return 0;
 }
 
@@ -853,14 +851,14 @@ static struct node_entry *nodemgr_create_node(octlet_t guid, struct csr1212_csr
        snprintf(ne->device.bus_id, BUS_ID_SIZE, "%016Lx",
                 (unsigned long long)(ne->guid));
 
-       ne->class_dev.dev = &ne->device;
-       ne->class_dev.class = &nodemgr_ne_class;
-       snprintf(ne->class_dev.class_id, BUS_ID_SIZE, "%016Lx",
-                (unsigned long long)(ne->guid));
+       ne->node_dev.parent = &ne->device;
+       ne->node_dev.class = &nodemgr_ne_class;
+       snprintf(ne->node_dev.bus_id, BUS_ID_SIZE, "%016Lx",
+               (unsigned long long)(ne->guid));
 
        if (device_register(&ne->device))
                goto fail_devreg;
-       if (class_device_register(&ne->class_dev))
+       if (device_register(&ne->node_dev))
                goto fail_classdevreg;
        get_device(&ne->device);
 
@@ -888,12 +886,12 @@ fail_alloc:
 
 static struct node_entry *find_entry_by_guid(u64 guid)
 {
-       struct class_device *cdev;
+       struct device *dev;
        struct node_entry *ne, *ret_ne = NULL;
 
        down(&nodemgr_ne_class.sem);
-       list_for_each_entry(cdev, &nodemgr_ne_class.children, node) {
-               ne = container_of(cdev, struct node_entry, class_dev);
+       list_for_each_entry(dev, &nodemgr_ne_class.devices, node) {
+               ne = container_of(dev, struct node_entry, node_dev);
 
                if (ne->guid == guid) {
                        ret_ne = ne;
@@ -909,12 +907,12 @@ static struct node_entry *find_entry_by_guid(u64 guid)
 static struct node_entry *find_entry_by_nodeid(struct hpsb_host *host,
                                               nodeid_t nodeid)
 {
-       struct class_device *cdev;
+       struct device *dev;
        struct node_entry *ne, *ret_ne = NULL;
 
        down(&nodemgr_ne_class.sem);
-       list_for_each_entry(cdev, &nodemgr_ne_class.children, node) {
-               ne = container_of(cdev, struct node_entry, class_dev);
+       list_for_each_entry(dev, &nodemgr_ne_class.devices, node) {
+               ne = container_of(dev, struct node_entry, node_dev);
 
                if (ne->host == host && ne->nodeid == nodeid) {
                        ret_ne = ne;
@@ -938,14 +936,14 @@ static void nodemgr_register_device(struct node_entry *ne,
        snprintf(ud->device.bus_id, BUS_ID_SIZE, "%s-%u",
                 ne->device.bus_id, ud->id);
 
-       ud->class_dev.dev = &ud->device;
-       ud->class_dev.class = &nodemgr_ud_class;
-       snprintf(ud->class_dev.class_id, BUS_ID_SIZE, "%s-%u",
+       ud->unit_dev.parent = &ud->device;
+       ud->unit_dev.class = &nodemgr_ud_class;
+       snprintf(ud->unit_dev.bus_id, BUS_ID_SIZE, "%s-%u",
                 ne->device.bus_id, ud->id);
 
        if (device_register(&ud->device))
                goto fail_devreg;
-       if (class_device_register(&ud->class_dev))
+       if (device_register(&ud->unit_dev))
                goto fail_classdevreg;
        get_device(&ud->device);
 
@@ -979,7 +977,8 @@ static struct unit_directory *nodemgr_process_unit_directory
 
        ud->ne = ne;
        ud->ignore_driver = ignore_drivers;
-       ud->address = ud_kv->offset + CSR1212_CONFIG_ROM_SPACE_BASE;
+       ud->address = ud_kv->offset + CSR1212_REGISTER_SPACE_BASE;
+       ud->directory_id = ud->address & 0xffffff;
        ud->ud_kv = ud_kv;
        ud->id = (*id)++;
 
@@ -1088,6 +1087,10 @@ static struct unit_directory *nodemgr_process_unit_directory
 
                        break;
 
+               case CSR1212_KV_ID_DIRECTORY_ID:
+                       ud->directory_id = kv->value.immediate;
+                       break;
+
                default:
                        break;
                }
@@ -1146,44 +1149,42 @@ static void nodemgr_process_root_directory(struct host_info *hi, struct node_ent
                last_key_id = kv->key.id;
        }
 
-       if (ne->vendor_name_kv &&
-           device_create_file(&ne->device, &dev_attr_ne_vendor_name_kv))
-               goto fail;
-       return;
-fail:
-       HPSB_ERR("Failed to add sysfs attribute for node %016Lx",
-                (unsigned long long)ne->guid);
+       if (ne->vendor_name_kv) {
+               int error = device_create_file(&ne->device,
+                                              &dev_attr_ne_vendor_name_kv);
+
+               if (error && error != -EEXIST)
+                       HPSB_ERR("Failed to add sysfs attribute");
+       }
 }
 
 #ifdef CONFIG_HOTPLUG
 
-static int nodemgr_uevent(struct class_device *cdev, char **envp, int num_envp,
+static int nodemgr_uevent(struct device *dev, char **envp, int num_envp,
                          char *buffer, int buffer_size)
 {
        struct unit_directory *ud;
        int i = 0;
        int length = 0;
+       int retval = 0;
        /* ieee1394:venNmoNspNverN */
        char buf[8 + 1 + 3 + 8 + 2 + 8 + 2 + 8 + 3 + 8 + 1];
 
-       if (!cdev)
+       if (!dev)
                return -ENODEV;
 
-       ud = container_of(cdev, struct unit_directory, class_dev);
+       ud = container_of(dev, struct unit_directory, unit_dev);
 
        if (ud->ne->in_limbo || ud->ignore_driver)
                return -ENODEV;
 
 #define PUT_ENVP(fmt,val)                                      \
 do {                                                           \
-       int printed;                                            \
-       envp[i++] = buffer;                                     \
-       printed = snprintf(buffer, buffer_size - length,        \
-                          fmt, val);                           \
-       if ((buffer_size - (length+printed) <= 0) || (i >= num_envp))   \
-               return -ENOMEM;                                 \
-       length += printed+1;                                    \
-       buffer += printed+1;                                    \
+       retval = add_uevent_var(envp, num_envp, &i,             \
+                               buffer, buffer_size, &length,   \
+                               fmt, val);                      \
+       if (retval)                                             \
+               return retval;                                  \
 } while (0)
 
        PUT_ENVP("VENDOR_ID=%06x", ud->vendor_id);
@@ -1207,7 +1208,7 @@ do {                                                              \
 
 #else
 
-static int nodemgr_uevent(struct class_device *cdev, char **envp, int num_envp,
+static int nodemgr_uevent(struct device *dev, char **envp, int num_envp,
                          char *buffer, int buffer_size)
 {
        return -ENODEV;
@@ -1378,8 +1379,10 @@ static void nodemgr_node_scan(struct host_info *hi, int generation)
 
 static void nodemgr_suspend_ne(struct node_entry *ne)
 {
-       struct class_device *cdev;
+       struct device *dev;
        struct unit_directory *ud;
+       struct device_driver *drv;
+       int error;
 
        HPSB_DEBUG("Node suspended: ID:BUS[" NODE_BUS_FMT "]  GUID[%016Lx]",
                   NODE_BUS_ARGS(ne->host, ne->nodeid), (unsigned long long)ne->guid);
@@ -1388,17 +1391,24 @@ static void nodemgr_suspend_ne(struct node_entry *ne)
        WARN_ON(device_create_file(&ne->device, &dev_attr_ne_in_limbo));
 
        down(&nodemgr_ud_class.sem);
-       list_for_each_entry(cdev, &nodemgr_ud_class.children, node) {
-               ud = container_of(cdev, struct unit_directory, class_dev);
+       list_for_each_entry(dev, &nodemgr_ud_class.devices, node) {
+               ud = container_of(dev, struct unit_directory, unit_dev);
                if (ud->ne != ne)
                        continue;
 
-               down_write(&ieee1394_bus_type.subsys.rwsem);
-               if (ud->device.driver &&
-                   (!ud->device.driver->suspend ||
-                     ud->device.driver->suspend(&ud->device, PMSG_SUSPEND)))
+               drv = get_driver(ud->device.driver);
+               if (!drv)
+                       continue;
+
+               error = 1; /* release if suspend is not implemented */
+               if (drv->suspend) {
+                       down(&ud->device.sem);
+                       error = drv->suspend(&ud->device, PMSG_SUSPEND);
+                       up(&ud->device.sem);
+               }
+               if (error)
                        device_release_driver(&ud->device);
-               up_write(&ieee1394_bus_type.subsys.rwsem);
+               put_driver(drv);
        }
        up(&nodemgr_ud_class.sem);
 }
@@ -1406,22 +1416,29 @@ static void nodemgr_suspend_ne(struct node_entry *ne)
 
 static void nodemgr_resume_ne(struct node_entry *ne)
 {
-       struct class_device *cdev;
+       struct device *dev;
        struct unit_directory *ud;
+       struct device_driver *drv;
 
        ne->in_limbo = 0;
        device_remove_file(&ne->device, &dev_attr_ne_in_limbo);
 
        down(&nodemgr_ud_class.sem);
-       list_for_each_entry(cdev, &nodemgr_ud_class.children, node) {
-               ud = container_of(cdev, struct unit_directory, class_dev);
+       list_for_each_entry(dev, &nodemgr_ud_class.devices, node) {
+               ud = container_of(dev, struct unit_directory, unit_dev);
                if (ud->ne != ne)
                        continue;
 
-               down_read(&ieee1394_bus_type.subsys.rwsem);
-               if (ud->device.driver && ud->device.driver->resume)
-                       ud->device.driver->resume(&ud->device);
-               up_read(&ieee1394_bus_type.subsys.rwsem);
+               drv = get_driver(ud->device.driver);
+               if (!drv)
+                       continue;
+
+               if (drv->resume) {
+                       down(&ud->device.sem);
+                       drv->resume(&ud->device);
+                       up(&ud->device.sem);
+               }
+               put_driver(drv);
        }
        up(&nodemgr_ud_class.sem);
 
@@ -1432,25 +1449,32 @@ static void nodemgr_resume_ne(struct node_entry *ne)
 
 static void nodemgr_update_pdrv(struct node_entry *ne)
 {
+       struct device *dev;
        struct unit_directory *ud;
+       struct device_driver *drv;
        struct hpsb_protocol_driver *pdrv;
-       struct class_device *cdev;
+       int error;
 
        down(&nodemgr_ud_class.sem);
-       list_for_each_entry(cdev, &nodemgr_ud_class.children, node) {
-               ud = container_of(cdev, struct unit_directory, class_dev);
+       list_for_each_entry(dev, &nodemgr_ud_class.devices, node) {
+               ud = container_of(dev, struct unit_directory, unit_dev);
                if (ud->ne != ne)
                        continue;
 
-               down_write(&ieee1394_bus_type.subsys.rwsem);
-               if (ud->device.driver) {
-                       pdrv = container_of(ud->device.driver,
-                                           struct hpsb_protocol_driver,
-                                           driver);
-                       if (pdrv->update && pdrv->update(ud))
-                               device_release_driver(&ud->device);
+               drv = get_driver(ud->device.driver);
+               if (!drv)
+                       continue;
+
+               error = 0;
+               pdrv = container_of(drv, struct hpsb_protocol_driver, driver);
+               if (pdrv->update) {
+                       down(&ud->device.sem);
+                       error = pdrv->update(ud);
+                       up(&ud->device.sem);
                }
-               up_write(&ieee1394_bus_type.subsys.rwsem);
+               if (error)
+                       device_release_driver(&ud->device);
+               put_driver(drv);
        }
        up(&nodemgr_ud_class.sem);
 }
@@ -1515,7 +1539,7 @@ static void nodemgr_probe_ne(struct host_info *hi, struct node_entry *ne, int ge
 static void nodemgr_node_probe(struct host_info *hi, int generation)
 {
        struct hpsb_host *host = hi->host;
-       struct class_device *cdev;
+       struct device *dev;
        struct node_entry *ne;
 
        /* Do some processing of the nodes we've probed. This pulls them
@@ -1528,13 +1552,13 @@ static void nodemgr_node_probe(struct host_info *hi, int generation)
         * improvement...) */
 
        down(&nodemgr_ne_class.sem);
-       list_for_each_entry(cdev, &nodemgr_ne_class.children, node) {
-               ne = container_of(cdev, struct node_entry, class_dev);
+       list_for_each_entry(dev, &nodemgr_ne_class.devices, node) {
+               ne = container_of(dev, struct node_entry, node_dev);
                if (!ne->needs_probe)
                        nodemgr_probe_ne(hi, ne, generation);
        }
-       list_for_each_entry(cdev, &nodemgr_ne_class.children, node) {
-               ne = container_of(cdev, struct node_entry, class_dev);
+       list_for_each_entry(dev, &nodemgr_ne_class.devices, node) {
+               ne = container_of(dev, struct node_entry, node_dev);
                if (ne->needs_probe)
                        nodemgr_probe_ne(hi, ne, generation);
        }
@@ -1692,18 +1716,12 @@ static int nodemgr_host_thread(void *__hi)
                if (kthread_should_stop())
                        goto exit;
 
-               if (mutex_lock_interruptible(&nodemgr_serialize)) {
-                       if (try_to_freeze())
-                               continue;
-                       goto exit;
-               }
-
                /* Pause for 1/4 second in 1/16 second intervals,
                 * to make sure things settle down. */
                g = get_hpsb_generation(host);
                for (i = 0; i < 4 ; i++) {
                        if (msleep_interruptible(63) || kthread_should_stop())
-                               goto unlock_exit;
+                               goto exit;
 
                        /* Now get the generation in which the node ID's we collect
                         * are valid.  During the bus scan we will use this generation
@@ -1713,7 +1731,7 @@ static int nodemgr_host_thread(void *__hi)
                        generation = get_hpsb_generation(host);
 
                        /* If we get a reset before we are done waiting, then
-                        * start the the waiting over again */
+                        * start the waiting over again */
                        if (generation != g)
                                g = generation, i = 0;
                }
@@ -1721,7 +1739,6 @@ static int nodemgr_host_thread(void *__hi)
                if (!nodemgr_check_irm_capability(host, reset_cycles) ||
                    !nodemgr_do_irm_duties(host, reset_cycles)) {
                        reset_cycles++;
-                       mutex_unlock(&nodemgr_serialize);
                        continue;
                }
                reset_cycles = 0;
@@ -1738,27 +1755,35 @@ static int nodemgr_host_thread(void *__hi)
 
                /* Update some of our sysfs symlinks */
                nodemgr_update_host_dev_links(host);
-
-               mutex_unlock(&nodemgr_serialize);
        }
-unlock_exit:
-       mutex_unlock(&nodemgr_serialize);
 exit:
        HPSB_VERBOSE("NodeMgr: Exiting thread");
        return 0;
 }
 
-int nodemgr_for_each_host(void *__data, int (*cb)(struct hpsb_host *, void *))
+/**
+ * nodemgr_for_each_host - call a function for each IEEE 1394 host
+ * @data: an address to supply to the callback
+ * @cb: function to call for each host
+ *
+ * Iterate the hosts, calling a given function with supplied data for each host.
+ * If the callback fails on a host, i.e. if it returns a non-zero value, the
+ * iteration is stopped.
+ *
+ * Return value: 0 on success, non-zero on failure (same as returned by last run
+ * of the callback).
+ */
+int nodemgr_for_each_host(void *data, int (*cb)(struct hpsb_host *, void *))
 {
-       struct class_device *cdev;
+       struct device *dev;
        struct hpsb_host *host;
        int error = 0;
 
        down(&hpsb_host_class.sem);
-       list_for_each_entry(cdev, &hpsb_host_class.children, node) {
-               host = container_of(cdev, struct hpsb_host, class_dev);
+       list_for_each_entry(dev, &hpsb_host_class.devices, node) {
+               host = container_of(dev, struct hpsb_host, host_dev);
 
-               if ((error = cb(host, __data)))
+               if ((error = cb(host, data)))
                        break;
        }
        up(&hpsb_host_class.sem);
@@ -1766,7 +1791,7 @@ int nodemgr_for_each_host(void *__data, int (*cb)(struct hpsb_host *, void *))
        return error;
 }
 
-/* The following four convenience functions use a struct node_entry
+/* The following two convenience functions use a struct node_entry
  * for addressing a node on the bus.  They are intended for use by any
  * process context, not just the nodemgr thread, so we need to be a
  * little careful when reading out the node ID and generation.  The
@@ -1781,12 +1806,20 @@ int nodemgr_for_each_host(void *__data, int (*cb)(struct hpsb_host *, void *))
  * ID's.
  */
 
-void hpsb_node_fill_packet(struct node_entry *ne, struct hpsb_packet *pkt)
+/**
+ * hpsb_node_fill_packet - fill some destination information into a packet
+ * @ne: destination node
+ * @packet: packet to fill in
+ *
+ * This will fill in the given, pre-initialised hpsb_packet with the current
+ * information from the node entry (host, node ID, bus generation number).
+ */
+void hpsb_node_fill_packet(struct node_entry *ne, struct hpsb_packet *packet)
 {
-       pkt->host = ne->host;
-       pkt->generation = ne->generation;
+       packet->host = ne->host;
+       packet->generation = ne->generation;
        barrier();
-       pkt->node_id = ne->nodeid;
+       packet->node_id = ne->nodeid;
 }
 
 int hpsb_node_write(struct node_entry *ne, u64 addr,