From patchwork Mon Oct 9 17:33:15 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ben Pfaff X-Patchwork-Id: 823386 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=openvswitch.org (client-ip=140.211.169.12; helo=mail.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3y9nQc1Tssz9t6C for ; Tue, 10 Oct 2017 04:33:27 +1100 (AEDT) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 11E86B59; Mon, 9 Oct 2017 17:33:24 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id E9B7FABC for ; Mon, 9 Oct 2017 17:33:22 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from relay5-d.mail.gandi.net (relay5-d.mail.gandi.net [217.70.183.197]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 3C98C48C for ; Mon, 9 Oct 2017 17:33:22 +0000 (UTC) X-Originating-IP: 208.91.2.3 Received: from sigabrt.benpfaff.org (unknown [208.91.2.3]) (Authenticated sender: blp@ovn.org) by relay5-d.mail.gandi.net (Postfix) with ESMTPSA id F3FBD41C07C; Mon, 9 Oct 2017 19:33:18 +0200 (CEST) From: Ben Pfaff To: dev@openvswitch.org Date: Mon, 9 Oct 2017 10:33:15 -0700 Message-Id: <20171009173315.6682-1-blp@ovn.org> X-Mailer: git-send-email 2.10.2 X-Spam-Status: No, score=-0.7 required=5.0 tests=RCVD_IN_DNSWL_LOW autolearn=disabled version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Cc: Ben Pfaff Subject: [ovs-dev] [PATCH] faq: Better document how to add vendor extensions. X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org Signed-off-by: Ben Pfaff Acked-by: Yi-Hung Wei --- Documentation/faq/contributing.rst | 44 +++++++++++++++++++++++++++----------- include/openvswitch/ofp-errors.h | 4 +++- 2 files changed, 34 insertions(+), 14 deletions(-) diff --git a/Documentation/faq/contributing.rst b/Documentation/faq/contributing.rst index 6dfc8bc4d436..d59376cd615c 100644 --- a/Documentation/faq/contributing.rst +++ b/Documentation/faq/contributing.rst @@ -33,22 +33,28 @@ Q: How do I implement a new OpenFlow message? as needed. (If you configure with ``--enable-Werror``, as described in :doc:`/intro/install/general`, then it is impossible to miss any warnings.) - If you need to add an OpenFlow vendor extension message for a vendor that - doesn't yet have any extension messages, then you will also need to edit - ``build-aux/extract-ofp-msgs``. + To add an OpenFlow vendor extension message (aka experimenter message) for + a vendor that doesn't yet have any extension messages, you will also need + to edit ``build-aux/extract-ofp-msgs`` and at least ``ofphdrs_decode()`` + and ``ofpraw_put__()`` in ``lib/ofp-msgs.c``. OpenFlow doesn't standardize + vendor extensions very well, so it's hard to make the process simpler than + that. (If you have a choice of how to design your vendor extension + messages, it will be easier if you make them resemble the ONF and OVS + extension messages.) Q: How do I add support for a new field or header? A: Add new members for your field to ``struct flow`` in ``lib/flow.h``, and add new enumerations for your new field to ``enum mf_field_id`` in - ``lib/meta-flow.h``, following the existing pattern. Also, add support to - ``miniflow_extract()`` in ``lib/flow.c`` for extracting your new field from - a packet into struct miniflow, and to ``nx_put_raw()`` in - ``lib/nx-match.c`` to output your new field in OXM matches. Then recompile - and fix all of the new warnings, implementing new functionality for the new - field or header as needed. (If you configure with ``--enable-Werror``, as - described in :doc:`/intro/install/general`, then it is impossible to miss - any warnings.) + ``lib/meta-flow.h``, following the existing pattern. If the field uses a + new OXM class, add it to OXM_CLASSES in ``build-aux/extract-ofp-fields``. + Also, add support to ``miniflow_extract()`` in ``lib/flow.c`` for + extracting your new field from a packet into struct miniflow, and to + ``nx_put_raw()`` in ``lib/nx-match.c`` to output your new field in OXM + matches. Then recompile and fix all of the new warnings, implementing new + functionality for the new field or header as needed. (If you configure + with ``--enable-Werror``, as described in :doc:`/intro/install/general`, + then it is impossible to miss any warnings.) If you want kernel datapath support for your new field, you also need to modify the kernel module for the operating systems you are interested in. @@ -71,5 +77,17 @@ Q: How do I add support for a new OpenFlow action? warnings.) If you need to add an OpenFlow vendor extension action for a vendor that - doesn't yet have any extension actions, then you will also need to edit - ``build-aux/extract-ofp-actions``. + doesn't yet have any extension actions, then you will also need to add the + vendor to ``vendor_map`` in ``build-aux/extract-ofp-actions``. Also, you + will need to add support for the vendor to ``ofpact_decode_raw()`` and + ``ofpact_put_raw()`` in ``lib/ofp-actions.c``. (If you have a choice of + how to design your vendor extension actions, it will be easier if you make + them resemble the ONF and OVS extension actions.) + +Q: How do I add support for a new OpenFlow error message? + + A: Add your new error to ``enum ofperr`` in + ``include/openvswitch/ofp-errors.h``. Read the large comment at the top of + the file for details. If you need to add an OpenFlow vendor extension + error for a vendor that doesn't yet have any, first add the vendor ID to + the ``_VENDOR_ID`` list in ``include/openflow/openflow-common.h``. diff --git a/include/openvswitch/ofp-errors.h b/include/openvswitch/ofp-errors.h index 3d09be354af9..5e20e1adb7cd 100644 --- a/include/openvswitch/ofp-errors.h +++ b/include/openvswitch/ofp-errors.h @@ -60,7 +60,9 @@ struct ofpbuf; * type, and sometimes a code for each protocol that supports the error: * * # The vendor is OF for standard OpenFlow error codes. Otherwise it - * is one of the *_VENDOR_ID codes defined in openflow-common.h. + * is one of the *_VENDOR_ID codes defined in openflow-common.h. (To + * add support for a new vendor, add a VENDOR_ID code to that + * header.) * * # The version can specify a specific OpenFlow version, a version * range delimited by "-", or an open-ended range with "+".