[RFC net-next 1/4] doc/netlink: Add batch op definitions to netlink-raw schema

[Donald Hunter <donald.hunter@gmail.com>]

The nftables netlink families use batch operations for create update and
delete operations. Extend the netlink-raw schema so that operations can
be marked as batch ops. Add definitions of the begin-batch and end-batch
messages.

The begin/end messages themselves are defined as ordinary ops, but there
are new attributes that describe the op name and parameters for the
begin/end messages.

The section of yaml spec that defines the begin/end ops looks like this;
the newtable op is marked 'is-batch: true' so the message needs to be
wrapped with 'batch-begin(res-id: 10)' and batch-end(res-id: 10) messages:

operations:
  enum-model: directional
  begin-batch:
    operation: batch-begin
    parameters:
      res-id: 10
  end-batch:
    operation: batch-end
    parameters:
      res-id: 10
  list:
    -
      name: batch-begin
      doc: Start a batch of operations
      attribute-set: batch-attrs
      fixed-header: nfgenmsg
      do:
        request:
          value: 0x10
          attributes:
            - genid
        reply:
          value: 0x10
          attributes:
            - genid
    -
      name: batch-end
      doc: Finish a batch of operations
      attribute-set: batch-attrs
      fixed-header: nfgenmsg
      do:
        request:
          value: 0x11
          attributes:
            - genid
    -
      name: newtable
      doc: Create a new table.
      attribute-set: table-attrs
      fixed-header: nfgenmsg
      do:
        request:
          value: 0xa00
          is-batch: True
          attributes:
            - name

Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
---
 Documentation/netlink/netlink-raw.yaml | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml
index ac4e05415f2f..eb35fee44898 100644
--- a/Documentation/netlink/netlink-raw.yaml
+++ b/Documentation/netlink/netlink-raw.yaml
@@ -446,6 +446,11 @@ properties:
                         i.e. requests and responses have different message enums.
                       $ref: '#/$defs/uint'
                     # End genetlink-legacy
+                    # Start netlink-raw
+                    is-batch:
+                      description: Must be part of a message batch
+                      type: boolean
+                    # End netlink-raw
                 reply: *subop-attr-list
                 pre:
                   description: Hook for a function to run before the main callback (pre_doit or start).
@@ -469,6 +474,22 @@ properties:
             mcgrp:
               description: Name of the multicast group generating given notification.
               type: string
+      # Start netlink-raw
+      begin-batch: &batch-params
+        description: Definition of a message call for a batch message
+        type: object
+        additionalProperties: False
+        properties:
+          operation:
+            description: Name of the operation
+            type: string
+          parameters:
+            description: Parameters for the operation
+            type: object
+            items:
+              type: object
+      end-batch: *batch-params
+      # End netlink-raw
   mcast-groups:
     description: List of multicast groups.
     type: object
-- 
2.42.0