[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [xen staging] docs: Move function and macro properties in docs/misra
commit b36d850c228807287b138b83fe6b198c943c2b66 Author: Simone Ballarin <simone.ballarin@xxxxxxxxxxx> AuthorDate: Tue Feb 27 16:36:30 2024 +0100 Commit: Jan Beulich <jbeulich@xxxxxxxx> CommitDate: Thu Feb 29 08:20:05 2024 +0100 docs: Move function and macro properties in docs/misra The list of function/macro properties is not MISRA-specific documentation. Their addition was directly motivated to address MISRA findings and they are not used elsewhere. For this reason, this patch moves these properties in docs/misra. This patch also fixes a Sphinx warning caused by the missing inclusion of the rst file in the toctree. Reported-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx> Fixes: f4519ee8 ("eclair: move function and macro properties outside ECLAIR") Signed-off-by: Simone Ballarin <simone.ballarin@xxxxxxxxxxx> Acked-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx> --- automation/eclair_analysis/propertyparser.py | 2 +- docs/function_macro_properties.json | 841 --------------------------- docs/function_macro_properties.rst | 58 -- docs/misra/function-macro-properties.json | 841 +++++++++++++++++++++++++++ docs/misra/function-macro-properties.rst | 58 ++ docs/misra/index.rst | 1 + 6 files changed, 901 insertions(+), 900 deletions(-) diff --git a/automation/eclair_analysis/propertyparser.py b/automation/eclair_analysis/propertyparser.py index 0d02f505a6..5059a68fec 100644 --- a/automation/eclair_analysis/propertyparser.py +++ b/automation/eclair_analysis/propertyparser.py @@ -2,7 +2,7 @@ import json import os script_dir = os.path.dirname(__file__) -properties_path = os.path.join(script_dir, "../../docs/function_macro_properties.json") +properties_path = os.path.join(script_dir, "../../docs/misra/function-macro-properties.json") output_path = os.path.join(script_dir, "ECLAIR/call_properties.ecl") with open(properties_path) as fp: diff --git a/docs/function_macro_properties.json b/docs/function_macro_properties.json deleted file mode 100644 index 74058297b5..0000000000 --- a/docs/function_macro_properties.json +++ /dev/null @@ -1,841 +0,0 @@ -{ - "version": "1.0", - "content": [ - { - "type": "function", - "value": "^printk.*$", - "properties":{ - "pointee_write": "1..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^debugtrace_printk.*$", - "properties":{ - "pointee_write": "1..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^panic.*$", - "properties":{ - "pointee_write": "1..=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^domain_crash$", - "properties":{ - "pointee_write": "2..=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^(g?d|mm_)?printk$", - "properties":{ - "pointee_write": "2..=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^guest_bug_on_failed$", - "properties":{ - "pointee_write": "1=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^spin_lock_init_prof$", - "properties":{ - "pointee_write": "2=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^sched_test_func$", - "properties":{ - "pointee_write": "1..=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^dev_(info|warn)$", - "properties":{ - "pointee_write": "1..=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^PAGING_DEBUG$", - "properties":{ - "pointee_write": "1..=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^ACPI_(WARNING|ERROR|INFO)$", - "properties":{ - "pointee_write": "1..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^fdt_get_property_by_offset_.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^read_atomic_size.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^device_tree_get_reg.*$", - "properties":{ - "pointee_write": "4..=always", - "pointee_read": "4..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^dt_get_range.*$", - "properties":{ - "pointee_write": "3..=always", - "pointee_read": "3..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^parse_static_mem_prop.*$", - "properties":{ - "pointee_write": "2..=always", - "pointee_read": "2..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^get_ttbr_and_gran_64bit.*$", - "properties":{ - "pointee_write": "1..2=always", - "pointee_read": "1..2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^hvm_emulate_init_once.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^__vmread.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^hvm_pci_decode_addr.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^vpci_mmcfg_decode_addr.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^x86emul_decode.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^unmap_grant_ref.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^arm_smmu_cmdq_build_cmd.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^pci_size_mem_bar.*$", - "properties":{ - "pointee_write": "4=always", - "pointee_read": "4=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^_hvm_read_entry.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^hvm_map_guest_frame_rw.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^guest_cpuid.*$", - "properties":{ - "pointee_write": "4=always", - "pointee_read": "4=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^epte_get_entry_emt.*$", - "properties":{ - "pointee_write": "5=always", - "pointee_read": "5=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^mcheck_mca_logout.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^set_field_in_reg_u32.*$", - "properties":{ - "pointee_write": "5=always", - "pointee_read": "5=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^alloc_affinity_masks.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^xasprintf.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^find_non_smt.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^call_rcu.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^getdomaininfo.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^MAPPING_(INSERT|SEARCH)\\(.*$", - "properties":{ - "pointee_write": "2..=always", - "pointee_read": "2..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^FormatDec.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^FormatHex.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^p2m_get_ioreq_server.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^elf_memset_unchecked.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^set_iommu_pte_present.*$", - "properties":{ - "pointee_write": "7=always", - "pointee_read": "7=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^clear_iommu_pte_present.*$", - "properties":{ - "pointee_write": "4=always", - "pointee_read": "4=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^vcpu_runstate_get.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^va_start.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^sgi_target_init.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^get_hw_residencies.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^x86_cpu_policy_to_featureset.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^simple_strtou?ll?\\(.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^msi_compose_msg.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^print_tainted.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^get_hvm_registers.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^x86_insn_modrm.*$", - "properties":{ - "pointee_write": "2..3=always", - "pointee_read": "2..3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^cpuid_count_leaf.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^rcu_lock_remote_domain_by_id.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^cpuid_count.*$", - "properties":{ - "pointee_write": "3..=always", - "pointee_read": "3..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^.*efi_boot_mem_unused.*$", - "properties":{ - "pointee_write": "1..=always", - "pointee_read": "1..=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^collect_time_info.*$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^setup_xstate_comp.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^map_domain_gfn.*$", - "properties":{ - "pointee_read": "5=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^fdt_getprop.*$", - "properties":{ - "pointee_read": "4=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^fdt_get_name.*$", - "properties":{ - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^fdt_get_property.*$", - "properties":{ - "pointee_read": "4=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^pci_get_host_bridge_segment.*$", - "properties":{ - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^dt_get_property.*$", - "properties":{ - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^dt_property_read_u32.*$", - "properties":{ - "pointee_read": "3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^dt_device_get_paddr.*$", - "properties":{ - "pointee_read": "3..4=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^get_evtchn_dt_property.*$", - "properties":{ - "pointee_write": "2..3=maybe", - "pointee_read": "2..3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^setup_chosen_node.*$", - "properties":{ - "pointee_write": "2..3=maybe", - "pointee_read": "2..3=never", - "taken": "" - } - }, - { - "type": "function", - "value": "^queue_remove_raw.*$", - "properties":{ - "pointee_read": "2=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^memset$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^va_start$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^memcmp$", - "properties":{ - "pointee_write": "1..2=never", - "taken": "" - } - }, - { - "type": "macro", - "value": "^memcpy$", - "properties":{ - "pointee_write": "1=always&&2..=never", - "pointee_read": "1=never&&2..=always", - "taken": "" - } - }, - { - "type": "function", - "value": "^get_cpu_info.*$", - "properties":{ - "attribute": "pure" - } - }, - { - "type": "function", - "value": "^pdx_to_pfn.*$", - "properties":{ - "attribute": "pure" - } - }, - { - "type": "function", - "value": "^is_pci_passthrough_enabled.*$", - "properties":{ - "attribute": "const" - } - }, - { - "type": "function", - "value": "^get_cycles.*$", - "properties":{ - "attribute": "noeffect" - } - }, - { - "type": "function", - "value": "^msi_gflags.*$", - "properties":{ - "attribute": "const" - } - }, - { - "type": "function", - "value": "^hvm_save_size.*$", - "properties":{ - "attribute": "pure" - } - }, - { - "type": "function", - "value": "^cpu_has.*$", - "properties":{ - "attribute": "pure" - } - }, - { - "type": "function", - "value": "^boot_cpu_has.*$", - "properties":{ - "attribute": "pure" - } - }, - { - "type": "function", - "value": "^get_cpu_info.*$", - "properties":{ - "attribute": "pure" - } - }, - { - "type": "function", - "value": "^put_pte_flags.*$", - "properties":{ - "attribute": "const" - } - }, - { - "type": "function", - "value": "^is_pv_cpu.*$", - "properties":{ - "attribute": "pure" - } - }, - { - "description": "Property inferred as a consequence of the semantics of device_tree_get_reg", - "type": "function", - "value": "^acquire_static_memory_bank.*$", - "properties":{ - "pointee_write": "4..=always", - "pointee_read": "4..=never", - "taken": "" - } - }, - { - "description": "Property inferred as a consequence of the semantics of dt_set_cell", - "type": "function", - "value": "^set_interrupt.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "description":"Property inferred as a consequence of the semantics of __p2m_get_mem_access", - "type": "function", - "value": "^p2m_get_mem_access.*$", - "properties":{ - "pointee_write": "3=always", - "pointee_read": "3=never", - "taken": "" - } - }, - { - "description": "This function has alternative definitions with props {write=always,read=never} and {write=never,read=never}", - "type": "function", - "value": "^alloc_cpumask_var.*$", - "properties":{ - "pointee_write": "1=maybe", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "description": "Property inferred as a consequence of the semantics of alloc_cpumask_var", - "type": "function", - "value": "^xenctl_bitmap_to_cpumask.*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "description": "The call to bitmap_and causes the pointee of dstp to be always written", - "type": "function", - "value": "^cpumask_(and|andnot|clear|copy|complement).*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "description": "The call to bitmap_and causes the pointee of dstp to be always written", - "type": "function", - "value": "^bitmap_(andnot|complement|fill).*$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "description": "The .*copy_(to|from).* helpers all have a memcpy-like expectation that the destination is a copy of the source. Furthermore, their uses do initialize the involved variables as needed by futher uses in the caller.", - "type": "macro", - "value": "^(__)?(raw_)?copy_from_(paddr|guest|compat)(_offset)?$", - "properties":{ - "pointee_write": "1=always", - "pointee_read": "1=never", - "taken": "" - } - }, - { - "description":"The .*copy_(to|from).* helpers all have a memcpy-like expectation that the destination is a copy of the source. Furthermore, their uses do initialize the involved variables as needed by futher uses in the caller.", - "type": "macro", - "value": "^(__)?copy_to_(guest|compat)(_offset)?$", - "properties":{ - "pointee_write": "2=always", - "pointee_read": "2=never", - "taken": "" - } - }, - { - "description": "Functions generated by build_atomic_read cannot be considered pure since the input pointer is volatile, but they do not produce any persistent side effect.", - "type": "function", - "value": "^read_u(8|16|32|64|int)_atomic.*$", - "properties":{ - "attribute": "noeffect" - } - }, - { - "description": "Functions generated by TYPE_SAFE are const.", - "type": "function", - "value": "^(mfn|gfn|pfn)_x\\(.*$", - "properties":{ - "attribute": "const" - } - }, - { - "description": "Functions generated by TYPE_SAFE are const.", - "type": "function", - "value": "^_(mfn|gfn|pfn)\\(.*$", - "properties":{ - "attribute": "const" - } - } - ] -} diff --git a/docs/function_macro_properties.rst b/docs/function_macro_properties.rst deleted file mode 100644 index ea6fb5cf1f..0000000000 --- a/docs/function_macro_properties.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. 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 diff --git a/docs/misra/function-macro-properties.json b/docs/misra/function-macro-properties.json new file mode 100644 index 0000000000..74058297b5 --- /dev/null +++ b/docs/misra/function-macro-properties.json @@ -0,0 +1,841 @@ +{ + "version": "1.0", + "content": [ + { + "type": "function", + "value": "^printk.*$", + "properties":{ + "pointee_write": "1..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^debugtrace_printk.*$", + "properties":{ + "pointee_write": "1..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^panic.*$", + "properties":{ + "pointee_write": "1..=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^domain_crash$", + "properties":{ + "pointee_write": "2..=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^(g?d|mm_)?printk$", + "properties":{ + "pointee_write": "2..=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^guest_bug_on_failed$", + "properties":{ + "pointee_write": "1=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^spin_lock_init_prof$", + "properties":{ + "pointee_write": "2=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^sched_test_func$", + "properties":{ + "pointee_write": "1..=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^dev_(info|warn)$", + "properties":{ + "pointee_write": "1..=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^PAGING_DEBUG$", + "properties":{ + "pointee_write": "1..=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^ACPI_(WARNING|ERROR|INFO)$", + "properties":{ + "pointee_write": "1..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^fdt_get_property_by_offset_.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^read_atomic_size.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^device_tree_get_reg.*$", + "properties":{ + "pointee_write": "4..=always", + "pointee_read": "4..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^dt_get_range.*$", + "properties":{ + "pointee_write": "3..=always", + "pointee_read": "3..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^parse_static_mem_prop.*$", + "properties":{ + "pointee_write": "2..=always", + "pointee_read": "2..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^get_ttbr_and_gran_64bit.*$", + "properties":{ + "pointee_write": "1..2=always", + "pointee_read": "1..2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^hvm_emulate_init_once.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^__vmread.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^hvm_pci_decode_addr.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^vpci_mmcfg_decode_addr.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^x86emul_decode.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^unmap_grant_ref.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^arm_smmu_cmdq_build_cmd.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^pci_size_mem_bar.*$", + "properties":{ + "pointee_write": "4=always", + "pointee_read": "4=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^_hvm_read_entry.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^hvm_map_guest_frame_rw.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^guest_cpuid.*$", + "properties":{ + "pointee_write": "4=always", + "pointee_read": "4=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^epte_get_entry_emt.*$", + "properties":{ + "pointee_write": "5=always", + "pointee_read": "5=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^mcheck_mca_logout.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^set_field_in_reg_u32.*$", + "properties":{ + "pointee_write": "5=always", + "pointee_read": "5=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^alloc_affinity_masks.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^xasprintf.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^find_non_smt.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^call_rcu.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^getdomaininfo.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^MAPPING_(INSERT|SEARCH)\\(.*$", + "properties":{ + "pointee_write": "2..=always", + "pointee_read": "2..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^FormatDec.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^FormatHex.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^p2m_get_ioreq_server.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^elf_memset_unchecked.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^set_iommu_pte_present.*$", + "properties":{ + "pointee_write": "7=always", + "pointee_read": "7=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^clear_iommu_pte_present.*$", + "properties":{ + "pointee_write": "4=always", + "pointee_read": "4=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^vcpu_runstate_get.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^va_start.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^sgi_target_init.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^get_hw_residencies.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^x86_cpu_policy_to_featureset.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^simple_strtou?ll?\\(.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^msi_compose_msg.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^print_tainted.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^get_hvm_registers.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^x86_insn_modrm.*$", + "properties":{ + "pointee_write": "2..3=always", + "pointee_read": "2..3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^cpuid_count_leaf.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^rcu_lock_remote_domain_by_id.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^cpuid_count.*$", + "properties":{ + "pointee_write": "3..=always", + "pointee_read": "3..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^.*efi_boot_mem_unused.*$", + "properties":{ + "pointee_write": "1..=always", + "pointee_read": "1..=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^collect_time_info.*$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^setup_xstate_comp.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^map_domain_gfn.*$", + "properties":{ + "pointee_read": "5=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^fdt_getprop.*$", + "properties":{ + "pointee_read": "4=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^fdt_get_name.*$", + "properties":{ + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^fdt_get_property.*$", + "properties":{ + "pointee_read": "4=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^pci_get_host_bridge_segment.*$", + "properties":{ + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^dt_get_property.*$", + "properties":{ + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^dt_property_read_u32.*$", + "properties":{ + "pointee_read": "3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^dt_device_get_paddr.*$", + "properties":{ + "pointee_read": "3..4=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^get_evtchn_dt_property.*$", + "properties":{ + "pointee_write": "2..3=maybe", + "pointee_read": "2..3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^setup_chosen_node.*$", + "properties":{ + "pointee_write": "2..3=maybe", + "pointee_read": "2..3=never", + "taken": "" + } + }, + { + "type": "function", + "value": "^queue_remove_raw.*$", + "properties":{ + "pointee_read": "2=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^memset$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^va_start$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^memcmp$", + "properties":{ + "pointee_write": "1..2=never", + "taken": "" + } + }, + { + "type": "macro", + "value": "^memcpy$", + "properties":{ + "pointee_write": "1=always&&2..=never", + "pointee_read": "1=never&&2..=always", + "taken": "" + } + }, + { + "type": "function", + "value": "^get_cpu_info.*$", + "properties":{ + "attribute": "pure" + } + }, + { + "type": "function", + "value": "^pdx_to_pfn.*$", + "properties":{ + "attribute": "pure" + } + }, + { + "type": "function", + "value": "^is_pci_passthrough_enabled.*$", + "properties":{ + "attribute": "const" + } + }, + { + "type": "function", + "value": "^get_cycles.*$", + "properties":{ + "attribute": "noeffect" + } + }, + { + "type": "function", + "value": "^msi_gflags.*$", + "properties":{ + "attribute": "const" + } + }, + { + "type": "function", + "value": "^hvm_save_size.*$", + "properties":{ + "attribute": "pure" + } + }, + { + "type": "function", + "value": "^cpu_has.*$", + "properties":{ + "attribute": "pure" + } + }, + { + "type": "function", + "value": "^boot_cpu_has.*$", + "properties":{ + "attribute": "pure" + } + }, + { + "type": "function", + "value": "^get_cpu_info.*$", + "properties":{ + "attribute": "pure" + } + }, + { + "type": "function", + "value": "^put_pte_flags.*$", + "properties":{ + "attribute": "const" + } + }, + { + "type": "function", + "value": "^is_pv_cpu.*$", + "properties":{ + "attribute": "pure" + } + }, + { + "description": "Property inferred as a consequence of the semantics of device_tree_get_reg", + "type": "function", + "value": "^acquire_static_memory_bank.*$", + "properties":{ + "pointee_write": "4..=always", + "pointee_read": "4..=never", + "taken": "" + } + }, + { + "description": "Property inferred as a consequence of the semantics of dt_set_cell", + "type": "function", + "value": "^set_interrupt.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "description":"Property inferred as a consequence of the semantics of __p2m_get_mem_access", + "type": "function", + "value": "^p2m_get_mem_access.*$", + "properties":{ + "pointee_write": "3=always", + "pointee_read": "3=never", + "taken": "" + } + }, + { + "description": "This function has alternative definitions with props {write=always,read=never} and {write=never,read=never}", + "type": "function", + "value": "^alloc_cpumask_var.*$", + "properties":{ + "pointee_write": "1=maybe", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "description": "Property inferred as a consequence of the semantics of alloc_cpumask_var", + "type": "function", + "value": "^xenctl_bitmap_to_cpumask.*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "description": "The call to bitmap_and causes the pointee of dstp to be always written", + "type": "function", + "value": "^cpumask_(and|andnot|clear|copy|complement).*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "description": "The call to bitmap_and causes the pointee of dstp to be always written", + "type": "function", + "value": "^bitmap_(andnot|complement|fill).*$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "description": "The .*copy_(to|from).* helpers all have a memcpy-like expectation that the destination is a copy of the source. Furthermore, their uses do initialize the involved variables as needed by futher uses in the caller.", + "type": "macro", + "value": "^(__)?(raw_)?copy_from_(paddr|guest|compat)(_offset)?$", + "properties":{ + "pointee_write": "1=always", + "pointee_read": "1=never", + "taken": "" + } + }, + { + "description":"The .*copy_(to|from).* helpers all have a memcpy-like expectation that the destination is a copy of the source. Furthermore, their uses do initialize the involved variables as needed by futher uses in the caller.", + "type": "macro", + "value": "^(__)?copy_to_(guest|compat)(_offset)?$", + "properties":{ + "pointee_write": "2=always", + "pointee_read": "2=never", + "taken": "" + } + }, + { + "description": "Functions generated by build_atomic_read cannot be considered pure since the input pointer is volatile, but they do not produce any persistent side effect.", + "type": "function", + "value": "^read_u(8|16|32|64|int)_atomic.*$", + "properties":{ + "attribute": "noeffect" + } + }, + { + "description": "Functions generated by TYPE_SAFE are const.", + "type": "function", + "value": "^(mfn|gfn|pfn)_x\\(.*$", + "properties":{ + "attribute": "const" + } + }, + { + "description": "Functions generated by TYPE_SAFE are const.", + "type": "function", + "value": "^_(mfn|gfn|pfn)\\(.*$", + "properties":{ + "attribute": "const" + } + } + ] +} diff --git a/docs/misra/function-macro-properties.rst b/docs/misra/function-macro-properties.rst new file mode 100644 index 0000000000..ea6fb5cf1f --- /dev/null +++ b/docs/misra/function-macro-properties.rst @@ -0,0 +1,58 @@ +.. 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 diff --git a/docs/misra/index.rst b/docs/misra/index.rst index 5068ee5aef..bde9d9cffb 100644 --- a/docs/misra/index.rst +++ b/docs/misra/index.rst @@ -16,3 +16,4 @@ Xen hypervisor code and related documents. documenting-violations exclude-list xen-static-analysis + function-macro-properties -- generated by git-patchbot for /home/xen/git/xen.git#staging
|
![]() |
Lists.xenproject.org is hosted with RackSpace, monitoring our |