| /* SPDX-License-Identifier: GPL-2.0 */ |
| /* |
| * Direct Internal Buffer Sharing |
| * |
| * Definitions for the DIBS module |
| * |
| * Copyright IBM Corp. 2025 |
| */ |
| #ifndef _DIBS_H |
| #define _DIBS_H |
| |
| #include <linux/device.h> |
| #include <linux/uuid.h> |
| |
| /* DIBS - Direct Internal Buffer Sharing - concept |
| * ----------------------------------------------- |
| * In the case of multiple system sharing the same hardware, dibs fabrics can |
| * provide dibs devices to these systems. The systems use dibs devices of the |
| * same fabric to communicate via dmbs (Direct Memory Buffers). Each dmb has |
| * exactly one owning local dibs device and one remote using dibs device, that |
| * is authorized to write into this dmb. This access control is provided by the |
| * dibs fabric. |
| * |
| * Because the access to the dmb is based on access to physical memory, it is |
| * lossless and synchronous. The remote devices can directly access any offset |
| * of the dmb. |
| * |
| * Dibs fabrics, dibs devices and dmbs are identified by tokens and ids. |
| * Dibs fabric id is unique within the same hardware (with the exception of the |
| * dibs loopback fabric), dmb token is unique within the same fabric, dibs |
| * device gids are guaranteed to be unique within the same fabric and |
| * statistically likely to be globally unique. The exchange of these tokens and |
| * ids between the systems is not part of the dibs concept. |
| * |
| * The dibs layer provides an abstraction between dibs device drivers and dibs |
| * clients. |
| */ |
| |
| /* DMB - Direct Memory Buffer |
| * -------------------------- |
| * A dibs client provides a dmb as input buffer for a local receiving |
| * dibs device for exactly one (remote) sending dibs device. Only this |
| * sending device can send data into this dmb using move_data(). Sender |
| * and receiver can be the same device. A dmb belongs to exactly one client. |
| */ |
| struct dibs_dmb { |
| /* tok - Token for this dmb |
| * Used by remote and local devices and clients to address this dmb. |
| * Provided by dibs fabric. Unique per dibs fabric. |
| */ |
| u64 dmb_tok; |
| /* rgid - GID of designated remote sending device */ |
| uuid_t rgid; |
| /* cpu_addr - buffer address */ |
| void *cpu_addr; |
| /* len - buffer length */ |
| u32 dmb_len; |
| /* idx - Index of this DMB on this receiving device */ |
| u32 idx; |
| /* VLAN support (deprecated) |
| * In order to write into a vlan-tagged dmb, the remote device needs |
| * to belong to the this vlan |
| */ |
| u32 vlan_valid; |
| u32 vlan_id; |
| /* optional, used by device driver */ |
| dma_addr_t dma_addr; |
| }; |
| |
| /* DIBS events |
| * ----------- |
| * Dibs devices can optionally notify dibs clients about events that happened |
| * in the fabric or at the remote device or remote dmb. |
| */ |
| enum dibs_event_type { |
| /* Buffer event, e.g. a remote dmb was unregistered */ |
| DIBS_BUF_EVENT, |
| /* Device event, e.g. a remote dibs device was disabled */ |
| DIBS_DEV_EVENT, |
| /* Software event, a dibs client can send an event signal to a |
| * remote dibs device. |
| */ |
| DIBS_SW_EVENT, |
| DIBS_OTHER_TYPE }; |
| |
| enum dibs_event_subtype { |
| DIBS_BUF_UNREGISTERED, |
| DIBS_DEV_DISABLED, |
| DIBS_DEV_ERR_STATE, |
| DIBS_OTHER_SUBTYPE |
| }; |
| |
| struct dibs_event { |
| u32 type; |
| u32 subtype; |
| /* uuid_null if invalid */ |
| uuid_t gid; |
| /* zero if invalid */ |
| u64 buffer_tok; |
| u64 time; |
| /* additional data or zero */ |
| u64 data; |
| }; |
| |
| struct dibs_dev; |
| |
| /* DIBS client |
| * ----------- |
| */ |
| #define MAX_DIBS_CLIENTS 8 |
| #define NO_DIBS_CLIENT 0xff |
| /* All dibs clients have access to all dibs devices. |
| * A dibs client provides the following functions to be called by dibs layer or |
| * dibs device drivers: |
| */ |
| struct dibs_client_ops { |
| /** |
| * add_dev() - add a dibs device |
| * @dev: device that was added |
| * |
| * Will be called during dibs_register_client() for all existing |
| * dibs devices and whenever a new dibs device is registered. |
| * dev is usable until dibs_client.remove() is called. |
| * *dev is protected by device refcounting. |
| */ |
| void (*add_dev)(struct dibs_dev *dev); |
| /** |
| * del_dev() - remove a dibs device |
| * @dev: device to be removed |
| * |
| * Will be called whenever a dibs device is removed. |
| * Will be called during dibs_unregister_client() for all existing |
| * dibs devices and whenever a dibs device is unregistered. |
| * The device has already stopped initiative for this client: |
| * No new handlers will be started. |
| * The device is no longer usable by this client after this call. |
| */ |
| void (*del_dev)(struct dibs_dev *dev); |
| /** |
| * handle_irq() - Handle signaling for a DMB |
| * @dev: device that owns the dmb |
| * @idx: Index of the dmb that got signalled |
| * @dmbemask: signaling mask of the dmb |
| * |
| * Handle signaling for a dmb that was registered by this client |
| * for this device. |
| * The dibs device can coalesce multiple signaling triggers into a |
| * single call of handle_irq(). dmbemask can be used to indicate |
| * different kinds of triggers. |
| * |
| * Context: Called in IRQ context by dibs device driver |
| */ |
| void (*handle_irq)(struct dibs_dev *dev, unsigned int idx, |
| u16 dmbemask); |
| /** |
| * handle_event() - Handle control information sent by device |
| * @dev: device reporting the event |
| * @event: ism event structure |
| * |
| * * Context: Called in IRQ context by dibs device driver |
| */ |
| void (*handle_event)(struct dibs_dev *dev, |
| const struct dibs_event *event); |
| }; |
| |
| struct dibs_client { |
| /* client name for logging and debugging purposes */ |
| const char *name; |
| const struct dibs_client_ops *ops; |
| /* client index - provided and used by dibs layer */ |
| u8 id; |
| }; |
| |
| /* Functions to be called by dibs clients: |
| */ |
| /** |
| * dibs_register_client() - register a client with dibs layer |
| * @client: this client |
| * |
| * Will call client->ops->add_dev() for all existing dibs devices. |
| * Return: zero on success. |
| */ |
| int dibs_register_client(struct dibs_client *client); |
| /** |
| * dibs_unregister_client() - unregister a client with dibs layer |
| * @client: this client |
| * |
| * Will call client->ops->del_dev() for all existing dibs devices. |
| * Return: zero on success. |
| */ |
| int dibs_unregister_client(struct dibs_client *client); |
| |
| /* dibs clients can call dibs device ops. */ |
| |
| /* DIBS devices |
| * ------------ |
| */ |
| |
| /* Defined fabric id / CHID for all loopback devices: |
| * All dibs loopback devices report this fabric id. In this case devices with |
| * the same fabric id can NOT communicate via dibs. Only loopback devices with |
| * the same dibs device gid can communicate (=same device with itself). |
| */ |
| #define DIBS_LOOPBACK_FABRIC 0xFFFF |
| |
| /* A dibs device provides the following functions to be called by dibs clients. |
| * They are mandatory, unless marked 'optional'. |
| */ |
| struct dibs_dev_ops { |
| /** |
| * get_fabric_id() |
| * @dev: local dibs device |
| * |
| * Only devices on the same dibs fabric can communicate. Fabric_id is |
| * unique inside the same HW system. Use fabric_id for fast negative |
| * checks, but only query_remote_gid() can give a reliable positive |
| * answer: |
| * Different fabric_id: dibs is not possible |
| * Same fabric_id: dibs may be possible or not |
| * (e.g. different HW systems) |
| * EXCEPTION: DIBS_LOOPBACK_FABRIC denotes an ism_loopback device |
| * that can only communicate with itself. Use dibs_dev.gid |
| * or query_remote_gid()to determine whether sender and |
| * receiver use the same ism_loopback device. |
| * Return: 2 byte dibs fabric id |
| */ |
| u16 (*get_fabric_id)(struct dibs_dev *dev); |
| /** |
| * query_remote_gid() |
| * @dev: local dibs device |
| * @rgid: gid of remote dibs device |
| * @vid_valid: if zero, vid will be ignored; |
| * deprecated, ignored if device does not support vlan |
| * @vid: VLAN id; deprecated, ignored if device does not support vlan |
| * |
| * Query whether a remote dibs device is reachable via this local device |
| * and this vlan id. |
| * Return: 0 if remote gid is reachable. |
| */ |
| int (*query_remote_gid)(struct dibs_dev *dev, const uuid_t *rgid, |
| u32 vid_valid, u32 vid); |
| /** |
| * max_dmbs() |
| * Return: Max number of DMBs that can be registered for this kind of |
| * dibs_dev |
| */ |
| int (*max_dmbs)(void); |
| /** |
| * register_dmb() - allocate and register a dmb |
| * @dev: dibs device |
| * @dmb: dmb struct to be registered |
| * @client: dibs client |
| * @vid: VLAN id; deprecated, ignored if device does not support vlan |
| * |
| * The following fields of dmb must provide valid input: |
| * @rgid: gid of remote user device |
| * @dmb_len: buffer length |
| * @idx: Optionally:requested idx (if non-zero) |
| * @vlan_valid: if zero, vlan_id will be ignored; |
| * deprecated, ignored if device does not support vlan |
| * @vlan_id: deprecated, ignored if device does not support vlan |
| * Upon return in addition the following fields will be valid: |
| * @dmb_tok: for usage by remote and local devices and clients |
| * @cpu_addr: allocated buffer |
| * @idx: dmb index, unique per dibs device |
| * @dma_addr: to be used by device driver,if applicable |
| * |
| * Allocate a dmb buffer and register it with this device and for this |
| * client. |
| * Return: zero on success |
| */ |
| int (*register_dmb)(struct dibs_dev *dev, struct dibs_dmb *dmb, |
| struct dibs_client *client); |
| /** |
| * unregister_dmb() - unregister and free a dmb |
| * @dev: dibs device |
| * @dmb: dmb struct to be unregistered |
| * The following fields of dmb must provide valid input: |
| * @dmb_tok |
| * @cpu_addr |
| * @idx |
| * |
| * Free dmb.cpu_addr and unregister the dmb from this device. |
| * Return: zero on success |
| */ |
| int (*unregister_dmb)(struct dibs_dev *dev, struct dibs_dmb *dmb); |
| /** |
| * move_data() - write into a remote dmb |
| * @dev: Local sending dibs device |
| * @dmb_tok: Token of the remote dmb |
| * @idx: signaling index in dmbemask |
| * @sf: signaling flag; |
| * if true, idx will be turned on at target dmbemask mask |
| * and target device will be signaled. |
| * @offset: offset within target dmb |
| * @data: pointer to data to be sent |
| * @size: length of data to be sent, can be zero. |
| * |
| * 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 signaling flag (sf) is true, bit number idx bit will be turned |
| * on in the dmbemask mask when handle_irq() is called at the remote |
| * dibs client that owns the target dmb. The target device may chose |
| * to coalesce the signaling triggers of multiple move_data() calls |
| * to the same target dmb into a single handle_irq() call. |
| * Return: zero on success |
| */ |
| int (*move_data)(struct dibs_dev *dev, u64 dmb_tok, unsigned int idx, |
| bool sf, unsigned int offset, void *data, |
| unsigned int size); |
| /** |
| * add_vlan_id() - add dibs device to vlan (optional, deprecated) |
| * @dev: dibs device |
| * @vlan_id: vlan id |
| * |
| * In order to write into a vlan-tagged dmb, the remote device needs |
| * to belong to the this vlan. A device can belong to more than 1 vlan. |
| * Any device can access an untagged dmb. |
| * Deprecated, only supported for backwards compatibility. |
| * Return: zero on success |
| */ |
| int (*add_vlan_id)(struct dibs_dev *dev, u64 vlan_id); |
| /** |
| * del_vlan_id() - remove dibs device from vlan (optional, deprecated) |
| * @dev: dibs device |
| * @vlan_id: vlan id |
| * Return: zero on success |
| */ |
| int (*del_vlan_id)(struct dibs_dev *dev, u64 vlan_id); |
| /** |
| * signal_event() - trigger an event at a remote dibs device (optional) |
| * @dev: local dibs device |
| * @rgid: gid of remote dibs device |
| * trigger_irq: zero: notification may be coalesced with other events |
| * non-zero: notify immediately |
| * @subtype: 4 byte event code, meaning is defined by dibs client |
| * @data: 8 bytes of additional information, |
| * meaning is defined by dibs client |
| * |
| * dibs devices can offer support for sending a control event of type |
| * EVENT_SWR to a remote dibs device. |
| * NOTE: handle_event() will be called for all registered dibs clients |
| * at the remote device. |
| * Return: zero on success |
| */ |
| int (*signal_event)(struct dibs_dev *dev, const uuid_t *rgid, |
| u32 trigger_irq, u32 event_code, u64 info); |
| /** |
| * support_mmapped_rdmb() - can this device provide memory mapped |
| * remote dmbs? (optional) |
| * @dev: dibs device |
| * |
| * A dibs device can provide a kernel address + length, that represent |
| * a remote target dmb (like MMIO). Alternatively to calling |
| * move_data(), a dibs client can write into such a ghost-send-buffer |
| * (= to this kernel address) and the data will automatically |
| * immediately appear in the target dmb, even without calling |
| * move_data(). |
| * |
| * Either all 3 function pointers for support_dmb_nocopy(), |
| * attach_dmb() and detach_dmb() are defined, or all of them must |
| * be NULL. |
| * |
| * Return: non-zero, if memory mapped remote dmbs are supported. |
| */ |
| int (*support_mmapped_rdmb)(struct dibs_dev *dev); |
| /** |
| * attach_dmb() - attach local memory to a remote dmb |
| * @dev: Local sending ism device |
| * @dmb: all other parameters are passed in the form of a |
| * dmb struct |
| * TODO: (THIS IS CONFUSING, should be changed) |
| * dmb_tok: (in) Token of the remote dmb, we want to attach to |
| * cpu_addr: (out) MMIO address |
| * dma_addr: (out) MMIO address (if applicable, invalid otherwise) |
| * dmb_len: (out) length of local MMIO region, |
| * equal to length of remote DMB. |
| * sba_idx: (out) index of remote dmb (NOT HELPFUL, should be removed) |
| * |
| * Provides a memory address to the sender that can be used to |
| * directly write into the remote dmb. |
| * Memory is available until detach_dmb is called |
| * |
| * Return: Zero upon success, Error code otherwise |
| */ |
| int (*attach_dmb)(struct dibs_dev *dev, struct dibs_dmb *dmb); |
| /** |
| * detach_dmb() - Detach the ghost buffer from a remote dmb |
| * @dev: ism device |
| * @token: dmb token of the remote dmb |
| * |
| * No need to free cpu_addr. |
| * |
| * Return: Zero upon success, Error code otherwise |
| */ |
| int (*detach_dmb)(struct dibs_dev *dev, u64 token); |
| }; |
| |
| struct dibs_dev { |
| struct list_head list; |
| struct device dev; |
| /* To be filled by device driver, before calling dibs_dev_add(): */ |
| const struct dibs_dev_ops *ops; |
| uuid_t gid; |
| /* priv pointer for device driver */ |
| void *drv_priv; |
| |
| /* priv pointer per client; for client usage only */ |
| void *priv[MAX_DIBS_CLIENTS]; |
| |
| /* get this lock before accessing any of the fields below */ |
| spinlock_t lock; |
| /* array of client ids indexed by dmb idx; |
| * can be used as indices into priv and subs arrays |
| */ |
| u8 *dmb_clientid_arr; |
| /* Sparse array of all ISM clients */ |
| struct dibs_client *subs[MAX_DIBS_CLIENTS]; |
| }; |
| |
| static inline void dibs_set_priv(struct dibs_dev *dev, |
| struct dibs_client *client, void *priv) |
| { |
| dev->priv[client->id] = priv; |
| } |
| |
| static inline void *dibs_get_priv(struct dibs_dev *dev, |
| struct dibs_client *client) |
| { |
| return dev->priv[client->id]; |
| } |
| |
| /* ------- End of client-only functions ----------- */ |
| |
| /* Functions to be called by dibs device drivers: |
| */ |
| /** |
| * dibs_dev_alloc() - allocate and reference device structure |
| * |
| * The following fields will be valid upon successful return: dev |
| * NOTE: Use put_device(dibs_get_dev(@dibs)) to give up your reference instead |
| * of freeing @dibs @dev directly once you have successfully called this |
| * function. |
| * Return: Pointer to dibs device structure |
| */ |
| struct dibs_dev *dibs_dev_alloc(void); |
| /** |
| * dibs_dev_add() - register with dibs layer and all clients |
| * @dibs: dibs device |
| * |
| * The following fields must be valid upon entry: dev, ops, drv_priv |
| * All fields will be valid upon successful return. |
| * Return: zero on success |
| */ |
| int dibs_dev_add(struct dibs_dev *dibs); |
| /** |
| * dibs_dev_del() - unregister from dibs layer and all clients |
| * @dibs: dibs device |
| */ |
| void dibs_dev_del(struct dibs_dev *dibs); |
| |
| #endif /* _DIBS_H */ |
