lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <YzVUJI11/1Cj7IL9@debian.me>
Date:   Thu, 29 Sep 2022 15:15:32 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     Jakub Kicinski <kuba@...nel.org>
Cc:     davem@...emloft.net, netdev@...r.kernel.org, edumazet@...gle.com,
        pabeni@...hat.com, robh@...nel.org, johannes@...solutions.net,
        ecree.xilinx@...il.com, stephen@...workplumber.org, sdf@...gle.com,
        f.fainelli@...il.com, fw@...len.de, linux-doc@...r.kernel.org,
        razor@...ckwall.org, nicolas.dichtel@...nd.com, gnault@...hat.com
Subject: Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec
 docs)

On Wed, Sep 28, 2022 at 06:11:17PM -0700, Jakub Kicinski wrote:
> diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst
> new file mode 100644
> index 000000000000..d0ec83df6b6b
> --- /dev/null
> +++ b/Documentation/core-api/netlink.rst
> @@ -0,0 +1,99 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> +
> +.. _kernel_netlink:
> +
> +===================================
> +Netlink notes for kernel developers
> +===================================
> +
> +General guidance
> +================
> +
> +Attribute enums
> +---------------
> +
> +Older families often define "null" attributes and commands with value
> +of ``0`` and named ``unspec``. This is supported (``type: unspec``)
> +but should be avoided in new families. The ``unspec`` enum values are
> +not used in practice, so just set the value of the first attribute to ``1``.
> +
> +Message enums
> +-------------
> +
> +Use the same command IDs for requests and replies. This makes it easier
> +to match them up, and we have plenty ID space.
> +

s/plenty/plenty of/

