Re: [i-g-t 4/7] docs: add the sections file

[Daniel Vetter <daniel@ffwll.ch>]

On Wed, Jun 11, 2014 at 11:35:40AM +0100, Thomas Wood wrote:
> On 10 June 2014 15:40, Daniel Vetter <daniel@ffwll.ch> wrote:
> > On Tue, Jun 10, 2014 at 03:30:54PM +0100, Thomas Wood wrote:
> >> This file can contain custom changes to the control the documentation
> >> output and therefore should be included in the repository.
> >>
> >> Signed-off-by: Thomas Wood <thomas.wood@intel.com>
> >
> > Doesn't that mean we need to update this when adding new symbols? Imo
> > forcing autogeneration is better since you can control the order also by
> > moving functions around in the .h files. Or what exactly is this for?
> > -Daniel
> 
> There are further annotations that can be made in this file, which is
> why gtk-doc does not automatically overwrite it when symbols and
> sections are added or removed:
> 
> https://developer.gnome.org/gtk-doc-manual/stable/metafiles_sections.html.en

Hm, I actually like the autogenerated one. Forcing people to do this by
hand pretty much means that it will get lost in most cases - doing the api
docs themselves is still often not done.

So for now I'd actually prefer if we hack the Makefiles to unconditionally
regen this, if possible. At least until we have a real use-case for this.
-Daniel
> 
> 
> >
> >> ---
> >>  docs/reference/intel-gpu-tools/.gitignore          |   1 -
> >>  .../intel-gpu-tools/intel-gpu-tools-sections.txt   | 378 +++++++++++++++++++++
> >>  2 files changed, 378 insertions(+), 1 deletion(-)
> >>  create mode 100644 docs/reference/intel-gpu-tools/intel-gpu-tools-sections.txt
> >>
> >> diff --git a/docs/reference/intel-gpu-tools/.gitignore b/docs/reference/intel-gpu-tools/.gitignore
> >> index 9415974..9fadbfc 100644
> >> --- a/docs/reference/intel-gpu-tools/.gitignore
> >> +++ b/docs/reference/intel-gpu-tools/.gitignore
> >> @@ -6,7 +6,6 @@
> >>  /intel-gpu-tools-decl-list.txt
> >>  /intel-gpu-tools-decl.txt
> >>  /intel-gpu-tools-overrides.txt
> >> -/intel-gpu-tools-sections.txt
> >>  /intel-gpu-tools-undeclared.txt
> >>  /intel-gpu-tools-undocumented.txt
> >>  /intel-gpu-tools-unused.txt
> >> diff --git a/docs/reference/intel-gpu-tools/intel-gpu-tools-sections.txt b/docs/reference/intel-gpu-tools/intel-gpu-tools-sections.txt
> >> new file mode 100644
> >> index 0000000..de6c76c
> >> --- /dev/null
> >> +++ b/docs/reference/intel-gpu-tools/intel-gpu-tools-sections.txt
> >> @@ -0,0 +1,378 @@
> >> +<SECTION>
> >> +<FILE>debug</FILE>
> >> +DEBUG_PROTOCOL_VERSION
> >> +COMMUNICATION_OFFSET
> >> +COMMUNICATION_QWORD
> >> +STATE_EU_MSG
> >> +STATE_CPU_ACK
> >> +STATE_OFFSET
> >> +STATE_QWORD
> >> +TX_OFFSET
> >> +TX_QWORD
> >> +RX_OFFSET
> >> +RX_QWORD
> >> +grf
> >> +mrf
> >> +cr
> >> +sr
> >> +DWORD8
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>drmtest</FILE>
> >> +mmap64
> >> +ARRAY_SIZE
> >> +ALIGN
> >> +drm_get_card
> >> +drm_open_any
> >> +drm_open_any_render
> >> +gem_quiescent_gpu
> >> +do_or_die
> >> +do_ioctl
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>igt_aux</FILE>
> >> +igt_fork_signal_helper
> >> +igt_stop_signal_helper
> >> +igt_exchange_int
> >> +igt_permute_array
> >> +igt_progress
> >> +igt_check_boolean_env_var
> >> +igt_aub_dump_enabled
> >> +igt_init_aperture_trashers
> >> +igt_trash_aperture
> >> +igt_cleanup_aperture_trashers
> >> +igt_system_suspend_autoresume
> >> +igt_drop_root
> >> +igt_wait_for_keypress
> >> +igt_runtime_pm_status
> >> +igt_setup_runtime_pm
> >> +igt_get_runtime_pm_status
> >> +igt_wait_for_pm_status
> >> +intel_purge_vm_caches
> >> +intel_get_avail_ram_mb
> >> +intel_get_total_ram_mb
> >> +intel_get_total_swap_mb
> >> +intel_check_memory
> >> +CHECK_RAM
> >> +CHECK_SWAP
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>igt_core</FILE>
> >> +IGT_EXIT_TIMEOUT
> >> +IGT_EXIT_SKIP
> >> +IGT_EXIT_SUCCESS
> >> +igt_fixture
> >> +igt_subtest_init
> >> +igt_opt_handler_t
> >> +igt_subtest_init_parse_opts
> >> +igt_tokencat
> >> +igt_subtest
> >> +igt_subtest_f
> >> +igt_subtest_name
> >> +igt_only_list_subtests
> >> +igt_main
> >> +igt_simple_init
> >> +igt_simple_main
> >> +igt_skip
> >> +igt_success
> >> +igt_fail
> >> +igt_exit
> >> +igt_assert
> >> +igt_assert_f
> >> +igt_assert_cmpint
> >> +igt_require
> >> +igt_skip_on
> >> +igt_require_f
> >> +igt_skip_on_f
> >> +igt_fork
> >> +igt_waitchildren
> >> +igt_helper_process
> >> +igt_fork_helper
> >> +igt_wait_helper
> >> +igt_stop_helper
> >> +igt_exit_handler_t
> >> +igt_install_exit_handler
> >> +igt_enable_exit_handler
> >> +igt_disable_exit_handler
> >> +igt_run_in_simulation
> >> +SLOW_QUICK
> >> +igt_skip_on_simulation
> >> +igt_log_level
> >> +igt_log
> >> +igt_vlog
> >> +igt_debug
> >> +igt_info
> >> +igt_warn
> >> +igt_warn_on
> >> +igt_warn_on_f
> >> +igt_set_timeout
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>igt_debugfs</FILE>
> >> +igt_debugfs_open
> >> +igt_debugfs_fopen
> >> +igt_pipe_crc_t
> >> +igt_crc_t
> >> +intel_pipe_crc_source
> >> +igt_crc_is_null
> >> +igt_crc_equal
> >> +igt_crc_to_string
> >> +igt_require_pipe_crc
> >> +igt_pipe_crc_new
> >> +igt_pipe_crc_free
> >> +igt_pipe_crc_start
> >> +igt_pipe_crc_stop
> >> +igt_pipe_crc_get_crcs
> >> +igt_pipe_crc_collect_crc
> >> +DROP_UNBOUND
> >> +DROP_BOUND
> >> +DROP_RETIRE
> >> +DROP_ACTIVE
> >> +DROP_ALL
> >> +igt_drop_caches_set
> >> +igt_disable_prefault
> >> +igt_enable_prefault
> >> +igt_open_forcewake_handle
> >> +stop_ring_flags
> >> +igt_to_stop_ring_flag
> >> +igt_set_stop_rings
> >> +igt_get_stop_rings
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>igt_fb</FILE>
> >> +cairo_surface_t
> >> +cairo_t
> >> +igt_fb
> >> +igt_text_align
> >> +igt_create_fb_with_bo_size
> >> +igt_create_fb
> >> +igt_create_color_fb
> >> +igt_remove_fb
> >> +igt_get_cairo_ctx
> >> +igt_paint_color
> >> +igt_paint_color_alpha
> >> +igt_paint_color_gradient
> >> +igt_paint_test_pattern
> >> +igt_paint_image
> >> +igt_write_fb_to_png
> >> +igt_cairo_printf_line
> >> +igt_bpp_depth_to_drm_format
> >> +igt_drm_format_to_bpp
> >> +igt_format_str
> >> +igt_get_all_formats
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>igt_kms</FILE>
> >> +pipe
> >> +pipe_name
> >> +igt_plane
> >> +plane_name
> >> +sprite_name
> >> +port
> >> +port_name
> >> +kmstest_connector_config
> >> +kmstest_get_connector_default_mode
> >> +kmstest_get_connector_config
> >> +kmstest_free_connector_config
> >> +kmstest_dump_mode
> >> +kmstest_get_pipe_from_crtc_id
> >> +kmstest_pipe_str
> >> +kmstest_encoder_type_str
> >> +kmstest_connector_status_str
> >> +kmstest_connector_type_str
> >> +kmstest_set_connector_dpms
> >> +igt_display_t
> >> +igt_pipe_t
> >> +igt_fixed_t
> >> +igt_plane_t
> >> +igt_pipe
> >> +igt_output_t
> >> +igt_display
> >> +igt_set_vt_graphics_mode
> >> +igt_display_init
> >> +igt_display_fini
> >> +igt_display_commit
> >> +igt_display_get_n_pipes
> >> +igt_output_name
> >> +igt_output_get_mode
> >> +igt_output_set_pipe
> >> +igt_output_get_plane
> >> +igt_plane_set_fb
> >> +igt_plane_set_position
> >> +igt_wait_for_vblank
> >> +for_each_connected_output
> >> +PIPE_ANY
> >> +IGT_FIXED
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>instdone</FILE>
> >> +MAX_INSTDONE_BITS
> >> +instdone_bit
> >> +num_instdone_bits
> >> +init_instdone_definitions
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>intel_batchbuffer</FILE>
> >> +BATCH_SZ
> >> +BATCH_RESERVED
> >> +intel_batchbuffer
> >> +intel_batchbuffer_alloc
> >> +intel_batchbuffer_free
> >> +intel_batchbuffer_flush
> >> +intel_batchbuffer_flush_on_ring
> >> +intel_batchbuffer_flush_with_context
> >> +intel_batchbuffer_reset
> >> +intel_batchbuffer_data
> >> +intel_batchbuffer_emit_reloc
> >> +intel_batchbuffer_space
> >> +intel_batchbuffer_emit_dword
> >> +intel_batchbuffer_require_space
> >> +BEGIN_BATCH
> >> +OUT_BATCH
> >> +OUT_RELOC_FENCED
> >> +OUT_RELOC
> >> +ADVANCE_BATCH
> >> +BLIT_COPY_BATCH_START
> >> +COLOR_BLIT_COPY_BATCH_START
> >> +BLIT_RELOC_UDW
> >> +intel_blt_copy
> >> +intel_copy_bo
> >> +igt_buf
> >> +igt_buf_width
> >> +igt_buf_height
> >> +igt_render_copyfunc_t
> >> +igt_get_render_copyfunc
> >> +igt_media_fillfunc_t
> >> +igt_get_media_fillfunc
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>intel_chipset</FILE>
> >> +intel_get_pci_device
> >> +intel_get_drm_devid
> >> +intel_gen
> >> +pch_type
> >> +intel_check_pch
> >> +HAS_IBX
> >> +HAS_CPT
> >> +HAS_LPT
> >> +IS_MOBILE
> >> +IS_G45
> >> +IS_GM45
> >> +IS_G4X
> >> +IS_ILD
> >> +IS_ILM
> >> +IS_915
> >> +IS_945GM
> >> +IS_945
> >> +IS_G33
> >> +IS_GEN2
> >> +IS_GEN3
> >> +IS_GEN4
> >> +IS_GEN5
> >> +IS_GEN6
> >> +IS_GEN7
> >> +IS_IVYBRIDGE
> >> +IS_VALLEYVIEW
> >> +IS_HSW_GT1
> >> +IS_HSW_GT2
> >> +IS_HSW_GT3
> >> +IS_HASWELL
> >> +IS_BROADWELL
> >> +IS_CHERRYVIEW
> >> +IS_GEN8
> >> +IS_965
> >> +IS_9XX
> >> +IS_INTEL
> >> +HAS_PCH_SPLIT
> >> +HAS_BLT_RING
> >> +HAS_BSD_RING
> >> +IS_BROADWATER
> >> +IS_CRESTLINE
> >> +HAS_VEBOX_RING
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>intel_io</FILE>
> >> +mmio
> >> +intel_mmio_use_pci_bar
> >> +intel_mmio_use_dump_file
> >> +intel_register_access_init
> >> +intel_register_access_fini
> >> +intel_register_read
> >> +intel_register_write
> >> +intel_register_access_needs_fakewake
> >> +INREG
> >> +OUTREG
> >> +intel_dpio_reg_read
> >> +intel_dpio_reg_write
> >> +intel_flisdsi_reg_read
> >> +intel_flisdsi_reg_write
> >> +intel_punit_read
> >> +intel_punit_write
> >> +intel_nc_read
> >> +intel_nc_write
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>ioctl_wrappers</FILE>
> >> +gem_handle_to_libdrm_bo
> >> +gem_set_tiling
> >> +gem_set_caching
> >> +gem_get_caching
> >> +gem_flink
> >> +gem_open
> >> +gem_close
> >> +gem_write
> >> +gem_read
> >> +gem_set_domain
> >> +gem_sync
> >> +gem_create
> >> +gem_execbuf
> >> +gem_mmap__gtt
> >> +gem_mmap__cpu
> >> +gem_mmap
> >> +gem_madvise
> >> +gem_context_create
> >> +gem_sw_finish
> >> +gem_bo_busy
> >> +gem_get_num_rings
> >> +gem_has_enable_ring
> >> +gem_has_bsd
> >> +gem_has_blt
> >> +gem_has_vebox
> >> +gem_uses_aliasing_ppgtt
> >> +gem_available_fences
> >> +gem_available_aperture_size
> >> +gem_aperture_size
> >> +gem_mappable_aperture_size
> >> +gem_require_caching
> >> +gem_require_ring
> >> +prime_handle_to_fd
> >> +prime_fd_to_handle
> >> +prime_get_size
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>media_fill</FILE>
> >> +gen8_media_fillfunc
> >> +gen7_media_fillfunc
> >> +</SECTION>
> >> +
> >> +<SECTION>
> >> +<FILE>rendercopy</FILE>
> >> +gen8_render_copyfunc
> >> +gen7_render_copyfunc
> >> +gen6_render_copyfunc
> >> +gen3_render_copyfunc
> >> +gen2_render_copyfunc
> >> +</SECTION>
> >> +
> >> --
> >> 1.9.3
> >>
> >> _______________________________________________
> >> Intel-gfx mailing list
> >> Intel-gfx@lists.freedesktop.org
> >> http://lists.freedesktop.org/mailman/listinfo/intel-gfx
> >
> > --
> > Daniel Vetter
> > Software Engineer, Intel Corporation
> > +41 (0) 79 365 57 48 - http://blog.ffwll.ch
> > ---------------------------------------------------------------------
> > Intel Corporation (UK) Limited
> > Registered No. 1134945 (England)
> > Registered Office: Pipers Way, Swindon SN3 1RJ
> > VAT No: 860 2173 47
> >
> > This e-mail and any attachments may contain confidential material for
> > the sole use of the intended recipient(s). Any review or distribution
> > by others is strictly prohibited. If you are not the intended
> > recipient, please contact the sender and delete all copies.
> >

-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch