| # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) |
| %YAML 1.2 |
| --- |
| $id: http://kernel.org/schemas/netlink/genetlink-c.yaml# |
| $schema: https://json-schema.org/draft-07/schema |
| |
| # Common defines |
| $defs: |
| uint: |
| type: integer |
| minimum: 0 |
| len-or-define: |
| type: [ string, integer ] |
| pattern: ^[0-9A-Za-z_-]+( - 1)?$ |
| minimum: 0 |
| len-or-limit: |
| # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc. |
| type: [ string, integer ] |
| pattern: ^[su](8|16|32|64)-(min|max)$ |
| minimum: 0 |
| |
| # Schema for specs |
| title: Protocol |
| description: Specification of a genetlink protocol |
| type: object |
| required: [ name, doc, attribute-sets, operations ] |
| additionalProperties: False |
| properties: |
| name: |
| description: Name of the genetlink family. |
| type: string |
| doc: |
| type: string |
| protocol: |
| description: Schema compatibility level. Default is "genetlink". |
| enum: [ genetlink, genetlink-c ] |
| uapi-header: |
| description: Path to the uAPI header, default is linux/${family-name}.h |
| type: string |
| # Start genetlink-c |
| c-family-name: |
| description: Name of the define for the family name. |
| type: string |
| c-version-name: |
| description: Name of the define for the version of the family. |
| type: string |
| max-by-define: |
| description: Makes the number of attributes and commands be specified by a define, not an enum value. |
| type: boolean |
| cmd-max-name: |
| description: Name of the define for the last operation in the list. |
| type: string |
| cmd-cnt-name: |
| description: The explicit name for constant holding the count of operations (last operation + 1). |
| type: string |
| # End genetlink-c |
| |
| definitions: |
| description: List of type and constant definitions (enums, flags, defines). |
| type: array |
| items: |
| type: object |
| required: [ type, name ] |
| additionalProperties: False |
| properties: |
| name: |
| type: string |
| header: |
| description: For C-compatible languages, header which already defines this value. |
| type: string |
| type: |
| enum: [ const, enum, flags ] |
| doc: |
| type: string |
| # For const |
| value: |
| description: For const - the value. |
| type: [ string, integer ] |
| # For enum and flags |
| value-start: |
| description: For enum or flags the literal initializer for the first value. |
| type: [ string, integer ] |
| entries: |
| description: For enum or flags array of values. |
| type: array |
| items: |
| oneOf: |
| - type: string |
| - type: object |
| required: [ name ] |
| additionalProperties: False |
| properties: |
| name: |
| type: string |
| value: |
| type: integer |
| doc: |
| type: string |
| render-max: |
| description: Render the max members for this enum. |
| type: boolean |
| # Start genetlink-c |
| enum-name: |
| description: Name for enum, if empty no name will be used. |
| type: [ string, "null" ] |
| name-prefix: |
| description: For enum the prefix of the values, optional. |
| type: string |
| # End genetlink-c |
| |
| attribute-sets: |
| description: Definition of attribute spaces for this family. |
| type: array |
| items: |
| description: Definition of a single attribute space. |
| type: object |
| required: [ name, attributes ] |
| additionalProperties: False |
| properties: |
| name: |
| description: | |
| Name used when referring to this space in other definitions, not used outside of the spec. |
| type: string |
| name-prefix: |
| description: | |
| Prefix for the C enum name of the attributes. Default family[name]-set[name]-a- |
| type: string |
| enum-name: |
| description: | |
| Name for the enum type of the attribute, if empty no name will be used. |
| type: [ string, "null" ] |
| doc: |
| description: Documentation of the space. |
| type: string |
| subset-of: |
| description: | |
| Name of another space which this is a logical part of. Sub-spaces can be used to define |
| a limited group of attributes which are used in a nest. |
| type: string |
| # Start genetlink-c |
| attr-cnt-name: |
| description: The explicit name for constant holding the count of attributes (last attr + 1). |
| type: string |
| attr-max-name: |
| description: The explicit name for last member of attribute enum. |
| type: string |
| # End genetlink-c |
| attributes: |
| description: List of attributes in the space. |
| type: array |
| items: |
| type: object |
| required: [ name ] |
| additionalProperties: False |
| properties: |
| name: |
| type: string |
| type: &attr-type |
| enum: [ unused, pad, flag, binary, |
| uint, sint, u8, u16, u32, u64, s32, s64, |
| string, nest, array-nest, nest-type-value ] |
| doc: |
| description: Documentation of the attribute. |
| type: string |
| value: |
| description: Value for the enum item representing this attribute in the uAPI. |
| $ref: '#/$defs/uint' |
| type-value: |
| description: Name of the value extracted from the type of a nest-type-value attribute. |
| type: array |
| items: |
| type: string |
| byte-order: |
| enum: [ little-endian, big-endian ] |
| multi-attr: |
| type: boolean |
| nested-attributes: |
| description: Name of the space (sub-space) used inside the attribute. |
| type: string |
| enum: |
| description: Name of the enum type used for the attribute. |
| type: string |
| enum-as-flags: |
| description: | |
| Treat the enum as flags. In most cases enum is either used as flags or as values. |
| Sometimes, however, both forms are necessary, in which case header contains the enum |
| form while specific attributes may request to convert the values into a bitfield. |
| type: boolean |
| checks: |
| description: Kernel input validation. |
| type: object |
| additionalProperties: False |
| properties: |
| flags-mask: |
| description: Name of the flags constant on which to base mask (unsigned scalar types only). |
| type: string |
| min: |
| description: Min value for an integer attribute. |
| $ref: '#/$defs/len-or-limit' |
| max: |
| description: Max value for an integer attribute. |
| $ref: '#/$defs/len-or-limit' |
| min-len: |
| description: Min length for a binary attribute. |
| $ref: '#/$defs/len-or-define' |
| max-len: |
| description: Max length for a string or a binary attribute. |
| $ref: '#/$defs/len-or-define' |
| exact-len: |
| description: Exact length for a string or a binary attribute. |
| $ref: '#/$defs/len-or-define' |
| unterminated-ok: |
| description: | |
| For string attributes, do not check whether attribute |
| contains the terminating null character. |
| type: boolean |
| sub-type: *attr-type |
| display-hint: &display-hint |
| description: | |
| Optional format indicator that is intended only for choosing |
| the right formatting mechanism when displaying values of this |
| type. |
| enum: [ hex, mac, fddi, ipv4, ipv6, uuid ] |
| # Start genetlink-c |
| name-prefix: |
| type: string |
| # End genetlink-c |
| |
| # Make sure name-prefix does not appear in subsets (subsets inherit naming) |
| dependencies: |
| name-prefix: |
| not: |
| required: [ subset-of ] |
| subset-of: |
| not: |
| required: [ name-prefix ] |
| |
| # type property is only required if not in subset definition |
| if: |
| properties: |
| subset-of: |
| not: |
| type: string |
| then: |
| properties: |
| attributes: |
| items: |
| required: [ type ] |
| |
| operations: |
| description: Operations supported by the protocol. |
| type: object |
| required: [ list ] |
| additionalProperties: False |
| properties: |
| enum-model: |
| description: | |
| The model of assigning values to the operations. |
| "unified" is the recommended model where all message types belong |
| to a single enum. |
| "directional" has the messages sent to the kernel and from the kernel |
| enumerated separately. |
| enum: [ unified ] |
| name-prefix: |
| description: | |
| Prefix for the C enum name of the command. The name is formed by concatenating |
| the prefix with the upper case name of the command, with dashes replaced by underscores. |
| type: string |
| enum-name: |
| description: | |
| Name for the enum type with commands, if empty no name will be used. |
| type: [ string, "null" ] |
| async-prefix: |
| description: Same as name-prefix but used to render notifications and events to separate enum. |
| type: string |
| async-enum: |
| description: | |
| Name for the enum type with commands, if empty no name will be used. |
| type: [ string, "null" ] |
| list: |
| description: List of commands |
| type: array |
| items: |
| type: object |
| additionalProperties: False |
| required: [ name, doc ] |
| properties: |
| name: |
| description: Name of the operation, also defining its C enum value in uAPI. |
| type: string |
| doc: |
| description: Documentation for the command. |
| type: string |
| value: |
| description: Value for the enum in the uAPI. |
| $ref: '#/$defs/uint' |
| attribute-set: |
| description: | |
| Attribute space from which attributes directly in the requests and replies |
| to this command are defined. |
| type: string |
| flags: &cmd_flags |
| description: Command flags. |
| type: array |
| items: |
| enum: [ admin-perm ] |
| dont-validate: |
| description: Kernel attribute validation flags. |
| type: array |
| items: |
| enum: [ strict, dump, dump-strict ] |
| config-cond: |
| description: | |
| Name of the kernel config option gating the presence of |
| the operation, without the 'CONFIG_' prefix. |
| type: string |
| do: &subop-type |
| description: Main command handler. |
| type: object |
| additionalProperties: False |
| properties: |
| request: &subop-attr-list |
| description: Definition of the request message for a given command. |
| type: object |
| additionalProperties: False |
| properties: |
| attributes: |
| description: | |
| Names of attributes from the attribute-set (not full attribute |
| definitions, just names). |
| type: array |
| items: |
| type: string |
| reply: *subop-attr-list |
| pre: |
| description: Hook for a function to run before the main callback (pre_doit or start). |
| type: string |
| post: |
| description: Hook for a function to run after the main callback (post_doit or done). |
| type: string |
| dump: *subop-type |
| notify: |
| description: Name of the command sharing the reply type with this notification. |
| type: string |
| event: |
| type: object |
| additionalProperties: False |
| properties: |
| attributes: |
| description: Explicit list of the attributes for the notification. |
| type: array |
| items: |
| type: string |
| mcgrp: |
| description: Name of the multicast group generating given notification. |
| type: string |
| mcast-groups: |
| description: List of multicast groups. |
| type: object |
| required: [ list ] |
| additionalProperties: False |
| properties: |
| list: |
| description: List of groups. |
| type: array |
| items: |
| type: object |
| required: [ name ] |
| additionalProperties: False |
| properties: |
| name: |
| description: | |
| The name for the group, used to form the define and the value of the define. |
| type: string |
| # Start genetlink-c |
| c-define-name: |
| description: Override for the name of the define in C uAPI. |
| type: string |
| # End genetlink-c |
| flags: *cmd_flags |
| |
| kernel-family: |
| description: Additional global attributes used for kernel C code generation. |
| type: object |
| additionalProperties: False |
| properties: |
| headers: |
| description: | |
| List of extra headers which should be included in the source |
| of the generated code. |
| type: array |
| items: |
| type: string |
| sock-priv: |
| description: | |
| Literal name of the type which is used within the kernel |
| to store the socket state. The type / structure is internal |
| to the kernel, and is not defined in the spec. |
| type: string |