> +Use separate command IDs for notifications. This makes it easier to
> +sort the notifications from replies (and present them to the user
> +application via a different API than replies).
> +
> +Answer requests
> +---------------
> +
> +Older families do not reply to all of the commands, especially NEW / ADD
> +commands. User only gets information whether the operation succeeded or
> +not via the ACK. Try to find useful data to return. Once the command is
> +added whether it replies with a full message or only an ACK is uAPI and
> +cannot be changed. It's better to err on the side of replying.
> +
> +Specifically NEW and ADD commands should reply with information identifying
> +the created object such as the allocated object's ID.
> +
> +Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
> +
> +NLM_F_ECHO
> +----------
> +
> +Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> +to take effect.
> +
> +Support dump consistency
> +------------------------
> +
> +If iterating over objects during dump may skip over objects or repeat
> +them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``.
> +
> +Netlink specification
> +=====================
> +
> +Documentation of the Netlink specification parts which are only relevant
> +to the kernel space.
> +
> +Globals
> +-------
> +
> +kernel-policy
> +~~~~~~~~~~~~~
> +
> +Defines if the kernel validation policy is per operation (``per-op``)
> +or for the entire family (``global``). New families should use ``per-op``
> +(default) to be able to narrow down the attributes accepted by a specific
> +command.
> +
> +checks
> +------
> +
> +Documentation for the ``checks`` sub-sections of attribute specs.
> +
> +unterminated-ok
> +~~~~~~~~~~~~~~~
> +
> +Accept strings without the null-termination (for legacy families only).
> +Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type.
> +
> +max-len
> +~~~~~~~
> +
> +Defines max length for a binary or string attribute (corresponding
> +to the ``len`` member of struct nla_policy). For string attributes terminating
> +null character is not counted towards ``max-len``.
> +
> +The field may either be a literal integer value or a name of a defined
> +constant. String types may reduce the constant by one
> +(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating
> +character so implementations should recognize such pattern.
> +
> +min-len
> +~~~~~~~
> +
> +Similar to ``max-len`` but defines minimum length.

Otherwise this doc is LGTM.

> diff --git a/Documentation/userspace-api/netlink/c-code-gen.rst b/Documentation/userspace-api/netlink/c-code-gen.rst
> new file mode 100644
> index 000000000000..7c6a86f9ceb9
> --- /dev/null
> +++ b/Documentation/userspace-api/netlink/c-code-gen.rst
> @@ -0,0 +1,104 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> +
> +==============================
> +Netlink spec C code generation
> +==============================
> +
> +This document describes how Netlink specifications are used to render
> +C code (uAPI, policies etc.). It also defines the additional properties
> +allowed in older families by the ``genetlink-c`` protocol level,
> +to control the naming.
> +
> +For brevity this document refers to ``name`` properties of various
> +objects by the object type. For example ``$attr`` is the value
> +of ``name`` in an attribute, and ``$family`` is the name of the
> +family (the global ``name`` property).
> +
> +The upper case is used to denote literal values, e.g. ``$family-CMD``
> +means the concatenation of ``$family``, a dash character, and the literal
> +``CMD``.
> +
> +The names of ``#defines`` and enum values are always converted to upper case,
> +and with dashes (``-``) replaced by underscores (``_``).
> +
> +If the constructured name is a C keyword, an extra underscore is
> +appended (``do`` -> ``do_``).
> +
> +Globals
> +=======
> +
> +``c-family-name`` controls the name of the ``#define`` for the family
> +name, default is ``$family-FAMILY-NAME``.
> +
> +``c-version-name`` controls the name of the ``#define`` for the version
> +of the family, default is ``$family-FAMILY-VERSION``.
> +
> +``max-by-define`` selects if max values for enums are defined as a
> +``#define`` rather than inside the enum.
> +
> +Definitions
> +===========
> +
> +Constants
> +---------
> +
> +Every constant is rendered as a ``#define``.
> +The name of the constant is ``$family-$constant`` and the value
> +is rendered as a string or integer according to its type in the spec.
> +
> +Enums and flags
> +---------------
> +
> +Enums are named ``$family-$enum``. The full name can be set directly
> +or suppressed by specifying the ``enum-name`` property.
> +Default entry name is ``$family-$enum-$entry``.
> +If ``name-prefix`` is specified it replaces the ``$family-$enum``
> +portion of the entry name.
> +
> +Attributes
> +==========
> +
> +Each attribute set (excluding fractional sets) is rendered as an enum.
> +
> +Attribute enums are traditionally unnamed in netlink headers.
> +If naming is desired ``enum-name`` can be used to specify the name.
> +
> +The default attribute name prefix is ``$family-A`` if the name of the set
> +is the same as the name of the family and ``$family-A-$set`` if the names
> +differ. The prefix can be overridden by the ``name-prefix`` property of a set.
> +The rest of the section will refer to the prefix as ``$pfx``.
> +
> +Attributes are named ``$pfx-$attribute``.
> +
> +Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX``
> +which are used for sizing attribute tables.
> +These two names can be specified directly with the ``attr-cnt-name``
> +and ``attr-max-name`` properties respectively.
> +
> +If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name``
> +will be specified as a ``#define`` rather than an enum value.
> +
> +Operations
> +==========
> +
> +Operations are named ``$family-CMD-$operation``.
> +If ``name-prefix`` is specified it replaces the ``$family-CMD``
> +portion of the name.
> +
> +Similarly to attribute enums operation enums end with special count and max
> +attributes. For operations those attributes can be renamed with
> +``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define``
> +is ``true``.
> +
> +Multicast groups
> +================
> +
> +Each multicast group gets a define rendered into the kernel uAPI header.
> +The name of the define is ``$family-MCGRP-$group``, and can be overwritten
> +with the ``c-define-name`` property.
> +
> +Code generation
> +===============
> +
> +uAPI header is assumed to come from ``<linux/$family.h>`` in the default header
> +search path. It can be changed using the ``uapi-header`` global property.

LGTM (grammar and formatting).

> diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst
> new file mode 100644
> index 000000000000..65cbbffee0bf
> --- /dev/null
> +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst
> @@ -0,0 +1,96 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> +
> +=================================================================
> +Netlink specification support for legacy Generic Netlink families
> +=================================================================
> +
> +This document describes the many additional quirks and properties
> +required to describe older Generic Netlink families which form
> +the ``genetlink-legacy`` protocol level.
> +
> +The spec is a work in progress, some of the quirks are just documented
> +for future reference.
> +
> +Specification (defined)
> +=======================
> +
> +Attribute type nests
> +--------------------
> +
> +New Netlink families should use ``multi-attr`` to define arrays.
> +Older families (e.g. ``genetlink`` control family) attempted to
> +define array types reusing attribute type to carry information.
> +
> +For reference the ``multi-attr`` array may look like this::
> +
> +  [ARRAY-ATTR]
> +    [INDEX (optionally)]
> +    [MEMBER1]
> +    [MEMBER2]
> +  [SOME-OTHER-ATTR]
> +  [ARRAY-ATTR]
> +    [INDEX (optionally)]
> +    [MEMBER1]
> +    [MEMBER2]
> +
> +where ``ARRAY-ATTR`` is the array entry type.
> +
> +array-nest
> +~~~~~~~~~~
> +
> +``array-nest`` creates the following structure::
> +
> +  [SOME-OTHER-ATTR]
> +  [ARRAY-ATTR]
> +    [ENTRY]
> +      [MEMBER1]
> +      [MEMBER2]
> +    [ENTRY]
> +      [MEMBER1]
> +      [MEMBER2]
> +
> +It wraps the entire array in an extra attribute (hence limiting its size
> +to 64kB). The ``ENTRY`` nests are special and have the index of the entry
> +as their type instead of normal attribute type.
> +
> +type-value
> +~~~~~~~~~~
> +
> +``type-value`` is a construct which uses attribute types to carry
> +information about a single object (often used when array is dumped
> +entry-by-entry).
> +
> +``type-value`` can have multiple levels of nesting, for example
> +genetlink's policy dumps create the following structures::
> +
> +  [POLICY-IDX]
> +    [ATTR-IDX]
> +      [POLICY-INFO-ATTR1]
> +      [POLICY-INFO-ATTR2]
> +
> +Where the first level of nest has the policy index as it's attribute
> +type, it contains a single nest which has the attribute index as its
> +type. Inside the attr-index nest are the policy attributes. Modern
> +Netlink families should have instead defined this as a flat structure,
> +the nesting serves no good purpose here.
> +
> +Other quirks (todo)
> +===================
> +
> +Structures
> +----------
> +
> +Legacy families can define C structures both to be used as the contents
> +of an attribute and as a fixed message header. The plan is to define
> +the structs in ``definitions`` and link the appropriate attrs.
> +
> +Multi-message DO
> +----------------
> +
> +New Netlink families should never respond to a DO operation with multiple
> +replies, with ``NLM_F_MULTI`` set. Use a filtered dump instead.
> +
> +At the spec level we can define a ``dumps`` property for the ``do``,
> +perhaps with values of ``combine`` and ``multi-object`` depending
> +on how the parsing should be implemented (parse into a single reply
> +vs list of objects i.e. pretty much a dump).

LGTM (grammar and formatting).

> diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst
> index b0c21538d97d..be250110c8f6 100644
> --- a/Documentation/userspace-api/netlink/index.rst
> +++ b/Documentation/userspace-api/netlink/index.rst
> @@ -10,3 +10,8 @@ Netlink documentation for users.
>     :maxdepth: 2
>  
>     intro
> +   specs
> +   c-code-gen
> +   genetlink-legacy
> +
> +See also :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`.
> diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst
> new file mode 100644
> index 000000000000..49f2f782f537
> --- /dev/null
> +++ b/Documentation/userspace-api/netlink/specs.rst
> @@ -0,0 +1,410 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> +
> +=========================================
> +Netlink protocol specifications (in YAML)
> +=========================================
> +
> +Netlink protocol specifications are complete, machine readable descriptions of
> +Netlink protocols written in YAML. The goal of the specifications is to allow
> +separating Netlink parsing from user space logic and minimize the amount of
> +hand written Netlink code for each new family, command, attribute.
> +Netlink specs should be complete and not depend on any other spec
> +or C header file, making it easy to use in languages which can't include
> +kernel headers directly.
> +
> +Internally kernel uses the YAML specs to generate:
> +
> + - the C uAPI header
> + - documentation of the protocol as a ReST file
> + - policy tables for input attribute validation
> + - operation tables
> +
> +YAML specifications can be found under ``Documentation/netlink/specs/``
> +
> +Compatibility levels
> +====================
> +
> +There are four schema levels for Netlink specs, from the simplest used
> +by new families to the most complex covering all the quirks of the old ones.
> +Each next level inherits the attributes of the previous level, meaning that
> +user capable of parsing more complex ``genetlink`` schemas is also compatible
> +with simpler ones. The levels are:
> +
> + - ``genetlink`` - most streamlined, should be used by all new families
> + - ``genetlink-c`` - superset of ``genetlink`` with extra attributes allowing
> +   customization of define and enum type and value names; this schema should
> +   be equivalent to ``genetlink`` for all implementations which don't interact
> +   directly with C uAPI headers
> + - ``genetlink-legacy`` - Generic Netlink catch all schema supporting quirks of
> +   all old genetlink families, strange attribute formats, binary structures etc.
> + - ``netlink-raw`` - catch all schema supporting pre-Generic Netlink protocols
> +   such as ``NETLINK_ROUTE``
> +
> +The definition of the schemas (in ``jsonschema``) can be found
> +under ``Documentation/netlink/``.
> +
> +Schema structure
> +================
> +
> +YAML schema has the following conceptual sections:
> +
> + - globals
> + - definitions
> + - attributes
> + - operations
> + - multicast groups
> +
> +Most properties in the schema accept (or in fact require) a ``doc``
> +sub-property documenting the defined object.
> +
> +The following sections describe the properties of the most modern ``genetlink``
> +schema. See the documentation of :doc:`genetlink-c <c-code-gen>`
> +for information on how C names are derived from name properties.
> +
> +genetlink
> +=========
> +
> +Globals
> +-------
> +
> +Attributes listed directly at the root level of the spec file.
> +
> +name
> +~~~~
> +
> +Name of the family. Name identifies the family in a unique way, since
> +the Family IDs are allocated dynamically.
> +
> +version
> +~~~~~~~
> +
> +Generic Netlink family version, default is 1.
> +
> +protocol
> +~~~~~~~~
> +
> +The schema level, default is ``genetlink``, which is the only value
> +allowed for new ``genetlink`` families.
> +
> +definitions
> +-----------
> +
> +Array of type and constant definitions.
> +
> +name
> +~~~~
> +
> +Name of the type / constant.
> +
> +type
> +~~~~
> +
> +One of the following types:
> +
> + - const - a single, standalone constant
> + - enum - defines an integer enumeration, with values for each entry
> +   incrementing by 1, (e.g. 0, 1, 2, 3)
> + - flags - defines an integer enumeration, with values for each entry
> +   occupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8)
> +
> +value
> +~~~~~
> +
> +The value for the ``const``.
> +
> +value-start
> +~~~~~~~~~~~
> +
> +The first value for ``enum`` and ``flags``, allows overriding the default
> +start value of ``0`` (for ``enum``) and starting bit (for ``flags``).
> +For ``flags`` ``value-start`` selects the starting bit, not the shifted value.
> +
> +Sparse enumerations are not supported.
> +
> +entries
> +~~~~~~~
> +
> +Array of names of the entries for ``enum`` and ``flags``.
> +
> +header
> +~~~~~~
> +
> +For C-compatible languages, header which already defines this value.
> +In case the definition is shared by multiple families (e.g. ``IFNAMSIZ``)
> +code generators for C-compabile languages may prefer to add an appropriate
> +include instead of rendering a new definition.
> +
> +attribute-sets
> +--------------
> +
> +This property contains information about netlink attributes of the family.
> +All families have at least one attribute set, most have multiple.
> +``attribute-sets`` is an array, with each entry describing a single set.
> +
> +Note that the spec is "flattened" and is not meant to visually resemble
> +the format of the netlink messages (unlike certain ad-hoc documentation
> +formats seen in kernel comments). In the spec subordinate attribute sets
> +are not defined inline as a nest, but defined in a separate attribute set
> +referred to with a ``nested-attributes`` property of the container.
> +
> +Spec may also contain fractional sets - sets which contain a ``subset-of``
> +property. Such sets describe a section of a full set, allowing narrowing down
> +which attributes are allowed in a nest or refining the validation criteria.
> +Fractional sets can only be used in nests. They are not rendered to the uAPI
> +in any fashion.
> +
> +name
> +~~~~
> +
> +Uniquely identifies the attribute set, operations and nested attributes
> +refer to the sets by the ``name``.
> +
> +subset-of
> +~~~~~~~~~
> +
> +Re-defines a portion of another set (a fractional set).
> +Allows narrowing down fields and changing validation criteria
> +or even types of attributes depending on the nest in which they
> +are contained. The ``value`` of each attribute in the fractional
> +set is implicitly the same as in the main set.
> +
> +attributes
> +~~~~~~~~~~
> +
> +List of attributes in the set.
> +
> +Attribute properties
> +--------------------
> +
> +name
> +~~~~
> +
> +Identifies the attribute, unique within the set.
> +
> +type
> +~~~~
> +
> +Netlink attribute type, see :ref:`attr_types`.
> +
> +.. _assign_val:
> +
> +value
> +~~~~~
> +
> +Numerical attribute ID, used in serialized Netlink messages.
> +The ``value`` property can be skipped, in which case the attribute ID
> +will be the value of the previous attribute plus one (recursively)
> +and ``0`` for the first attribute in the attribute set.
> +
> +Note that the ``value`` of an attribute is defined only in its main set.
> +
> +enum
> +~~~~
> +
> +For integer types specifies that values in the attribute belong to a defined
> +``enum``. Note that in case of ``flags`` the values may be combined.
> +
> +nested-attributes
> +~~~~~~~~~~~~~~~~~
> +
> +Identifies the attribute space for attributes nested within given attribute.
> +Only valid for complex attributes which may have sub-attributes.
> +
> +multi-attr (arrays)
> +~~~~~~~~~~~~~~~~~~~
> +
> +Boolean property signifying that the attribute may be present multiple times.
> +Allowing an attribute to repeat is the recommended way of implementing arrays
> +(no extra nesting).
> +
> +byte-order
> +~~~~~~~~~~
> +
> +For integer types specifies attribute byte order - ``little-endian``
> +or ``big-endian``.
> +
> +checks
> +~~~~~~
> +
> +Input validation constraints used by the kernel. User space should query
> +the policy of the running kernel using Generic Netlink introspection,
> +rather than depend on what is specified in the spec file.
> +
> +The validation policy in the kernel is formed by combining the type
> +definition (``type`` and ``nested-attributes``) and the ``checks``.
> +
> +operations
> +----------
> +
> +This section describes messages passed between the kernel and the user space.
> +There are three types of entries in this section - operations, notifications
> +and events.
> +
> +Operations describe the most common request - response communication. User
> +sends a request and kernel replies. Each operation may contain any combination
> +of the two modes familiar to netlink users - ``do`` and ``dump``.
> +``do`` and ``dump`` in turn contain a combination of ``request`` and
> +``response`` properties. If no explicit message with attributes is passed
> +in a given direction (e.g. a ``dump`` which does not accept filter, or a ``do``
> +of a SET operation to which the kernel responds with just the netlink error
> +code) ``request`` or ``response`` section can be skipped.
> +``request`` and ``response`` sections list the attributes allowed in a message.
> +The list contains only the names of attributes from a set referred
> +to by the ``attribute-set`` property.
> +
> +Notifications and events both refer to the asynchronous messages sent by
> +the kernel to members of a multicast group. The difference between the
> +two is that a notification shares its contents with a GET operation
> +(the name of the GET operation is specified in the ``notify`` property).
> +This arrangement is commonly used for notifications about
> +objects where the notification carries the full object definition.
> +
> +Events are more focused and carry only a subset of information rather than full
> +object state (a made up example would be a link state change event with just
> +the interface name and the new link state). Events contain the ``event``
> +property. Events are considered less idiomatic for netlink and notifications
> +should be preferred.
> +
> +list
> +~~~~
> +
> +The only property of ``operations`` for ``genetlink``, holds the list of
> +operations, notifications etc.
> +
> +Operation properties
> +--------------------
> +
> +name
> +~~~~
> +
> +Identifies the operation.
> +
> +value
> +~~~~~
> +
> +Numerical message ID, used in serialized Netlink messages.
> +The same enumeration rules are applied as to
> +:ref:`attribute values<assign_val>`.
> +
> +attribute-set
> +~~~~~~~~~~~~~
> +
> +Specifies the attribute set contained within the message.
> +
> +do
> +~~~
> +
> +Specification for the ``doit`` request. Should contain ``request``, ``reply``
> +or both of these properties, each holding a :ref:`attr_list`.
> +
> +dump
> +~~~~
> +
> +Specification for the ``dumpit`` request. Should contain ``request``, ``reply``
> +or both of these properties, each holding a :ref:`attr_list`.
> +
> +notify
> +~~~~~~
> +
> +Designates the message as a notification. Contains the name of the operation
> +(possibly the same as the operation holding this property) which shares
> +the contents with the notification (``do``).
> +
> +event
> +~~~~~
> +
> +Specification of attributes in the event, holds a :ref:`attr_list`.
> +``event`` property is mutually exclusive with ``notify``.
> +
> +mcgrp
> +~~~~~
> +
> +Used with ``event`` and ``notify``, specifies which multicast group
> +message belongs to.
> +
> +.. _attr_list:
> +
> +Message attribute list
> +----------------------
> +
> +``request``, ``reply`` and ``event`` properties have a single ``attributes``
> +property which holds the list of attribute names.
> +
> +mcast-groups
> +------------
> +
> +This section lists the multicast groups of the family.
> +
> +list
> +~~~~
> +
> +The only property of ``mcast-groups`` for ``genetlink``, holds the list
> +of groups.
> +
> +Multicast group properties
> +--------------------------
> +
> +name
> +~~~~
> +
> +Uniquely identifies the multicast group in the family. Similarly to
> +Family ID, Multicast Group ID needs to be resolved at runtime, based
> +on the name.
> +
> +.. _attr_types:
> +
> +Attribute types
> +===============
> +
> +This section describes the attribute types supported by the ``genetlink``
> +compatibility level. Refer to documentation of different levels for additional
> +attribute types.
> +
> +Scalar integer types
> +--------------------
> +
> +Fixed-width integer types:
> +``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``.
> +
> +Note that types smaller than 32 bit should be avoided as using them
> +does not save any memory in Netlink messages (due to alignment).
> +See :ref:`pad_type` for padding of 64 bit attributes.
> +
> +The payload of the attribute is the integer in host order unless ``byte-order``
> +specifies otherwise.
> +
> +.. _pad_type:
> +
> +pad
> +---
> +
> +Special attribute type used for padding attributes which require alignment
> +bigger than standard 4B alignment required by netlink (e.g. 64 bit integers).
> +There can only be a single attribute of the ``pad`` type in any attribute set
> +and it should be automatically used for padding when needed.
> +
> +flag
> +----
> +
> +Attribute with no payload, its presence is the entire information.
> +
> +binary
> +------
> +
> +Raw binary data attribute, the contents are opaque to generic code.
> +
> +string
> +------
> +
> +Character string. Unless ``checks`` has ``unterminated-ok`` set to ``true``
> +the string is required to be null terminated.
> +``max-len`` in ``checks`` indicates the longest possible string,
> +if not present the length of the string is unbounded.
> +
> +Note that ``max-len`` does not count the terminating character.
> +
> +nest
> +----
> +
> +Attribute containing other (nested) attributes.
> +``nested-attributes`` specifies which attribute set is used inside.

LGTM (grammar and formatting).

All docs have been reviewed, thanks.

Reviewed-by: Bagas Sanjaya <bagasdotme@...il.com>

-- 
An old man doll... just what I always wanted! - Clara

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