Commit 340bb1ac authored by Tom Parkin's avatar Tom Parkin Committed by David S. Miller
Browse files

l2tp: improve API documentation in l2tp_core.h 



* Improve the description of the key l2tp subsystem data structures.
 * Add high-level description of the main APIs for interacting with l2tp
   core.
 * Add documentation for the l2tp netlink session command callbacks.
 * Document the session pseudowire callbacks.

Signed-off-by: default avatarTom Parkin <tparkin@katalix.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent ca7885db

net/l2tp/l2tp_core.h

+72 −14
Original line number Diff line number Diff line
@@ -15,15 +15,15 @@ 
#include <net/xfrm.h>

#endif



/* Just some random numbers */

/* Random numbers used for internal consistency checks of tunnel and session structures */

#define L2TP_TUNNEL_MAGIC	0x42114DDA

#define L2TP_SESSION_MAGIC	0x0C04EB7D



/* Per tunnel, session hash table size */

/* Per tunnel session hash table size */

#define L2TP_HASH_BITS	4

#define L2TP_HASH_SIZE	BIT(L2TP_HASH_BITS)



/* System-wide, session hash table size */

/* System-wide session hash table size */

#define L2TP_HASH_BITS_2	8

#define L2TP_HASH_SIZE_2	BIT(L2TP_HASH_BITS_2)
@@ -43,9 +43,7 @@ struct l2tp_stats { 


struct l2tp_tunnel;



/* Describes a session. Contains information to determine incoming

 * packets and transmit outgoing ones.

 */

/* L2TP session configuration */

struct l2tp_session_cfg {

	enum l2tp_pwtype	pw_type;

	unsigned int		recv_seq:1;	/* expect receive packets with sequence numbers? */
@@ -63,6 +61,11 @@ struct l2tp_session_cfg { 
	char			*ifname;

};



/* Represents a session (pseudowire) instance.

 * Tracks runtime state including cookies, dataplane packet sequencing, and IO statistics.

 * Is linked into a per-tunnel session hashlist; and in the case of an L2TPv3 session into

 * an additional per-net ("global") hashlist.

 */

struct l2tp_session {

	int			magic;		/* should be L2TP_SESSION_MAGIC */

	long			dead;
@@ -101,15 +104,32 @@ struct l2tp_session { 
	struct l2tp_stats	stats;

	struct hlist_node	global_hlist;	/* global hash list node */



	/* Session receive handler for data packets.

	 * Each pseudowire implementation should implement this callback in order to

	 * handle incoming packets.  Packets are passed to the pseudowire handler after

	 * reordering, if data sequence numbers are enabled for the session.

	 */

	void (*recv_skb)(struct l2tp_session *session, struct sk_buff *skb, int data_len);



	/* Session close handler.

	 * Each pseudowire implementation may implement this callback in order to carry

	 * out pseudowire-specific shutdown actions.

	 * The callback is called by core after unhashing the session and purging its

	 * reorder queue.

	 */

	void (*session_close)(struct l2tp_session *session);



	/* Session show handler.

	 * Pseudowire-specific implementation of debugfs session rendering.

	 * The callback is called by l2tp_debugfs.c after rendering core session

	 * information.

	 */

	void (*show)(struct seq_file *m, void *priv);



	u8			priv[];		/* private data */

};



/* Describes the tunnel. It contains info to track all the associated

 * sessions so incoming packets can be sorted out

 */

/* L2TP tunnel configuration */

struct l2tp_tunnel_cfg {

	int			debug;		/* bitmask of debug message categories */

	enum l2tp_encap_type	encap;
@@ -128,6 +148,12 @@ struct l2tp_tunnel_cfg { 
				udp6_zero_rx_checksums:1;

};



/* Represents a tunnel instance.

 * Tracks runtime state including IO statistics.

 * Holds the tunnel socket (either passed from userspace or directly created by the kernel).

 * Maintains a hashlist of sessions belonging to the tunnel instance.

 * Is linked into a per-net list of tunnels.

 */

struct l2tp_tunnel {

	int			magic;		/* Should be L2TP_TUNNEL_MAGIC */
@@ -162,10 +188,23 @@ struct l2tp_tunnel { 
	struct work_struct	del_work;

};



/* Pseudowire ops callbacks for use with the l2tp genetlink interface */

struct l2tp_nl_cmd_ops {

	/* The pseudowire session create callback is responsible for creating a session

	 * instance for a specific pseudowire type.

	 * It must call l2tp_session_create and l2tp_session_register to register the

	 * session instance, as well as carry out any pseudowire-specific initialisation.

	 * It must return >= 0 on success, or an appropriate negative errno value on failure.

	 */

	int (*session_create)(struct net *net, struct l2tp_tunnel *tunnel,

			      u32 session_id, u32 peer_session_id,

			      struct l2tp_session_cfg *cfg);



	/* The pseudowire session delete callback is responsible for initiating the deletion

	 * of a session instance.

	 * It must call l2tp_session_delete, as well as carry out any pseudowire-specific

	 * teardown actions.

	 */

	void (*session_delete)(struct l2tp_session *session);

};
@@ -174,11 +213,16 @@ static inline void *l2tp_session_priv(struct l2tp_session *session) 
	return &session->priv[0];

}



/* Tunnel and session refcounts */

void l2tp_tunnel_inc_refcount(struct l2tp_tunnel *tunnel);

void l2tp_tunnel_dec_refcount(struct l2tp_tunnel *tunnel);

void l2tp_session_inc_refcount(struct l2tp_session *session);

void l2tp_session_dec_refcount(struct l2tp_session *session);



/* Tunnel and session lookup.

 * These functions take a reference on the instances they return, so

 * the caller must ensure that the reference is dropped appropriately.

 */

struct l2tp_tunnel *l2tp_tunnel_get(const struct net *net, u32 tunnel_id);

struct l2tp_tunnel *l2tp_tunnel_get_nth(const struct net *net, int nth);

struct l2tp_session *l2tp_tunnel_get_session(struct l2tp_tunnel *tunnel,
@@ -189,33 +233,47 @@ struct l2tp_session *l2tp_session_get_nth(struct l2tp_tunnel *tunnel, int nth); 
struct l2tp_session *l2tp_session_get_by_ifname(const struct net *net,

						const char *ifname);



/* Tunnel and session lifetime management.

 * Creation of a new instance is a two-step process: create, then register.

 * Destruction is triggered using the *_delete functions, and completes asynchronously.

 */

int l2tp_tunnel_create(struct net *net, int fd, int version, u32 tunnel_id,

		       u32 peer_tunnel_id, struct l2tp_tunnel_cfg *cfg,

		       struct l2tp_tunnel **tunnelp);

int l2tp_tunnel_register(struct l2tp_tunnel *tunnel, struct net *net,

			 struct l2tp_tunnel_cfg *cfg);



void l2tp_tunnel_delete(struct l2tp_tunnel *tunnel);



struct l2tp_session *l2tp_session_create(int priv_size,

					 struct l2tp_tunnel *tunnel,

					 u32 session_id, u32 peer_session_id,

					 struct l2tp_session_cfg *cfg);

int l2tp_session_register(struct l2tp_session *session,

			  struct l2tp_tunnel *tunnel);



void l2tp_session_delete(struct l2tp_session *session);



/* Receive path helpers.  If data sequencing is enabled for the session these

 * functions handle queuing and reordering prior to passing packets to the

 * pseudowire code to be passed to userspace.

 */

void l2tp_recv_common(struct l2tp_session *session, struct sk_buff *skb,

		      unsigned char *ptr, unsigned char *optr, u16 hdrflags,

		      int length);

int l2tp_udp_encap_recv(struct sock *sk, struct sk_buff *skb);

void l2tp_session_set_header_len(struct l2tp_session *session, int version);



/* Transmit path helpers for sending packets over the tunnel socket. */

void l2tp_session_set_header_len(struct l2tp_session *session, int version);

int l2tp_xmit_skb(struct l2tp_session *session, struct sk_buff *skb,

		  int hdr_len);



int l2tp_nl_register_ops(enum l2tp_pwtype pw_type,

			 const struct l2tp_nl_cmd_ops *ops);

/* Pseudowire management.

 * Pseudowires should register with l2tp core on module init, and unregister

 * on module exit.

 */

int l2tp_nl_register_ops(enum l2tp_pwtype pw_type, const struct l2tp_nl_cmd_ops *ops);

void l2tp_nl_unregister_ops(enum l2tp_pwtype pw_type);



/* IOCTL helper for IP encap modules. */

int l2tp_ioctl(struct sock *sk, int cmd, unsigned long arg);



static inline int l2tp_get_l2specific_len(struct l2tp_session *session)

CRA Git | Maintained and supported by SUSTech CRA and CCSE