1.. SPDX-License-Identifier: CC-BY-4.0
2
3Properties list for Xen
4=======================
5
6Some functions and macros are found to have properties relevant to
7the Xen codebase. For this reason, the file docs/properties.json
8contains all the needed properties.
9
10Here is an example of the properties.json file::
11
12  {
13     "version": "1.0",
14     "content": [
15        {
16           "description": ""
17           "type": "function",       // required
18           "value:": "^printk*.$",   // required
19           "properties":{
20              "pointee_write": "1..2=never",
21              "pointee_read": "",
22              "taken": ""
23              "attribute": ""
24           }
25        }
26     ]
27  }
28
29Here is an explanation of the fields inside an object of the "content" array:
30
31 - description: a brief description of why the properties apply
32 - type: this is the kind of the element called: it may be either ``macro`` or ``function``
33 - value: must be a regex, starting with ^ and ending with $ and matching function fully
34   qualified name or macro name.
35 - properties: a list of properties applied to said function.
36   Possible values are:
37
38    - pointee_write: indicate the write use for call arguments that correspond to
39      parameters whose pointee types are non-const
40    - pointee_read: indicate the read use for call arguments that correspond to
41      parameters whose pointee types are non-const
42    - taken: indicates that the specified address arguments may be stored in objects
43      that persist after the function has ceased to exist (excluding the returned value);
44      address arguments not listed are never taken
45    - attribute: attributes a function may have. Possible values are pure, const and noeffect.
46
47   pointee_read and pointee_write use a specific kind of argument, structured as pointee_arg=rw:
48
49    - pointee_arg: argument index for callee. Index 0 refers to the return value,
50      the indices of the arguments start from 1. It can be either a single value or a range.
51    - rw: a value that's either always, maybe or never
52
53       - always: for pointee_read: argument pointee is expected to be fully read in the function body,
54         for pointee_write: argument pointee is fully initialized at function exit
55       - maybe: for pointee_read: argument pointee may be expected to be read in the function body,
56         for pointee_write: argument pointee may be written by function body
57       - never: for pointee_read: argument pointee is not expected to be read in the function body,
58         for pointee_write: argument pointee is never written by function body
59