Note that in this RFC this patch is not complete, future versions
of this patch need to contain comments for all ism_ops.
Especially signal_event() and handle_event() need a good generic
description.
Signed-off-by: Alexandra Winter <wintera@xxxxxxxxxxxxx>
---
include/linux/ism.h | 115 ++++++++++++++++++++++++++++++++++++++++----
1 file changed, 105 insertions(+), 10 deletions(-)
diff --git a/include/linux/ism.h b/include/linux/ism.h
index 50975847248f..bc165d077071 100644
--- a/include/linux/ism.h
+++ b/include/linux/ism.h
@@ -13,11 +13,26 @@
#include <linux/workqueue.h>
#include <linux/uuid.h>
-/* The remote peer rgid can use dmb_tok to write into this buffer. */
+/*
+ * DMB - Direct Memory Buffer
+ * ==========================
+ * An ism client provides an DMB as input buffer for a local receiving
+ * ism device for exactly one (remote) sending ism device. Only this
+ * sending device can send data into this DMB using move_data(). Sender
+ * and receiver can be the same device.
+ * TODO: Alignment and length rules (CPU and DMA). Device specific?
+ */
struct ism_dmb {
+ /* dmb_tok - Token for this dmb
+ * Used by remote sender to address this dmb.
+ * Provided by ism fabric in register_dmb().
+ * Unique per ism fabric.
+ */
u64 dmb_tok;
+ /* rgid - GID of designated remote sending device */
u64 rgid;
u32 dmb_len;
+ /* sba_idx - Index of this DMB on this receiving device */
u32 sba_idx;
u32 vlan_valid;
u32 vlan_id;
@@ -25,6 +40,8 @@ struct ism_dmb {
dma_addr_t dma_addr;
};
+/* ISM event structure (currently device type specific) */
+// TODO: Define and describe generic event properties
struct ism_event {
u32 type;
u32 code;
@@ -33,38 +50,89 @@ struct ism_event {
u64 info;
};
+//TODO: use enum typedef
#define ISM_EVENT_DMB 0
#define ISM_EVENT_GID 1
#define ISM_EVENT_SWR 2
struct ism_dev;
+/*
+ * ISM clients
+ * ===========
+ * All ism clients have access to all ism devices
+ * and must provide the following functions to be called by
+ * ism device drivers:
+ */
struct ism_client {
+ /* client name for logging and debugging purposes */
const char *name;
+ /**
+ * add() - add an ism device
+ * @dev: device that was added
+ *
+ * Will be called during ism_register_client() for all existing
+ * ism devices and whenever a new ism device is registered.
+ * *dev is valid until ism_client->remove() is called.
+ */
void (*add)(struct ism_dev *dev);
+ /**
+ * remove() - remove an ism device
+ * @dev: device to be removed
+ *
+ * Will be called whenever an ism device is unregistered.
+ * Before this call the device is already inactive: It will
+ * no longer call client handlers.
+ * The client must not access *dev after this call.
+ */
void (*remove)(struct ism_dev *dev);
+ /**
+ * handle_event() - Handle control information sent by device
+ * @dev: device reporting the event
+ * @event: ism event structure
+ */
void (*handle_event)(struct ism_dev *dev, struct ism_event *event);
- /* Parameter dmbemask contains a bit vector with updated DMBEs, if sent
- * via ism_move_data(). Callback function must handle all active bits
- * indicated by dmbemask.
+ /**
+ * handle_irq() - Handle signalling of a DMB
+ * @dev: device owns the dmb
+ * @bit: sba_idx=idx of the ism_dmb that got signalled
+ * TODO: Pass a priv pointer to ism_dmb instead of 'bit'(?)
+ * @dmbemask: ism signalling mask of the dmb
+ *
+ * Handle signalling of a dmb that was registered by this client
+ * for this device.
+ * The ism device can coalesce multiple signalling triggers into a
+ * single call of handle_irq(). dmbemask can be used to indicate
+ * different kinds of triggers.
*/
void (*handle_irq)(struct ism_dev *dev, unsigned int bit, u16 dmbemask);
- /* Private area - don't touch! */
+ /* client index - provided by ism layer */
u8 id;
};
int ism_register_client(struct ism_client *client);
int ism_unregister_client(struct ism_client *client);
+//TODO: Pair descriptions with functions
+/*
+ * ISM devices
+ * ===========
+ */
/* Mandatory operations for all ism devices:
* int (*query_remote_gid)(struct ism_dev *dev, uuid_t *rgid,
* u32 vid_valid, u32 vid);
* Query whether remote GID rgid is reachable via this device and this
* vlan id. Vlan id is only checked if vid_valid != 0.
+ * Returns 0 if remote gid is reachable.
*
* int (*register_dmb)(struct ism_dev *dev, struct ism_dmb *dmb,
* void *client);
- * Register an ism_dmb buffer for this device and this client.
+ * Allocate and register an ism_dmb buffer for this device and this client.
+ * The following fields of ism_dmb must be valid:
+ * rgid, dmb_len, vlan_*; Optionally:requested sba_idx (non-zero)
+ * Upon return the following fields will be valid: dmb_tok, sba_idx
+ * cpu_addr, dma_addr (if applicable)
+ * Returns zero on success
*
* int (*unregister_dmb)(struct ism_dev *dev, struct ism_dmb *dmb);
* Unregister an ism_dmb buffer
@@ -81,10 +149,15 @@ int ism_unregister_client(struct ism_client *client);
* u16 (*get_chid)(struct ism_dev *dev);
* Returns ism fabric identifier (channel id) of this device.
* Only devices on the same ism fabric can communicate.
- * chid is unique per HW system, except for 0xFFFF, which denotes
- * an ism_loopback device that can only communicate with itself.
- * Use chid for fast negative checks, but only query_remote_gid()
- * can give a reliable positive answer.
+ * chid is unique per HW system. Use chid for fast negative checks,
+ * but only query_remote_gid() can give a reliable positive answer:
+ * Different chid: ism is not possible
+ * Same chid: ism traffic may be possible or not
+ * (e.g. different HW systems)
+ * EXCEPTION: A value of 0xFFFF denotes an ism_loopback device
+ * that can only communicate with itself. Use GID or
+ * query_remote_gid()to determine whether sender and
+ * receiver use the same ism_loopback device.
*
* struct device* (*get_dev)(struct ism_dev *dev);
*
@@ -109,6 +182,28 @@ struct ism_ops {
int (*register_dmb)(struct ism_dev *dev, struct ism_dmb *dmb,
struct ism_client *client);
int (*unregister_dmb)(struct ism_dev *dev, struct ism_dmb *dmb);
+ /**
+ * move_data() - write into a remote dmb
+ * @dev: Local sending ism device
+ * @dmb_tok: Token of the remote dmb
+ * @idx: signalling index
+ * @sf: signalling flag;
+ * if true, idx will be turned on at target ism interrupt mask
+ * and target device will be signalled, if required.
+ * @offset: offset within target dmb
+ * @data: pointer to data to be sent
+ * @size: length of data to be sent
+ *
+ * Use dev to write data of size at offset into a remote dmb
+ * identified by dmb_tok. Data is moved synchronously, *data can
+ * be freed when this function returns.
+ *
+ * If signalling flag (sf) is true, bit number idx bit will be
+ * turned on in the ism signalling mask, that belongs to the
+ * target dmb, and handle_irq() of the ism client that owns this
+ * dmb will be called, if required. The target device may chose to
+ * coalesce multiple signalling triggers.
+ */
int (*move_data)(struct ism_dev *dev, u64 dmb_tok, unsigned int idx,
bool sf, unsigned int offset, void *data,
unsigned int size);
--
2.45.2
