Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make Kernel API docs easily accessible #89

Open
0xricksanchez opened this issue Sep 3, 2022 · 3 comments
Open

Make Kernel API docs easily accessible #89

0xricksanchez opened this issue Sep 3, 2022 · 3 comments

Comments

@0xricksanchez
Copy link
Owner

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
Copy link
Owner Author

0xricksanchez commented Sep 5, 2022

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: sphinx-doc/sphinx#8313
Related: sphinx-doc/sphinx#8241

@0xricksanchez
Copy link
Owner Author

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
Copy link
Owner Author

0xricksanchez commented Sep 5, 2022

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: readthedocs/readthedocs.org#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...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant