[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [Xen-devel] RFC/Proposal: Partial `libxenctrl` API/ABI stabilisation
On Mon, 2015-05-18 at 16:30 +0100, Ian Campbell wrote: > % Partial `libxenctrl` API/ABI stabilisation I really ought to have CC-d the other tools maintainers on this, done here. Note there are some minor updates in a reply to Andy Cooper too. > % Ian Campbell <ian.campbell@xxxxxxxxxx> > % Draft A > > # Introduction > > The low-level `libxenctrl` library currently has an unstable API and > ABI and some of the hypervisor interfaces which it exposes are > similarly unstable. > > However several external projects use some of these interfaces (at > least: qemu and kexec-tools), which presents problems for distros and > other consumers. In particular the need for spurious rebuilds of those > components against newer versions of Xen and difficulty supporting > parallel installation of different versions of Xen (useful during > upgrade). > > This document considers whether parts of `libxenctrl` can be split out > into new libraries with more useful API and ABI guarantees. > > XXX: I haven't yet done a full pass over the list of symbols in > `libxenctrl` to categorise them and decide where they belong. I > thought I would get some early feedback first and just picked a few > representative examples for each library. > > # ABI/API Compatibility Classes > > Compatibility opportunities: > > * `LAPI` -- Library API > * `LABI` -- Library ABI > * `HABI` -- Hypervisor ABI (includes ioctls). > > Each can either be Stable (`S`), Unstable (`U`) or don't care (`x`, > because made moot by higher level interface class, e.g. no real point > from an application PoV to a Stable HABI behind a unstable LABI). > > Stable vs. Unstable is across major hypervisor version bump, always > aim to be stable across point releases. > > For libraries Stable means `SONAME` major component, but forward > compatible only (i.e. old app on new library works, new app on old > library may not link due to e.g. new symbols. This is the normal > SONAME expectation). XXX find a link to the sort of scheme I mean. > > `HABI` may include ioctls used to access those ABIs, typically these > are already required to be stable by the relevant OS maintainers. > > A library interface may fall into one of these categories (I expect > there are others and we may not want any library to use some of even > these): > > * Unstable `LAPI` (`Uxx`) > * The Wild West > * Current Examples: `libxenctrl` > > * Stable `LAPI`, Unstable `LABI` (`SUx`) > * Requires application rebuild for a new Xen version, but not > application source code changes. > * Current Examples: `libxenlight` > > * Stable `LAPI`, Stable `LABI`, Unstable `HABI` (`SSU`) > * Library can be switched out via dynamic linking across > hypervisor upgrade (mechanism TBD, pos. distro specific, e.g. > symlink switched on boot). Requires application/daemon restart > but not rebuild (but changing hypervisor version involves a > reboot anyway). > * Current Examples: None?? > > * Stable `LAPI`, Stable `LABI`, Stable `HABI` (`SSS`) > * Applications linked again a library will function against any > hypervisor version. > * Current Examples: None?? > > # Goal > > Provide `SSU` or `SSS` interfaces for major external consumers of > current libxenctrl functionality. > > Out of scope (for now): `SSU` or `SSS` interfaces for consumers of > `libxenlight`. Rationale: Lets focus on fixing external consumers of > libxenctrl first. > > # Major External Consumers of `libxenctrl` > > * qemu > * kexec tools > * in guest tools e.g. users of `libxenstore`, `libvchan`, and by > extension `grant table` and `event channel` functionality. NB: > `libxenstore` is already `SSU` or `SSS` (XXX?) > > # `libxenctrl` symbols > > Gathered by: > > nm tools/libxc/libxenctrl.so | grep ' [Tt] ' | cut -f 3 -d \ | sort -u > > `libxenctrl` today exposes many symbols which look to be internal. We > should consider also reducing that set by using > `__attribute__((visibility("hidden")))`. > > The following proposes some functional groupings via some proposed > split library names. In some cases we may also wish to consider > replacing an API with one which can be properly maintained going > forwards. e.g.: > > - perhaps replacing domctl's used by qemu with new stable > hypercall ABIs and reflecting that in new library APIs. > - perhaps exposing more constrained versions of some broad interfaces > for external users. > > XXX: Change `xc_*` namespacing as well as library names? > > ## `libxenhypercall` > > Core open/close interface, "make a hypercall" functionality, hypercall > buffers. > > All other libraries likely depend on this. Applications do as well in > order to access open/close interface at least. > > - xc_interface_close > - xc_interface_is_fake (???) > - xc_interface_open > - xc_hypercall_buffer_array_create > - xc_hypercall_buffer_array_destroy > > ## `libxenevtchn` > > Interacting with `/dev/xen/evtchn` > > - xc_evtchn_alloc_unbound > - xc_evtchn_bind_interdomain > - xc_evtchn_bind_unbound_port > - xc_evtchn_bind_virq > - xc_evtchn_close > - xc_evtchn_fd > - xc_evtchn_notify > - xc_evtchn_open > - xc_evtchn_pending > - xc_evtchn_reset > - xc_evtchn_status > - xc_evtchn_unbind > - xc_evtchn_unmask > > ## `libxengnttab` > > Interacting with `/dev/xen/gnt{shr,alloc}` > > XXX two libs or one? > > - xc_gntshr_close > - xc_gntshr_munmap > - xc_gntshr_open > - xc_gntshr_share_page_notify > - xc_gntshr_share_pages > - xc_gnttab_close > - xc_gnttab_get_version > - xc_gnttab_map_domain_grant_refs > - xc_gnttab_map_grant_ref > - xc_gnttab_map_grant_ref_notify > - xc_gnttab_map_grant_refs > - xc_gnttab_map_table_v1 > - xc_gnttab_map_table_v2 > - xc_gnttab_munmap > - xc_gnttab_op > - xc_gnttab_open > - xc_gnttab_set_max_grants > > ## `libxendevicemodel` > > Functions specifically for use by device model > > ## `libxenkexec` > > Functions specifically for use by kexec tools > > - xc_kexec_exec > - xc_kexec_get_range > - xc_kexec_load > - xc_kexec_unload > > ## `libxentoollog` > > Logging stuff (already logically separate?) > > - xtl_createlogger_stdiostream > - xtl_level_to_string > - xtl_log > - xtl_logger_destroy > - xtl_logv > - xtl_progress > - xtl_stdiostream_adjust_flags > - xtl_stdiostream_set_minlevel > > ## `libxenctrl` (Unclassified remains) > > XXX Lots of this should be internal/hidden > > - bitmap_64_to_byte > - bitmap_byte_to_64 > - call_gmon_start > - deregister_tm_clones > - discard_file_cache > - do_domctl > - do_evtchn_op > - __do_global_dtors_aux > - __do_global_dtors_aux_fini_array_entry > - do_memory_op > - do_multicall_op > - do_physdev_op > - do_platform_op > - do_sysctl > - do_sysctl_save > - do_tmem_op > - do_xen_hypercall > - do_xen_version > - elfnote_dump_core_header > - elfnote_dump_format_version > - elfnote_dump_none > - elfnote_dump_xen_version > - elfnote_fill_format_version > - elfnote_fill_xen_version > - elfnote_init > - _fini > - flush_mmu_updates > - frame_dummy > - __frame_dummy_init_array_entry > - _gnttab_map_table > - hypercall_buffer_cache_alloc > - hypercall_buffer_cache_free > - hypercall_buffer_cache_lock > - hypercall_buffer_cache_unlock > - _init > - linux_evtchn_bind_interdomain > - linux_evtchn_bind_unbound_port > - linux_evtchn_bind_virq > - linux_evtchn_close > - linux_evtchn_fd > - linux_evtchn_notify > - linux_evtchn_open > - linux_evtchn_pending > - linux_evtchn_unbind > - linux_evtchn_unmask > - linux_gntshr_close > - linux_gntshr_munmap > - linux_gntshr_open > - linux_gntshr_share_pages > - linux_gnttab_close > - linux_gnttab_grant_map > - linux_gnttab_munmap > - linux_gnttab_open > - linux_gnttab_set_max_grants > - linux_osdep_init > - linux_privcmd_alloc_hypercall_buffer > - linux_privcmd_close > - linux_privcmd_free_hypercall_buffer > - linux_privcmd_hypercall > - linux_privcmd_map_foreign_batch > - linux_privcmd_map_foreign_bulk > - linux_privcmd_map_foreign_range > - linux_privcmd_map_foreign_ranges > - linux_privcmd_open > - local_file_dump > - modify_returncode > - progress_erase > - read_exact > - register_tm_clones > - retry_paged > - stdiostream_destroy > - stdiostream_message > - stdiostream_progress > - stdiostream_vmessage > - tbuf_enable > - VALGRIND_PRINTF > - VALGRIND_PRINTF_BACKTRACE > - write_exact > - writev_exact > - xc_add_mmu_update > - xc_alloc_mmu_updates > - xc_assign_device > - xc_assign_dt_device > - xc_availheap > - _xc_clean_errbuf > - xc_clear_domain_pages > - xc_clear_last_error > - xc_copy_to_domain_page > - xc_core_arch_auto_translated_physmap > - xc_core_arch_context_get_shdr > - xc_core_arch_get_scratch_gpfn > - xc_core_arch_gpfn_may_present > - xc_core_arch_map_p2m > - xc_core_arch_map_p2m_rw > - xc_core_arch_map_p2m_writable > - xc_core_arch_memory_map_get > - xc_core_ehdr_init > - xc_core_shdr_free > - xc_core_shdr_get > - xc_core_shdr_init > - xc_core_shdr_set > - xc_core_strtab_free > - xc_core_strtab_get > - xc_core_strtab_init > - xc_cpumap_alloc > - xc_cpumap_clearcpu > - xc_cpumap_setcpu > - xc_cpumap_testcpu > - xc_cpu_offline > - xc_cpu_online > - xc_cpupool_addcpu > - xc_cpupool_create > - xc_cpupool_destroy > - xc_cpupool_freeinfo > - xc_cpupool_getinfo > - xc_cpupool_infofree > - xc_cpupool_movedomain > - xc_cpupool_removecpu > - xc_cputopoinfo > - xc_deassign_device > - xc_deassign_dt_device > - xc_disable_turbo > - xc_domain_add_to_physmap > - xc_domain_bind_pt_irq > - xc_domain_bind_pt_irq_int > - xc_domain_bind_pt_isa_irq > - xc_domain_bind_pt_pci_irq > - xc_domain_bind_pt_spi_irq > - xc_domain_cacheflush > - xc_domain_claim_pages > - xc_domain_create > - xc_domain_create_config > - xc_domain_debug_control > - xc_domain_decrease_reservation > - xc_domain_decrease_reservation_exact > - xc_domain_destroy > - xc_domain_disable_migrate > - xc_domain_dumpcore > - xc_domain_dumpcore_via_callback > - xc_domain_get_cpu_usage > - xc_domain_get_guest_width > - xc_domain_getinfo > - xc_domain_getinfolist > - xc_domain_get_machine_address_size > - xc_domain_get_pod_target > - xc_domain_get_tsc_info > - xc_domain_hvm_getcontext > - xc_domain_hvm_getcontext_partial > - xc_domain_hvm_setcontext > - xc_domain_increase_reservation > - xc_domain_increase_reservation_exact > - xc_domain_iomem_permission > - xc_domain_ioport_mapping > - xc_domain_ioport_permission > - xc_domain_irq_permission > - xc_domain_maximum_gpfn > - xc_domain_max_vcpus > - xc_domain_memory_exchange_pages > - xc_domain_memory_mapping > - xc_domain_node_getaffinity > - xc_domain_node_setaffinity > - xc_domain_nr_gpfns > - xc_domain_p2m_audit > - xc_domain_pause > - xc_domain_pin_memory_cacheattr > - xc_domain_pod_target > - xc_domain_populate_physmap > - xc_domain_populate_physmap_exact > - xc_domain_resume > - xc_domain_resume_any > - xc_domain_resume_cooperative > - xc_domain_send_trigger > - xc_domain_set_access_required > - xc_domain_setdebugging > - xc_domain_sethandle > - xc_domain_set_machine_address_size > - xc_domain_set_max_evtchn > - xc_domain_setmaxmem > - xc_domain_set_memmap_limit > - xc_domain_set_memory_map > - xc_domain_set_pod_target > - xc_domain_set_target > - xc_domain_set_time_offset > - xc_domain_set_tsc_info > - xc_domain_set_virq_handler > - xc_domain_setvnuma > - xc_domain_shutdown > - xc_domain_subscribe_for_suspend > - xc_domain_suppress_spurious_page_faults > - xc_domain_unbind_msi_irq > - xc_domain_unbind_pt_irq > - xc_domain_unbind_pt_irq_int > - xc_domain_unbind_pt_spi_irq > - xc_domain_unpause > - xc_domain_update_msi_irq > - xc_domctl > - xc_enable_turbo > - xc_error_code_to_desc > - xc_ffs16 > - xc_ffs32 > - xc_ffs64 > - xc_ffs8 > - xc_flask_access > - xc_flask_add > - xc_flask_add_device > - xc_flask_add_iomem > - xc_flask_add_ioport > - xc_flask_add_pirq > - xc_flask_avc_cachestats > - xc_flask_avc_hashstats > - xc_flask_context_to_sid > - xc_flask_del > - xc_flask_del_device > - xc_flask_del_iomem > - xc_flask_del_ioport > - xc_flask_del_pirq > - xc_flask_getavc_threshold > - xc_flask_getbool_byid > - xc_flask_getbool_byname > - xc_flask_getenforce > - xc_flask_load > - xc_flask_op > - xc_flask_policyvers > - xc_flask_relabel_domain > - xc_flask_setavc_threshold > - xc_flask_setbool > - xc_flask_setenforce > - xc_flask_sid_to_context > - xc_flush_mmu_updates > - xc_get_cpufreq_avgfreq > - xc_get_cpufreq_para > - xc_get_cpuidle_max_cstate > - xc_getcpuinfo > - xc_get_cpumap_size > - xc_get_device_group > - xc_get_hvm_param > - xc_get_last_error > - xc_get_machine_memory_map > - xc_get_max_cpus > - xc_get_max_nodes > - xc_get_mem_access > - xc_get_nodemap_size > - xc_get_online_cpus > - xc_get_pfn_list > - xc_get_pfn_type_batch > - xc_get_tot_pages > - xc_get_vcpu_migration_delay > - xc_hvm_create_ioreq_server > - xc_hvm_destroy_ioreq_server > - xc_hvm_get_ioreq_server_info > - xc_hvm_inject_msi > - xc_hvm_inject_trap > - xc_hvm_map_io_range_to_ioreq_server > - xc_hvm_map_pcidev_to_ioreq_server > - xc_hvm_modified_memory > - xc_hvm_param_deprecated_check > - xc_hvm_param_get > - xc_hvm_param_set > - xc_hvm_set_ioreq_server_state > - xc_hvm_set_isa_irq_level > - xc_hvm_set_mem_type > - xc_hvm_set_pci_intx_level > - xc_hvm_set_pci_link_route > - xc_hvm_track_dirty_vram > - xc_hvm_unmap_io_range_from_ioreq_server > - xc_hvm_unmap_pcidev_from_ioreq_server > - xc__hypercall_bounce_post > - xc__hypercall_bounce_pre > - xc__hypercall_buffer_alloc > - xc__hypercall_buffer_alloc_pages > - xc__hypercall_buffer_array_alloc > - xc__hypercall_buffer_array_get > - xc__hypercall_buffer_cache_release > - xc__hypercall_buffer_free > - xc__hypercall_buffer_free_pages > - _xc_init_errbuf > - xc_interface_close > - xc_interface_close_common > - xc_interface_is_fake > - xc_interface_open > - xc_interface_open_common > - xc_lockprof_query > - xc_lockprof_query_number > - xc_lockprof_reset > - xc_machphys_mfn_list > - xc_make_page_below_4G > - xc_map_domain_meminfo > - xc_map_foreign_batch > - xc_map_foreign_batch_single > - xc_map_foreign_bulk > - xc_map_foreign_bulk_compat > - xc_map_foreign_pages > - xc_map_foreign_range > - xc_map_foreign_ranges > - xc_maximum_ram_page > - xc_mca_op > - xc_mem_access_disable_emulate > - xc_mem_access_enable_emulate > - xc_memalign > - xc_mem_paging_disable > - xc_mem_paging_enable > - xc_mem_paging_evict > - xc_mem_paging_load > - xc_mem_paging_memop > - xc_mem_paging_nominate > - xc_mem_paging_prep > - xc_mem_paging_resume > - xc_memshr_add_to_physmap > - xc_memshr_audit > - xc_memshr_control > - xc_memshr_debug_gfn > - xc_memshr_debug_gref > - xc_memshr_domain_resume > - xc_memshr_memop > - xc_memshr_nominate_gfn > - xc_memshr_nominate_gref > - xc_memshr_ring_disable > - xc_memshr_ring_enable > - xc_memshr_share_gfns > - xc_memshr_share_grefs > - xc_mmuext_op > - xc_monitor_disable > - xc_monitor_enable > - xc_monitor_mov_to_cr0 > - xc_monitor_mov_to_cr3 > - xc_monitor_mov_to_cr4 > - xc_monitor_mov_to_msr > - xc_monitor_resume > - xc_monitor_singlestep > - xc_monitor_software_breakpoint > - xc_nodemap_alloc > - xc_numainfo > - xc_osdep_get_info > - xc_osdep_log > - xc_osdep_put > - xc_osdep_type_name > - xc_pcitopoinfo > - xc_perfc_query > - xc_perfc_query_number > - xc_perfc_reset > - xc_pfn_to_mfn > - xc_physdev_map_pirq > - xc_physdev_map_pirq_msi > - xc_physdev_pci_access_modify > - xc_physdev_unmap_pirq > - xc_physinfo > - xc_pm_get_cxstat > - xc_pm_get_max_cx > - xc_pm_get_max_px > - xc_pm_get_pxstat > - xc_pm_reset_cxstat > - xc_pm_reset_pxstat > - xc_psr_cmt_attach > - xc_psr_cmt_detach > - xc_psr_cmt_enabled > - xc_psr_cmt_get_data > - xc_psr_cmt_get_domain_rmid > - xc_psr_cmt_get_l3_cache_size > - xc_psr_cmt_get_l3_event_mask > - xc_psr_cmt_get_l3_upscaling_factor > - xc_psr_cmt_get_total_rmid > - xc_readconsolering > - xc_report > - xc_report_error > - xc_report_progress_single > - xc_report_progress_step > - xc_reportv > - xc_resource_op > - xc_resource_op_multi > - xc_resource_op_one > - xc_sched_arinc653_schedule_get > - xc_sched_arinc653_schedule_set > - xc_sched_credit2_domain_get > - xc_sched_credit2_domain_set > - xc_sched_credit_domain_get > - xc_sched_credit_domain_set > - xc_sched_credit_params_get > - xc_sched_credit_params_set > - xc_sched_id > - xc_sched_rtds_domain_get > - xc_sched_rtds_domain_set > - xc_sedf_domain_get > - xc_sedf_domain_set > - xc_send_debug_keys > - xc_set_broken_page_p2m > - xc_set_cpufreq_gov > - xc_set_cpufreq_para > - xc_set_cpuidle_max_cstate > - xc_set_hvm_param > - xc_set_mem_access > - xc_set_progress_prefix > - xc_set_sched_opt_smt > - xc_set_vcpu_migration_delay > - xc_shadow_control > - xc_sharing_freed_pages > - xc_sharing_used_frames > - xc_strerror > - xc_sysctl > - xc_tbuf_disable > - xc_tbuf_enable > - xc_tbuf_get_size > - xc_tbuf_set_cpu_mask > - xc_tbuf_set_evt_mask > - xc_tbuf_set_size > - xc_test_assign_device > - xc_test_assign_dt_device > - xc_tmem_auth > - xc_tmem_control > - xc_tmem_control_oid > - xc_tmem_restore > - xc_tmem_restore_extra > - xc_tmem_restore_new_pool > - xc_tmem_save > - xc_tmem_save_done > - xc_tmem_save_extra > - xc_tmem_uuid_parse > - xc_translate_foreign_address > - xc_unmap_domain_meminfo > - xc_vcpu_getaffinity > - xc_vcpu_getcontext > - xc_vcpu_getinfo > - xc_vcpu_setaffinity > - xc_vcpu_setcontext > - xc_version > - xc_vm_event_control > - xc_vm_event_enable > - xc_watchdog > - xc_interface_close_common > - xc_interface_open_common > > # Symbols used by qemu > > $ nm tools/qemu-xen-dir-remote/i386-softmmu/qemu-system-i386 | grep > \\bU.xc_ > > - xc_domain_add_to_physmap > - xc_domain_bind_pt_pci_irq > - xc_domain_create > - xc_domain_destroy > - xc_domain_getinfo > - xc_domain_ioport_mapping > - xc_domain_max_vcpus > - xc_domain_memory_mapping > - xc_domain_pin_memory_cacheattr > - xc_domain_populate_physmap_exact > - xc_domain_setmaxmem > - xc_domain_shutdown > - xc_domain_unbind_msi_irq > - xc_domain_unbind_pt_irq > - xc_domain_unpause > - xc_domain_update_msi_irq > - xc_evtchn_alloc_unbound > - xc_evtchn_bind_interdomain > - xc_evtchn_close > - xc_evtchn_fd > - xc_evtchn_notify > - xc_evtchn_open > - xc_evtchn_pending > - xc_evtchn_unbind > - xc_evtchn_unmask > - xc_get_hvm_param > - xc_gnttab_close > - xc_gnttab_map_grant_ref > - xc_gnttab_map_grant_refs > - xc_gnttab_munmap > - xc_gnttab_open > - xc_gnttab_set_max_grants > - xc_hvm_inject_msi > - xc_hvm_modified_memory > - xc_hvm_set_isa_irq_level > - xc_hvm_set_mem_type > - xc_hvm_set_pci_intx_level > - xc_hvm_set_pci_link_route > - xc_hvm_track_dirty_vram > - xc_interface_close > - xc_interface_open > - xc_linux_build > - xc_map_foreign_bulk > - xc_map_foreign_pages > - xc_map_foreign_range > - xc_physdev_map_pirq > - xc_physdev_map_pirq_msi > - xc_physdev_unmap_pirq > - xc_set_hvm_param > > # Symbols used by kexec > > - xc__hypercall_buffer_array_alloc > - xc_get_machine_memory_map > - xc_get_max_cpus > - xc_hypercall_buffer_array_create > - xc_hypercall_buffer_array_destroy > - xc_interface_close > - xc_interface_open > - xc_kexec_exec > - xc_kexec_get_range > - xc_kexec_load > - xc_kexec_unload > - xc_version > > > > _______________________________________________ > Xen-devel mailing list > Xen-devel@xxxxxxxxxxxxx > http://lists.xen.org/xen-devel _______________________________________________ Xen-devel mailing list Xen-devel@xxxxxxxxxxxxx http://lists.xen.org/xen-devel
|
Lists.xenproject.org is hosted with RackSpace, monitoring our |