search

0xricksanchez / like-dbg

Fully dockerized Linux kernel debugging environment
MIT License
737 stars 58 forks source link

Make Kernel API docs easily accessible #89

Open 0xricksanchez opened 2 years ago

0xricksanchez commented 2 years ago

Sometimes you just want to quickly look up basic kernel APIs. Sadly, man(9) is not always available. So, it would be nice to have a convenient way to look up kernel API functions from the terminal.

0xricksanchez commented 2 years ago

Building the docs for the current Linux kernels with sphinx-5.1.1 does not work:

make htmldocs
  SPHINX  xmldocs --> file:///kernel_root/linux-5.10.77_x86_64/Documentation/output/xml
  PARSE   include/uapi/linux/dvb/audio.h
  PARSE   include/uapi/linux/dvb/ca.h
  PARSE   include/uapi/linux/dvb/dmx.h
  PARSE   include/uapi/linux/dvb/frontend.h
  PARSE   include/uapi/linux/dvb/net.h
  PARSE   include/uapi/linux/dvb/video.h
  PARSE   include/uapi/linux/videodev2.h
  PARSE   include/uapi/linux/media.h
  PARSE   include/uapi/linux/cec.h
  PARSE   include/uapi/linux/lirc.h
WARNING: The kernel documentation build process
        support for Sphinx v3.0 and above is brand new. Be prepared for
        possible issues in the generated output.
        WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid language code. Falling back to 'en' (English).
./include/net/sock.h:525: warning: Function parameter or member 'sk_peer_lock' not described in 'sock'
./drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c:86: warning: Function parameter or member 'work' not described in 'amdgpu_dm_irq_handler_data'
./include/drm/drm_file.h:365: warning: Function parameter or member 'master_lookup_lock' not described in 'drm_file'
./include/linux/spi/spi.h:673: warning: Function parameter or member 'devm_allocated' not described in 'spi_controller'
./drivers/gpu/host1x/bus.c:742: warning: Excess function parameter 'key' description in '__host1x_client_register'
./include/linux/device.h:561: warning: Function parameter or member 'msi_lock' not described in 'device'
kernel_root/linux-5.10.77_x86_64/Documentation/arm64/tagged-address-abi.rst:52: ERROR: Unexpected indentation.
kernel_root/linux-5.10.77_x86_64/Documentation/driver-api/80211/mac80211:109: ./include/net/mac80211.h:4719: WARNING: Duplicate C declaration, also defined at driver-api/80211/mac80211:1011.
Declaration is '.. c:function:: void ieee80211_tx_status (struct ieee80211_hw *hw, struct sk_buff *skb)'.
kernel_root/linux-5.10.77_x86_64/Documentation/networking/netdev-FAQ.rst:148: WARNING: Title underline too short.

Q: Are there special rules regarding stable submissions on netdev?
---------------------------------------------------------------
kernel_root/linux-5.10.77_x86_64/Documentation/networking/netdev-FAQ.rst:148: WARNING: Title underline too short.

Q: Are there special rules regarding stable submissions on netdev?
---------------------------------------------------------------
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/drm-kms:349: ./drivers/gpu/drm/drm_fourcc.c:312: WARNING: Duplicate C declaration, also defined at gpu/drm-kms:3.
Declaration is '.. c:function:: const struct drm_format_info * drm_format_info (u32 format)'.
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/drm-kms:433: ./drivers/gpu/drm/drm_modeset_lock.c:338: WARNING: Duplicate C declaration, also defined at gpu/drm-kms:46.
Declaration is '.. c:function:: int drm_modeset_lock (struct drm_modeset_lock *lock, struct drm_modeset_acquire_ctx *ctx)'.
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/drm-uapi:346: ./drivers/gpu/drm/drm_ioctl.c:923: WARNING: Duplicate C declaration, also defined at gpu/drm-uapi:70.
Declaration is '.. c:function:: bool drm_ioctl_flags (unsigned int nr, unsigned int *flags)'.
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/i915:22: ./drivers/gpu/drm/i915/intel_runtime_pm.c:423: WARNING: Inline strong start-string without end-string.
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/todo.rst:283: ERROR: Unexpected indentation.
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/todo.rst:284: WARNING: Block quote ends without a blank line; unexpected unindent.
kernel_root/linux-5.10.77_x86_64/Documentation/driver-api/usb/gadget.rst:759: WARNING: Duplicate C declaration, also defined at driver-api/usb/usb:967.
Declaration is '.. c:function:: int usb_string(struct usb_device *dev, int index, char *buf, size_t size)'.
kernel_root/linux-5.10.77_x86_64/Documentation/driver-api/miscellaneous:48: ./drivers/pwm/core.c:667: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:294.
Declaration is '.. c:function:: int pwm_capture (struct pwm_device *pwm, struct pwm_capture *result, unsigned long timeout)'.

