Re: [PATCH DOCDAY] netif.h: describe request/response structures in terms of binary layout

["Jürgen Groß" <jgross@suse.com>]

On 02/25/2015 01:16 PM, Ian Campbell wrote:
> In RFC style, rather than relying on the implicit assumptions of a
> particular C ABI.
>
> I have also confirmed, using the Python gdb extension technique in
> [0], that the struct offsets (in a Linux binary at least) are the same
> as described here.
>
> I took the opportunity to also confirm that x86_32, x86_64, arm32 and
> arm64 are all the same.
>
> This highlighted that struct netif_rx_request was missing some
> explicit padding, which is added here.
>
> Lastly, fixup some struct names to allow the generated docs to
> properly hyperlink, mainly by adding the _t to type names where
> appropriate, but also s/netif_tx_extra/netif_extra_info_t/.
>
> [] http://stackoverflow.com/questions/9788679/how-to-get-the-relative-adress-of-a-field-in-a-structure-dump-c,
>
> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> Cc: Roger Pau Monné <roger.pau@citrix.com>
> Cc: Wei Liu <wei.liu2@citrix.com>

One general question: should the RFC-like description really contain
macro names instead of explicit values?

> ---
>   xen/include/public/io/netif.h |  137 ++++++++++++++++++++++++++++++++++++++---
>   1 file changed, 127 insertions(+), 10 deletions(-)
>
> diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
> index 61e9aea..03b14fe 100644
> --- a/xen/include/public/io/netif.h
> +++ b/xen/include/public/io/netif.h
> @@ -137,13 +137,129 @@
>
>   /*
>    * This is the 'wire' format for packets:
> - *  Request 1: netif_tx_request -- NETTXF_* (any flags)
> - * [Request 2: netif_tx_extra]  (only if request 1 has NETTXF_extra_info)
> - * [Request 3: netif_tx_extra]  (only if request 2 has XEN_NETIF_EXTRA_MORE)
> - *  Request 4: netif_tx_request -- NETTXF_more_data
> - *  Request 5: netif_tx_request -- NETTXF_more_data
> + *  Request 1: netif_tx_request_t -- NETTXF_* (any flags)
> + * [Request 2: netif_extra_info_t] (only if request 1 has NETTXF_extra_info)
> + * [Request 3: netif_extra_info_t] (only if request 2 has XEN_NETIF_EXTRA_MORE)
> + *  Request 4: netif_tx_request_t -- NETTXF_more_data
> + *  Request 5: netif_tx_request_t -- NETTXF_more_data
>    *  ...
> - *  Request N: netif_tx_request -- 0
> + *  Request N: netif_tx_request_t -- 0
> + */
> +
> +/*
> + * Guest transmit
> + * ==============
> + *
> + * Ring slot size is 12 octets, however not all request/response
> + * structs use the full size.
> + *
> + * tx request data (netif_tx_request_t)
> + * ------------------------------------
> + *
> + *    0     1     2     3     4     5     6     7  octet
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * | grant ref             | offset    | flags     |
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * | id        | size      |
> + * +-----+-----+-----+-----+
> + *
> + * grant ref: Reference to buffer page.
> + * offset: Offset within buffer page.
> + * flags: NETTXF_*.
> + * id: request identifier, echoed in response.
> + * size: packet size in bytes.
> + *
> + * tx response (netif_tx_response_t)
> + * ---------------------------------
> + *
> + *    0     1     2     3     4     5     6     7  octet
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * | id        | status    | unused                |
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * | unused                |
> + * +-----+-----+-----+-----+
> + *
> + * id: reflects id in transmit request
> + * status: NETIF_RSP_*
> + *
> + * Guest receive
> + * =============
> +

Empty line intended?

> + * Ring slot size is 8 octets.
> + *
> + * rx request (netif_rx_request_t)
> + * -------------------------------
> + *
> + *    0     1     2     3     4     5     6     7  octet
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * | id        | pad       | gref                  |
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + *
> + * id: request identifier, echoed in response.
> + * gref: reference to incoming granted frame.
> + *
> + * rx response (netif_rx_response_t)
> + * ---------------------------------
> + *
> + *    0     1     2     3     4     5     6     7  octet
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * | id        | offset    | flags     | status    |
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + *
> + * id: reflects id in receive request
> + * offset: offset in page of start of received packet
> + * flags: NETRXF_*
> + * status: -ve: NETIF_RSP_*; +ve: Rx'ed pkt size.

What is -/+ve?

> + *
> + * Extra Info
> + * ==========
> + *
> + * Can be present if initial request has NET{T,R}XF_extra_info, or
> + * previous extra request has XEN_NETIF_EXTRA_MORE.
> + *
> + * The struct therefore needs to fit into either a tx or rx slot and
> + * is therefore limited to 8 octets.
> + *
> + * extra info (netif_extra_info_t)
> + * -------------------------------
> + *
> + * General format:
> + *
> + *    0     1     2     3     4     5     6     7  octet
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * |type |flags| type specfic data                 |
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * | padding for tx        |
> + * +-----+-----+-----+-----+
> + *
> + * type: XEN_NETIF_EXTRA_TYPE_*
> + * flags: XEN_NETIF_EXTRA_FLAG_*
> + * padding for tx: present only in the tx case due to 8 octet limit
> + *     from rx case. Not shown in type specific entries below.
> + *
> + * XEN_NETIF_EXTRA_TYPE_GSO:
> + *
> + *    0     1     2     3     4     5     6     7  octet
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * |type |flags| size      |type | pad | features  |
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + *
> + * type: Must be XEN_NETIF_EXTRA_TYPE_GSO
> + * flags: XEN_NETIF_EXTRA_FLAG_*
> + * size: Maximum payload size of each segment.
> + * type: XEN_NETIF_GSO_TYPE_*
> + * features: EN_NETIF_GSO_FEAT_*
> + *
> + * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}:
> + *
> + *    0     1     2     3     4     5     6     7  octet
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + * |type |flags| addr                              |
> + * +-----+-----+-----+-----+-----+-----+-----+-----+
> + *
> + * type: Must be XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}
> + * flags: XEN_NETIF_EXTRA_FLAG_*
> + * addr: addrss to add/remove

s/addrss/address/

Juergen

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel