wwan.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2/* Copyright (c) 2021, Linaro Ltd <loic.poulain@linaro.org> */
  3
  4#ifndef __WWAN_H
  5#define __WWAN_H
  6
  7#include <linux/poll.h>
  8#include <linux/netdevice.h>
  9#include <linux/types.h>
 10
 11/**
 12 * enum wwan_port_type - WWAN port types
 13 * @WWAN_PORT_AT: AT commands
 14 * @WWAN_PORT_MBIM: Mobile Broadband Interface Model control
 15 * @WWAN_PORT_QMI: Qcom modem/MSM interface for modem control
 16 * @WWAN_PORT_QCDM: Qcom Modem diagnostic interface
 17 * @WWAN_PORT_FIREHOSE: XML based command protocol
 18 * @WWAN_PORT_XMMRPC: Control protocol for Intel XMM modems
 19 * @WWAN_PORT_FASTBOOT: Fastboot protocol control
 20 * @WWAN_PORT_ADB: ADB protocol control
 21 * @WWAN_PORT_MIPC: MTK MIPC diagnostic interface
 22 *
 23 * @WWAN_PORT_MAX: Highest supported port types
 24 * @WWAN_PORT_UNKNOWN: Special value to indicate an unknown port type
 25 * @__WWAN_PORT_MAX: Internal use
 26 */
 27enum wwan_port_type {
 28	WWAN_PORT_AT,
 29	WWAN_PORT_MBIM,
 30	WWAN_PORT_QMI,
 31	WWAN_PORT_QCDM,
 32	WWAN_PORT_FIREHOSE,
 33	WWAN_PORT_XMMRPC,
 34	WWAN_PORT_FASTBOOT,
 35	WWAN_PORT_ADB,
 36	WWAN_PORT_MIPC,
 37
 38	/* Add new port types above this line */
 39
 40	__WWAN_PORT_MAX,
 41	WWAN_PORT_MAX = __WWAN_PORT_MAX - 1,
 42	WWAN_PORT_UNKNOWN,
 43};
 44
 45struct device;
 46struct file;
 47struct netlink_ext_ack;
 48struct sk_buff;
 49struct wwan_port;
 50
 51/** struct wwan_port_ops - The WWAN port operations
 52 * @start: The routine for starting the WWAN port device.
 53 * @stop: The routine for stopping the WWAN port device.
 54 * @tx: Non-blocking routine that sends WWAN port protocol data to the device.
 55 * @tx_blocking: Optional blocking routine that sends WWAN port protocol data
 56 *               to the device.
 57 * @tx_poll: Optional routine that sets additional TX poll flags.
 58 *
 59 * The wwan_port_ops structure contains a list of low-level operations
 60 * that control a WWAN port device. All functions are mandatory unless specified.
 61 */
 62struct wwan_port_ops {
 63	int (*start)(struct wwan_port *port);
 64	void (*stop)(struct wwan_port *port);
 65	int (*tx)(struct wwan_port *port, struct sk_buff *skb);
 66
 67	/* Optional operations */
 68	int (*tx_blocking)(struct wwan_port *port, struct sk_buff *skb);
 69	__poll_t (*tx_poll)(struct wwan_port *port, struct file *filp,
 70			    poll_table *wait);
 71};
 72
 73/** struct wwan_port_caps - The WWAN port capbilities
 74 * @frag_len: WWAN port TX fragments length
 75 * @headroom_len: WWAN port TX fragments reserved headroom length
 76 */
 77struct wwan_port_caps {
 78	size_t frag_len;
 79	unsigned int headroom_len;
 80};
 81
 82/**
 83 * wwan_create_port - Add a new WWAN port
 84 * @parent: Device to use as parent and shared by all WWAN ports
 85 * @type: WWAN port type
 86 * @ops: WWAN port operations
 87 * @caps: WWAN port capabilities
 88 * @drvdata: Pointer to caller driver data
 89 *
 90 * Allocate and register a new WWAN port. The port will be automatically exposed
 91 * to user as a character device and attached to the right virtual WWAN device,
 92 * based on the parent pointer. The parent pointer is the device shared by all
 93 * components of a same WWAN modem (e.g. USB dev, PCI dev, MHI controller...).
 94 *
 95 * drvdata will be placed in the WWAN port device driver data and can be
 96 * retrieved with wwan_port_get_drvdata().
 97 *
 98 * This function must be balanced with a call to wwan_remove_port().
 99 *
100 * Returns: a valid pointer to wwan_port on success or PTR_ERR on failure
101 */
102struct wwan_port *wwan_create_port(struct device *parent,
103				   enum wwan_port_type type,
104				   const struct wwan_port_ops *ops,
105				   struct wwan_port_caps *caps,
106				   void *drvdata);
107
108/**
109 * wwan_remove_port - Remove a WWAN port
110 * @port: WWAN port to remove
111 *
112 * Remove a previously created port.
113 */
114void wwan_remove_port(struct wwan_port *port);
115
116/**
117 * wwan_port_rx - Receive data from the WWAN port
118 * @port: WWAN port for which data is received
119 * @skb: Pointer to the rx buffer
120 *
121 * A port driver calls this function upon data reception (MBIM, AT...).
122 */
123void wwan_port_rx(struct wwan_port *port, struct sk_buff *skb);
124
125/**
126 * wwan_port_txoff - Stop TX on WWAN port
127 * @port: WWAN port for which TX must be stopped
128 *
129 * Used for TX flow control, a port driver calls this function to indicate TX
130 * is temporary unavailable (e.g. due to ring buffer fullness).
131 */
132void wwan_port_txoff(struct wwan_port *port);
133
134
135/**
136 * wwan_port_txon - Restart TX on WWAN port
137 * @port: WWAN port for which TX must be restarted
138 *
139 * Used for TX flow control, a port driver calls this function to indicate TX
140 * is available again.
141 */
142void wwan_port_txon(struct wwan_port *port);
143
144/**
145 * wwan_port_get_drvdata - Retrieve driver data from a WWAN port
146 * @port: Related WWAN port
147 */
148void *wwan_port_get_drvdata(struct wwan_port *port);
149
150/**
151 * struct wwan_netdev_priv - WWAN core network device private data
152 * @link_id: WWAN device data link id
153 * @drv_priv: driver private data area, size is determined in &wwan_ops
154 */
155struct wwan_netdev_priv {
156	u32 link_id;
157
158	/* must be last */
159	u8 drv_priv[] __aligned(sizeof(void *));
160};
161
162static inline void *wwan_netdev_drvpriv(struct net_device *dev)
163{
164	return ((struct wwan_netdev_priv *)netdev_priv(dev))->drv_priv;
165}
166
167/*
168 * Used to indicate that the WWAN core should not create a default network
169 * link.
170 */
171#define WWAN_NO_DEFAULT_LINK		U32_MAX
172
173/**
174 * struct wwan_ops - WWAN device ops
175 * @priv_size: size of private netdev data area
176 * @setup: set up a new netdev
177 * @newlink: register the new netdev
178 * @dellink: remove the given netdev
179 */
180struct wwan_ops {
181	unsigned int priv_size;
182	void (*setup)(struct net_device *dev);
183	int (*newlink)(void *ctxt, struct net_device *dev,
184		       u32 if_id, struct netlink_ext_ack *extack);
185	void (*dellink)(void *ctxt, struct net_device *dev,
186			struct list_head *head);
187};
188
189int wwan_register_ops(struct device *parent, const struct wwan_ops *ops,
190		      void *ctxt, u32 def_link_id);
191
192void wwan_unregister_ops(struct device *parent);
193
194#ifdef CONFIG_WWAN_DEBUGFS
195struct dentry *wwan_get_debugfs_dir(struct device *parent);
196void wwan_put_debugfs_dir(struct dentry *dir);
197#else
198static inline struct dentry *wwan_get_debugfs_dir(struct device *parent)
199{
200	return ERR_PTR(-ENODEV);
201}
202static inline void wwan_put_debugfs_dir(struct dentry *dir) {}
203#endif
204
205#endif /* __WWAN_H */