Related: https://github.com/sphinx-doc/sphinx/pull/8313 Related: https://github.com/sphinx-doc/sphinx/issues/8241

0xricksanchez commented 2 years ago

For the most basic ones we could just scrape https://www.kernel.org/doc/htmldocs/kernel-api/API-<func>.html on demand… I am not confident in how complete/correct these are since those were deprecated in favor for the sphinx one over at https://www.kernel.org/doc/html/latest/

0xricksanchez commented 2 years ago

Apparently, the requirements listed in <kernel_root>/Documentation/sphinx/requirements.txt in the Kernel Version 5.10.77 were missing:

Jinja<3.1
six

After fixing that, building the docs is still not straightforward (for this version):

make htmldocs
#@./scripts/sphinx-pre-install --version-check
  SPHINX  htmldocs --> file://kernel_root/linux-5.10.77_x86_64/Documentation/output
  PARSE   include/uapi/linux/dvb/audio.h
  PARSE   include/uapi/linux/dvb/ca.h
  PARSE   include/uapi/linux/dvb/dmx.h
  PARSE   include/uapi/linux/dvb/frontend.h
  PARSE   include/uapi/linux/dvb/net.h
  PARSE   include/uapi/linux/dvb/video.h
  PARSE   include/uapi/linux/videodev2.h
  PARSE   include/uapi/linux/media.h
  PARSE   include/uapi/linux/cec.h
  PARSE   include/uapi/linux/lirc.h
./include/net/sock.h:525: warning: Function parameter or member 'sk_peer_lock' not described in 'sock'
./drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c:86: warning: Function parameter or member 'work' not described in 'amdgpu_dm_irq_handler_data'
./include/linux/spi/spi.h:673: warning: Function parameter or member 'devm_allocated' not described in 'spi_controller'
./include/drm/drm_file.h:365: warning: Function parameter or member 'master_lookup_lock' not described in 'drm_file'
./include/linux/device.h:561: warning: Function parameter or member 'msi_lock' not described in 'device'
./drivers/gpu/host1x/bus.c:742: warning: Excess function parameter 'key' description in '__host1x_client_register'
kernel_root/linux-5.10.77_x86_64/Documentation/arm64/tagged-address-abi.rst:52: WARNING: Unexpected indentation.
kernel_root/linux-5.10.77_x86_64/Documentation/networking/netdev-FAQ.rst:148: WARNING: Title underline too short.

Q: Are there special rules regarding stable submissions on netdev?
---------------------------------------------------------------
kernel_root/linux-5.10.77_x86_64/Documentation/networking/netdev-FAQ.rst:148: WARNING: Title underline too short.

Q: Are there special rules regarding stable submissions on netdev?
---------------------------------------------------------------
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/i915:22: ./drivers/gpu/drm/i915/intel_runtime_pm.c:423: WARNING: Inline strong start-string without end-string.
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/todo.rst:283: WARNING: Unexpected indentation.
kernel_root/linux-5.10.77_x86_64/Documentation/gpu/todo.rst:284: WARNING: Block quote ends without a blank line; unexpected unindent.

Related: https://github.com/readthedocs/readthedocs.org/issues/9038

Bottom-line: Always building the docs for the kernel version specified config.ini seems very much error-prone, depending on how the requirements shift, or if that specific version of the kernel does not want to let us build the docs...

Maybe always building the docs for the latest kernel version (as shown here: https://www.kernel.org/doc/html/latest/) could help us.

Alternatively, learning how to scrape the online sphinx documentation to allow a use-case like the following would be nice too:

./tellme "unregister_chrdev_region"

The above should return an easily digestible format (e.g.: rendered HTML) like the following to the CLI:

image

This would eradicate the need to use a browser for searching...