deploy: ba18f1e #3054 (opened)

Author: cseci

pull/3054/_sources/ci.rst.txt

@@ -0,0 +1,195 @@
+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_chec 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`.
+
+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/3054/_sources/contribute.rst.txt

@@ -0,0 +1,105 @@
+.. _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 v2024.1
+<https://github.com/Xilinx/linux-xlnx/tree/xilinx-v2024.1>`__. For details
+about the merge see commit :git-linux:`d31fa3135dbef8bf186a7c42fd87b3eedd8446e9
+<commit/d31fa3135dbef8bf186a7c42fd87b3eedd8446e9>` (Merge tag ``xilinx-v2024.1``
+of https://github.com/Xilinx/linux-xlnx.git). In this Xilinx release, the
+current version of upstream Linux is `Linux 6.6
+<https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tag/?h=v6.6>`__.
+
+For legacy reasons, the :git-linux:`xcomm_zynq <tree/xcomm_zynq>` branch is
+still available and should be in-sync with current master. That branch used to
+be the old master branch.
+
+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 :dokuwiki:`on the wiki
+<resources/fpga/docs/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 branch :git-linux:`adi-4.9.0 <tree/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 <tree/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:`d45e196f59364e9f5eafe46027a7d2af349083974
+<commit/d45e196f59364e9f5eafe46027a7d2af349083974>`
+in the ADI repo and commit `45e196f59364e9f5eafe46027a7d2af349083974
+<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. At the time of writing it is 5.10 so that :git-linux:`adi-5.10.0
+<tree/adi-5.10.0>` is the latest. Also note that a diff between the latest
+rebased branch and master (``git diff master adi-5.10.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. At the time of writing, the
+kernel version in master is 5.10 so that the correspondent latest rpi branch is
+:git-linux:`rpi-5.10.y <tree/rpi-5.10.y>`.
+
+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 <tree/altera_4.0>`
+- :git-linux:`altera_4.4 <tree/altera_4.4>`
+- :git-linux:`altera_4.6 <tree/altera_4.6>`
+- :git-linux:`altera_4.9 <tree/altera_4.9>`
+
+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.
+
+The hope is that with the upcoming Linux 4.19, 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/3054/_sources/getting_started.rst.txt

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

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

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

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

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

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

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

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

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

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

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

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

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