xref: /illumos-gate/usr/src/uts/common/xen/public/io/netif.h (revision 55fea89d)
1 /******************************************************************************
2  * netif.h
3  *
4  * Unified network-device I/O interface for Xen guest OSes.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  * DEALINGS IN THE SOFTWARE.
23  *
24  * Copyright (c) 2003-2004, Keir Fraser
25  */
26 
27 #ifndef __XEN_PUBLIC_IO_NETIF_H__
28 #define __XEN_PUBLIC_IO_NETIF_H__
29 
30 #include "ring.h"
31 #include "../grant_table.h"
32 
33 /*
34  * Notifications after enqueuing any type of message should be conditional on
35  * the appropriate req_event or rsp_event field in the shared ring.
36  * If the client sends notification for rx requests then it should specify
37  * feature 'feature-rx-notify' via xenbus. Otherwise the backend will assume
38  * that it cannot safely queue packets (as it may not be kicked to send them).
39  */
40 
41 /*
42  * This is the 'wire' format for packets:
43  *  Request 1: netif_tx_request -- NETTXF_* (any flags)
44  * [Request 2: netif_tx_extra]  (only if request 1 has NETTXF_extra_info)
45  * [Request 3: netif_tx_extra]  (only if request 2 has XEN_NETIF_EXTRA_MORE)
46  *  Request 4: netif_tx_request -- NETTXF_more_data
47  *  Request 5: netif_tx_request -- NETTXF_more_data
48  *  ...
49  *  Request N: netif_tx_request -- 0
50  */
51 
52 /* Protocol checksum field is blank in the packet (hardware offload)? */
53 #define _NETTXF_csum_blank     (0)
54 #define  NETTXF_csum_blank     (1U<<_NETTXF_csum_blank)
55 
56 /* Packet data has been validated against protocol checksum. */
57 #define _NETTXF_data_validated (1)
58 #define  NETTXF_data_validated (1U<<_NETTXF_data_validated)
59 
60 /* Packet continues in the next request descriptor. */
61 #define _NETTXF_more_data      (2)
62 #define  NETTXF_more_data      (1U<<_NETTXF_more_data)
63 
64 /* Packet to be followed by extra descriptor(s). */
65 #define _NETTXF_extra_info     (3)
66 #define  NETTXF_extra_info     (1U<<_NETTXF_extra_info)
67 
68 struct netif_tx_request {
69     grant_ref_t gref;      /* Reference to buffer page */
70     uint16_t offset;       /* Offset within buffer page */
71     uint16_t flags;        /* NETTXF_* */
72     uint16_t id;           /* Echoed in response message. */
73     uint16_t size;         /* Packet size in bytes.       */
74 };
75 typedef struct netif_tx_request netif_tx_request_t;
76 
77 /* Types of netif_extra_info descriptors. */
78 #define XEN_NETIF_EXTRA_TYPE_NONE      (0)  /* Never used - invalid */
79 #define XEN_NETIF_EXTRA_TYPE_GSO       (1)  /* u.gso */
80 #define XEN_NETIF_EXTRA_TYPE_MCAST_ADD (2)  /* u.mcast */
81 #define XEN_NETIF_EXTRA_TYPE_MCAST_DEL (3)  /* u.mcast */
82 #define XEN_NETIF_EXTRA_TYPE_MAX       (4)
83 
84 /* netif_extra_info flags. */
85 #define _XEN_NETIF_EXTRA_FLAG_MORE (0)
86 #define XEN_NETIF_EXTRA_FLAG_MORE  (1U<<_XEN_NETIF_EXTRA_FLAG_MORE)
87 
88 /* GSO types - only TCPv4 currently supported. */
89 #define XEN_NETIF_GSO_TYPE_TCPV4        (1)
90 
91 /*
92  * This structure needs to fit within both netif_tx_request and
93  * netif_rx_response for compatibility.
94  */
95 struct netif_extra_info {
96     uint8_t type;  /* XEN_NETIF_EXTRA_TYPE_* */
97     uint8_t flags; /* XEN_NETIF_EXTRA_FLAG_* */
98 
99     union {
100         /*
101          * XEN_NETIF_EXTRA_TYPE_GSO:
102          */
103         struct {
104             /*
105              * Maximum payload size of each segment. For example, for TCP this
106              * is just the path MSS.
107              */
108             uint16_t size;
109 
110             /*
111              * GSO type. This determines the protocol of the packet and any
112              * extra features required to segment the packet properly.
113              */
114             uint8_t type; /* XEN_NETIF_GSO_TYPE_* */
115 
116             /* Future expansion. */
117             uint8_t pad;
118 
119             /*
120              * GSO features. This specifies any extra GSO features required
121              * to process this packet, such as ECN support for TCPv4.
122              */
123             uint16_t features; /* XEN_NETIF_GSO_FEAT_* */
124         } gso;
125 
126         /*
127          * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}:
128          * Backend advertises availability via 'feature-multicast-control'
129          * xenbus node containing value '1'.
130          * Frontend requests this feature by advertising
131          * 'request-multicast-control' xenbus node containing value '1'.
132          * If multicast control is requested then multicast flooding is
133          * disabled and the frontend must explicitly register its interest
134          * in multicast groups using dummy transmit requests containing
135          * MCAST_{ADD,DEL} extra-info fragments.
136          */
137         struct {
138             uint8_t addr[6]; /* Address to add/remove. */
139         } mcast;
140 
141         uint16_t pad[3];
142     } u;
143 };
144 typedef struct netif_extra_info netif_extra_info_t;
145 
146 struct netif_tx_response {
147     uint16_t id;
148     int16_t  status;       /* NETIF_RSP_* */
149 };
150 typedef struct netif_tx_response netif_tx_response_t;
151 
152 struct netif_rx_request {
153     uint16_t    id;        /* Echoed in response message.        */
154     grant_ref_t gref;      /* Reference to incoming granted frame */
155 };
156 typedef struct netif_rx_request netif_rx_request_t;
157 
158 /* Packet data has been validated against protocol checksum. */
159 #define _NETRXF_data_validated (0)
160 #define  NETRXF_data_validated (1U<<_NETRXF_data_validated)
161 
162 /* Protocol checksum field is blank in the packet (hardware offload)? */
163 #define _NETRXF_csum_blank     (1)
164 #define  NETRXF_csum_blank     (1U<<_NETRXF_csum_blank)
165 
166 /* Packet continues in the next request descriptor. */
167 #define _NETRXF_more_data      (2)
168 #define  NETRXF_more_data      (1U<<_NETRXF_more_data)
169 
170 /* Packet to be followed by extra descriptor(s). */
171 #define _NETRXF_extra_info     (3)
172 #define  NETRXF_extra_info     (1U<<_NETRXF_extra_info)
173 
174 struct netif_rx_response {
175     uint16_t id;
176     uint16_t offset;       /* Offset in page of start of received packet  */
177     uint16_t flags;        /* NETRXF_* */
178     int16_t  status;       /* -ve: BLKIF_RSP_* ; +ve: Rx'ed pkt size. */
179 };
180 typedef struct netif_rx_response netif_rx_response_t;
181 
182 /*
183  * Generate netif ring structures and types.
184  */
185 
186 DEFINE_RING_TYPES(netif_tx, struct netif_tx_request, struct netif_tx_response);
187 DEFINE_RING_TYPES(netif_rx, struct netif_rx_request, struct netif_rx_response);
188 
189 #define NETIF_RSP_DROPPED         -2
190 #define NETIF_RSP_ERROR           -1
191 #define NETIF_RSP_OKAY             0
192 /* No response: used for auxiliary requests (e.g., netif_tx_extra). */
193 #define NETIF_RSP_NULL             1
194 
195 #endif
196 
197 /*
198  * Local variables:
199  * mode: C
200  * c-set-style: "BSD"
201  * c-basic-offset: 4
202  * tab-width: 4
203  * indent-tabs-mode: nil
204  * End:
205  */
206