deploy: 6f50b05 #3203 (opened)

https://analogdevicesinc.github.io/linux/pull/3203

Author: cseci

pull/3203/_sources/ci.rst.txt

@@ -0,0 +1,205 @@
+Contribution guidelines
+=======================
+
+This page serves the purpose of providing pointers and a brief introduction to
+contributing to the Linux Kernel, using the tools available as well as wrappers
+maintained by Analog Devices Inc.
+
+.. tip::
+
+   When using :git-linux:`/`, the :doc:`ci` system automates most checks inside
+   a container (:git-linux:`ci:container`). See :ref:`interactive-run` for
+   interactive usage.
+
+Code checkers
+-------------
+
+There are many checkers to catch issues before submitting changes to the Kernel
+mailing lists. :git-linux:`ci:ci/build.sh` combines all of the checkers so that
+they can be run with one command using a standard configuration. The checkers
+supported by build.sh are as follows.
+
+Checkpatch
+~~~~~~~~~~
+
+:external+upstream:doc:`dev-tools/checkpatch`
+(:git-linux:`scripts/checkpatch.pl`) is a perl script which checks for trivial
+style violations in patches and optionally corrects them. Checkpatch can also
+be run on file contexts and without the kernel tree.
+
+It is the bare-minimum tool before submitting any patch series.
+
+Usage:
+
+.. code:: bash
+
+   ./scripts/checkpatch.pl [OPTION]... [FILE]...
+
+.. important::
+
+   You must always adjust the style to match the guidelines of the
+   :ref:`subsystem` you are collaborating to.
+
+To run it as a low-budget `lsp server <https://en.wikipedia.org/wiki/Language_Server_Protocol>`__, do:
+
+.. code:: bash
+
+   while true; do \
+     scripts/checkpatch.pl --color=always drivers/power/supply/max77928_charger.c  \
+                           --strict \
+                           --ignore FILE_PATH_CHANGES \
+                           --ignore LONG_LINE \
+                           --ignore LONG_LINE_STRING \
+                           --ignore LONG_LINE_COMMENT \
+                           --ignore PARENTHESIS_ALIGNMENT \
+                           --ignore CAMELCASE \
+                           --ignore UNDOCUMENTED_DT_STRING \
+                           --strict \ > /tmp/output ; clear ; cat /tmp/output ; \
+   done
+
+Sparse and smatch
+~~~~~~~~~~~~~~~~~
+
+:external+upstream:doc:`dev-tools/sparse` is a semantic checker for C programs;
+it can be used to find a number of potential problems with kernel code.
+Usage:
+
+.. shell::
+
+   ~/linux
+   $make C=1
+
+And `Smatch <https://smatch.sourceforge.net/>`__ is a static analysis tool for
+C mostly for the linux kernel.
+Usage:
+
+.. shell::
+
+   ~/linux
+   $make C=1 CHECK="smatch -p=kernel"
+
+Further reading: `Finding locking bugs with Smatch <https://lwn.net/Articles/1023646/>`__
+
+GCC fanalyzer
+~~~~~~~~~~~~~
+
+GCC's
+`-fanalyzer <https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html#index-analyzer>`__
+enables an static analysis of program flow which looks for "interesting"
+interprocedural paths through the code, and issues warnings for problems found
+on them.
+
+Since it is a flag, it must be appended to the compile command, either to the
+`KCFLAGS`:
+
+.. shell::
+
+   ~/linux
+   $make KCFLAGS=" -fanalyzer"
+
+To analyze a single file, generate compile commands with
+`./scripts/clang-tools/gen_compile_commands.py`, extract the compile command
+for the ``.c`` file and append ``-fanalyzer``.
+
+Clang static analyzer
+~~~~~~~~~~~~~~~~~~~~~
+
+`Clang static analyzer <https://clang-analyzer.llvm.org/>`__  is a source code
+analysis tool that finds bugs in C, C++, and Objective-C programs.
+
+Since it is a flag, it must be appended to the compile command, either to the
+`KCFLAGS`:
+
+.. shell::
+
+   ~/linux
+   $make LLVM=1 KCFLAGS=" --analyze -Xanalyzer"
+
+To analyze a single file, generate compile commands with
+`./scripts/clang-tools/gen_compile_commands.py`, extract the compile command
+for the ``.c`` file and append ``--analyze -Xanalyzer``.
+
+Devicetree
+----------
+
+The "Open Firmware Device Tree", or simply
+:external+upstream:doc:`Devicetree <devicetree/usage-model>` (DT), is a data
+structure and language for describing hardware. More specifically, it is a
+description of hardware that is readable by an operating system so that the
+operating system doesn’t need to hard code details of the machine.
+
+Even though some devicetrees are provided with the Linux Kernel, in general,
+a custom devicetree will need to be written to describe a specific board or
+device, using the protopytes provided by the
+:git-linux:`Documentation/devicetree/bindings/**/*.yaml <Documentation/devicetree/bindings>` files.
+
+When submitting dt-bindings, you must check:
+
+.. shell::
+
+   ~/linux
+   $make dt_binding_check CONFIG_DTC=y DT_CHECKER_FLAGS=-m  DT_SCHEMA_FILES="./path/to/.yaml"
+
+For warnings and erros and resolve accordingly.
+
+.. _b4:
+
+B4
+--
+
+:external+b4:doc:`B4 <index>` is a tool created to make it easier for project
+developers and maintainers to use a distributed development workflow that
+relies on patches and distribution lists for code contributions and review.
+
+Take some time to try it out, and understand how it simplies many tasks.
+B4 tools is not currently leveraged by continuous integration, and you
+must run it locally.
+
+The section that you will most interested in is the
+:external+b4:doc:`contributor/overview`, where the contributor workflow is
+extensively detailed, as well as the tools to ease it, such as
+:external+b4:doc:`b4 prep <contributor/prep>`,
+:external+b4:doc:`b4 send <contributor/send>`, and
+:external+b4:doc:`b4 trailers <contributor/trailers>`.
+
+.. _subsystem:
+
+Subsytems
+---------
+
+The Linux kernel is organized into subsystems—logical divisions around
+functionality such as core APIs (memory, scheduling, locking, timers), driver
+interfaces (networking, storage, input, etc.), and various device-oriented
+modules (IIO, USB, SPI, etc.). Each subsystem encapsulates its own APIs,
+conventions, and lifecycle, helping maintain modularity and clarity. For an
+up-to-date map of these subsystems and their interfaces, see
+:external+upstream:doc:`subsystem-apis`.
+
+When developing for a particular subsystem, look for the appropriate git tree
+in the :git-linux:`MAINTAINERS` file to work on. Development branches may be
+force pushed. It is reasonable to base you work on top of the current latest
+tag, such as `v6.19-rc1
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?h=v6.19-rc1&id=8f0b4cce4481fb22653697cced8d0d04027cb1e8>`__
+or near it, this avoids unnecessary merge commits when pulling changes.
+
+For some subsystems, CI/CD is automatically applied to developemnt branches as
+described at :ref:`ci`.
+
+IIO Subsytem
+~~~~~~~~~~~~
+
+The :external+upstream:doc:`Industrial I/O subsystem <driver-api/iio/intro>` is
+intended to provide support for devices that in some senses are analog to
+digital or digital to analog converters (ADCs, DACs). Devices that fall into
+this category are: ADCs, accelerometers, gyros, IMUs, capacitance to digital
+converters, pressure sensors, light and proximity sensors, temperature sensors,
+magnetometers, DACs, DDS (Direct Digital Synthesis), variable/programmable gain
+amplifiers (VGA, PGA). These devices typically would be connected via SPI or
+I2C.
+
+The overall aim is to fill the gap between the somewhat similar hwmon and input
+subsystems. Hwmon is very much directed at low sample rate sensors used in
+applications such as fan speed control and temperature measurement.
+
+To continuous capture data based on a trigger source,
+:external+upstream:doc:`iio/iio_devbuf` are used.

