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: Tom Parkin <tparkin@katalix.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Tom Parkin 2020-07-28 18:20:33 +01:00 committed by David S. Miller
parent ca7885dbcd
commit 340bb1ac45

View File

@ -15,15 +15,15 @@
#include <net/xfrm.h> #include <net/xfrm.h>
#endif #endif
/* Just some random numbers */ /* Random numbers used for internal consistency checks of tunnel and session structures */
#define L2TP_TUNNEL_MAGIC 0x42114DDA #define L2TP_TUNNEL_MAGIC 0x42114DDA
#define L2TP_SESSION_MAGIC 0x0C04EB7D #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_BITS 4
#define L2TP_HASH_SIZE BIT(L2TP_HASH_BITS) #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_BITS_2 8
#define L2TP_HASH_SIZE_2 BIT(L2TP_HASH_BITS_2) #define L2TP_HASH_SIZE_2 BIT(L2TP_HASH_BITS_2)
@ -43,9 +43,7 @@ struct l2tp_stats {
struct l2tp_tunnel; struct l2tp_tunnel;
/* Describes a session. Contains information to determine incoming /* L2TP session configuration */
* packets and transmit outgoing ones.
*/
struct l2tp_session_cfg { struct l2tp_session_cfg {
enum l2tp_pwtype pw_type; enum l2tp_pwtype pw_type;
unsigned int recv_seq:1; /* expect receive packets with sequence numbers? */ unsigned int recv_seq:1; /* expect receive packets with sequence numbers? */
@ -63,6 +61,11 @@ struct l2tp_session_cfg {
char *ifname; 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 { struct l2tp_session {
int magic; /* should be L2TP_SESSION_MAGIC */ int magic; /* should be L2TP_SESSION_MAGIC */
long dead; long dead;
@ -101,15 +104,32 @@ struct l2tp_session {
struct l2tp_stats stats; struct l2tp_stats stats;
struct hlist_node global_hlist; /* global hash list node */ 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); 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); 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); void (*show)(struct seq_file *m, void *priv);
u8 priv[]; /* private data */ u8 priv[]; /* private data */
}; };
/* Describes the tunnel. It contains info to track all the associated /* L2TP tunnel configuration */
* sessions so incoming packets can be sorted out
*/
struct l2tp_tunnel_cfg { struct l2tp_tunnel_cfg {
int debug; /* bitmask of debug message categories */ int debug; /* bitmask of debug message categories */
enum l2tp_encap_type encap; enum l2tp_encap_type encap;
@ -128,6 +148,12 @@ struct l2tp_tunnel_cfg {
udp6_zero_rx_checksums:1; 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 { struct l2tp_tunnel {
int magic; /* Should be L2TP_TUNNEL_MAGIC */ int magic; /* Should be L2TP_TUNNEL_MAGIC */
@ -162,10 +188,23 @@ struct l2tp_tunnel {
struct work_struct del_work; struct work_struct del_work;
}; };
/* Pseudowire ops callbacks for use with the l2tp genetlink interface */
struct l2tp_nl_cmd_ops { 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, int (*session_create)(struct net *net, struct l2tp_tunnel *tunnel,
u32 session_id, u32 peer_session_id, u32 session_id, u32 peer_session_id,
struct l2tp_session_cfg *cfg); 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); 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]; return &session->priv[0];
} }
/* Tunnel and session refcounts */
void l2tp_tunnel_inc_refcount(struct l2tp_tunnel *tunnel); void l2tp_tunnel_inc_refcount(struct l2tp_tunnel *tunnel);
void l2tp_tunnel_dec_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_inc_refcount(struct l2tp_session *session);
void l2tp_session_dec_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(const struct net *net, u32 tunnel_id);
struct l2tp_tunnel *l2tp_tunnel_get_nth(const struct net *net, int nth); struct l2tp_tunnel *l2tp_tunnel_get_nth(const struct net *net, int nth);
struct l2tp_session *l2tp_tunnel_get_session(struct l2tp_tunnel *tunnel, 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, struct l2tp_session *l2tp_session_get_by_ifname(const struct net *net,
const char *ifname); 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, int l2tp_tunnel_create(struct net *net, int fd, int version, u32 tunnel_id,
u32 peer_tunnel_id, struct l2tp_tunnel_cfg *cfg, u32 peer_tunnel_id, struct l2tp_tunnel_cfg *cfg,
struct l2tp_tunnel **tunnelp); struct l2tp_tunnel **tunnelp);
int l2tp_tunnel_register(struct l2tp_tunnel *tunnel, struct net *net, int l2tp_tunnel_register(struct l2tp_tunnel *tunnel, struct net *net,
struct l2tp_tunnel_cfg *cfg); struct l2tp_tunnel_cfg *cfg);
void l2tp_tunnel_delete(struct l2tp_tunnel *tunnel); void l2tp_tunnel_delete(struct l2tp_tunnel *tunnel);
struct l2tp_session *l2tp_session_create(int priv_size, struct l2tp_session *l2tp_session_create(int priv_size,
struct l2tp_tunnel *tunnel, struct l2tp_tunnel *tunnel,
u32 session_id, u32 peer_session_id, u32 session_id, u32 peer_session_id,
struct l2tp_session_cfg *cfg); struct l2tp_session_cfg *cfg);
int l2tp_session_register(struct l2tp_session *session, int l2tp_session_register(struct l2tp_session *session,
struct l2tp_tunnel *tunnel); struct l2tp_tunnel *tunnel);
void l2tp_session_delete(struct l2tp_session *session); 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, void l2tp_recv_common(struct l2tp_session *session, struct sk_buff *skb,
unsigned char *ptr, unsigned char *optr, u16 hdrflags, unsigned char *ptr, unsigned char *optr, u16 hdrflags,
int length); int length);
int l2tp_udp_encap_recv(struct sock *sk, struct sk_buff *skb); 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 l2tp_xmit_skb(struct l2tp_session *session, struct sk_buff *skb,
int hdr_len); int hdr_len);
int l2tp_nl_register_ops(enum l2tp_pwtype pw_type, /* Pseudowire management.
const struct l2tp_nl_cmd_ops *ops); * 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); 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); int l2tp_ioctl(struct sock *sk, int cmd, unsigned long arg);
static inline int l2tp_get_l2specific_len(struct l2tp_session *session) static inline int l2tp_get_l2specific_len(struct l2tp_session *session)