mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 02:01:24 +01:00
Maria Celeste Cesario
f4519ee87e
Function and macro properties contained in ECLAIR/call_properties.ecl are of general interest: this patch moves these annotations in a generaric JSON file in docs. In this way, they can be exploited for other purposes (i.e. documentation, other tools). Add rst file containing explanation on how to update function_macro_properties.json. Add script to convert the JSON file in ECL configurations. Remove ECLAIR/call_properties.ecl: the file is now automatically generated from the JSON file. Signed-off-by: Maria Celeste Cesario <maria.celeste.cesario@bugseng.com> Signed-off-by: Simone Ballarin <simone.ballarin@bugseng.com> Acked-by: Stefano Stabellini <sstabellini@kernel.org>
59 lines
2.5 KiB
ReStructuredText
59 lines
2.5 KiB
ReStructuredText
.. SPDX-License-Identifier: CC-BY-4.0
|
|
|
|
Properties list for Xen
|
|
=======================
|
|
|
|
Some functions and macros are found to have properties relevant to
|
|
the Xen codebase. For this reason, the file docs/properties.json
|
|
contains all the needed properties.
|
|
|
|
Here is an example of the properties.json file::
|
|
|
|
{
|
|
"version": "1.0",
|
|
"content": [
|
|
{
|
|
"description": ""
|
|
"type": "function", // required
|
|
"value:": "^printk*.$", // required
|
|
"properties":{
|
|
"pointee_write": "1..2=never",
|
|
"pointee_read": "",
|
|
"taken": ""
|
|
"attribute": ""
|
|
}
|
|
}
|
|
]
|
|
}
|
|
|
|
Here is an explanation of the fields inside an object of the "content" array:
|
|
|
|
- description: a brief description of why the properties apply
|
|
- type: this is the kind of the element called: it may be either ``macro`` or ``function``
|
|
- value: must be a regex, starting with ^ and ending with $ and matching function fully
|
|
qualified name or macro name.
|
|
- properties: a list of properties applied to said function.
|
|
Possible values are:
|
|
|
|
- pointee_write: indicate the write use for call arguments that correspond to
|
|
parameters whose pointee types are non-const
|
|
- pointee_read: indicate the read use for call arguments that correspond to
|
|
parameters whose pointee types are non-const
|
|
- taken: indicates that the specified address arguments may be stored in objects
|
|
that persist after the function has ceased to exist (excluding the returned value);
|
|
address arguments not listed are never taken
|
|
- attribute: attributes a function may have. Possible values are pure, const and noeffect.
|
|
|
|
pointee_read and pointee_write use a specific kind of argument, structured as pointee_arg=rw:
|
|
|
|
- pointee_arg: argument index for callee. Index 0 refers to the return value,
|
|
the indices of the arguments start from 1. It can be either a single value or a range.
|
|
- rw: a value that's either always, maybe or never
|
|
|
|
- always: for pointee_read: argument pointee is expected to be fully read in the function body,
|
|
for pointee_write: argument pointee is fully initialized at function exit
|
|
- maybe: for pointee_read: argument pointee may be expected to be read in the function body,
|
|
for pointee_write: argument pointee may be written by function body
|
|
- never: for pointee_read: argument pointee is not expected to be read in the function body,
|
|
for pointee_write: argument pointee is never written by function body
|