pull/3203/_sources/contribute.rst.txt

@@ -0,0 +1,100 @@
+.. _getting_started:
+
+Getting Started
+===============
+
+Description
+-----------
+
+The Linux kernel in this repository is the
+`Linux kernel from Xilinx <https://github.com/Xilinx/linux-xlnx>`__
+together with drivers & patches applied from Analog Devices.
+
+Details about the drivers that are of interest and supported by this repository
+can be found on the
+:dokuwiki:`Analog Devices wiki <resources/tools-software/linux-drivers-all>`.
+This readme focuses on details specific to how this code is
+structured/organized, how it was derived, etc.
+
+The current main is based on `xilinx v2025.1 <https://github.com/Xilinx/linux-xlnx/tree/xilinx-v2025.1>`__.
+For details about the merge see commit
+:git-linux:`3b1f15dc5c4d <commit/3b1f15dc5c4de92663059705d6f1cb6fc87d4470+>`
+(Merge tag ``xilinx-v2025.1`` of https://github.com/Xilinx/linux-xlnx.git).
+In this Xilinx release, the current version of upstream Linux is
+`Linux 6.12 <https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tag/?h=v6.12>`__.
+
+How to build
+------------
+
+For build instructions
+:dokuwiki:`check the wiki <resources/tools-software/linux-drivers-all#building_the_adi_linux_kernel>`.
+
+Release branches
+----------------
+
+All release branches have the ``[YEAR]_R[NUM]`` format. There are some special
+release branches sometimes (like ``2014_R2_altera``, because it wasn't always
+possible to match the Linux repo between Xilinx & Intel/Altera.
+
+Each release is matched with a release from the :git-hdl:`HDL repo </>`. The
+branching name/model for the HDL repo differs a bit from the one in this repo,
+but the matching should be obvious. Therefore, each kernel in the release
+branches is be built using the toolchains from a specific version of Vivado &
+Quartus. A matching of these can be found at :external+hdl:ref:`releases`.
+Release branches can be built using other GCC toolchains, but in the official
+SD-card images provided, they will use the toolchains from Vivado/Quartus.
+
+Rebased branches
+----------------
+
+Starting with :git-linux:`adi-4.9.0:` there are rebased branches. They're
+typically rebased branches from Xilinx with the ADI patches on top so that it's
+easier to identify patches that are not yet upstreamed.
+
+For :git-linux:`adi-4.9.0:` the base was branch
+`xlnx_rebase_v4.9 <https://github.com/Xilinx/linux-xlnx/tree/xlnx_rebase_v4.9>`__
+at commit
+:git-linux:`e5c22c2179cf <commit/e5c22c2179cfbec584d2c540d40a0c3d7a20770c+>`
+in the ADI repo and commit
+`45e196f59364 <https://github.com/Xilinx/linux-xlnx/commit/45e196f59364e9f5eafe46027a7d2af349083974>`__
+in the Xilinx repo. All ADI patches & drivers up to a specific point in time
+were cherry-picked to that branch from master. Note that since the
+``adi-4.9.0`` branch is the first rebased branch, it's not particularly the
+best rebase that could have been done, but it should provide some patches that
+are somewhat reasonable to take and apply on top of an upstream 4.9 kernel
+after some polishing.
+
+The latest rebased branch depends on the current linux version supported in
+master. Also note that a diff between the latest rebased branch and `xlnx-main`
+(e.g., ``git diff xlnx-main adi-6.12.0``) must be NULL.
+
+Raspberry Pi branches
+---------------------
+
+These provide a kernel that is good to run on a Raspberry Pi board. All the
+drivers present in the master branch should be automatically cherry-picked into
+the latest rpi branch.
+
+As in the rebased branches, the latest rpi branch should be in accordance with
+the current kernel version supported in master.
+
+Intel/Altera branches
+---------------------
+
+Because the kernel versions that Intel/Altera were usually not in sync with
+Xilinx's, ``altera-*`` branches were created:
+
+- :git-linux:`altera_4.0 <altera_4.0:>`
+- :git-linux:`altera_4.4 <altera_4.4:>`
+- :git-linux:`altera_4.6 <altera_4.6:>`
+- :git-linux:`altera_4.9 <altera_4.9:>`
+- :git-linux:`altera_4.14 <altera_4.14:>`
+
+These branches are derived from the
+`Intel/Altera linux kernel repo <https://github.com/altera-opensource/linux-socfpga>`__,
+together with some merged versions of old master branches.
+
+These branches would stop existing, since Intel/Altera seems to keep in sync
+their kernel version with more recent non-LTS kernels. Typically the
+releases/references that are provided for these boards should already be in the
+mainline kernel, so these branches should no longer be needed.

pull/3203/_sources/getting_started.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../Documentation/iio/ad3552r.rst

pull/3203/_sources/iio/ad3552r.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../Documentation/iio/ad4000.rst

pull/3203/_sources/iio/ad4000.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../Documentation/iio/ad4695.rst

pull/3203/_sources/iio/ad4695.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../Documentation/iio/ad7191.rst

pull/3203/_sources/iio/ad7191.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../Documentation/iio/ad7380.rst

pull/3203/_sources/iio/ad7380.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../Documentation/iio/ad7625.rst

pull/3203/_sources/iio/ad7625.rst.txt

@@ -0,0 +1 @@
+.. include:: ../../Documentation/iio/ad7944.rst