diff mbox

[v6,1/2] public/io/netif.h: clarifications to wire formats

Message ID 1452528329-10952-2-git-send-email-paul.durrant@citrix.com (mailing list archive)
State New, archived
Headers show

Commit Message

Paul Durrant Jan. 11, 2016, 4:05 p.m. UTC 
My previous patch 03809ae7 "document transmit and receive wire formats
separately" improved documentation of the receive and transmit wire
formats but further clarifications were requested.

This patch adds those clarifications.

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
Cc: Ian Campbell <ian.campbell@citrix.com>
Cc: Ian Jackson <ian.jackson@eu.citrix.com>
Cc: Jan Beulich <jbeulich@suse.com>
Cc: Keir Fraser <keir@xen.org>
Cc: Tim Deegan <tim@xen.org>
---

v6:
 - v4 of the original patch was committed so this is an
   incremental version of the patch in v5.

v5:
 - Add extra clarifications.
---
 xen/include/public/io/netif.h | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)
diff mbox

Patch

diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
index 1790ea0..0a3272f 100644
--- a/xen/include/public/io/netif.h
+++ b/xen/include/public/io/netif.h
@@ -154,19 +154,29 @@ 
  * Guest transmit
  * ==============
  *
- * This is the 'wire' format for packets:
+ * This is the 'wire' format for transmit (frontend -> backend) packets:
+ *
  *  Fragment 1: netif_tx_request_t  - flags = NETTXF_*
  *                                    size = total packet size
  * [Extra 1: netif_extra_info_t]    - (only if fragment 1 flags include
  *                                     NETTXF_extra_info)
+ *  ...
  * [Extra N: netif_extra_info_t]    - (only if extra N-1 flags include
  *                                     XEN_NETIF_EXTRA_MORE)
  *  ...
  *  Fragment N: netif_tx_request_t  - (only if fragment N-1 flags include
- *                                     NETTXF_more_data)
+ *                                     NETTXF_more_data - flags on preceding
+ *                                     extras are not relevent here)
  *                                    flags = 0
  *                                    size = fragment size
  *
+ * NOTE:
+ *
+ * This format slightly is different from that used for receive
+ * (backend -> frontend) packets. Specifically, in a multi-fragment
+ * packet the actual size of fragment 1 can only be determined by
+ * subtracting the sizes of fragments 2..N from the total packet size.
+ *
  * Ring slot size is 12 octets, however not all request/response
  * structs use the full size.
  *
@@ -202,19 +212,29 @@ 
  * Guest receive
  * =============
  *
- * This is the 'wire' format for packets:
+ * This is the 'wire' format for receive (backend -> frontend) packets:
+ *
  *  Fragment 1: netif_rx_request_t  - flags = NETRXF_*
  *                                    size = fragment size
  * [Extra 1: netif_extra_info_t]    - (only if fragment 1 flags include
  *                                     NETRXF_extra_info)
+ *  ...
  * [Extra N: netif_extra_info_t]    - (only if extra N-1 flags include
  *                                     XEN_NETIF_EXTRA_MORE)
  *  ...
  *  Fragment N: netif_rx_request_t  - (only if fragment N-1 flags include
- *                                     NETRXF_more_data)
+ *                                     NETRXF_more_data - flags on preceding
+ *                                     extras are not relevent here)
  *                                    flags = 0
  *                                    size = fragment size
  *
+ * NOTE:
+ *
+ * This format slightly is different from that used for transmit
+ * (frontend -> backend) packets. Specifically, in a multi-fragment
+ * packet the size of the packet can only be determined by summing the
+ * sizes of fragments 1..N.
+ *
  * Ring slot size is 8 octets.
  *
  * rx request (netif_rx_request_t)